set -e; \
here=`cd $(SRCDIR); pwd`; \
point=$$here/util/point.sh; \
- for ds in apps:1 crypto:3 ssl:3; do \
- defdir=`echo $$ds | cut -f1 -d:`; \
- defsec=`echo $$ds | cut -f2 -d:`; \
- for p in $(SRCDIR)/doc/$$defdir/*.pod; do \
- SEC=`sed -ne 's/^=for *comment *openssl_manual_section: *\([0-9]\) *$$/\1/p' $$p`; \
- [ -z "$$SEC" ] && SEC=$$defsec; \
+ for ds in man1 man3 man5 man7 ; do \
+ SEC=`echo $$ds | sed -e s/man//`; \
+ for p in $(SRCDIR)/doc/$$ds/*.pod; do \
fn=`basename $$p .pod`; \
Name=$$fn; \
NAME=`echo $$fn | tr '[a-z]' '[A-Z]'`; \
UNINSTALL_DOCS=\
set -e; \
here=`cd $(SRCDIR); pwd`; \
- for ds in apps:1 crypto:3 ssl:3; do \
- defdir=`echo $$ds | cut -f1 -d:`; \
- defsec=`echo $$ds | cut -f2 -d:`; \
- for p in $(SRCDIR)/doc/$$defdir/*.pod; do \
- SEC=`sed -ne 's/^=for *comment *openssl_manual_section: *\([0-9]\) *$$/\1/p' $$p`; \
- [ -z "$$SEC" ] && SEC=$$defsec; \
+ for ds in man1 man3 man5 man7 ; do \
+ SEC=`echo $$ds | sed -e s/man//`; \
+ for p in $(SRCDIR)/doc/$$ds/*.pod; do \
fn=`basename $$p .pod`; \
suf=`eval "echo $$OUTSUFFIX"`; \
top=`eval "echo $$OUTTOP"`; \
HOWTO/
A few how-to documents; not necessarily up-to-date
-apps/
+
+man1/
The openssl command-line tools; start with openssl.pod
-ssl/
- The SSL library; start with ssl.pod
-crypto/
- The cryptographic library; start with crypto.pod
+
+man3/
+ The SSL library and the crypto library
+
+man5/
+ File formats
+
+man7/
+ Overviews; start with crypto.pod and ssl.pod, for example
Formatted versions of the manpages (apps,ssl,crypto) can be found at
https://www.openssl.org/docs/manpages.html
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CA.pl - friendlier interface for OpenSSL certificate programs
-
-=head1 SYNOPSIS
-
-B<CA.pl>
-[B<-?>]
-[B<-h>]
-[B<-help>]
-[B<-newcert>]
-[B<-newreq>]
-[B<-newreq-nodes>]
-[B<-newca>]
-[B<-xsign>]
-[B<-sign>]
-[B<-signreq>]
-[B<-signcert>]
-[B<-verify>]
-[B<files>]
-
-=head1 DESCRIPTION
-
-The B<CA.pl> script is a perl script that supplies the relevant command line
-arguments to the B<openssl> command for some common certificate operations.
-It is intended to simplify the process of certificate creation and management
-by the use of some simple options.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<?>, B<-h>, B<-help>
-
-prints a usage message.
-
-=item B<-newcert>
-
-creates a new self signed certificate. The private key is written to the file
-"newkey.pem" and the request written to the file "newreq.pem".
-
-=item B<-newreq>
-
-creates a new certificate request. The private key is written to the file
-"newkey.pem" and the request written to the file "newreq.pem".
-
-=item B<-newreq-nodes>
-
-is like B<-newreq> except that the private key will not be encrypted.
-
-=item B<-newca>
-
-creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert>
-and B<-xsign> options). The user is prompted to enter the filename of the CA
-certificates (which should also contain the private key) or by hitting ENTER
-details of the CA will be prompted for. The relevant files and directories
-are created in a directory called "demoCA" in the current directory.
-
-=item B<-pkcs12>
-
-create a PKCS#12 file containing the user certificate, private key and CA
-certificate. It expects the user certificate and private key to be in the
-file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem,
-it creates a file "newcert.p12". This command can thus be called after the
-B<-sign> option. The PKCS#12 file can be imported directly into a browser.
-If there is an additional argument on the command line it will be used as the
-"friendly name" for the certificate (which is typically displayed in the browser
-list box), otherwise the name "My Certificate" is used.
-
-=item B<-sign>, B<-signreq>, B<-xsign>
-
-calls the B<ca> program to sign a certificate request. It expects the request
-to be in the file "newreq.pem". The new certificate is written to the file
-"newcert.pem" except in the case of the B<-xsign> option when it is written
-to standard output.
-
-
-=item B<-signCA>
-
-this option is the same as the B<-signreq> option except it uses the configuration
-file section B<v3_ca> and so makes the signed request a valid CA certificate. This
-is useful when creating intermediate CA from a root CA.
-
-=item B<-signcert>
-
-this option is the same as B<-sign> except it expects a self signed certificate
-to be present in the file "newreq.pem".
-
-=item B<-crl>
-
-generate a CRL
-
-=item B<-revoke certfile [reason]>
-
-revoke the certificate contained in the specified B<certfile>. An optional
-reason may be specified, and must be one of: B<unspecified>,
-B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
-B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
-
-=item B<-verify>
-
-verifies certificates against the CA certificate for "demoCA". If no certificates
-are specified on the command line it tries to verify the file "newcert.pem".
-
-=item B<files>
-
-one or more optional certificate file names for use with the B<-verify> command.
-
-=back
-
-=head1 EXAMPLES
-
-Create a CA hierarchy:
-
- CA.pl -newca
-
-Complete certificate creation example: create a CA, create a request, sign
-the request and finally create a PKCS#12 file containing it.
-
- CA.pl -newca
- CA.pl -newreq
- CA.pl -signreq
- CA.pl -pkcs12 "My Test Certificate"
-
-=head1 DSA CERTIFICATES
-
-Although the B<CA.pl> creates RSA CAs and requests it is still possible to
-use it with DSA certificates and requests using the L<req(1)> command
-directly. The following example shows the steps that would typically be taken.
-
-Create some DSA parameters:
-
- openssl dsaparam -out dsap.pem 1024
-
-Create a DSA CA certificate and private key:
-
- openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem
-
-Create the CA directories and files:
-
- CA.pl -newca
-
-enter cacert.pem when prompted for the CA file name.
-
-Create a DSA certificate request and private key (a different set of parameters
-can optionally be created first):
-
- openssl req -out newreq.pem -newkey dsa:dsap.pem
-
-Sign the request:
-
- CA.pl -signreq
-
-=head1 NOTES
-
-Most of the filenames mentioned can be modified by editing the B<CA.pl> script.
-
-If the demoCA directory already exists then the B<-newca> command will not
-overwrite it and will do nothing. This can happen if a previous call using
-the B<-newca> option terminated abnormally. To get the correct behaviour
-delete the demoCA directory if it already exists.
-
-Under some environments it may not be possible to run the B<CA.pl> script
-directly (for example Win32) and the default configuration file location may
-be wrong. In this case the command:
-
- perl -S CA.pl
-
-can be used and the B<OPENSSL_CONF> environment variable changed to point to
-the correct path of the configuration file "openssl.cnf".
-
-The script is intended as a simple front end for the B<openssl> program for use
-by a beginner. Its behaviour isn't always what is wanted. For more control over the
-behaviour of the certificate commands call the B<openssl> command directly.
-
-=head1 ENVIRONMENT VARIABLES
-
-The variable B<OPENSSL_CONF> if defined allows an alternative configuration
-file location to be specified, it should contain the full path to the
-configuration file, not just its directory.
-
-=head1 SEE ALSO
-
-L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>,
-L<config(5)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-asn1parse - ASN.1 parsing tool
-
-=head1 SYNOPSIS
-
-B<openssl> B<asn1parse>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-noout>]
-[B<-offset number>]
-[B<-length number>]
-[B<-i>]
-[B<-oid filename>]
-[B<-dump>]
-[B<-dlimit num>]
-[B<-strparse offset>]
-[B<-genstr string>]
-[B<-genconf file>]
-[B<-strictpem>]
-[B<-item name>]
-
-=head1 DESCRIPTION
-
-The B<asn1parse> command is a diagnostic utility that can parse ASN.1
-structures. It can also be used to extract data from ASN.1 formatted data.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform> B<DER|PEM>
-
-the input format. B<DER> is binary format and B<PEM> (the default) is base64
-encoded.
-
-=item B<-in filename>
-
-the input file, default is standard input
-
-=item B<-out filename>
-
-output file to place the DER encoded data into. If this
-option is not present then no data will be output. This is most useful when
-combined with the B<-strparse> option.
-
-=item B<-noout>
-
-don't output the parsed version of the input file.
-
-=item B<-offset number>
-
-starting offset to begin parsing, default is start of file.
-
-=item B<-length number>
-
-number of bytes to parse, default is until end of file.
-
-=item B<-i>
-
-indents the output according to the "depth" of the structures.
-
-=item B<-oid filename>
-
-a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
-file is described in the NOTES section below.
-
-=item B<-dump>
-
-dump unknown data in hex format.
-
-=item B<-dlimit num>
-
-like B<-dump>, but only the first B<num> bytes are output.
-
-=item B<-strparse offset>
-
-parse the contents octets of the ASN.1 object starting at B<offset>. This
-option can be used multiple times to "drill down" into a nested structure.
-
-=item B<-genstr string>, B<-genconf file>
-
-generate encoded data based on B<string>, B<file> or both using
-L<ASN1_generate_nconf(3)> format. If B<file> only is
-present then the string is obtained from the default section using the name
-B<asn1>. The encoded data is passed through the ASN1 parser and printed out as
-though it came from a file, the contents can thus be examined and written to a
-file using the B<out> option.
-
-=item B<-strictpem>
-
-If this option is used then B<-inform> will be ignored. Without this option any
-data in a PEM format input file will be treated as being base64 encoded and
-processed whether it has the normal PEM BEGIN and END markers or not. This
-option will ignore any data prior to the start of the BEGIN marker, or after an
-END marker in a PEM file.
-
-=item B<-item name>
-
-attempt to decode and print the data as B<ASN1_ITEM name>. This can be used to
-print out the fields of any supported ASN.1 structure if the type is known.
-
-=back
-
-=head2 Output
-
-The output will typically contain lines like this:
-
- 0:d=0 hl=4 l= 681 cons: SEQUENCE
-
-.....
-
- 229:d=3 hl=3 l= 141 prim: BIT STRING
- 373:d=2 hl=3 l= 162 cons: cont [ 3 ]
- 376:d=3 hl=3 l= 159 cons: SEQUENCE
- 379:d=4 hl=2 l= 29 cons: SEQUENCE
- 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier
- 386:d=5 hl=2 l= 22 prim: OCTET STRING
- 410:d=4 hl=2 l= 112 cons: SEQUENCE
- 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier
- 417:d=5 hl=2 l= 105 prim: OCTET STRING
- 524:d=4 hl=2 l= 12 cons: SEQUENCE
-
-.....
-
-This example is part of a self-signed certificate. Each line starts with the
-offset in decimal. B<d=XX> specifies the current depth. The depth is increased
-within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
-(tag and length octets) of the current type. B<l=XX> gives the length of
-the contents octets.
-
-The B<-i> option can be used to make the output more readable.
-
-Some knowledge of the ASN.1 structure is needed to interpret the output.
-
-In this example the BIT STRING at offset 229 is the certificate public key.
-The contents octets of this will contain the public key information. This can
-be examined using the option B<-strparse 229> to yield:
-
- 0:d=0 hl=3 l= 137 cons: SEQUENCE
- 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
- 135:d=1 hl=2 l= 3 prim: INTEGER :010001
-
-=head1 NOTES
-
-If an OID is not part of OpenSSL's internal table it will be represented in
-numerical form (for example 1.2.3.4). The file passed to the B<-oid> option
-allows additional OIDs to be included. Each line consists of three columns,
-the first column is the OID in numerical format and should be followed by white
-space. The second column is the "short name" which is a single word followed
-by white space. The final column is the rest of the line and is the
-"long name". B<asn1parse> displays the long name. Example:
-
-C<1.2.3.4 shortName A long name>
-
-=head1 EXAMPLES
-
-Parse a file:
-
- openssl asn1parse -in file.pem
-
-Parse a DER file:
-
- openssl asn1parse -inform DER -in file.der
-
-Generate a simple UTF8String:
-
- openssl asn1parse -genstr 'UTF8:Hello World'
-
-Generate and write out a UTF8String, don't print parsed output:
-
- openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der
-
-Generate using a config file:
-
- openssl asn1parse -genconf asn1.cnf -noout -out asn1.der
-
-Example config file:
-
- asn1=SEQUENCE:seq_sect
-
- [seq_sect]
-
- field1=BOOL:TRUE
- field2=EXP:0, UTF8:some random string
-
-
-=head1 BUGS
-
-There should be options to change the format of output lines. The output of some
-ASN.1 types is not well handled (if at all).
-
-=head1 SEE ALSO
-
-L<ASN1_generate_nconf(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ca - sample minimal CA application
-
-=head1 SYNOPSIS
-
-B<openssl> B<ca>
-[B<-help>]
-[B<-verbose>]
-[B<-config filename>]
-[B<-name section>]
-[B<-gencrl>]
-[B<-revoke file>]
-[B<-valid file>]
-[B<-status serial>]
-[B<-updatedb>]
-[B<-crl_reason reason>]
-[B<-crl_hold instruction>]
-[B<-crl_compromise time>]
-[B<-crl_CA_compromise time>]
-[B<-crldays days>]
-[B<-crlhours hours>]
-[B<-crlexts section>]
-[B<-startdate date>]
-[B<-enddate date>]
-[B<-days arg>]
-[B<-md arg>]
-[B<-policy arg>]
-[B<-keyfile arg>]
-[B<-keyform PEM|DER>]
-[B<-key arg>]
-[B<-passin arg>]
-[B<-cert file>]
-[B<-selfsign>]
-[B<-in file>]
-[B<-out file>]
-[B<-notext>]
-[B<-outdir dir>]
-[B<-infiles>]
-[B<-spkac file>]
-[B<-ss_cert file>]
-[B<-preserveDN>]
-[B<-noemailDN>]
-[B<-batch>]
-[B<-msie_hack>]
-[B<-extensions section>]
-[B<-extfile section>]
-[B<-engine id>]
-[B<-subj arg>]
-[B<-utf8>]
-[B<-create_serial>]
-[B<-multivalue-rdn>]
-
-=head1 DESCRIPTION
-
-The B<ca> command is a minimal CA application. It can be used
-to sign certificate requests in a variety of forms and generate
-CRLs it also maintains a text database of issued certificates
-and their status.
-
-The options descriptions will be divided into each purpose.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-verbose>
-
-this prints extra details about the operations being performed.
-
-=item B<-config filename>
-
-specifies the configuration file to use.
-
-=item B<-name section>
-
-specifies the configuration file section to use (overrides
-B<default_ca> in the B<ca> section).
-
-=item B<-in filename>
-
-an input filename containing a single certificate request to be
-signed by the CA.
-
-=item B<-ss_cert filename>
-
-a single self-signed certificate to be signed by the CA.
-
-=item B<-spkac filename>
-
-a file containing a single Netscape signed public key and challenge
-and additional field values to be signed by the CA. See the B<SPKAC FORMAT>
-section for information on the required input and output format.
-
-=item B<-infiles>
-
-if present this should be the last option, all subsequent arguments
-are taken as the names of files containing certificate requests.
-
-=item B<-out filename>
-
-the output file to output certificates to. The default is standard
-output. The certificate details will also be printed out to this
-file in PEM format (except that B<-spkac> outputs DER format).
-
-=item B<-outdir directory>
-
-the directory to output certificates to. The certificate will be
-written to a filename consisting of the serial number in hex with
-".pem" appended.
-
-=item B<-cert>
-
-the CA certificate file.
-
-=item B<-keyfile filename>
-
-the private key to sign requests with.
-
-=item B<-keyform PEM|DER>
-
-the format of the data in the private key file.
-The default is PEM.
-
-=item B<-key password>
-
-the password used to encrypt the private key. Since on some
-systems the command line arguments are visible (e.g. Unix with
-the 'ps' utility) this option should be used with caution.
-
-=item B<-selfsign>
-
-indicates the issued certificates are to be signed with the key
-the certificate requests were signed with (given with B<-keyfile>).
-Certificate requests signed with a different key are ignored. If
-B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
-ignored.
-
-A consequence of using B<-selfsign> is that the self-signed
-certificate appears among the entries in the certificate database
-(see the configuration option B<database>), and uses the same
-serial number counter as all other certificates sign with the
-self-signed certificate.
-
-=item B<-passin arg>
-
-the key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-notext>
-
-don't output the text form of a certificate to the output file.
-
-=item B<-startdate date>
-
-this allows the start date to be explicitly set. The format of the
-date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
-
-=item B<-enddate date>
-
-this allows the expiry date to be explicitly set. The format of the
-date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
-
-=item B<-days arg>
-
-the number of days to certify the certificate for.
-
-=item B<-md alg>
-
-the message digest to use.
-Any digest supported by the OpenSSL B<dgst> command can be used.
-This option also applies to CRLs.
-
-=item B<-policy arg>
-
-this option defines the CA "policy" to use. This is a section in
-the configuration file which decides which fields should be mandatory
-or match the CA certificate. Check out the B<POLICY FORMAT> section
-for more information.
-
-=item B<-msie_hack>
-
-this is a legacy option to make B<ca> work with very old versions of
-the IE certificate enrollment control "certenr3". It used UniversalStrings
-for almost everything. Since the old control has various security bugs
-its use is strongly discouraged. The newer control "Xenroll" does not
-need this option.
-
-=item B<-preserveDN>
-
-Normally the DN order of a certificate is the same as the order of the
-fields in the relevant policy section. When this option is set the order
-is the same as the request. This is largely for compatibility with the
-older IE enrollment control which would only accept certificates if their
-DNs match the order of the request. This is not needed for Xenroll.
-
-=item B<-noemailDN>
-
-The DN of a certificate can contain the EMAIL field if present in the
-request DN, however it is good policy just having the e-mail set into
-the altName extension of the certificate. When this option is set the
-EMAIL field is removed from the certificate' subject and set only in
-the, eventually present, extensions. The B<email_in_dn> keyword can be
-used in the configuration file to enable this behaviour.
-
-=item B<-batch>
-
-this sets the batch mode. In this mode no questions will be asked
-and all certificates will be certified automatically.
-
-=item B<-extensions section>
-
-the section of the configuration file containing certificate extensions
-to be added when a certificate is issued (defaults to B<x509_extensions>
-unless the B<-extfile> option is used). If no extension section is
-present then, a V1 certificate is created. If the extension section
-is present (even if it is empty), then a V3 certificate is created. See the:w
-L<x509v3_config(5)> manual page for details of the
-extension section format.
-
-=item B<-extfile file>
-
-an additional configuration file to read certificate extensions from
-(using the default section unless the B<-extensions> option is also
-used).
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<ca>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<-subj arg>
-
-supersedes subject name given in the request.
-The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by \ (backslash), no spaces are skipped.
-
-=item B<-utf8>
-
-this option causes field values to be interpreted as UTF8 strings, by
-default they are interpreted as ASCII. This means that the field
-values, whether prompted from a terminal or obtained from a
-configuration file, must be valid UTF8 strings.
-
-=item B<-create_serial>
-
-if reading serial from the text file as specified in the configuration
-fails, specifying this option creates a new random serial to be used as next
-serial number.
-
-=item B<-multivalue-rdn>
-
-This option causes the -subj argument to be interpreted with full
-support for multivalued RDNs. Example:
-
-I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
-
-If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
-
-=back
-
-=head1 CRL OPTIONS
-
-=over 4
-
-=item B<-gencrl>
-
-this option generates a CRL based on information in the index file.
-
-=item B<-crldays num>
-
-the number of days before the next CRL is due. That is the days from
-now to place in the CRL nextUpdate field.
-
-=item B<-crlhours num>
-
-the number of hours before the next CRL is due.
-
-=item B<-revoke filename>
-
-a filename containing a certificate to revoke.
-
-=item B<-valid filename>
-
-a filename containing a certificate to add a Valid certificate entry.
-
-=item B<-status serial>
-
-displays the revocation status of the certificate with the specified
-serial number and exits.
-
-=item B<-updatedb>
-
-Updates the database index to purge expired certificates.
-
-=item B<-crl_reason reason>
-
-revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
-B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
-B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
-insensitive. Setting any revocation reason will make the CRL v2.
-
-In practice B<removeFromCRL> is not particularly useful because it is only used
-in delta CRLs which are not currently implemented.
-
-=item B<-crl_hold instruction>
-
-This sets the CRL revocation reason code to B<certificateHold> and the hold
-instruction to B<instruction> which must be an OID. Although any OID can be
-used only B<holdInstructionNone> (the use of which is discouraged by RFC2459)
-B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used.
-
-=item B<-crl_compromise time>
-
-This sets the revocation reason to B<keyCompromise> and the compromise time to
-B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>.
-
-=item B<-crl_CA_compromise time>
-
-This is the same as B<crl_compromise> except the revocation reason is set to
-B<CACompromise>.
-
-=item B<-crlexts section>
-
-the section of the configuration file containing CRL extensions to
-include. If no CRL extension section is present then a V1 CRL is
-created, if the CRL extension section is present (even if it is
-empty) then a V2 CRL is created. The CRL extensions specified are
-CRL extensions and B<not> CRL entry extensions. It should be noted
-that some software (for example Netscape) can't handle V2 CRLs. See
-L<x509v3_config(5)> manual page for details of the
-extension section format.
-
-=back
-
-=head1 CONFIGURATION FILE OPTIONS
-
-The section of the configuration file containing options for B<ca>
-is found as follows: If the B<-name> command line option is used,
-then it names the section to be used. Otherwise the section to
-be used must be named in the B<default_ca> option of the B<ca> section
-of the configuration file (or in the default section of the
-configuration file). Besides B<default_ca>, the following options are
-read directly from the B<ca> section:
- RANDFILE
- preserve
- msie_hack
-With the exception of B<RANDFILE>, this is probably a bug and may
-change in future releases.
-
-Many of the configuration file options are identical to command line
-options. Where the option is present in the configuration file
-and the command line the command line value is used. Where an
-option is described as mandatory then it must be present in
-the configuration file or the command line equivalent (if
-any) used.
-
-=over 4
-
-=item B<oid_file>
-
-This specifies a file containing additional B<OBJECT IDENTIFIERS>.
-Each line of the file should consist of the numerical form of the
-object identifier followed by white space then the short name followed
-by white space and finally the long name.
-
-=item B<oid_section>
-
-This specifies a section in the configuration file containing extra
-object identifiers. Each line should consist of the short name of the
-object identifier followed by B<=> and the numerical form. The short
-and long names are the same when this option is used.
-
-=item B<new_certs_dir>
-
-the same as the B<-outdir> command line option. It specifies
-the directory where new certificates will be placed. Mandatory.
-
-=item B<certificate>
-
-the same as B<-cert>. It gives the file containing the CA
-certificate. Mandatory.
-
-=item B<private_key>
-
-same as the B<-keyfile> option. The file containing the
-CA private key. Mandatory.
-
-=item B<RANDFILE>
-
-a file used to read and write random number seed information, or
-an EGD socket (see L<RAND_egd(3)>).
-
-=item B<default_days>
-
-the same as the B<-days> option. The number of days to certify
-a certificate for.
-
-=item B<default_startdate>
-
-the same as the B<-startdate> option. The start date to certify
-a certificate for. If not set the current time is used.
-
-=item B<default_enddate>
-
-the same as the B<-enddate> option. Either this option or
-B<default_days> (or the command line equivalents) must be
-present.
-
-=item B<default_crl_hours default_crl_days>
-
-the same as the B<-crlhours> and the B<-crldays> options. These
-will only be used if neither command line option is present. At
-least one of these must be present to generate a CRL.
-
-=item B<default_md>
-
-the same as the B<-md> option. Mandatory.
-
-=item B<database>
-
-the text database file to use. Mandatory. This file must be present
-though initially it will be empty.
-
-=item B<unique_subject>
-
-if the value B<yes> is given, the valid certificate entries in the
-database must have unique subjects. if the value B<no> is given,
-several valid certificate entries may have the exact same subject.
-The default value is B<yes>, to be compatible with older (pre 0.9.8)
-versions of OpenSSL. However, to make CA certificate roll-over easier,
-it's recommended to use the value B<no>, especially if combined with
-the B<-selfsign> command line option.
-
-=item B<serial>
-
-a text file containing the next serial number to use in hex. Mandatory.
-This file must be present and contain a valid serial number.
-
-=item B<crlnumber>
-
-a text file containing the next CRL number to use in hex. The crl number
-will be inserted in the CRLs only if this file exists. If this file is
-present, it must contain a valid CRL number.
-
-=item B<x509_extensions>
-
-the same as B<-extensions>.
-
-=item B<crl_extensions>
-
-the same as B<-crlexts>.
-
-=item B<preserve>
-
-the same as B<-preserveDN>
-
-=item B<email_in_dn>
-
-the same as B<-noemailDN>. If you want the EMAIL field to be removed
-from the DN of the certificate simply set this to 'no'. If not present
-the default is to allow for the EMAIL filed in the certificate's DN.
-
-=item B<msie_hack>
-
-the same as B<-msie_hack>
-
-=item B<policy>
-
-the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
-for more information.
-
-=item B<name_opt>, B<cert_opt>
-
-these options allow the format used to display the certificate details
-when asking the user to confirm signing. All the options supported by
-the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
-here, except the B<no_signame> and B<no_sigdump> are permanently set
-and cannot be disabled (this is because the certificate signature cannot
-be displayed because the certificate has not been signed at this point).
-
-For convenience the values B<ca_default> are accepted by both to produce
-a reasonable output.
-
-If neither option is present the format used in earlier versions of
-OpenSSL is used. Use of the old format is B<strongly> discouraged because
-it only displays fields mentioned in the B<policy> section, mishandles
-multicharacter string types and does not display extensions.
-
-=item B<copy_extensions>
-
-determines how extensions in certificate requests should be handled.
-If set to B<none> or this option is not present then extensions are
-ignored and not copied to the certificate. If set to B<copy> then any
-extensions present in the request that are not already present are copied
-to the certificate. If set to B<copyall> then all extensions in the
-request are copied to the certificate: if the extension is already present
-in the certificate it is deleted first. See the B<WARNINGS> section before
-using this option.
-
-The main use of this option is to allow a certificate request to supply
-values for certain extensions such as subjectAltName.
-
-=back
-
-=head1 POLICY FORMAT
-
-The policy section consists of a set of variables corresponding to
-certificate DN fields. If the value is "match" then the field value
-must match the same field in the CA certificate. If the value is
-"supplied" then it must be present. If the value is "optional" then
-it may be present. Any fields not mentioned in the policy section
-are silently deleted, unless the B<-preserveDN> option is set but
-this can be regarded more of a quirk than intended behaviour.
-
-=head1 SPKAC FORMAT
-
-The input to the B<-spkac> command line option is a Netscape
-signed public key and challenge. This will usually come from
-the B<KEYGEN> tag in an HTML form to create a new private key.
-It is however possible to create SPKACs using the B<spkac> utility.
-
-The file should contain the variable SPKAC set to the value of
-the SPKAC and also the required DN components as name value pairs.
-If you need to include the same component twice then it can be
-preceded by a number and a '.'.
-
-When processing SPKAC format, the output is DER if the B<-out>
-flag is used, but PEM format if sending to stdout or the B<-outdir>
-flag is used.
-
-=head1 EXAMPLES
-
-Note: these examples assume that the B<ca> directory structure is
-already set up and the relevant files already exist. This usually
-involves creating a CA certificate and private key with B<req>, a
-serial number file and an empty index file and placing them in
-the relevant directories.
-
-To use the sample configuration file below the directories demoCA,
-demoCA/private and demoCA/newcerts would be created. The CA
-certificate would be copied to demoCA/cacert.pem and its private
-key to demoCA/private/cakey.pem. A file demoCA/serial would be
-created containing for example "01" and the empty index file
-demoCA/index.txt.
-
-
-Sign a certificate request:
-
- openssl ca -in req.pem -out newcert.pem
-
-Sign a certificate request, using CA extensions:
-
- openssl ca -in req.pem -extensions v3_ca -out newcert.pem
-
-Generate a CRL
-
- openssl ca -gencrl -out crl.pem
-
-Sign several requests:
-
- openssl ca -infiles req1.pem req2.pem req3.pem
-
-Certify a Netscape SPKAC:
-
- openssl ca -spkac spkac.txt
-
-A sample SPKAC file (the SPKAC line has been truncated for clarity):
-
- SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
- CN=Steve Test
- emailAddress=steve@openssl.org
- 0.OU=OpenSSL Group
- 1.OU=Another Group
-
-A sample configuration file with the relevant sections for B<ca>:
-
- [ ca ]
- default_ca = CA_default # The default ca section
-
- [ CA_default ]
-
- dir = ./demoCA # top dir
- database = $dir/index.txt # index file.
- new_certs_dir = $dir/newcerts # new certs dir
-
- certificate = $dir/cacert.pem # The CA cert
- serial = $dir/serial # serial no file
- private_key = $dir/private/cakey.pem# CA private key
- RANDFILE = $dir/private/.rand # random number file
-
- default_days = 365 # how long to certify for
- default_crl_days= 30 # how long before next CRL
- default_md = md5 # md to use
-
- policy = policy_any # default policy
- email_in_dn = no # Don't add the email into cert DN
-
- name_opt = ca_default # Subject name display option
- cert_opt = ca_default # Certificate display option
- copy_extensions = none # Don't copy extensions from request
-
- [ policy_any ]
- countryName = supplied
- stateOrProvinceName = optional
- organizationName = optional
- organizationalUnitName = optional
- commonName = supplied
- emailAddress = optional
-
-=head1 FILES
-
-Note: the location of all files can change either by compile time options,
-configuration file entries, environment variables or command line options.
-The values below reflect the default values.
-
- /usr/local/ssl/lib/openssl.cnf - master configuration file
- ./demoCA - main CA directory
- ./demoCA/cacert.pem - CA certificate
- ./demoCA/private/cakey.pem - CA private key
- ./demoCA/serial - CA serial number file
- ./demoCA/serial.old - CA serial number backup file
- ./demoCA/index.txt - CA text database file
- ./demoCA/index.txt.old - CA text database backup file
- ./demoCA/certs - certificate output file
- ./demoCA/.rnd - CA random seed information
-
-=head1 ENVIRONMENT VARIABLES
-
-B<OPENSSL_CONF> reflects the location of master configuration file it can
-be overridden by the B<-config> command line option.
-
-=head1 RESTRICTIONS
-
-The text database index file is a critical part of the process and
-if corrupted it can be difficult to fix. It is theoretically possible
-to rebuild the index file from all the issued certificates and a current
-CRL: however there is no option to do this.
-
-V2 CRL features like delta CRLs are not currently supported.
-
-Although several requests can be input and handled at once it is only
-possible to include one SPKAC or self-signed certificate.
-
-=head1 BUGS
-
-The use of an in-memory text database can cause problems when large
-numbers of certificates are present because, as the name implies
-the database has to be kept in memory.
-
-The B<ca> command really needs rewriting or the required functionality
-exposed at either a command or interface level so a more friendly utility
-(perl script or GUI) can handle things properly. The script
-B<CA.pl> helps a little but not very much.
-
-Any fields in a request that are not present in a policy are silently
-deleted. This does not happen if the B<-preserveDN> option is used. To
-enforce the absence of the EMAIL field within the DN, as suggested by
-RFCs, regardless the contents of the request' subject the B<-noemailDN>
-option can be used. The behaviour should be more friendly and
-configurable.
-
-Canceling some commands by refusing to certify a certificate can
-create an empty file.
-
-=head1 WARNINGS
-
-The B<ca> command is quirky and at times downright unfriendly.
-
-The B<ca> utility was originally meant as an example of how to do things
-in a CA. It was not supposed to be used as a full blown CA itself:
-nevertheless some people are using it for this purpose.
-
-The B<ca> command is effectively a single user command: no locking is
-done on the various files and attempts to run more than one B<ca> command
-on the same database can have unpredictable results.
-
-The B<copy_extensions> option should be used with caution. If care is
-not taken then it can be a security risk. For example if a certificate
-request contains a basicConstraints extension with CA:TRUE and the
-B<copy_extensions> value is set to B<copyall> and the user does not spot
-this when the certificate is displayed then this will hand the requester
-a valid CA certificate.
-
-This situation can be avoided by setting B<copy_extensions> to B<copy>
-and including basicConstraints with CA:FALSE in the configuration file.
-Then if the request contains a basicConstraints extension it will be
-ignored.
-
-It is advisable to also include values for other extensions such
-as B<keyUsage> to prevent a request supplying its own values.
-
-Additional restrictions can be placed on the CA certificate itself.
-For example if the CA certificate has:
-
- basicConstraints = CA:TRUE, pathlen:0
-
-then even if a certificate is issued with CA:TRUE it will not be valid.
-
-=head1 SEE ALSO
-
-L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
-L<config(5)>, L<x509v3_config(5)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ciphers - SSL cipher display and cipher list tool
-
-=head1 SYNOPSIS
-
-B<openssl> B<ciphers>
-[B<-help>]
-[B<-s>]
-[B<-v>]
-[B<-V>]
-[B<-ssl3>]
-[B<-tls1>]
-[B<-tls1_1>]
-[B<-tls1_2>]
-[B<-s>]
-[B<-psk>]
-[B<-srp>]
-[B<-stdname>]
-[B<cipherlist>]
-
-=head1 DESCRIPTION
-
-The B<ciphers> command converts textual OpenSSL cipher lists into ordered
-SSL cipher preference lists. It can be used as a test tool to determine
-the appropriate cipherlist.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print a usage message.
-
-=item B<-s>
-
-Only list supported ciphers: those consistent with the security level, and
-minimum and maximum protocol version. This is closer to the actual cipher list
-an application will support.
-
-PSK and SRP ciphers are not enabled by default: they require B<-psk> or B<-srp>
-to enable them.
-
-It also does not change the default list of supported signature algorithms.
-
-On a server the list of supported ciphers might also exclude other ciphers
-depending on the configured certificates and presence of DH parameters.
-
-If this option is not used then all ciphers that match the cipherlist will be
-listed.
-
-=item B<-psk>
-
-When combined with B<-s> includes cipher suites which require PSK.
-
-=item B<-srp>
-
-When combined with B<-s> includes cipher suites which require SRP.
-
-=item B<-v>
-
-Verbose output: For each ciphersuite, list details as provided by
-L<SSL_CIPHER_description(3)>.
-
-=item B<-V>
-
-Like B<-v>, but include the official cipher suite values in hex.
-
-=item B<-tls1_2>
-
-In combination with the B<-s> option, list the ciphers which would be used if
-TLSv1.2 were negotiated.
-
-=item B<-ssl3>
-
-In combination with the B<-s> option, list the ciphers which would be used if
-SSLv3 were negotiated.
-
-=item B<-tls1>
-
-In combination with the B<-s> option, list the ciphers which would be used if
-TLSv1 were negotiated.
-
-=item B<-tls1_1>
-
-In combination with the B<-s> option, list the ciphers which would be used if
-TLSv1.1 were negotiated.
-
-=item B<-stdname>
-
-precede each ciphersuite by its standard name: only available is OpenSSL
-is built with tracing enabled (B<enable-ssl-trace> argument to Configure).
-
-=item B<cipherlist>
-
-a cipher list to convert to a cipher preference list. If it is not included
-then the default cipher list will be used. The format is described below.
-
-=back
-
-=head1 CIPHER LIST FORMAT
-
-The cipher list consists of one or more I<cipher strings> separated by colons.
-Commas or spaces are also acceptable separators but colons are normally used.
-
-The actual cipher string can take several different forms.
-
-It can consist of a single cipher suite such as B<RC4-SHA>.
-
-It can represent a list of cipher suites containing a certain algorithm, or
-cipher suites of a certain type. For example B<SHA1> represents all ciphers
-suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3
-algorithms.
-
-Lists of cipher suites can be combined in a single cipher string using the
-B<+> character. This is used as a logical B<and> operation. For example
-B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES
-algorithms.
-
-Each cipher string can be optionally preceded by the characters B<!>,
-B<-> or B<+>.
-
-If B<!> is used then the ciphers are permanently deleted from the list.
-The ciphers deleted can never reappear in the list even if they are
-explicitly stated.
-
-If B<-> is used then the ciphers are deleted from the list, but some or
-all of the ciphers can be added again by later options.
-
-If B<+> is used then the ciphers are moved to the end of the list. This
-option doesn't add any new ciphers it just moves matching existing ones.
-
-If none of these characters is present then the string is just interpreted
-as a list of ciphers to be appended to the current preference list. If the
-list includes any ciphers already present they will be ignored: that is they
-will not moved to the end of the list.
-
-The cipher string B<@STRENGTH> can be used at any point to sort the current
-cipher list in order of encryption algorithm key length.
-
-The cipher string B<@SECLEVEL=n> can be used at any point to set the security
-level to B<n>.
-
-=head1 CIPHER STRINGS
-
-The following is a list of all permitted cipher strings and their meanings.
-
-=over 4
-
-=item B<DEFAULT>
-
-The default cipher list.
-This is determined at compile time and is normally
-B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>.
-When used, this must be the first cipherstring specified.
-
-=item B<COMPLEMENTOFDEFAULT>
-
-The ciphers included in B<ALL>, but not enabled by default. Currently
-this includes all RC4 and anonymous ciphers. Note that this rule does
-not cover B<eNULL>, which is not included by B<ALL> (use B<COMPLEMENTOFALL> if
-necessary). Note that RC4 based ciphersuites are not built into OpenSSL by
-default (see the enable-weak-ssl-ciphers option to Configure).
-
-=item B<ALL>
-
-All cipher suites except the B<eNULL> ciphers (which must be explicitly enabled
-if needed).
-As of OpenSSL 1.0.0, the B<ALL> cipher suites are sensibly ordered by default.
-
-=item B<COMPLEMENTOFALL>
-
-The cipher suites not enabled by B<ALL>, currently B<eNULL>.
-
-=item B<HIGH>
-
-"high" encryption cipher suites. This currently means those with key lengths
-larger than 128 bits, and some cipher suites with 128-bit keys.
-
-=item B<MEDIUM>
-
-"medium" encryption cipher suites, currently some of those using 128 bit
-encryption.
-
-=item B<LOW>
-
-"low" encryption cipher suites, currently those using 64 or 56 bit
-encryption algorithms but excluding export cipher suites. All these
-ciphersuites have been removed as of OpenSSL 1.1.0.
-
-=item B<eNULL>, B<NULL>
-
-The "NULL" ciphers that is those offering no encryption. Because these offer no
-encryption at all and are a security risk they are not enabled via either the
-B<DEFAULT> or B<ALL> cipher strings.
-Be careful when building cipherlists out of lower-level primitives such as
-B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers. When in
-doubt, include B<!eNULL> in your cipherlist.
-
-=item B<aNULL>
-
-The cipher suites offering no authentication. This is currently the anonymous
-DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable
-to "man in the middle" attacks and so their use is discouraged.
-These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL>
-ciphers.
-Be careful when building cipherlists out of lower-level primitives such as
-B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers.
-When in doubt, include B<!aNULL> in your cipherlist.
-
-=item B<kRSA>, B<aRSA>, B<RSA>
-
-Cipher suites using RSA key exchange, authentication or either respectively.
-
-=item B<kDHr>, B<kDHd>, B<kDH>
-
-Cipher suites using static DH key agreement and DH certificates signed by CAs
-with RSA and DSS keys or either respectively.
-All these cipher suites have been removed in OpenSSL 1.1.0.
-
-=item B<kDHE>, B<kEDH>, B<DH>
-
-Cipher suites using ephemeral DH key agreement, including anonymous cipher
-suites.
-
-=item B<DHE>, B<EDH>
-
-Cipher suites using authenticated ephemeral DH key agreement.
-
-=item B<ADH>
-
-Anonymous DH cipher suites, note that this does not include anonymous Elliptic
-Curve DH (ECDH) cipher suites.
-
-=item B<kEECDH>, B<kECDHE>, B<ECDH>
-
-Cipher suites using ephemeral ECDH key agreement, including anonymous
-cipher suites.
-
-=item B<ECDHE>, B<EECDH>
-
-Cipher suites using authenticated ephemeral ECDH key agreement.
-
-=item B<AECDH>
-
-Anonymous Elliptic Curve Diffie-Hellman cipher suites.
-
-=item B<aDSS>, B<DSS>
-
-Cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
-
-=item B<aDH>
-
-Cipher suites effectively using DH authentication, i.e. the certificates carry
-DH keys.
-All these cipher suites have been removed in OpenSSL 1.1.0.
-
-=item B<aECDSA>, B<ECDSA>
-
-Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
-keys.
-
-=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3>
-
-Lists ciphersuites which are only supported in at least TLS v1.2, TLS v1.0 or
-SSL v3.0 respectively.
-Note: there are no ciphersuites specific to TLS v1.1.
-Since this is only the minimum version, if, for example, TLSv1.0 is negotiated
-then both TLSv1.0 and SSLv3.0 ciphersuites are available.
-
-Note: these cipher strings B<do not> change the negotiated version of SSL or
-TLS, they only affect the list of available cipher suites.
-
-=item B<AES128>, B<AES256>, B<AES>
-
-cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
-
-=item B<AESGCM>
-
-AES in Galois Counter Mode (GCM): these ciphersuites are only supported
-in TLS v1.2.
-
-=item B<AESCCM>, B<AESCCM8>
-
-AES in Cipher Block Chaining - Message Authentication Mode (CCM): these
-ciphersuites are only supported in TLS v1.2. B<AESCCM> references CCM
-cipher suites using both 16 and 8 octet Integrity Check Value (ICV)
-while B<AESCCM8> only references 8 octet ICV.
-
-=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
-
-cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
-CAMELLIA.
-
-=item B<CHACHA20>
-
-cipher suites using ChaCha20.
-
-=item B<3DES>
-
-cipher suites using triple DES.
-
-=item B<DES>
-
-Cipher suites using DES (not triple DES).
-All these cipher suites have been removed in OpenSSL 1.1.0.
-
-=item B<RC4>
-
-Cipher suites using RC4.
-
-=item B<RC2>
-
-Cipher suites using RC2.
-
-=item B<IDEA>
-
-Cipher suites using IDEA.
-
-=item B<SEED>
-
-Cipher suites using SEED.
-
-=item B<MD5>
-
-Cipher suites using MD5.
-
-=item B<SHA1>, B<SHA>
-
-Cipher suites using SHA1.
-
-=item B<SHA256>, B<SHA384>
-
-Ciphersuites using SHA256 or SHA384.
-
-=item B<aGOST>
-
-Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication
-(needs an engine supporting GOST algorithms).
-
-=item B<aGOST01>
-
-Cipher suites using GOST R 34.10-2001 authentication.
-
-=item B<kGOST>
-
-Cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
-
-=item B<GOST94>
-
-Cipher suites, using HMAC based on GOST R 34.11-94.
-
-=item B<GOST89MAC>
-
-Cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
-
-=item B<PSK>
-
-All cipher suites using pre-shared keys (PSK).
-
-=item B<kPSK>, B<kECDHEPSK>, B<kDHEPSK>, B<kRSAPSK>
-
-Cipher suites using PSK key exchange, ECDHE_PSK, DHE_PSK or RSA_PSK.
-
-=item B<aPSK>
-
-Cipher suites using PSK authentication (currently all PSK modes apart from
-RSA_PSK).
-
-=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
-
-Enables suite B mode of operation using 128 (permitting 192 bit mode by peer)
-128 bit (not permitting 192 bit by peer) or 192 bit level of security
-respectively.
-If used these cipherstrings should appear first in the cipher
-list and anything after them is ignored.
-Setting Suite B mode has additional consequences required to comply with
-RFC6460.
-In particular the supported signature algorithms is reduced to support only
-ECDSA and SHA256 or SHA384, only the elliptic curves P-256 and P-384 can be
-used and only the two suite B compliant ciphersuites
-(ECDHE-ECDSA-AES128-GCM-SHA256 and ECDHE-ECDSA-AES256-GCM-SHA384) are
-permissible.
-
-=back
-
-=head1 CIPHER SUITE NAMES
-
-The following lists give the SSL or TLS cipher suites names from the
-relevant specification and their OpenSSL equivalents. It should be noted,
-that several cipher suite names do not include the authentication used,
-e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
-
-=head2 SSL v3.0 cipher suites
-
- SSL_RSA_WITH_NULL_MD5 NULL-MD5
- SSL_RSA_WITH_NULL_SHA NULL-SHA
- SSL_RSA_WITH_RC4_128_MD5 RC4-MD5
- SSL_RSA_WITH_RC4_128_SHA RC4-SHA
- SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
- SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
-
- SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA
- SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA
- SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
- SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
-
- SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
- SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
-
- SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented.
- SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented.
- SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented.
-
-=head2 TLS v1.0 cipher suites
-
- TLS_RSA_WITH_NULL_MD5 NULL-MD5
- TLS_RSA_WITH_NULL_SHA NULL-SHA
- TLS_RSA_WITH_RC4_128_MD5 RC4-MD5
- TLS_RSA_WITH_RC4_128_SHA RC4-SHA
- TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
- TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
-
- TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
- TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
- TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
- TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
-
- TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
- TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
-
-=head2 AES ciphersuites from RFC3268, extending TLS v1.0
-
- TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA
- TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA
-
- TLS_DH_DSS_WITH_AES_128_CBC_SHA DH-DSS-AES128-SHA
- TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA
- TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA
- TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA
-
- TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA
- TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE-RSA-AES128-SHA
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA
-
- TLS_DH_anon_WITH_AES_128_CBC_SHA ADH-AES128-SHA
- TLS_DH_anon_WITH_AES_256_CBC_SHA ADH-AES256-SHA
-
-=head2 Camellia ciphersuites from RFC4132, extending TLS v1.0
-
- TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA
- TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA
-
- TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA DH-DSS-CAMELLIA128-SHA
- TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA DH-DSS-CAMELLIA256-SHA
- TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA DH-RSA-CAMELLIA128-SHA
- TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA DH-RSA-CAMELLIA256-SHA
-
- TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA
- TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA
- TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA DHE-RSA-CAMELLIA128-SHA
- TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA DHE-RSA-CAMELLIA256-SHA
-
- TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA ADH-CAMELLIA128-SHA
- TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA ADH-CAMELLIA256-SHA
-
-=head2 SEED ciphersuites from RFC4162, extending TLS v1.0
-
- TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA
-
- TLS_DH_DSS_WITH_SEED_CBC_SHA DH-DSS-SEED-SHA
- TLS_DH_RSA_WITH_SEED_CBC_SHA DH-RSA-SEED-SHA
-
- TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA
- TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA
-
- TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA
-
-=head2 GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0
-
-Note: these ciphers require an engine which including GOST cryptographic
-algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
-
- TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89
- TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89
- TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94
- TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94
-
-=head2 Additional Export 1024 and other cipher suites
-
-Note: these ciphers can also be used in SSL v3.
-
- TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA
-
-=head2 Elliptic curve cipher suites.
-
- TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA
- TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA
- TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA
-
- TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA
- TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA
- TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA
-
- TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA
- TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA
- TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA
- TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA
- TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA
-
-=head2 TLS v1.2 cipher suites
-
- TLS_RSA_WITH_NULL_SHA256 NULL-SHA256
-
- TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256
- TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256
- TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384
-
- TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH-RSA-AES128-SHA256
- TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH-RSA-AES256-SHA256
- TLS_DH_RSA_WITH_AES_128_GCM_SHA256 DH-RSA-AES128-GCM-SHA256
- TLS_DH_RSA_WITH_AES_256_GCM_SHA384 DH-RSA-AES256-GCM-SHA384
-
- TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH-DSS-AES128-SHA256
- TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH-DSS-AES256-SHA256
- TLS_DH_DSS_WITH_AES_128_GCM_SHA256 DH-DSS-AES128-GCM-SHA256
- TLS_DH_DSS_WITH_AES_256_GCM_SHA384 DH-DSS-AES256-GCM-SHA384
-
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE-RSA-AES128-SHA256
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE-RSA-AES256-SHA256
- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE-RSA-AES128-GCM-SHA256
- TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE-RSA-AES256-GCM-SHA384
-
- TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE-DSS-AES128-SHA256
- TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE-DSS-AES256-SHA256
- TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256
- TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384
-
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384
-
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384
-
- TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256
- TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256
- TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256
- TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384
-
- RSA_WITH_AES_128_CCM AES128-CCM
- RSA_WITH_AES_256_CCM AES256-CCM
- DHE_RSA_WITH_AES_128_CCM DHE-RSA-AES128-CCM
- DHE_RSA_WITH_AES_256_CCM DHE-RSA-AES256-CCM
- RSA_WITH_AES_128_CCM_8 AES128-CCM8
- RSA_WITH_AES_256_CCM_8 AES256-CCM8
- DHE_RSA_WITH_AES_128_CCM_8 DHE-RSA-AES128-CCM8
- DHE_RSA_WITH_AES_256_CCM_8 DHE-RSA-AES256-CCM8
- ECDHE_ECDSA_WITH_AES_128_CCM ECDHE-ECDSA-AES128-CCM
- ECDHE_ECDSA_WITH_AES_256_CCM ECDHE-ECDSA-AES256-CCM
- ECDHE_ECDSA_WITH_AES_128_CCM_8 ECDHE-ECDSA-AES128-CCM8
- ECDHE_ECDSA_WITH_AES_256_CCM_8 ECDHE-ECDSA-AES256-CCM8
-
-=head2 Camellia HMAC-Based ciphersuites from RFC6367, extending TLS v1.2
-
- TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256
- TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384
- TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-RSA-CAMELLIA128-SHA256
- TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-RSA-CAMELLIA256-SHA384
-
-=head2 Pre-shared keying (PSK) ciphersuites
-
- PSK_WITH_NULL_SHA PSK-NULL-SHA
- DHE_PSK_WITH_NULL_SHA DHE-PSK-NULL-SHA
- RSA_PSK_WITH_NULL_SHA RSA-PSK-NULL-SHA
-
- PSK_WITH_RC4_128_SHA PSK-RC4-SHA
- PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
- PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
- PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
-
- DHE_PSK_WITH_RC4_128_SHA DHE-PSK-RC4-SHA
- DHE_PSK_WITH_3DES_EDE_CBC_SHA DHE-PSK-3DES-EDE-CBC-SHA
- DHE_PSK_WITH_AES_128_CBC_SHA DHE-PSK-AES128-CBC-SHA
- DHE_PSK_WITH_AES_256_CBC_SHA DHE-PSK-AES256-CBC-SHA
-
- RSA_PSK_WITH_RC4_128_SHA RSA-PSK-RC4-SHA
- RSA_PSK_WITH_3DES_EDE_CBC_SHA RSA-PSK-3DES-EDE-CBC-SHA
- RSA_PSK_WITH_AES_128_CBC_SHA RSA-PSK-AES128-CBC-SHA
- RSA_PSK_WITH_AES_256_CBC_SHA RSA-PSK-AES256-CBC-SHA
-
- PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
- PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
- DHE_PSK_WITH_AES_128_GCM_SHA256 DHE-PSK-AES128-GCM-SHA256
- DHE_PSK_WITH_AES_256_GCM_SHA384 DHE-PSK-AES256-GCM-SHA384
- RSA_PSK_WITH_AES_128_GCM_SHA256 RSA-PSK-AES128-GCM-SHA256
- RSA_PSK_WITH_AES_256_GCM_SHA384 RSA-PSK-AES256-GCM-SHA384
-
- PSK_WITH_AES_128_CBC_SHA256 PSK-AES128-CBC-SHA256
- PSK_WITH_AES_256_CBC_SHA384 PSK-AES256-CBC-SHA384
- PSK_WITH_NULL_SHA256 PSK-NULL-SHA256
- PSK_WITH_NULL_SHA384 PSK-NULL-SHA384
- DHE_PSK_WITH_AES_128_CBC_SHA256 DHE-PSK-AES128-CBC-SHA256
- DHE_PSK_WITH_AES_256_CBC_SHA384 DHE-PSK-AES256-CBC-SHA384
- DHE_PSK_WITH_NULL_SHA256 DHE-PSK-NULL-SHA256
- DHE_PSK_WITH_NULL_SHA384 DHE-PSK-NULL-SHA384
- RSA_PSK_WITH_AES_128_CBC_SHA256 RSA-PSK-AES128-CBC-SHA256
- RSA_PSK_WITH_AES_256_CBC_SHA384 RSA-PSK-AES256-CBC-SHA384
- RSA_PSK_WITH_NULL_SHA256 RSA-PSK-NULL-SHA256
- RSA_PSK_WITH_NULL_SHA384 RSA-PSK-NULL-SHA384
- PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
- PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
-
- ECDHE_PSK_WITH_RC4_128_SHA ECDHE-PSK-RC4-SHA
- ECDHE_PSK_WITH_3DES_EDE_CBC_SHA ECDHE-PSK-3DES-EDE-CBC-SHA
- ECDHE_PSK_WITH_AES_128_CBC_SHA ECDHE-PSK-AES128-CBC-SHA
- ECDHE_PSK_WITH_AES_256_CBC_SHA ECDHE-PSK-AES256-CBC-SHA
- ECDHE_PSK_WITH_AES_128_CBC_SHA256 ECDHE-PSK-AES128-CBC-SHA256
- ECDHE_PSK_WITH_AES_256_CBC_SHA384 ECDHE-PSK-AES256-CBC-SHA384
- ECDHE_PSK_WITH_NULL_SHA ECDHE-PSK-NULL-SHA
- ECDHE_PSK_WITH_NULL_SHA256 ECDHE-PSK-NULL-SHA256
- ECDHE_PSK_WITH_NULL_SHA384 ECDHE-PSK-NULL-SHA384
-
- PSK_WITH_CAMELLIA_128_CBC_SHA256 PSK-CAMELLIA128-SHA256
- PSK_WITH_CAMELLIA_256_CBC_SHA384 PSK-CAMELLIA256-SHA384
-
- DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 DHE-PSK-CAMELLIA128-SHA256
- DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 DHE-PSK-CAMELLIA256-SHA384
-
- RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 RSA-PSK-CAMELLIA128-SHA256
- RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 RSA-PSK-CAMELLIA256-SHA384
-
- ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-PSK-CAMELLIA128-SHA256
- ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-PSK-CAMELLIA256-SHA384
-
- PSK_WITH_AES_128_CCM PSK-AES128-CCM
- PSK_WITH_AES_256_CCM PSK-AES256-CCM
- DHE_PSK_WITH_AES_128_CCM DHE-PSK-AES128-CCM
- DHE_PSK_WITH_AES_256_CCM DHE-PSK-AES256-CCM
- PSK_WITH_AES_128_CCM_8 PSK-AES128-CCM8
- PSK_WITH_AES_256_CCM_8 PSK-AES256-CCM8
- DHE_PSK_WITH_AES_128_CCM_8 DHE-PSK-AES128-CCM8
- DHE_PSK_WITH_AES_256_CCM_8 DHE-PSK-AES256-CCM8
-
-=head2 ChaCha20-Poly1305 cipher suites, extending TLS v1.2
-
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-RSA-CHACHA20-POLY1305
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-ECDSA-CHACHA20-POLY1305
- TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 DHE-RSA-CHACHA20-POLY1305
- TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 PSK-CHACHA20-POLY1305
- TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 ECDHE-PSK-CHACHA20-POLY1305
- TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 DHE-PSK-CHACHA20-POLY1305
- TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 RSA-PSK-CHACHA20-POLY1305
-
-=head2 Older names used by OpenSSL
-
-The following names are accepted by older releases:
-
- SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA)
- SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA)
-
-=head1 NOTES
-
-Some compiled versions of OpenSSL may not include all the ciphers
-listed here because some ciphers were excluded at compile time.
-
-=head1 EXAMPLES
-
-Verbose listing of all OpenSSL ciphers including NULL ciphers:
-
- openssl ciphers -v 'ALL:eNULL'
-
-Include all ciphers except NULL and anonymous DH then sort by
-strength:
-
- openssl ciphers -v 'ALL:!ADH:@STRENGTH'
-
-Include all ciphers except ones with no encryption (eNULL) or no
-authentication (aNULL):
-
- openssl ciphers -v 'ALL:!aNULL'
-
-Include only 3DES ciphers and then place RSA ciphers last:
-
- openssl ciphers -v '3DES:+RSA'
-
-Include all RC4 ciphers but leave out those without authentication:
-
- openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
-
-Include all ciphers with RSA authentication but leave out ciphers without
-encryption.
-
- openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
-
-Set security level to 2 and display all ciphers consistent with level 2:
-
- openssl ciphers -s -v 'ALL:@SECLEVEL=2'
-
-=head1 SEE ALSO
-
-L<s_client(1)>, L<s_server(1)>, L<ssl(3)>
-
-=head1 HISTORY
-
-The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-cms - CMS utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<cms>
-[B<-help>]
-[B<-encrypt>]
-[B<-decrypt>]
-[B<-sign>]
-[B<-verify>]
-[B<-cmsout>]
-[B<-resign>]
-[B<-data_create>]
-[B<-data_out>]
-[B<-digest_create>]
-[B<-digest_verify>]
-[B<-compress>]
-[B<-uncompress>]
-[B<-EncryptedData_encrypt>]
-[B<-sign_receipt>]
-[B<-verify_receipt receipt>]
-[B<-in filename>]
-[B<-inform SMIME|PEM|DER>]
-[B<-rctform SMIME|PEM|DER>]
-[B<-out filename>]
-[B<-outform SMIME|PEM|DER>]
-[B<-stream -indef -noindef>]
-[B<-noindef>]
-[B<-content filename>]
-[B<-text>]
-[B<-noout>]
-[B<-print>]
-[B<-CAfile file>]
-[B<-CApath dir>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-attime timestamp>]
-[B<-check_ss_sig>]
-[B<-crl_check>]
-[B<-crl_check_all>]
-[B<-explicit_policy>]
-[B<-extended_crl>]
-[B<-ignore_critical>]
-[B<-inhibit_any>]
-[B<-inhibit_map>]
-[B<-no_check_time>]
-[B<-partial_chain>]
-[B<-policy arg>]
-[B<-policy_check>]
-[B<-policy_print>]
-[B<-purpose purpose>]
-[B<-suiteB_128>]
-[B<-suiteB_128_only>]
-[B<-suiteB_192>]
-[B<-trusted_first>]
-[B<-no_alt_chains>]
-[B<-use_deltas>]
-[B<-auth_level num>]
-[B<-verify_depth num>]
-[B<-verify_email email>]
-[B<-verify_hostname hostname>]
-[B<-verify_ip ip>]
-[B<-verify_name name>]
-[B<-x509_strict>]
-[B<-md digest>]
-[B<-[cipher]>]
-[B<-nointern>]
-[B<-no_signer_cert_verify>]
-[B<-nocerts>]
-[B<-noattr>]
-[B<-nosmimecap>]
-[B<-binary>]
-[B<-crlfeol>]
-[B<-asciicrlf>]
-[B<-nodetach>]
-[B<-certfile file>]
-[B<-certsout file>]
-[B<-signer file>]
-[B<-recip file>]
-[B<-keyid>]
-[B<-receipt_request_all -receipt_request_first>]
-[B<-receipt_request_from emailaddress>]
-[B<-receipt_request_to emailaddress>]
-[B<-receipt_request_print>]
-[B<-secretkey key>]
-[B<-secretkeyid id>]
-[B<-econtent_type type>]
-[B<-inkey file>]
-[B<-keyopt name:parameter>]
-[B<-passin arg>]
-[B<-rand file(s)>]
-[B<cert.pem...>]
-[B<-to addr>]
-[B<-from addr>]
-[B<-subject subj>]
-[cert.pem]...
-
-=head1 DESCRIPTION
-
-The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
-verify, compress and uncompress S/MIME messages.
-
-=head1 COMMAND OPTIONS
-
-There are fourteen operation options that set the type of operation to be
-performed. The meaning of the other options varies according to the operation
-type.
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-encrypt>
-
-encrypt mail for the given recipient certificates. Input file is the message
-to be encrypted. The output file is the encrypted mail in MIME format. The
-actual CMS type is <B>EnvelopedData<B>.
-
-Note that no revocation check is done for the recipient cert, so if that
-key has been compromised, others may be able to decrypt the text.
-
-=item B<-decrypt>
-
-decrypt mail using the supplied certificate and private key. Expects an
-encrypted mail message in MIME format for the input file. The decrypted mail
-is written to the output file.
-
-=item B<-debug_decrypt>
-
-this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used
-with caution: see the notes section below.
-
-=item B<-sign>
-
-sign mail using the supplied certificate and private key. Input file is
-the message to be signed. The signed message in MIME format is written
-to the output file.
-
-=item B<-verify>
-
-verify signed mail. Expects a signed mail message on input and outputs
-the signed data. Both clear text and opaque signing is supported.
-
-=item B<-cmsout>
-
-takes an input message and writes out a PEM encoded CMS structure.
-
-=item B<-resign>
-
-resign a message: take an existing message and one or more new signers.
-
-=item B<-data_create>
-
-Create a CMS B<Data> type.
-
-=item B<-data_out>
-
-B<Data> type and output the content.
-
-=item B<-digest_create>
-
-Create a CMS B<DigestedData> type.
-
-=item B<-digest_verify>
-
-Verify a CMS B<DigestedData> type and output the content.
-
-=item B<-compress>
-
-Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib>
-support for this option to work, otherwise it will output an error.
-
-=item B<-uncompress>
-
-Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be
-compiled with B<zlib> support for this option to work, otherwise it will
-output an error.
-
-=item B<-EncryptedData_encrypt>
-
-Encrypt content using supplied symmetric key and algorithm using a CMS
-B<EncrytedData> type and output the content.
-
-=item B<-sign_receipt>
-
-Generate and output a signed receipt for the supplied message. The input
-message B<must> contain a signed receipt request. Functionality is otherwise
-similar to the B<-sign> operation.
-
-=item B<-verify_receipt receipt>
-
-Verify a signed receipt in filename B<receipt>. The input message B<must>
-contain the original receipt request. Functionality is otherwise similar
-to the B<-verify> operation.
-
-=item B<-in filename>
-
-the input message to be encrypted or signed or the message to be decrypted
-or verified.
-
-=item B<-inform SMIME|PEM|DER>
-
-this specifies the input format for the CMS structure. The default
-is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
-format change this to expect PEM and DER format CMS structures
-instead. This currently only affects the input format of the CMS
-structure, if no CMS structure is being input (for example with
-B<-encrypt> or B<-sign>) this option has no effect.
-
-=item B<-rctform SMIME|PEM|DER>
-
-specify the format for a signed receipt for use with the B<-receipt_verify>
-operation.
-
-=item B<-out filename>
-
-the message text that has been decrypted or verified or the output MIME
-format message that has been signed or verified.
-
-=item B<-outform SMIME|PEM|DER>
-
-this specifies the output format for the CMS structure. The default
-is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER>
-format change this to write PEM and DER format CMS structures
-instead. This currently only affects the output format of the CMS
-structure, if no CMS structure is being output (for example with
-B<-verify> or B<-decrypt>) this option has no effect.
-
-=item B<-stream -indef -noindef>
-
-the B<-stream> and B<-indef> options are equivalent and enable streaming I/O
-for encoding operations. This permits single pass processing of data without
-the need to hold the entire contents in memory, potentially supporting very
-large files. Streaming is automatically set for S/MIME signing with detached
-data if the output format is B<SMIME> it is currently off by default for all
-other operations.
-
-=item B<-noindef>
-
-disable streaming I/O where it would produce and indefinite length constructed
-encoding. This option currently has no effect. In future streaming will be
-enabled by default on all relevant operations and this option will disable it.
-
-=item B<-content filename>
-
-This specifies a file containing the detached content, this is only
-useful with the B<-verify> command. This is only usable if the CMS
-structure is using the detached signature form where the content is
-not included. This option will override any content if the input format
-is S/MIME and it uses the multipart/signed MIME content type.
-
-=item B<-text>
-
-this option adds plain text (text/plain) MIME headers to the supplied
-message if encrypting or signing. If decrypting or verifying it strips
-off text headers: if the decrypted or verified message is not of MIME
-type text/plain then an error occurs.
-
-=item B<-noout>
-
-for the B<-cmsout> operation do not output the parsed CMS structure. This
-is useful when combined with the B<-print> option or if the syntax of the CMS
-structure is being checked.
-
-=item B<-print>
-
-for the B<-cmsout> operation print out all fields of the CMS structure. This
-is mainly useful for testing purposes.
-
-=item B<-CAfile file>
-
-a file containing trusted CA certificates, only used with B<-verify>.
-
-=item B<-CApath dir>
-
-a directory containing trusted CA certificates, only used with
-B<-verify>. This directory must be a standard certificate directory: that
-is a hash of each subject name (using B<x509 -hash>) should be linked
-to each certificate.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-md digest>
-
-digest algorithm to use when signing or resigning. If not present then the
-default digest algorithm for the signing key will be used (usually SHA1).
-
-=item B<-[cipher]>
-
-the encryption algorithm to use. For example triple DES (168 bits) - B<-des3>
-or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
-EVP_get_cipherbyname() function) can also be used preceded by a dash, for
-example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for a list of ciphers
-supported by your version of OpenSSL.
-
-If not specified triple DES is used. Only used with B<-encrypt> and
-B<-EncryptedData_create> commands.
-
-=item B<-nointern>
-
-when verifying a message normally certificates (if any) included in
-the message are searched for the signing certificate. With this option
-only the certificates specified in the B<-certfile> option are used.
-The supplied certificates can still be used as untrusted CAs however.
-
-=item B<-no_signer_cert_verify>
-
-do not verify the signers certificate of a signed message.
-
-=item B<-nocerts>
-
-when signing a message the signer's certificate is normally included
-with this option it is excluded. This will reduce the size of the
-signed message but the verifier must have a copy of the signers certificate
-available locally (passed using the B<-certfile> option for example).
-
-=item B<-noattr>
-
-normally when a message is signed a set of attributes are included which
-include the signing time and supported symmetric algorithms. With this
-option they are not included.
-
-=item B<-nosmimecap>
-
-exclude the list of supported algorithms from signed attributes, other options
-such as signing time and content type are still included.
-
-=item B<-binary>
-
-normally the input message is converted to "canonical" format which is
-effectively using CR and LF as end of line: as required by the S/MIME
-specification. When this option is present no translation occurs. This
-is useful when handling binary data which may not be in MIME format.
-
-=item B<-crlfeol>
-
-normally the output file uses a single B<LF> as end of line. When this
-option is present B<CRLF> is used instead.
-
-=item B<-asciicrlf>
-
-when signing use ASCII CRLF format canonicalisation. This strips trailing
-whitespace from all lines, deletes trailing blank lines at EOF and sets
-the encapsulated content type. This option is normally used with detached
-content and an output signature format of DER. This option is not normally
-needed when verifying as it is enabled automatically if the encapsulated
-content format is detected.
-
-=item B<-nodetach>
-
-when signing a message use opaque signing: this form is more resistant
-to translation by mail relays but it cannot be read by mail agents that
-do not support S/MIME. Without this option cleartext signing with
-the MIME type multipart/signed is used.
-
-=item B<-certfile file>
-
-allows additional certificates to be specified. When signing these will
-be included with the message. When verifying these will be searched for
-the signers certificates. The certificates should be in PEM format.
-
-=item B<-certsout file>
-
-any certificates contained in the message are written to B<file>.
-
-=item B<-signer file>
-
-a signing certificate when signing or resigning a message, this option can be
-used multiple times if more than one signer is required. If a message is being
-verified then the signers certificates will be written to this file if the
-verification was successful.
-
-=item B<-recip file>
-
-when decrypting a message this specifies the recipients certificate. The
-certificate must match one of the recipients of the message or an error
-occurs.
-
-When encrypting a message this option may be used multiple times to specify
-each recipient. This form B<must> be used if customised parameters are
-required (for example to specify RSA-OAEP).
-
-=item B<-keyid>
-
-use subject key identifier to identify certificates instead of issuer name and
-serial number. The supplied certificate B<must> include a subject key
-identifier extension. Supported by B<-sign> and B<-encrypt> options.
-
-=item B<-receipt_request_all -receipt_request_first>
-
-for B<-sign> option include a signed receipt request. Indicate requests should
-be provided by all recipient or first tier recipients (those mailed directly
-and not from a mailing list). Ignored it B<-receipt_request_from> is included.
-
-=item B<-receipt_request_from emailaddress>
-
-for B<-sign> option include a signed receipt request. Add an explicit email
-address where receipts should be supplied.
-
-=item B<-receipt_request_to emailaddress>
-
-Add an explicit email address where signed receipts should be sent to. This
-option B<must> but supplied if a signed receipt it requested.
-
-=item B<-receipt_request_print>
-
-For the B<-verify> operation print out the contents of any signed receipt
-requests.
-
-=item B<-secretkey key>
-
-specify symmetric key to use. The key must be supplied in hex format and be
-consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
-B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
-with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
-content encryption key using an AES key in the B<KEKRecipientInfo> type.
-
-=item B<-secretkeyid id>
-
-the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type.
-This option B<must> be present if the B<-secretkey> option is used with
-B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the
-relevant key if it is not supplied then an attempt is used to decrypt any
-B<KEKRecipientInfo> structures.
-
-=item B<-econtent_type type>
-
-set the encapsulated content type to B<type> if not supplied the B<Data> type
-is used. The B<type> argument can be any valid OID name in either text or
-numerical format.
-
-=item B<-inkey file>
-
-the private key to use when signing or decrypting. This must match the
-corresponding certificate. If this option is not specified then the
-private key must be included in the certificate file specified with
-the B<-recip> or B<-signer> file. When signing this option can be used
-multiple times to specify successive keys.
-
-=item B<-keyopt name:opt>
-
-for signing and encryption this option can be used multiple times to
-set customised parameters for the preceding key or certificate. It can
-currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
-or to modify default parameters for ECDH.
-
-=item B<-passin arg>
-
-the private key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<cert.pem...>
-
-one or more certificates of message recipients: used when encrypting
-a message.
-
-=item B<-to, -from, -subject>
-
-the relevant mail headers. These are included outside the signed
-portion of a message so they may be included manually. If signing
-then many S/MIME mail clients check the signers certificate's email
-address matches that specified in the From: address.
-
-=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
-B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
-B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
-B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
-B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
-B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
-B<-verify_ip>, B<-verify_name>, B<-x509_strict>
-
-Set various certificate chain validation options. See the
-L<verify(1)> manual page for details.
-
-=back
-
-=head1 NOTES
-
-The MIME message must be sent without any blank lines between the
-headers and the output. Some mail programs will automatically add
-a blank line. Piping the mail directly to sendmail is one way to
-achieve the correct format.
-
-The supplied message to be signed or encrypted must include the
-necessary MIME headers or many S/MIME clients won't display it
-properly (if at all). You can use the B<-text> option to automatically
-add plain text headers.
-
-A "signed and encrypted" message is one where a signed message is
-then encrypted. This can be produced by encrypting an already signed
-message: see the examples section.
-
-This version of the program only allows one signer per message but it
-will verify multiple signers on received messages. Some S/MIME clients
-choke if a message contains multiple signers. It is possible to sign
-messages "in parallel" by signing an already signed message.
-
-The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
-clients. Strictly speaking these process CMS enveloped data: CMS
-encrypted data is used for other purposes.
-
-The B<-resign> option uses an existing message digest when adding a new
-signer. This means that attributes must be present in at least one existing
-signer using the same message digest or this operation will fail.
-
-The B<-stream> and B<-indef> options enable streaming I/O support.
-As a result the encoding is BER using indefinite length constructed encoding
-and no longer DER. Streaming is supported for the B<-encrypt> operation and the
-B<-sign> operation if the content is not detached.
-
-Streaming is always used for the B<-sign> operation with detached data but
-since the content is no longer part of the CMS structure the encoding
-remains DER.
-
-If the B<-decrypt> option is used without a recipient certificate then an
-attempt is made to locate the recipient by trying each potential recipient
-in turn using the supplied private key. To thwart the MMA attack
-(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
-tried whether they succeed or not and if no recipients match the message
-is "decrypted" using a random key which will typically output garbage.
-The B<-debug_decrypt> option can be used to disable the MMA attack protection
-and return an error if no recipient can be found: this option should be used
-with caution. For a fuller description see L<CMS_decrypt(3)>).
-
-=head1 EXIT CODES
-
-=over 4
-
-=item Z<>0
-
-the operation was completely successfully.
-
-=item Z<>1
-
-an error occurred parsing the command options.
-
-=item Z<>2
-
-one of the input files could not be read.
-
-=item Z<>3
-
-an error occurred creating the CMS file or when reading the MIME
-message.
-
-=item Z<>4
-
-an error occurred decrypting or verifying the message.
-
-=item Z<>5
-
-the message was verified correctly but an error occurred writing out
-the signers certificates.
-
-=back
-
-=head1 COMPATIBILITY WITH PKCS#7 format.
-
-The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
-utility supports Cryptographic Message Syntax format. Use of some features
-will result in messages which cannot be processed by applications which only
-support the older format. These are detailed below.
-
-The use of the B<-keyid> option with B<-sign> or B<-encrypt>.
-
-The B<-outform PEM> option uses different headers.
-
-The B<-compress> option.
-
-The B<-secretkey> option when used with B<-encrypt>.
-
-The use of PSS with B<-sign>.
-
-The use of OAEP or non-RSA keys with B<-encrypt>.
-
-Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
-be processed by the older B<smime> command.
-
-=head1 EXAMPLES
-
-Create a cleartext signed message:
-
- openssl cms -sign -in message.txt -text -out mail.msg \
- -signer mycert.pem
-
-Create an opaque signed message
-
- openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
- -signer mycert.pem
-
-Create a signed message, include some additional certificates and
-read the private key from another file:
-
- openssl cms -sign -in in.txt -text -out mail.msg \
- -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
-
-Create a signed message with two signers, use key identifier:
-
- openssl cms -sign -in message.txt -text -out mail.msg \
- -signer mycert.pem -signer othercert.pem -keyid
-
-Send a signed message under Unix directly to sendmail, including headers:
-
- openssl cms -sign -in in.txt -text -signer mycert.pem \
- -from steve@openssl.org -to someone@somewhere \
- -subject "Signed message" | sendmail someone@somewhere
-
-Verify a message and extract the signer's certificate if successful:
-
- openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
-
-Send encrypted mail using triple DES:
-
- openssl cms -encrypt -in in.txt -from steve@openssl.org \
- -to someone@somewhere -subject "Encrypted message" \
- -des3 user.pem -out mail.msg
-
-Sign and encrypt mail:
-
- openssl cms -sign -in ml.txt -signer my.pem -text \
- | openssl cms -encrypt -out mail.msg \
- -from steve@openssl.org -to someone@somewhere \
- -subject "Signed and Encrypted message" -des3 user.pem
-
-Note: the encryption command does not include the B<-text> option because the
-message being encrypted already has MIME headers.
-
-Decrypt mail:
-
- openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
-
-The output from Netscape form signing is a PKCS#7 structure with the
-detached signature format. You can use this program to verify the
-signature by line wrapping the base64 encoded structure and surrounding
-it with:
-
- -----BEGIN PKCS7-----
- -----END PKCS7-----
-
-and using the command,
-
- openssl cms -verify -inform PEM -in signature.pem -content content.txt
-
-alternatively you can base64 decode the signature and use
-
- openssl cms -verify -inform DER -in signature.der -content content.txt
-
-Create an encrypted message using 128 bit Camellia:
-
- openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
-
-Add a signer to an existing message:
-
- openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
-
-Sign mail using RSA-PSS:
-
- openssl cms -sign -in message.txt -text -out mail.msg \
- -signer mycert.pem -keyopt rsa_padding_mode:pss
-
-Create encrypted mail using RSA-OAEP:
-
- openssl cms -encrypt -in plain.txt -out mail.msg \
- -recip cert.pem -keyopt rsa_padding_mode:oaep
-
-Use SHA256 KDF with an ECDH certificate:
-
- openssl cms -encrypt -in plain.txt -out mail.msg \
- -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
-
-=head1 BUGS
-
-The MIME parser isn't very clever: it seems to handle most messages that I've
-thrown at it but it may choke on others.
-
-The code currently will only write out the signer's certificate to a file: if
-the signer has a separate encryption certificate this must be manually
-extracted. There should be some heuristic that determines the correct
-encryption certificate.
-
-Ideally a database should be maintained of a certificates for each email
-address.
-
-The code doesn't currently take note of the permitted symmetric encryption
-algorithms as supplied in the SMIMECapabilities signed attribute. this means the
-user has to manually include the correct encryption algorithm. It should store
-the list of permitted ciphers in a database and only use those.
-
-No revocation checking is done on the signer's certificate.
-
-=head1 HISTORY
-
-The use of multiple B<-signer> options and the B<-resign> command were first
-added in OpenSSL 1.0.0
-
-The B<keyopt> option was first added in OpenSSL 1.1.0
-
-The use of B<-recip> to specify the recipient when encrypting mail was first
-added to OpenSSL 1.1.0
-
-Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
-
-The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
-to OpenSSL 1.1.0.
-
-The -no_alt_chains options was first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:5
-
-=head1 NAME
-
-config - OpenSSL CONF library configuration files
-
-=head1 DESCRIPTION
-
-The OpenSSL CONF library can be used to read configuration files.
-It is used for the OpenSSL master configuration file B<openssl.cnf>
-and in a few other places like B<SPKAC> files and certificate extension
-files for the B<x509> utility. OpenSSL applications can also use the
-CONF library for their own purposes.
-
-A configuration file is divided into a number of sections. Each section
-starts with a line B<[ section_name ]> and ends when a new section is
-started or end of file is reached. A section name can consist of
-alphanumeric characters and underscores.
-
-The first section of a configuration file is special and is referred
-to as the B<default> section this is usually unnamed and is from the
-start of file until the first named section. When a name is being looked up
-it is first looked up in a named section (if any) and then the
-default section.
-
-The environment is mapped onto a section called B<ENV>.
-
-Comments can be included by preceding them with the B<#> character
-
-Each section in a configuration file consists of a number of name and
-value pairs of the form B<name=value>
-
-The B<name> string can contain any alphanumeric characters as well as
-a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
-
-The B<value> string consists of the string following the B<=> character
-until end of line with any leading and trailing white space removed.
-
-The value string undergoes variable expansion. This can be done by
-including the form B<$var> or B<${var}>: this will substitute the value
-of the named variable in the current section. It is also possible to
-substitute a value from another section using the syntax B<$section::name>
-or B<${section::name}>. By using the form B<$ENV::name> environment
-variables can be substituted. It is also possible to assign values to
-environment variables by using the name B<ENV::name>, this will work
-if the program looks up environment variables using the B<CONF> library
-instead of calling getenv() directly.
-
-It is possible to escape certain characters by using any kind of quote
-or the B<\> character. By making the last character of a line a B<\>
-a B<value> string can be spread across multiple lines. In addition
-the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
-
-=head1 OPENSSL LIBRARY CONFIGURATION
-
-Applications can automatically configure certain
-aspects of OpenSSL using the master OpenSSL configuration file, or optionally
-an alternative configuration file. The B<openssl> utility includes this
-functionality: any sub command uses the master OpenSSL configuration file
-unless an option is used in the sub command to use an alternative configuration
-file.
-
-To enable library configuration the default section needs to contain an
-appropriate line which points to the main configuration section. The default
-name is B<openssl_conf> which is used by the B<openssl> utility. Other
-applications may use an alternative name such as B<myapplicaton_conf>.
-
-The configuration section should consist of a set of name value pairs which
-contain specific module configuration information. The B<name> represents
-the name of the I<configuration module> the meaning of the B<value> is
-module specific: it may, for example, represent a further configuration
-section containing configuration module specific information. E.g.
-
- openssl_conf = openssl_init
-
- [openssl_init]
-
- oid_section = new_oids
- engines = engine_section
-
- [new_oids]
-
- ... new oids here ...
-
- [engine_section]
-
- ... engine stuff here ...
-
-The features of each configuration module are described below.
-
-=head2 ASN1 Object Configuration Module
-
-This module has the name B<oid_section>. The value of this variable points
-to a section containing name value pairs of OIDs: the name is the OID short
-and long name, the value is the numerical form of the OID. Although some of
-the B<openssl> utility sub commands already have their own ASN1 OBJECT section
-functionality not all do. By using the ASN1 OBJECT configuration module
-B<all> the B<openssl> utility sub commands can see the new objects as well
-as any compliant applications. For example:
-
- [new_oids]
-
- some_new_oid = 1.2.3.4
- some_other_oid = 1.2.3.5
-
-It is also possible to set the value to the long name followed
-by a comma and the numerical OID form. For example:
-
- shortName = some object long name, 1.2.3.4
-
-=head2 Engine Configuration Module
-
-This ENGINE configuration module has the name B<engines>. The value of this
-variable points to a section containing further ENGINE configuration
-information.
-
-The section pointed to by B<engines> is a table of engine names (though see
-B<engine_id> below) and further sections containing configuration information
-specific to each ENGINE.
-
-Each ENGINE specific section is used to set default algorithms, load
-dynamic, perform initialization and send ctrls. The actual operation performed
-depends on the I<command> name which is the name of the name value pair. The
-currently supported commands are listed below.
-
-For example:
-
- [engine_section]
-
- # Configure ENGINE named "foo"
- foo = foo_section
- # Configure ENGINE named "bar"
- bar = bar_section
-
- [foo_section]
- ... foo ENGINE specific commands ...
-
- [bar_section]
- ... "bar" ENGINE specific commands ...
-
-The command B<engine_id> is used to give the ENGINE name. If used this
-command must be first. For example:
-
- [engine_section]
- # This would normally handle an ENGINE named "foo"
- foo = foo_section
-
- [foo_section]
- # Override default name and use "myfoo" instead.
- engine_id = myfoo
-
-The command B<dynamic_path> loads and adds an ENGINE from the given path. It
-is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
-by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
-not the required behaviour then alternative ctrls can be sent directly
-to the dynamic ENGINE using ctrl commands.
-
-The command B<init> determines whether to initialize the ENGINE. If the value
-is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
-initialized the ENGINE immediately. If the B<init> command is not present
-then an attempt will be made to initialize the ENGINE after all commands in
-its section have been processed.
-
-The command B<default_algorithms> sets the default algorithms an ENGINE will
-supply using the functions ENGINE_set_default_string().
-
-If the name matches none of the above command names it is assumed to be a
-ctrl command which is sent to the ENGINE. The value of the command is the
-argument to the ctrl command. If the value is the string B<EMPTY> then no
-value is sent to the command.
-
-For example:
-
-
- [engine_section]
-
- # Configure ENGINE named "foo"
- foo = foo_section
-
- [foo_section]
- # Load engine from DSO
- dynamic_path = /some/path/fooengine.so
- # A foo specific ctrl.
- some_ctrl = some_value
- # Another ctrl that doesn't take a value.
- other_ctrl = EMPTY
- # Supply all default algorithms
- default_algorithms = ALL
-
-=head2 EVP Configuration Module
-
-This modules has the name B<alg_section> which points to a section containing
-algorithm commands.
-
-Currently the only algorithm command supported is B<fips_mode> whose
-value should be a boolean string such as B<on> or B<off>. If the value is
-B<on> this attempt to enter FIPS mode. If the call fails or the library is
-not FIPS capable then an error occurs.
-
-For example:
-
- alg_section = evp_settings
-
- [evp_settings]
-
- fips_mode = on
-
-=head2 SSL Configuration Module
-
-This module has the name B<ssl_conf> which points to a section containing
-SSL configurations.
-
-Each line in the SSL configuration section contains the name of the
-configuration and the section containing it.
-
-Each configuration section consists of command value pairs for B<SSL_CONF>.
-Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls
-SSL_CTX_config() or SSL_config() with the appropriate configuration name.
-
-Note: any characters before an initial dot in the configuration section are
-ignored so the same command can be used multiple times.
-
-For example:
-
- ssl_conf = ssl_sect
-
- [ssl_sect]
-
- server = server_section
-
- [server_section]
-
- RSA.Certificate = server-rsa.pem
- ECDSA.Certificate = server-ecdsa.pem
- Ciphers = ALL:!RC4
-
-=head1 NOTES
-
-If a configuration file attempts to expand a variable that doesn't exist
-then an error is flagged and the file will not load. This can happen
-if an attempt is made to expand an environment variable that doesn't
-exist. For example in a previous version of OpenSSL the default OpenSSL
-master configuration file used the value of B<HOME> which may not be
-defined on non Unix systems and would cause an error.
-
-This can be worked around by including a B<default> section to provide
-a default value: then if the environment lookup fails the default value
-will be used instead. For this to work properly the default value must
-be defined earlier in the configuration file than the expansion. See
-the B<EXAMPLES> section for an example of how to do this.
-
-If the same variable exists in the same section then all but the last
-value will be silently ignored. In certain circumstances such as with
-DNs the same field may occur multiple times. This is usually worked
-around by ignoring any characters before an initial B<.> e.g.
-
- 1.OU="My first OU"
- 2.OU="My Second OU"
-
-=head1 EXAMPLES
-
-Here is a sample configuration file using some of the features
-mentioned above.
-
- # This is the default section.
-
- HOME=/temp
- RANDFILE= ${ENV::HOME}/.rnd
- configdir=$ENV::HOME/config
-
- [ section_one ]
-
- # We are now in section one.
-
- # Quotes permit leading and trailing whitespace
- any = " any variable name "
-
- other = A string that can \
- cover several lines \
- by including \\ characters
-
- message = Hello World\n
-
- [ section_two ]
-
- greeting = $section_one::message
-
-This next example shows how to expand environment variables safely.
-
-Suppose you want a variable called B<tmpfile> to refer to a
-temporary filename. The directory it is placed in can determined by
-the B<TEMP> or B<TMP> environment variables but they may not be
-set to any value at all. If you just include the environment variable
-names and the variable doesn't exist then this will cause an error when
-an attempt is made to load the configuration file. By making use of the
-default section both values can be looked up with B<TEMP> taking
-priority and B</tmp> used if neither is defined:
-
- TMP=/tmp
- # The above value is used if TMP isn't in the environment
- TEMP=$ENV::TMP
- # The above value is used if TEMP isn't in the environment
- tmpfile=${ENV::TEMP}/tmp.filename
-
-Simple OpenSSL library configuration example to enter FIPS mode:
-
- # Default appname: should match "appname" parameter (if any)
- # supplied to CONF_modules_load_file et al.
- openssl_conf = openssl_conf_section
-
- [openssl_conf_section]
- # Configuration module list
- alg_section = evp_sect
-
- [evp_sect]
- # Set to "yes" to enter FIPS mode if supported
- fips_mode = yes
-
-Note: in the above example you will get an error in non FIPS capable versions
-of OpenSSL.
-
-More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
-
- # Default appname: should match "appname" parameter (if any)
- # supplied to CONF_modules_load_file et al.
- openssl_conf = openssl_conf_section
-
- [openssl_conf_section]
- # Configuration module list
- alg_section = evp_sect
- oid_section = new_oids
-
- [evp_sect]
- # This will have no effect as FIPS mode is off by default.
- # Set to "yes" to enter FIPS mode, if supported
- fips_mode = no
-
- [new_oids]
- # New OID, just short name
- newoid1 = 1.2.3.4.1
- # New OID shortname and long name
- newoid2 = New OID 2 long name, 1.2.3.4.2
-
-The above examples can be used with any application supporting library
-configuration if "openssl_conf" is modified to match the appropriate "appname".
-
-For example if the second sample file above is saved to "example.cnf" then
-the command line:
-
- OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
-
-will output:
-
- 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
-
-showing that the OID "newoid1" has been added as "1.2.3.4.1".
-
-=head1 BUGS
-
-Currently there is no way to include characters using the octal B<\nnn>
-form. Strings are all null terminated so nulls cannot form part of
-the value.
-
-The escaping isn't quite right: if you want to use sequences like B<\n>
-you can't use any quote escaping on the same line.
-
-Files are loaded in a single pass. This means that an variable expansion
-will only work if the variables referenced are defined earlier in the
-file.
-
-=head1 SEE ALSO
-
-L<x509(1)>, L<req(1)>, L<ca(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-crl - CRL utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<crl>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-text>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-nameopt option>]
-[B<-noout>]
-[B<-hash>]
-[B<-issuer>]
-[B<-lastupdate>]
-[B<-nextupdate>]
-[B<-CAfile file>]
-[B<-CApath dir>]
-
-=head1 DESCRIPTION
-
-The B<crl> command processes CRL files in DER or PEM format.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. B<DER> format is DER encoded CRL
-structure. B<PEM> (the default) is a base64 encoded version of
-the DER form with header and footer lines.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read from or standard input if this
-option is not specified.
-
-=item B<-out filename>
-
-specifies the output filename to write to or standard output by
-default.
-
-=item B<-text>
-
-print out the CRL in text form.
-
-=item B<-nameopt option>
-
-option which determines how the subject or issuer names are displayed. See
-the description of B<-nameopt> in L<x509(1)>.
-
-=item B<-noout>
-
-don't output the encoded version of the CRL.
-
-=item B<-hash>
-
-output a hash of the issuer name. This can be use to lookup CRLs in
-a directory by issuer name.
-
-=item B<-hash_old>
-
-outputs the "hash" of the CRL issuer name using the older algorithm
-as used by OpenSSL versions before 1.0.0.
-
-=item B<-issuer>
-
-output the issuer name.
-
-=item B<-lastupdate>
-
-output the lastUpdate field.
-
-=item B<-nextupdate>
-
-output the nextUpdate field.
-
-=item B<-CAfile file>
-
-verify the signature on a CRL by looking up the issuing certificate in
-B<file>
-
-=item B<-CApath dir>
-
-verify the signature on a CRL by looking up the issuing certificate in
-B<dir>. This directory must be a standard certificate directory: that
-is a hash of each subject name (using B<x509 -hash>) should be linked
-to each certificate.
-
-=back
-
-=head1 NOTES
-
-The PEM CRL format uses the header and footer lines:
-
- -----BEGIN X509 CRL-----
- -----END X509 CRL-----
-
-=head1 EXAMPLES
-
-Convert a CRL file from PEM to DER:
-
- openssl crl -in crl.pem -outform DER -out crl.der
-
-Output the text form of a DER encoded certificate:
-
- openssl crl -in crl.der -text -noout
-
-=head1 BUGS
-
-Ideally it should be possible to create a CRL using appropriate options
-and files too.
-
-=head1 SEE ALSO
-
-L<crl2pkcs7(1)>, L<ca(1)>, L<x509(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates
-
-=head1 SYNOPSIS
-
-B<openssl> B<crl2pkcs7>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-certfile filename>]
-[B<-nocrl>]
-
-=head1 DESCRIPTION
-
-The B<crl2pkcs7> command takes an optional CRL and one or more
-certificates and converts them into a PKCS#7 degenerate "certificates
-only" structure.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the CRL input format. B<DER> format is DER encoded CRL
-structure.B<PEM> (the default) is a base64 encoded version of
-the DER form with header and footer lines.
-
-=item B<-outform DER|PEM>
-
-This specifies the PKCS#7 structure output format. B<DER> format is DER
-encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of
-the DER form with header and footer lines.
-
-=item B<-in filename>
-
-This specifies the input filename to read a CRL from or standard input if this
-option is not specified.
-
-=item B<-out filename>
-
-specifies the output filename to write the PKCS#7 structure to or standard
-output by default.
-
-=item B<-certfile filename>
-
-specifies a filename containing one or more certificates in B<PEM> format.
-All certificates in the file will be added to the PKCS#7 structure. This
-option can be used more than once to read certificates form multiple
-files.
-
-=item B<-nocrl>
-
-normally a CRL is included in the output file. With this option no CRL is
-included in the output file and a CRL is not read from the input file.
-
-=back
-
-=head1 EXAMPLES
-
-Create a PKCS#7 structure from a certificate and CRL:
-
- openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem
-
-Creates a PKCS#7 structure in DER format with no CRL from several
-different certificates:
-
- openssl crl2pkcs7 -nocrl -certfile newcert.pem
- -certfile demoCA/cacert.pem -outform DER -out p7.der
-
-=head1 NOTES
-
-The output file is a PKCS#7 signed data structure containing no signers and
-just certificates and an optional CRL.
-
-This utility can be used to send certificates and CAs to Netscape as part of
-the certificate enrollment process. This involves sending the DER encoded output
-as MIME type application/x-x509-user-cert.
-
-The B<PEM> encoded form with the header and footer lines removed can be used to
-install user certificates and CAs in MSIE using the Xenroll control.
-
-=head1 SEE ALSO
-
-L<pkcs7(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5, blake2b, blake2s - message digests
-
-=head1 SYNOPSIS
-
-B<openssl> B<dgst>
-[B<-help>]
-[B<-I<digest>>]
-[B<-c>]
-[B<-d>]
-[B<-hex>]
-[B<-binary>]
-[B<-r>]
-[B<-out filename>]
-[B<-sign filename>]
-[B<-keyform arg>]
-[B<-passin arg>]
-[B<-verify filename>]
-[B<-prverify filename>]
-[B<-signature filename>]
-[B<-hmac key>]
-[B<-fips-fingerprint>]
-[B<-engine id>]
-[B<-engine_impl>]
-[B<file...>]
-
-B<openssl>
-[I<digest>]
-[B<...>]
-
-=head1 DESCRIPTION
-
-The digest functions output the message digest of a supplied file or files
-in hexadecimal. The digest functions also generate and verify digital
-signatures using message digests.
-
-The generic name, B<dgst>, may be used with an option specifying the
-algorithm to be used.
-The default digest is I<sha256>.
-A supported I<digest> name may also be used as the command name.
-To see the list of supported algorithms, use the I<list --digest-commands>
-command.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-I<digest>>
-
-Specifies name of a supported digest to be used. To see the list of
-supported digests, use the command I<list --digest-commands>.
-
-=item B<-c>
-
-print out the digest in two digit groups separated by colons, only relevant if
-B<hex> format output is used.
-
-=item B<-d>
-
-print out BIO debugging information.
-
-=item B<-hex>
-
-digest is to be output as a hex dump. This is the default case for a "normal"
-digest as opposed to a digital signature. See NOTES below for digital
-signatures using B<-hex>.
-
-=item B<-binary>
-
-output the digest or signature in binary form.
-
-=item B<-r>
-
-output the digest in the "coreutils" format used by programs like B<sha1sum>.
-
-=item B<-out filename>
-
-filename to output to, or standard output by default.
-
-=item B<-sign filename>
-
-digitally sign the digest using the private key in "filename".
-
-=item B<-keyform arg>
-
-Specifies the key format to sign digest with. The DER, PEM, P12,
-and ENGINE formats are supported.
-
-=item B<-sigopt nm:v>
-
-Pass options to the signature algorithm during sign or verify operations.
-Names and values of these options are algorithm-specific.
-
-
-=item B<-passin arg>
-
-the private key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-verify filename>
-
-verify the signature using the public key in "filename".
-The output is either "Verification OK" or "Verification Failure".
-
-=item B<-prverify filename>
-
-verify the signature using the private key in "filename".
-
-=item B<-signature filename>
-
-the actual signature to verify.
-
-=item B<-hmac key>
-
-create a hashed MAC using "key".
-
-=item B<-mac alg>
-
-create MAC (keyed Message Authentication Code). The most popular MAC
-algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
-which are not based on hash, for instance B<gost-mac> algorithm,
-supported by B<ccgost> engine. MAC keys and other options should be set
-via B<-macopt> parameter.
-
-=item B<-macopt nm:v>
-
-Passes options to MAC algorithm, specified by B<-mac> key.
-Following options are supported by both by B<HMAC> and B<gost-mac>:
-
-=over 8
-
-=item B<key:string>
-
-Specifies MAC key as alphanumeric string (use if key contain printable
-characters only). String length must conform to any restrictions of
-the MAC algorithm for example exactly 32 chars for gost-mac.
-
-=item B<hexkey:string>
-
-Specifies MAC key in hexadecimal form (two hex digits per byte).
-Key length must conform to any restrictions of the MAC algorithm
-for example exactly 32 chars for gost-mac.
-
-=back
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-fips-fingerprint>
-
-compute HMAC using a specific key
-for certain OpenSSL-FIPS operations.
-
-=item B<-engine id>
-
-Use engine B<id> for operations (including private key storage).
-This engine is not used as source for digest algorithms, unless it is
-also specified in the configuration file or B<-engine_impl> is also
-specified.
-
-=item B<-engine_impl>
-
-When used with the B<-engine> option, it specifies to also use
-engine B<id> for digest operations.
-
-=item B<file...>
-
-file or files to digest. If no files are specified then standard input is
-used.
-
-=back
-
-
-=head1 EXAMPLES
-
-To create a hex-encoded message digest of a file:
- openssl dgst -md5 -hex file.txt
-
-To sign a file using SHA-256 with binary file output:
- openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt
-
-To verify a signature:
- openssl dgst -sha256 -verify publickey.pem \
- -signature signature.sign \
- file.txt
-
-
-=head1 NOTES
-
-The digest mechanisms that are available will depend on the options
-used when building OpenSSL.
-The B<list digest-commands> command can be used to list them.
-
-New or agile applications should use probably use SHA-256. Other digests,
-particularly SHA-1 and MD5, are still widely used for interoperating
-with existing formats and protocols.
-
-When signing a file, B<dgst> will automatically determine the algorithm
-(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
-When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
-itself, not the related data to identify the signer and algorithm used in
-formats such as x.509, CMS, and S/MIME.
-
-A source of random numbers is required for certain signing algorithms, in
-particular ECDSA and DSA.
-
-The signing and verify options should only be used if a single file is
-being signed or verified.
-
-Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r"
-or similar program to transform the hex signature into a binary signature
-prior to verification.
-
-=head1 HISTORY
-
-The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0
-The FIPS-related options were removed in OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-dhparam - DH parameter manipulation and generation
-
-=head1 SYNOPSIS
-
-B<openssl dhparam>
-[B<-help>]
-[B<-inform DER|PEM>]
-[B<-outform DER|PEM>]
-[B<-in> I<filename>]
-[B<-out> I<filename>]
-[B<-dsaparam>]
-[B<-check>]
-[B<-noout>]
-[B<-text>]
-[B<-C>]
-[B<-2>]
-[B<-5>]
-[B<-rand> I<file(s)>]
-[B<-engine id>]
-[I<numbits>]
-
-=head1 DESCRIPTION
-
-This command is used to manipulate DH parameter files.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. The B<DER> option uses an ASN1 DER encoded
-form compatible with the PKCS#3 DHparameter structure. The PEM form is the
-default format: it consists of the B<DER> format base64 encoded with
-additional header and footer lines.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in> I<filename>
-
-This specifies the input filename to read parameters from or standard input if
-this option is not specified.
-
-=item B<-out> I<filename>
-
-This specifies the output filename parameters to. Standard output is used
-if this option is not present. The output filename should B<not> be the same
-as the input filename.
-
-=item B<-dsaparam>
-
-If this option is used, DSA rather than DH parameters are read or created;
-they are converted to DH format. Otherwise, "strong" primes (such
-that (p-1)/2 is also prime) will be used for DH parameter generation.
-
-DH parameter generation with the B<-dsaparam> option is much faster,
-and the recommended exponent length is shorter, which makes DH key
-exchange more efficient. Beware that with such DSA-style DH
-parameters, a fresh DH key should be created for each use to
-avoid small-subgroup attacks that may be possible otherwise.
-
-=item B<-check>
-
-Performs numerous checks to see if the supplied parameters are valid and
-displays a warning if not.
-
-=item B<-2>, B<-5>
-
-The generator to use, either 2 or 5. If present then the
-input file is ignored and parameters are generated instead. If not
-present but B<numbits> is present, parameters are generated with the
-default generator 2.
-
-=item B<-rand> I<file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item I<numbits>
-
-this option specifies that a parameter set should be generated of size
-I<numbits>. It must be the last option. If this option is present then
-the input file is ignored and parameters are generated instead. If
-this option is not present but a generator (B<-2> or B<-5>) is
-present, parameters are generated with a default length of 2048 bits.
-
-=item B<-noout>
-
-this option inhibits the output of the encoded version of the parameters.
-
-=item B<-text>
-
-this option prints out the DH parameters in human readable form.
-
-=item B<-C>
-
-this option converts the parameters into C code. The parameters can then
-be loaded by calling the get_dhNNNN() function.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<dhparam>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 WARNINGS
-
-The program B<dhparam> combines the functionality of the programs B<dh> and
-B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh>
-programs are retained for now but may have different purposes in future
-versions of OpenSSL.
-
-=head1 NOTES
-
-PEM format DH parameters use the header and footer lines:
-
- -----BEGIN DH PARAMETERS-----
- -----END DH PARAMETERS-----
-
-OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42
-DH.
-
-This program manipulates DH parameters not keys.
-
-=head1 BUGS
-
-There should be a way to generate and manipulate DH keys.
-
-=head1 SEE ALSO
-
-L<dsaparam(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-dsa - DSA key processing
-
-=head1 SYNOPSIS
-
-B<openssl> B<dsa>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-in filename>]
-[B<-passin arg>]
-[B<-out filename>]
-[B<-passout arg>]
-[B<-aes128>]
-[B<-aes192>]
-[B<-aes256>]
-[B<-camellia128>]
-[B<-camellia192>]
-[B<-camellia256>]
-[B<-des>]
-[B<-des3>]
-[B<-idea>]
-[B<-text>]
-[B<-noout>]
-[B<-modulus>]
-[B<-pubin>]
-[B<-pubout>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<dsa> command processes DSA keys. They can be converted between various
-forms and their components printed out. B<Note> This command uses the
-traditional SSLeay compatible format for private key encryption: newer
-applications should use the more secure PKCS#8 format using the B<pkcs8>
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. The B<DER> option with a private key uses
-an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of
-version (currently zero), p, q, g, the public and private key components
-respectively as ASN.1 INTEGERs. When used with a public key it uses a
-SubjectPublicKeyInfo structure: it is an error if the key is not DSA.
-
-The B<PEM> form is the default format: it consists of the B<DER> format base64
-encoded with additional header and footer lines. In the case of a private key
-PKCS#8 format is also accepted.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read a key from or standard input if this
-option is not specified. If the key is encrypted a pass phrase will be
-prompted for.
-
-=item B<-passin arg>
-
-the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-out filename>
-
-This specifies the output filename to write a key to or standard output by
-is not specified. If any encryption options are set then a pass phrase will be
-prompted for. The output filename should B<not> be the same as the input
-filename.
-
-=item B<-passout arg>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
-
-These options encrypt the private key with the specified
-cipher before outputting it. A pass phrase is prompted for.
-If none of these options is specified the key is written in plain text. This
-means that using the B<dsa> utility to read in an encrypted key with no
-encryption option can be used to remove the pass phrase from a key, or by
-setting the encryption options it can be use to add or change the pass phrase.
-These options can only be used with PEM format output files.
-
-=item B<-text>
-
-prints out the public, private key components and parameters.
-
-=item B<-noout>
-
-this option prevents output of the encoded version of the key.
-
-=item B<-modulus>
-
-this option prints out the value of the public key component of the key.
-
-=item B<-pubin>
-
-by default a private key is read from the input file: with this option a
-public key is read instead.
-
-=item B<-pubout>
-
-by default a private key is output. With this option a public
-key will be output instead. This option is automatically set if the input is
-a public key.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<dsa>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 NOTES
-
-The PEM private key format uses the header and footer lines:
-
- -----BEGIN DSA PRIVATE KEY-----
- -----END DSA PRIVATE KEY-----
-
-The PEM public key format uses the header and footer lines:
-
- -----BEGIN PUBLIC KEY-----
- -----END PUBLIC KEY-----
-
-=head1 EXAMPLES
-
-To remove the pass phrase on a DSA private key:
-
- openssl dsa -in key.pem -out keyout.pem
-
-To encrypt a private key using triple DES:
-
- openssl dsa -in key.pem -des3 -out keyout.pem
-
-To convert a private key from PEM to DER format:
-
- openssl dsa -in key.pem -outform DER -out keyout.der
-
-To print out the components of a private key to standard output:
-
- openssl dsa -in key.pem -text -noout
-
-To just output the public part of a private key:
-
- openssl dsa -in key.pem -pubout -out pubkey.pem
-
-=head1 SEE ALSO
-
-L<dsaparam(1)>, L<gendsa(1)>, L<rsa(1)>,
-L<genrsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-dsaparam - DSA parameter manipulation and generation
-
-=head1 SYNOPSIS
-
-B<openssl dsaparam>
-[B<-help>]
-[B<-inform DER|PEM>]
-[B<-outform DER|PEM>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-noout>]
-[B<-text>]
-[B<-C>]
-[B<-rand file(s)>]
-[B<-genkey>]
-[B<-engine id>]
-[B<numbits>]
-
-=head1 DESCRIPTION
-
-This command is used to manipulate or generate DSA parameter files.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. The B<DER> option uses an ASN1 DER encoded
-form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting
-of p, q and g respectively. The PEM form is the default format: it consists
-of the B<DER> format base64 encoded with additional header and footer lines.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read parameters from or standard input if
-this option is not specified. If the B<numbits> parameter is included then
-this option will be ignored.
-
-=item B<-out filename>
-
-This specifies the output filename parameters to. Standard output is used
-if this option is not present. The output filename should B<not> be the same
-as the input filename.
-
-=item B<-noout>
-
-this option inhibits the output of the encoded version of the parameters.
-
-=item B<-text>
-
-this option prints out the DSA parameters in human readable form.
-
-=item B<-C>
-
-this option converts the parameters into C code. The parameters can then
-be loaded by calling the get_dsaXXX() function.
-
-=item B<-genkey>
-
-this option will generate a DSA either using the specified or generated
-parameters.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<numbits>
-
-this option specifies that a parameter set should be generated of size
-B<numbits>. It must be the last option. If this option is included then
-the input file (if any) is ignored.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<dsaparam>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 NOTES
-
-PEM format DSA parameters use the header and footer lines:
-
- -----BEGIN DSA PARAMETERS-----
- -----END DSA PARAMETERS-----
-
-DSA parameter generation is a slow process and as a result the same set of
-DSA parameters is often used to generate several distinct keys.
-
-=head1 SEE ALSO
-
-L<gendsa(1)>, L<dsa(1)>, L<genrsa(1)>,
-L<rsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ec - EC key processing
-
-=head1 SYNOPSIS
-
-B<openssl> B<ec>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-in filename>]
-[B<-passin arg>]
-[B<-out filename>]
-[B<-passout arg>]
-[B<-des>]
-[B<-des3>]
-[B<-idea>]
-[B<-text>]
-[B<-noout>]
-[B<-param_out>]
-[B<-pubin>]
-[B<-pubout>]
-[B<-conv_form arg>]
-[B<-param_enc arg>]
-[B<-no_public>]
-[B<-check>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<ec> command processes EC keys. They can be converted between various
-forms and their components printed out. B<Note> OpenSSL uses the
-private key format specified in 'SEC 1: Elliptic Curve Cryptography'
-(http://www.secg.org/). To convert an OpenSSL EC private key into the
-PKCS#8 private key format use the B<pkcs8> command.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. The B<DER> option with a private key uses
-an ASN.1 DER encoded SEC1 private key. When used with a public key it
-uses the SubjectPublicKeyInfo structure as specified in RFC 3280.
-The B<PEM> form is the default format: it consists of the B<DER> format base64
-encoded with additional header and footer lines. In the case of a private key
-PKCS#8 format is also accepted.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read a key from or standard input if this
-option is not specified. If the key is encrypted a pass phrase will be
-prompted for.
-
-=item B<-passin arg>
-
-the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-out filename>
-
-This specifies the output filename to write a key to or standard output by
-is not specified. If any encryption options are set then a pass phrase will be
-prompted for. The output filename should B<not> be the same as the input
-filename.
-
-=item B<-passout arg>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-des|-des3|-idea>
-
-These options encrypt the private key with the DES, triple DES, IDEA or
-any other cipher supported by OpenSSL before outputting it. A pass phrase is
-prompted for.
-If none of these options is specified the key is written in plain text. This
-means that using the B<ec> utility to read in an encrypted key with no
-encryption option can be used to remove the pass phrase from a key, or by
-setting the encryption options it can be use to add or change the pass phrase.
-These options can only be used with PEM format output files.
-
-=item B<-text>
-
-prints out the public, private key components and parameters.
-
-=item B<-noout>
-
-this option prevents output of the encoded version of the key.
-
-=item B<-modulus>
-
-this option prints out the value of the public key component of the key.
-
-=item B<-pubin>
-
-by default a private key is read from the input file: with this option a
-public key is read instead.
-
-=item B<-pubout>
-
-by default a private key is output. With this option a public
-key will be output instead. This option is automatically set if the input is
-a public key.
-
-=item B<-conv_form>
-
-This specifies how the points on the elliptic curve are converted
-into octet strings. Possible values are: B<compressed> (the default
-value), B<uncompressed> and B<hybrid>. For more information regarding
-the point conversion forms please read the X9.62 standard.
-B<Note> Due to patent issues the B<compressed> option is disabled
-by default for binary curves and can be enabled by defining
-the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
-
-=item B<-param_enc arg>
-
-This specifies how the elliptic curve parameters are encoded.
-Possible value are: B<named_curve>, i.e. the ec parameters are
-specified by an OID, or B<explicit> where the ec parameters are
-explicitly given (see RFC 3279 for the definition of the
-EC parameters structures). The default value is B<named_curve>.
-B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
-is currently not implemented in OpenSSL.
-
-=item B<-no_public>
-
-This option omits the public key components from the private key output.
-
-=item B<-check>
-
-this option checks the consistency of an EC private or public key.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<ec>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 NOTES
-
-The PEM private key format uses the header and footer lines:
-
- -----BEGIN EC PRIVATE KEY-----
- -----END EC PRIVATE KEY-----
-
-The PEM public key format uses the header and footer lines:
-
- -----BEGIN PUBLIC KEY-----
- -----END PUBLIC KEY-----
-
-=head1 EXAMPLES
-
-To encrypt a private key using triple DES:
-
- openssl ec -in key.pem -des3 -out keyout.pem
-
-To convert a private key from PEM to DER format:
-
- openssl ec -in key.pem -outform DER -out keyout.der
-
-To print out the components of a private key to standard output:
-
- openssl ec -in key.pem -text -noout
-
-To just output the public part of a private key:
-
- openssl ec -in key.pem -pubout -out pubkey.pem
-
-To change the parameters encoding to B<explicit>:
-
- openssl ec -in key.pem -param_enc explicit -out keyout.pem
-
-To change the point conversion form to B<compressed>:
-
- openssl ec -in key.pem -conv_form compressed -out keyout.pem
-
-=head1 SEE ALSO
-
-L<ecparam(1)>, L<dsa(1)>, L<rsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ecparam - EC parameter manipulation and generation
-
-=head1 SYNOPSIS
-
-B<openssl ecparam>
-[B<-help>]
-[B<-inform DER|PEM>]
-[B<-outform DER|PEM>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-noout>]
-[B<-text>]
-[B<-C>]
-[B<-check>]
-[B<-name arg>]
-[B<-list_curves>]
-[B<-conv_form arg>]
-[B<-param_enc arg>]
-[B<-no_seed>]
-[B<-rand file(s)>]
-[B<-genkey>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-This command is used to manipulate or generate EC parameter files.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. The B<DER> option uses an ASN.1 DER encoded
-form compatible with RFC 3279 EcpkParameters. The PEM form is the default
-format: it consists of the B<DER> format base64 encoded with additional
-header and footer lines.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read parameters from or standard input if
-this option is not specified.
-
-=item B<-out filename>
-
-This specifies the output filename parameters to. Standard output is used
-if this option is not present. The output filename should B<not> be the same
-as the input filename.
-
-=item B<-noout>
-
-This option inhibits the output of the encoded version of the parameters.
-
-=item B<-text>
-
-This option prints out the EC parameters in human readable form.
-
-=item B<-C>
-
-This option converts the EC parameters into C code. The parameters can then
-be loaded by calling the get_ec_group_XXX() function.
-
-=item B<-check>
-
-Validate the elliptic curve parameters.
-
-=item B<-name arg>
-
-Use the EC parameters with the specified 'short' name. Use B<-list_curves>
-to get a list of all currently implemented EC parameters.
-
-=item B<-list_curves>
-
-If this options is specified B<ecparam> will print out a list of all
-currently implemented EC parameters names and exit.
-
-=item B<-conv_form>
-
-This specifies how the points on the elliptic curve are converted
-into octet strings. Possible values are: B<compressed> (the default
-value), B<uncompressed> and B<hybrid>. For more information regarding
-the point conversion forms please read the X9.62 standard.
-B<Note> Due to patent issues the B<compressed> option is disabled
-by default for binary curves and can be enabled by defining
-the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
-
-=item B<-param_enc arg>
-
-This specifies how the elliptic curve parameters are encoded.
-Possible value are: B<named_curve>, i.e. the ec parameters are
-specified by an OID, or B<explicit> where the ec parameters are
-explicitly given (see RFC 3279 for the definition of the
-EC parameters structures). The default value is B<named_curve>.
-B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
-is currently not implemented in OpenSSL.
-
-=item B<-no_seed>
-
-This option inhibits that the 'seed' for the parameter generation
-is included in the ECParameters structure (see RFC 3279).
-
-=item B<-genkey>
-
-This option will generate an EC private key using the specified parameters.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<ecparam>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 NOTES
-
-PEM format EC parameters use the header and footer lines:
-
- -----BEGIN EC PARAMETERS-----
- -----END EC PARAMETERS-----
-
-OpenSSL is currently not able to generate new groups and therefore
-B<ecparam> can only create EC parameters from known (named) curves.
-
-=head1 EXAMPLES
-
-To create EC parameters with the group 'prime192v1':
-
- openssl ecparam -out ec_param.pem -name prime192v1
-
-To create EC parameters with explicit parameters:
-
- openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit
-
-To validate given EC parameters:
-
- openssl ecparam -in ec_param.pem -check
-
-To create EC parameters and a private key:
-
- openssl ecparam -out ec_key.pem -name prime192v1 -genkey
-
-To change the point encoding to 'compressed':
-
- openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed
-
-To print out the EC parameters to standard output:
-
- openssl ecparam -in ec_param.pem -noout -text
-
-=head1 SEE ALSO
-
-L<ec(1)>, L<dsaparam(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-enc - symmetric cipher routines
-
-=head1 SYNOPSIS
-
-B<openssl enc -ciphername>
-[B<-help>]
-[B<-ciphers>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-pass arg>]
-[B<-e>]
-[B<-d>]
-[B<-a/-base64>]
-[B<-A>]
-[B<-k password>]
-[B<-kfile filename>]
-[B<-K key>]
-[B<-iv IV>]
-[B<-S salt>]
-[B<-salt>]
-[B<-nosalt>]
-[B<-z>]
-[B<-md digest>]
-[B<-p>]
-[B<-P>]
-[B<-bufsize number>]
-[B<-nopad>]
-[B<-debug>]
-[B<-none>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The symmetric cipher commands allow data to be encrypted or decrypted
-using various block and stream ciphers using keys based on passwords
-or explicitly provided. Base64 encoding or decoding can also be performed
-either by itself or in addition to the encryption or decryption.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-ciphers>
-
-List all supported ciphers.
-
-=item B<-in filename>
-
-the input filename, standard input by default.
-
-=item B<-out filename>
-
-the output filename, standard output by default.
-
-=item B<-pass arg>
-
-the password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-e>
-
-encrypt the input data: this is the default.
-
-=item B<-d>
-
-decrypt the input data.
-
-=item B<-a>
-
-base64 process the data. This means that if encryption is taking place
-the data is base64 encoded after encryption. If decryption is set then
-the input data is base64 decoded before being decrypted.
-
-=item B<-base64>
-
-same as B<-a>
-
-=item B<-A>
-
-if the B<-a> option is set then base64 process the data on one line.
-
-=item B<-k password>
-
-the password to derive the key from. This is for compatibility with previous
-versions of OpenSSL. Superseded by the B<-pass> argument.
-
-=item B<-kfile filename>
-
-read the password to derive the key from the first line of B<filename>.
-This is for compatibility with previous versions of OpenSSL. Superseded by
-the B<-pass> argument.
-
-=item B<-md digest>
-
-Use the specified digest to create the key from the passphrase.
-The default algorithm is sha-256.
-
-=item B<-nosalt>
-
-don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
-used except for test purposes or compatibility with ancient versions of
-OpenSSL.
-
-=item B<-salt>
-
-use salt (randomly generated or provide with B<-S> option) when
-encrypting (this is the default).
-
-=item B<-S salt>
-
-the actual salt to use: this must be represented as a string of hex digits.
-
-=item B<-K key>
-
-the actual key to use: this must be represented as a string comprised only
-of hex digits. If only the key is specified, the IV must additionally specified
-using the B<-iv> option. When both a key and a password are specified, the
-key given with the B<-K> option will be used and the IV generated from the
-password will be taken. It probably does not make much sense to specify
-both key and password.
-
-=item B<-iv IV>
-
-the actual IV to use: this must be represented as a string comprised only
-of hex digits. When only the key is specified using the B<-K> option, the
-IV must explicitly be defined. When a password is being specified using
-one of the other options, the IV is generated from this password.
-
-=item B<-p>
-
-print out the key and IV used.
-
-=item B<-P>
-
-print out the key and IV used then immediately exit: don't do any encryption
-or decryption.
-
-=item B<-bufsize number>
-
-set the buffer size for I/O
-
-=item B<-nopad>
-
-disable standard block padding
-
-=item B<-debug>
-
-debug the BIOs used for I/O.
-
-=item B<-z>
-
-Compress or decompress clear text using zlib before encryption or after
-decryption. This option exists only if OpenSSL with compiled with zlib
-or zlib-dynamic option.
-
-=item B<-none>
-
-Use NULL cipher (no encryption or decryption of input).
-
-=back
-
-=head1 NOTES
-
-The program can be called either as B<openssl ciphername> or
-B<openssl enc -ciphername>. But the first form doesn't work with
-engine-provided ciphers, because this form is processed before the
-configuration file is read and any ENGINEs loaded.
-
-Engines which provide entirely new encryption algorithms (such as ccgost
-engine which provides gost89 algorithm) should be configured in the
-configuration file. Engines, specified in the command line using -engine
-options can only be used for hardware-assisted implementations of
-ciphers, which are supported by OpenSSL core or other engine, specified
-in the configuration file.
-
-When enc command lists supported ciphers, ciphers provided by engines,
-specified in the configuration files are listed too.
-
-A password will be prompted for to derive the key and IV if necessary.
-
-The B<-salt> option should B<ALWAYS> be used if the key is being derived
-from a password unless you want compatibility with previous versions of
-OpenSSL.
-
-Without the B<-salt> option it is possible to perform efficient dictionary
-attacks on the password and to attack stream cipher encrypted data. The reason
-for this is that without the salt the same password always generates the same
-encryption key. When the salt is being used the first eight bytes of the
-encrypted data are reserved for the salt: it is generated at random when
-encrypting a file and read from the encrypted file when it is decrypted.
-
-Some of the ciphers do not have large keys and others have security
-implications if not used correctly. A beginner is advised to just use
-a strong block cipher in CBC mode such as bf or des3.
-
-All the block ciphers normally use PKCS#5 padding also known as standard block
-padding: this allows a rudimentary integrity or password check to be
-performed. However since the chance of random data passing the test is
-better than 1 in 256 it isn't a very good test.
-
-If padding is disabled then the input data must be a multiple of the cipher
-block length.
-
-All RC2 ciphers have the same key and effective key length.
-
-Blowfish and RC5 algorithms use a 128 bit key.
-
-=head1 SUPPORTED CIPHERS
-
-Note that some of these ciphers can be disabled at compile time
-and some are available only if an appropriate engine is configured
-in the configuration file. The output of the B<enc> command run with
-unsupported options (for example B<openssl enc -help>) includes a
-list of ciphers, supported by your version of OpenSSL, including
-ones provided by configured engines.
-
-The B<enc> program does not support authenticated encryption modes
-like CCM and GCM. The utility does not store or retrieve the
-authentication tag.
-
-
- base64 Base 64
-
- bf-cbc Blowfish in CBC mode
- bf Alias for bf-cbc
- bf-cfb Blowfish in CFB mode
- bf-ecb Blowfish in ECB mode
- bf-ofb Blowfish in OFB mode
-
- cast-cbc CAST in CBC mode
- cast Alias for cast-cbc
- cast5-cbc CAST5 in CBC mode
- cast5-cfb CAST5 in CFB mode
- cast5-ecb CAST5 in ECB mode
- cast5-ofb CAST5 in OFB mode
-
- des-cbc DES in CBC mode
- des Alias for des-cbc
- des-cfb DES in CBC mode
- des-ofb DES in OFB mode
- des-ecb DES in ECB mode
-
- des-ede-cbc Two key triple DES EDE in CBC mode
- des-ede Two key triple DES EDE in ECB mode
- des-ede-cfb Two key triple DES EDE in CFB mode
- des-ede-ofb Two key triple DES EDE in OFB mode
-
- des-ede3-cbc Three key triple DES EDE in CBC mode
- des-ede3 Three key triple DES EDE in ECB mode
- des3 Alias for des-ede3-cbc
- des-ede3-cfb Three key triple DES EDE CFB mode
- des-ede3-ofb Three key triple DES EDE in OFB mode
-
- desx DESX algorithm.
-
- gost89 GOST 28147-89 in CFB mode (provided by ccgost engine)
- gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
-
- idea-cbc IDEA algorithm in CBC mode
- idea same as idea-cbc
- idea-cfb IDEA in CFB mode
- idea-ecb IDEA in ECB mode
- idea-ofb IDEA in OFB mode
-
- rc2-cbc 128 bit RC2 in CBC mode
- rc2 Alias for rc2-cbc
- rc2-cfb 128 bit RC2 in CFB mode
- rc2-ecb 128 bit RC2 in ECB mode
- rc2-ofb 128 bit RC2 in OFB mode
- rc2-64-cbc 64 bit RC2 in CBC mode
- rc2-40-cbc 40 bit RC2 in CBC mode
-
- rc4 128 bit RC4
- rc4-64 64 bit RC4
- rc4-40 40 bit RC4
-
- rc5-cbc RC5 cipher in CBC mode
- rc5 Alias for rc5-cbc
- rc5-cfb RC5 cipher in CFB mode
- rc5-ecb RC5 cipher in ECB mode
- rc5-ofb RC5 cipher in OFB mode
-
- aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode
- aes[128|192|256] Alias for aes-[128|192|256]-cbc
- aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode
- aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode
- aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode
- aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode
- aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode
-
-=head1 EXAMPLES
-
-Just base64 encode a binary file:
-
- openssl base64 -in file.bin -out file.b64
-
-Decode the same file
-
- openssl base64 -d -in file.b64 -out file.bin
-
-Encrypt a file using triple DES in CBC mode using a prompted password:
-
- openssl des3 -salt -in file.txt -out file.des3
-
-Decrypt a file using a supplied password:
-
- openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
-
-Encrypt a file then base64 encode it (so it can be sent via mail for example)
-using Blowfish in CBC mode:
-
- openssl bf -a -salt -in file.txt -out file.bf
-
-Base64 decode a file then decrypt it:
-
- openssl bf -d -salt -a -in file.bf -out file.txt
-
-Decrypt some data using a supplied 40 bit RC4 key:
-
- openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
-
-=head1 BUGS
-
-The B<-A> option when used with large files doesn't work properly.
-
-There should be an option to allow an iteration count to be included.
-
-The B<enc> program only supports a fixed number of algorithms with
-certain parameters. So if, for example, you want to use RC2 with a
-76 bit key or RC4 with an 84 bit key you can't use this program.
-
-=head1 HISTORY
-
-The default digest was changed from MD5 to SHA256 in Openssl 1.1.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-engine - load and query engines
-
-=head1 SYNOPSIS
-
-B<openssl engine>
-[ I<engine...> ]
-[B<-v>]
-[B<-vv>]
-[B<-vvv>]
-[B<-vvv>]
-[B<-vvv>]
-[B<-c>]
-[B<-t>]
-[B<-tt>]
-[B<-pre> I<command>]
-[B<-post> I<command>]
-[ I<engine...> ]
-
-=head1 DESCRIPTION
-
-The B<engine> command is used to query the status and capabilities
-of the specified B<engine>'s.
-Engines may be specified before and after all other command-line flags.
-Only those specified are queried.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-v> B<-vv> B<-vvv> B<-vvvv>
-
-Provides information about each specified engine. The first flag lists
-all the possible run-time control commands; the second adds a
-description of each command; the third adds the input flags, and the
-final option adds the internal input flags.
-
-=item B<-c>
-
-Lists the capabilities of each engine.
-
-=item B<-t>
-
-Tests if each specified engine is available, and displays the answer.
-
-=item B<-tt>
-
-Displays an error trace for any unavailable engine.
-
-=item B<-pre> I<command>
-
-=item B<-post> I<command>
-
-Command-line configuration of engines.
-The B<-pre> command is given to the engine before it is loaded and
-the B<-post> command is given after the engine is loaded.
-The I<command> is of the form I<cmd:val> where I<cmd> is the command,
-and I<val> is the value for the command.
-See the example below.
-
-=back
-
-=head1 EXAMPLE
-
-To list all the commands available to a dynamic engine:
-
- % openssl engine -t -tt -vvvv dynamic
- (dynamic) Dynamic engine loading support
- [ unavailable ]
- SO_PATH: Specifies the path to the new ENGINE shared library
- (input flags): STRING
- NO_VCHECK: Specifies to continue even if version checking fails (boolean)
- (input flags): NUMERIC
- ID: Specifies an ENGINE id name for loading
- (input flags): STRING
- LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory)
- (input flags): NUMERIC
- DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory)
- (input flags): NUMERIC
- DIR_ADD: Adds a directory from which ENGINEs can be loaded
- (input flags): STRING
- LOAD: Load up the ENGINE specified by other settings
- (input flags): NO_INPUT
-
-To list the capabilities of the I<rsax> engine:
-
- % openssl engine -c
- (rsax) RSAX engine support
- [RSA]
- (dynamic) Dynamic engine loading support
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-errstr - lookup error codes
-
-=head1 SYNOPSIS
-
-B<openssl errstr error_code>
-
-=head1 DESCRIPTION
-
-Sometimes an application will not load error message and only
-numerical forms will be available. The B<errstr> utility can be used to
-display the meaning of the hex code. The hex code is the hex digits after the
-second colon.
-
-=head1 COMMAND OPTIONS
-
-None.
-
-=head1 EXAMPLE
-
-The error code:
-
- 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
-
-can be displayed with:
-
- openssl errstr 2006D080
-
-to produce the error message:
-
- error:2006D080:BIO routines:BIO_new_file:no such file
-
-=head1 SEE ALSO
-
-L<err(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-gendsa - generate a DSA private key from a set of parameters
-
-=head1 SYNOPSIS
-
-B<openssl> B<gendsa>
-[B<-help>]
-[B<-out filename>]
-[B<-aes128>]
-[B<-aes192>]
-[B<-aes256>]
-[B<-camellia128>]
-[B<-camellia192>]
-[B<-camellia256>]
-[B<-des>]
-[B<-des3>]
-[B<-idea>]
-[B<-rand file(s)>]
-[B<-engine id>]
-[B<paramfile>]
-
-=head1 DESCRIPTION
-
-The B<gendsa> command generates a DSA private key from a DSA parameter file
-(which will be typically generated by the B<openssl dsaparam> command).
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-out filename>
-
-Output the key to the specified file. If this argument is not specified then
-standard output is used.
-
-=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
-
-These options encrypt the private key with specified
-cipher before outputting it. A pass phrase is prompted for.
-If none of these options is specified no encryption is used.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<gendsa>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<paramfile>
-
-This option specifies the DSA parameter file to use. The parameters in this
-file determine the size of the private key. DSA parameters can be generated
-and examined using the B<openssl dsaparam> command.
-
-=back
-
-=head1 NOTES
-
-DSA key generation is little more than random number generation so it is
-much quicker that RSA key generation for example.
-
-=head1 SEE ALSO
-
-L<dsaparam(1)>, L<dsa(1)>, L<genrsa(1)>,
-L<rsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-genpkey - generate a private key
-
-=head1 SYNOPSIS
-
-B<openssl> B<genpkey>
-[B<-help>]
-[B<-out filename>]
-[B<-outform PEM|DER>]
-[B<-pass arg>]
-[B<-cipher>]
-[B<-engine id>]
-[B<-paramfile file>]
-[B<-algorithm alg>]
-[B<-pkeyopt opt:value>]
-[B<-genparam>]
-[B<-text>]
-
-=head1 DESCRIPTION
-
-The B<genpkey> command generates a private key.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-out filename>
-
-Output the key to the specified file. If this argument is not specified then
-standard output is used.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format DER or PEM.
-
-=item B<-pass arg>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-cipher>
-
-This option encrypts the private key with the supplied cipher. Any algorithm
-name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<genpkey>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms. If used this option should precede all other
-options.
-
-=item B<-algorithm alg>
-
-public key algorithm to use such as RSA, DSA or DH. If used this option must
-precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
-are mutually exclusive.
-
-=item B<-pkeyopt opt:value>
-
-set the public key algorithm option B<opt> to B<value>. The precise set of
-options supported depends on the public key algorithm used and its
-implementation. See B<KEY GENERATION OPTIONS> below for more details.
-
-=item B<-genparam>
-
-generate a set of parameters instead of a private key. If used this option must
-precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
-
-=item B<-paramfile filename>
-
-Some public key algorithms generate a private key based on a set of parameters.
-They can be supplied using this option. If this option is used the public key
-algorithm used is determined by the parameters. If used this option must
-precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
-are mutually exclusive.
-
-=item B<-text>
-
-Print an (unencrypted) text representation of private and public keys and
-parameters along with the PEM or DER structure.
-
-=back
-
-=head1 KEY GENERATION OPTIONS
-
-The options supported by each algorithm and indeed each implementation of an
-algorithm can vary. The options for the OpenSSL implementations are detailed
-below.
-
-=head1 RSA KEY GENERATION OPTIONS
-
-=over 4
-
-=item B<rsa_keygen_bits:numbits>
-
-The number of bits in the generated key. If not specified 1024 is used.
-
-=item B<rsa_keygen_pubexp:value>
-
-The RSA public exponent value. This can be a large decimal or
-hexadecimal value if preceded by B<0x>. Default value is 65537.
-
-=back
-
-=head1 DSA PARAMETER GENERATION OPTIONS
-
-=over 4
-
-=item B<dsa_paramgen_bits:numbits>
-
-The number of bits in the generated parameters. If not specified 1024 is used.
-
-=back
-
-=head1 DH PARAMETER GENERATION OPTIONS
-
-=over 4
-
-=item B<dh_paramgen_prime_len:numbits>
-
-The number of bits in the prime parameter B<p>.
-
-=item B<dh_paramgen_generator:value>
-
-The value to use for the generator B<g>.
-
-=item B<dh_rfc5114:num>
-
-If this option is set then the appropriate RFC5114 parameters are used
-instead of generating new parameters. The value B<num> can take the
-values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of
-1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup
-and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
-2.1, 2.2 and 2.3 respectively.
-
-=back
-
-=head1 EC PARAMETER GENERATION OPTIONS
-
-The EC parameter generation options below can also
-be supplied as EC key generation options. This can (for example) generate a
-key from a named curve without the need to use an explicit parameter file.
-
-=over 4
-
-=item B<ec_paramgen_curve:curve>
-
-the EC curve to use. OpenSSL supports NIST curve names such as "P-256".
-
-=item B<ec_param_enc:encoding>
-
-the encoding to use for parameters. The "encoding" parameter must be either
-"named_curve" or "explicit".
-
-=back
-
-=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS
-
-Gost 2001 support is not enabled by default. To enable this algorithm,
-one should load the ccgost engine in the OpenSSL configuration file.
-See README.gost file in the engines/ccgost directory of the source
-distribution for more details.
-
-Use of a parameter file for the GOST R 34.10 algorithm is optional.
-Parameters can be specified during key generation directly as well as
-during generation of parameter file.
-
-=over 4
-
-=item B<paramset:name>
-
-Specifies GOST R 34.10-2001 parameter set according to RFC 4357.
-Parameter set can be specified using abbreviated name, object short name or
-numeric OID. Following parameter sets are supported:
-
- paramset OID Usage
- A 1.2.643.2.2.35.1 Signature
- B 1.2.643.2.2.35.2 Signature
- C 1.2.643.2.2.35.3 Signature
- XA 1.2.643.2.2.36.0 Key exchange
- XB 1.2.643.2.2.36.1 Key exchange
- test 1.2.643.2.2.35.0 Test purposes
-
-=back
-
-=head1 X25519 KEY GENERATION OPTIONS
-
-The X25519 algorithm does not currently support any key generation options.
-
-
-=head1 NOTES
-
-The use of the genpkey program is encouraged over the algorithm specific
-utilities because additional algorithm options and ENGINE provided algorithms
-can be used.
-
-=head1 EXAMPLES
-
-Generate an RSA private key using default parameters:
-
- openssl genpkey -algorithm RSA -out key.pem
-
-Encrypt output private key using 128 bit AES and the passphrase "hello":
-
- openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
-
-Generate a 2048 bit RSA key using 3 as the public exponent:
-
- openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \
- -pkeyopt rsa_keygen_pubexp:3
-
-Generate 1024 bit DSA parameters:
-
- openssl genpkey -genparam -algorithm DSA -out dsap.pem \
- -pkeyopt dsa_paramgen_bits:1024
-
-Generate DSA key from parameters:
-
- openssl genpkey -paramfile dsap.pem -out dsakey.pem
-
-Generate 1024 bit DH parameters:
-
- openssl genpkey -genparam -algorithm DH -out dhp.pem \
- -pkeyopt dh_paramgen_prime_len:1024
-
-Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
-
- openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
-
-Generate DH key from parameters:
-
- openssl genpkey -paramfile dhp.pem -out dhkey.pem
-
-Generate EC parameters:
-
- openssl genpkey -genparam -algorithm EC -out ecp.pem \
- -pkeyopt ec_paramgen_curve:secp384r1 \
- -pkeyopt ec_param_enc:named_curve
-
-Generate EC key from parameters:
-
- openssl genpkey -paramfile ecp.pem -out eckey.pem
-
-Generate EC key directly:
-
- openssl genpkey -algorithm EC -out eckey.pem \
- -pkeyopt ec_paramgen_curve:P-384 \
- -pkeyopt ec_param_enc:named_curve
-
-Generate an X25519 private key:
-
- openssl genpkey -algorithm X25519 -out xkey.pem
-
-=head1 HISTORY
-
-The ability to use NIST curve names, and to generate an EC key directly,
-were added in OpenSSL 1.0.2.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-genrsa - generate an RSA private key
-
-=head1 SYNOPSIS
-
-B<openssl> B<genrsa>
-[B<-help>]
-[B<-out filename>]
-[B<-passout arg>]
-[B<-aes128>]
-[B<-aes192>]
-[B<-aes256>]
-[B<-camellia128>]
-[B<-camellia192>]
-[B<-camellia256>]
-[B<-des>]
-[B<-des3>]
-[B<-idea>]
-[B<-f4>]
-[B<-3>]
-[B<-rand file(s)>]
-[B<-engine id>]
-[B<numbits>]
-
-=head1 DESCRIPTION
-
-The B<genrsa> command generates an RSA private key.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-out filename>
-
-Output the key to the specified file. If this argument is not specified then
-standard output is used.
-
-=item B<-passout arg>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
-
-These options encrypt the private key with specified
-cipher before outputting it. If none of these options is
-specified no encryption is used. If encryption is used a pass phrase is prompted
-for if it is not supplied via the B<-passout> argument.
-
-=item B<-F4|-3>
-
-the public exponent to use, either 65537 or 3. The default is 65537.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<genrsa>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<numbits>
-
-the size of the private key to generate in bits. This must be the last option
-specified. The default is 512.
-
-=back
-
-=head1 NOTES
-
-RSA private key generation essentially involves the generation of two prime
-numbers. When generating a private key various symbols will be output to
-indicate the progress of the generation. A B<.> represents each number which
-has passed an initial sieve test, B<+> means a number has passed a single
-round of the Miller-Rabin primality test. A newline means that the number has
-passed all the prime tests (the actual number depends on the key size).
-
-Because key generation is a random process the time taken to generate a key
-may vary somewhat.
-
-=head1 BUGS
-
-A quirk of the prime generation algorithm is that it cannot generate small
-primes. Therefore the number of bits should not be less that 64. For typical
-private keys this will not matter because for security reasons they will
-be much larger (typically 1024 bits).
-
-=head1 SEE ALSO
-
-L<gendsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-list - list algorithms and features
-
-=head1 SYNOPSIS
-
-B<openssl list>
-[B<-help>]
-[B<-commands>]
-[B<-digest-commands>]
-[B<-digest-algorithms>]
-[B<-cipher-commands>]
-[B<-cipher-algorithms>]
-[B<-public-key-algorithms>]
-[B<-disabled>]
-
-=head1 DESCRIPTION
-
-This command is used to generate list of algorithms or disabled
-features.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Display out a usage message.
-
-=item B<-commands>
-
-Display a list of standard commands.
-
-=item B<-digest-commands>
-
-Display a list of message digest commands, which are typically used
-as input to the L<dgst(1)> or L<speed(1)> commands.
-
-=item B<-digest-algorithms>
-
-Display a list of message digest algorithms.
-If a line is of the form
- foo => bar
-then B<foo> is an alias for the official algorithm name, B<bar>.
-
-=item B<-cipher-commands>
-
-Display a list of cipher commands, which are typically used as input
-to the L<dgst(1)> or L<speed(1)> commands.
-
-=item B<-cipher-algorithms>
-
-Display a list of cipher algorithms.
-If a line is of the form
- foo => bar
-then B<foo> is an alias for the official algorithm name, B<bar>.
-
-=item B<-public-key-algorithms>
-
-Display a list of public key algorithms, with each algorithm as
-a block of multiple lines, all but the first are indented.
-
-=item B<-disabled>
-
-Display a list of disabled features, those that were compiled out
-of the installation.
-
-=back
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-nseq - create or examine a Netscape certificate sequence
-
-=head1 SYNOPSIS
-
-B<openssl> B<nseq>
-[B<-help>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-toseq>]
-
-=head1 DESCRIPTION
-
-The B<nseq> command takes a file containing a Netscape certificate
-sequence and prints out the certificates contained in it or takes a
-file of certificates and converts it into a Netscape certificate
-sequence.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-in filename>
-
-This specifies the input filename to read or standard input if this
-option is not specified.
-
-=item B<-out filename>
-
-specifies the output filename or standard output by default.
-
-=item B<-toseq>
-
-normally a Netscape certificate sequence will be input and the output
-is the certificates contained in it. With the B<-toseq> option the
-situation is reversed: a Netscape certificate sequence is created from
-a file of certificates.
-
-=back
-
-=head1 EXAMPLES
-
-Output the certificates in a Netscape certificate sequence
-
- openssl nseq -in nseq.pem -out certs.pem
-
-Create a Netscape certificate sequence
-
- openssl nseq -in certs.pem -toseq -out nseq.pem
-
-=head1 NOTES
-
-The B<PEM> encoded form uses the same headers and footers as a certificate:
-
- -----BEGIN CERTIFICATE-----
- -----END CERTIFICATE-----
-
-A Netscape certificate sequence is a Netscape specific form that can be sent
-to browsers as an alternative to the standard PKCS#7 format when several
-certificates are sent to the browser: for example during certificate enrollment.
-It is used by Netscape certificate server for example.
-
-=head1 BUGS
-
-This program needs a few more options: like allowing DER or PEM input and
-output files and allowing multiple certificate files to be used.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ocsp - Online Certificate Status Protocol utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<ocsp>
-[B<-help>]
-[B<-out file>]
-[B<-issuer file>]
-[B<-cert file>]
-[B<-serial n>]
-[B<-signer file>]
-[B<-signkey file>]
-[B<-sign_other file>]
-[B<-no_certs>]
-[B<-req_text>]
-[B<-resp_text>]
-[B<-text>]
-[B<-reqout file>]
-[B<-respout file>]
-[B<-reqin file>]
-[B<-respin file>]
-[B<-nonce>]
-[B<-no_nonce>]
-[B<-url URL>]
-[B<-host host:port>]
-[B<-header>]
-[B<-path>]
-[B<-CApath dir>]
-[B<-CAfile file>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-attime timestamp>]
-[B<-check_ss_sig>]
-[B<-crl_check>]
-[B<-crl_check_all>]
-[B<-explicit_policy>]
-[B<-extended_crl>]
-[B<-ignore_critical>]
-[B<-inhibit_any>]
-[B<-inhibit_map>]
-[B<-no_check_time>]
-[B<-partial_chain>]
-[B<-policy arg>]
-[B<-policy_check>]
-[B<-policy_print>]
-[B<-purpose purpose>]
-[B<-suiteB_128>]
-[B<-suiteB_128_only>]
-[B<-suiteB_192>]
-[B<-trusted_first>]
-[B<-no_alt_chains>]
-[B<-use_deltas>]
-[B<-auth_level num>]
-[B<-verify_depth num>]
-[B<-verify_email email>]
-[B<-verify_hostname hostname>]
-[B<-verify_ip ip>]
-[B<-verify_name name>]
-[B<-x509_strict>]
-[B<-VAfile file>]
-[B<-validity_period n>]
-[B<-status_age n>]
-[B<-noverify>]
-[B<-verify_other file>]
-[B<-trust_other>]
-[B<-no_intern>]
-[B<-no_signature_verify>]
-[B<-no_cert_verify>]
-[B<-no_chain>]
-[B<-no_cert_checks>]
-[B<-no_explicit>]
-[B<-port num>]
-[B<-index file>]
-[B<-CA file>]
-[B<-rsigner file>]
-[B<-rkey file>]
-[B<-rother file>]
-[B<-resp_no_certs>]
-[B<-nmin n>]
-[B<-ndays n>]
-[B<-resp_key_id>]
-[B<-nrequest n>]
-[B<-md5|-sha1|...>]
-
-=head1 DESCRIPTION
-
-The Online Certificate Status Protocol (OCSP) enables applications to
-determine the (revocation) state of an identified certificate (RFC 2560).
-
-The B<ocsp> command performs many common OCSP tasks. It can be used
-to print out requests and responses, create requests and send queries
-to an OCSP responder and behave like a mini OCSP server itself.
-
-=head1 COMMAND OPTIONS
-
-This command operates as either a client or a server.
-The options are described below, divided into those two modes.
-
-=head2 OCSP Client Options
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-out filename>
-
-specify output filename, default is standard output.
-
-=item B<-issuer filename>
-
-This specifies the current issuer certificate. This option can be used
-multiple times. The certificate specified in B<filename> must be in
-PEM format. This option B<MUST> come before any B<-cert> options.
-
-=item B<-cert filename>
-
-Add the certificate B<filename> to the request. The issuer certificate
-is taken from the previous B<issuer> option, or an error occurs if no
-issuer certificate is specified.
-
-=item B<-serial num>
-
-Same as the B<cert> option except the certificate with serial number
-B<num> is added to the request. The serial number is interpreted as a
-decimal integer unless preceded by B<0x>. Negative integers can also
-be specified by preceding the value by a B<-> sign.
-
-=item B<-signer filename>, B<-signkey filename>
-
-Sign the OCSP request using the certificate specified in the B<signer>
-option and the private key specified by the B<signkey> option. If
-the B<signkey> option is not present then the private key is read
-from the same file as the certificate. If neither option is specified then
-the OCSP request is not signed.
-
-=item B<-sign_other filename>
-
-Additional certificates to include in the signed request.
-
-=item B<-nonce>, B<-no_nonce>
-
-Add an OCSP nonce extension to a request or disable OCSP nonce addition.
-Normally if an OCSP request is input using the B<reqin> option no
-nonce is added: using the B<nonce> option will force addition of a nonce.
-If an OCSP request is being created (using B<cert> and B<serial> options)
-a nonce is automatically added specifying B<no_nonce> overrides this.
-
-=item B<-req_text>, B<-resp_text>, B<-text>
-
-print out the text form of the OCSP request, response or both respectively.
-
-=item B<-reqout file>, B<-respout file>
-
-write out the DER encoded certificate request or response to B<file>.
-
-=item B<-reqin file>, B<-respin file>
-
-read OCSP request or response file from B<file>. These option are ignored
-if OCSP request or response creation is implied by other options (for example
-with B<serial>, B<cert> and B<host> options).
-
-=item B<-url responder_url>
-
-specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
-
-=item B<-host hostname:port>, B<-path pathname>
-
-if the B<host> option is present then the OCSP request is sent to the host
-B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
-or "/" by default. This is equivalent to specifying B<-url> with scheme
-http:// and the given hostname, port, and pathname.
-
-=item B<-header name=value>
-
-Adds the header B<name> with the specified B<value> to the OCSP request
-that is sent to the responder.
-This may be repeated.
-
-=item B<-timeout seconds>
-
-connection timeout to the OCSP responder in seconds
-
-=item B<-CAfile file>, B<-CApath pathname>
-
-file or pathname containing trusted CA certificates. These are used to verify
-the signature on the OCSP response.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
-B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
-B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
-B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
-B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
-B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
-B<-verify_ip>, B<-verify_name>, B<-x509_strict>
-
-Set different certificate verification options.
-See L<verify(1)> manual page for details.
-
-=item B<-verify_other file>
-
-file containing additional certificates to search when attempting to locate
-the OCSP response signing certificate. Some responders omit the actual signer's
-certificate from the response: this option can be used to supply the necessary
-certificate in such cases.
-
-=item B<-trust_other>
-
-the certificates specified by the B<-verify_other> option should be explicitly
-trusted and no additional checks will be performed on them. This is useful
-when the complete responder certificate chain is not available or trusting a
-root CA is not appropriate.
-
-=item B<-VAfile file>
-
-file containing explicitly trusted responder certificates. Equivalent to the
-B<-verify_other> and B<-trust_other> options.
-
-=item B<-noverify>
-
-don't attempt to verify the OCSP response signature or the nonce values. This
-option will normally only be used for debugging since it disables all verification
-of the responders certificate.
-
-=item B<-no_intern>
-
-ignore certificates contained in the OCSP response when searching for the
-signers certificate. With this option the signers certificate must be specified
-with either the B<-verify_other> or B<-VAfile> options.
-
-=item B<-no_signature_verify>
-
-don't check the signature on the OCSP response. Since this option tolerates invalid
-signatures on OCSP responses it will normally only be used for testing purposes.
-
-=item B<-no_cert_verify>
-
-don't verify the OCSP response signers certificate at all. Since this option allows
-the OCSP response to be signed by any certificate it should only be used for
-testing purposes.
-
-=item B<-no_chain>
-
-do not use certificates in the response as additional untrusted CA
-certificates.
-
-=item B<-no_explicit>
-
-do not explicitly trust the root CA if it is set to be trusted for OCSP signing.
-
-=item B<-no_cert_checks>
-
-don't perform any additional checks on the OCSP response signers certificate.
-That is do not make any checks to see if the signers certificate is authorised
-to provide the necessary status information: as a result this option should
-only be used for testing purposes.
-
-=item B<-validity_period nsec>, B<-status_age age>
-
-these options specify the range of times, in seconds, which will be tolerated
-in an OCSP response. Each certificate status response includes a B<notBefore>
-time and an optional B<notAfter> time. The current time should fall between
-these two values, but the interval between the two times may be only a few
-seconds. In practice the OCSP responder and clients clocks may not be precisely
-synchronised and so such a check may fail. To avoid this the
-B<-validity_period> option can be used to specify an acceptable error range in
-seconds, the default value is 5 minutes.
-
-If the B<notAfter> time is omitted from a response then this means that new
-status information is immediately available. In this case the age of the
-B<notBefore> field is checked to see it is not older than B<age> seconds old.
-By default this additional check is not performed.
-
-=item B<-[digest]>
-
-this option sets digest algorithm to use for certificate identification in the
-OCSP request. Any digest supported by the OpenSSL B<dgst> command can be used.
-The default is SHA-1. This option may be used multiple times to specify the
-digest used by subsequent certificate identifiers.
-
-=back
-
-=head2 OCSP Server Options
-
-=over 4
-
-=item B<-index indexfile>
-
-B<indexfile> is a text index file in B<ca> format containing certificate revocation
-information.
-
-If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise
-it is in client mode. The request(s) the responder processes can be either specified on
-the command line (using B<issuer> and B<serial> options), supplied in a file (using the
-B<reqin> option) or via external OCSP clients (if B<port> or B<url> is specified).
-
-If the B<index> option is present then the B<CA> and B<rsigner> options must also be
-present.
-
-=item B<-CA file>
-
-CA certificate corresponding to the revocation information in B<indexfile>.
-
-=item B<-rsigner file>
-
-The certificate to sign OCSP responses with.
-
-=item B<-rother file>
-
-Additional certificates to include in the OCSP response.
-
-=item B<-resp_no_certs>
-
-Don't include any certificates in the OCSP response.
-
-=item B<-resp_key_id>
-
-Identify the signer certificate using the key ID, default is to use the subject name.
-
-=item B<-rkey file>
-
-The private key to sign OCSP responses with: if not present the file specified in the
-B<rsigner> option is used.
-
-=item B<-port portnum>
-
-Port to listen for OCSP requests on. The port may also be specified using the B<url>
-option.
-
-=item B<-nrequest number>
-
-The OCSP server will exit after receiving B<number> requests, default unlimited.
-
-=item B<-nmin minutes>, B<-ndays days>
-
-Number of minutes or days when fresh revocation information is available: used in the
-B<nextUpdate> field. If neither option is present then the B<nextUpdate> field
-is omitted meaning fresh revocation information is immediately available.
-
-=back
-
-=head1 OCSP Response verification.
-
-OCSP Response follows the rules specified in RFC2560.
-
-Initially the OCSP responder certificate is located and the signature on
-the OCSP request checked using the responder certificate's public key.
-
-Then a normal certificate verify is performed on the OCSP responder certificate
-building up a certificate chain in the process. The locations of the trusted
-certificates used to build the chain can be specified by the B<CAfile>
-and B<CApath> options or they will be looked for in the standard OpenSSL
-certificates directory.
-
-If the initial verify fails then the OCSP verify process halts with an
-error.
-
-Otherwise the issuing CA certificate in the request is compared to the OCSP
-responder certificate: if there is a match then the OCSP verify succeeds.
-
-Otherwise the OCSP responder certificate's CA is checked against the issuing
-CA certificate in the request. If there is a match and the OCSPSigning
-extended key usage is present in the OCSP responder certificate then the
-OCSP verify succeeds.
-
-Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders
-CA is checked to see if it is trusted for OCSP signing. If it is the OCSP
-verify succeeds.
-
-If none of these checks is successful then the OCSP verify fails.
-
-What this effectively means if that if the OCSP responder certificate is
-authorised directly by the CA it is issuing revocation information about
-(and it is correctly configured) then verification will succeed.
-
-If the OCSP responder is a "global responder" which can give details about
-multiple CAs and has its own separate certificate chain then its root
-CA can be trusted for OCSP signing. For example:
-
- openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
-
-Alternatively the responder certificate itself can be explicitly trusted
-with the B<-VAfile> option.
-
-=head1 NOTES
-
-As noted, most of the verify options are for testing or debugging purposes.
-Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global
-VA') B<-VAfile> options need to be used.
-
-The OCSP server is only useful for test and demonstration purposes: it is
-not really usable as a full OCSP responder. It contains only a very
-simple HTTP request handling and can only handle the POST form of OCSP
-queries. It also handles requests serially meaning it cannot respond to
-new requests until it has processed the current one. The text index file
-format of revocation is also inefficient for large quantities of revocation
-data.
-
-It is possible to run the B<ocsp> application in responder mode via a CGI
-script using the B<reqin> and B<respout> options.
-
-=head1 EXAMPLES
-
-Create an OCSP request and write it to a file:
-
- openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
-
-Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
-response to a file, print it out in text form, and verify the response:
-
- openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
- -url http://ocsp.myhost.com/ -resp_text -respout resp.der
-
-Read in an OCSP response and print out text form:
-
- openssl ocsp -respin resp.der -text -noverify
-
-OCSP server on port 8888 using a standard B<ca> configuration, and a separate
-responder certificate. All requests and responses are printed to a file.
-
- openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
- -text -out log.txt
-
-As above but exit after processing one request:
-
- openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
- -nrequest 1
-
-Query status information using an internally generated request:
-
- openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
- -issuer demoCA/cacert.pem -serial 1
-
-Query status information using request read from a file, and write the response
-to a second file.
-
- openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
- -reqin req.der -respout resp.der
-
-=head1 HISTORY
-
-The -no_alt_chains options was first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-openssl - OpenSSL command line tool
-
-=head1 SYNOPSIS
-
-B<openssl>
-I<command>
-[ I<command_opts> ]
-[ I<command_args> ]
-
-B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<public-key-algorithms>]
-
-B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
-
-=head1 DESCRIPTION
-
-OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL
-v2/v3) and Transport Layer Security (TLS v1) network protocols and related
-cryptography standards required by them.
-
-The B<openssl> program is a command line tool for using the various
-cryptography functions of OpenSSL's B<crypto> library from the shell.
-It can be used for
-
- o Creation and management of private keys, public keys and parameters
- o Public key cryptographic operations
- o Creation of X.509 certificates, CSRs and CRLs
- o Calculation of Message Digests
- o Encryption and Decryption with Ciphers
- o SSL/TLS Client and Server Tests
- o Handling of S/MIME signed or encrypted mail
- o Time Stamp requests, generation and verification
-
-=head1 COMMAND SUMMARY
-
-The B<openssl> program provides a rich variety of commands (I<command> in the
-SYNOPSIS above), each of which often has a wealth of options and arguments
-(I<command_opts> and I<command_args> in the SYNOPSIS).
-
-The list parameters B<standard-commands>, B<digest-commands>,
-and B<cipher-commands> output a list (one entry per line) of the names
-of all standard commands, message digest commands, or cipher commands,
-respectively, that are available in the present B<openssl> utility.
-
-The list parameters B<cipher-algorithms> and
-B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
-
- from => to
-
-The list parameter B<public-key-algorithms> lists all supported public
-key algorithms.
-
-The command B<no->I<XXX> tests whether a command of the
-specified name is available. If no command named I<XXX> exists, it
-returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1
-and prints I<XXX>. In both cases, the output goes to B<stdout> and
-nothing is printed to B<stderr>. Additional command line arguments
-are always ignored. Since for each cipher there is a command of the
-same name, this provides an easy way for shell scripts to test for the
-availability of ciphers in the B<openssl> program. (B<no->I<XXX> is
-not able to detect pseudo-commands such as B<quit>,
-B<list>, or B<no->I<XXX> itself.)
-
-=head2 Standard Commands
-
-=over 10
-
-=item L<B<asn1parse>|asn1parse(1)>
-
-Parse an ASN.1 sequence.
-
-=item L<B<ca>|ca(1)>
-
-Certificate Authority (CA) Management.
-
-=item L<B<ciphers>|ciphers(1)>
-
-Cipher Suite Description Determination.
-
-=item L<B<cms>|cms(1)>
-
-CMS (Cryptographic Message Syntax) utility
-
-=item L<B<crl>|crl(1)>
-
-Certificate Revocation List (CRL) Management.
-
-=item L<B<crl2pkcs7>|crl2pkcs7(1)>
-
-CRL to PKCS#7 Conversion.
-
-=item L<B<dgst>|dgst(1)>
-
-Message Digest Calculation.
-
-=item B<dh>
-
-Diffie-Hellman Parameter Management.
-Obsoleted by L<B<dhparam>|dhparam(1)>.
-
-=item L<B<dhparam>|dhparam(1)>
-
-Generation and Management of Diffie-Hellman Parameters. Superseded by
-L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
-
-
-=item L<B<dsa>|dsa(1)>
-
-DSA Data Management.
-
-=item L<B<dsaparam>|dsaparam(1)>
-
-DSA Parameter Generation and Management. Superseded by
-L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
-
-=item L<B<ec>|ec(1)>
-
-EC (Elliptic curve) key processing
-
-=item L<B<ecparam>|ecparam(1)>
-
-EC parameter manipulation and generation
-
-=item L<B<enc>|enc(1)>
-
-Encoding with Ciphers.
-
-=item L<B<engine>|engine(1)>
-
-Engine (loadable module) information and manipulation.
-
-=item L<B<errstr>|errstr(1)>
-
-Error Number to Error String Conversion.
-
-=item B<gendh>
-
-Generation of Diffie-Hellman Parameters.
-Obsoleted by L<B<dhparam>|dhparam(1)>.
-
-=item L<B<gendsa>|gendsa(1)>
-
-Generation of DSA Private Key from Parameters. Superseded by
-L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>
-
-=item L<B<genpkey>|genpkey(1)>
-
-Generation of Private Key or Parameters.
-
-=item L<B<genrsa>|genrsa(1)>
-
-Generation of RSA Private Key. Superseded by L<B<genpkey>|genpkey(1)>.
-
-=item L<B<nseq>|nseq(1)>
-
-Create or examine a Netscape certificate sequence
-
-=item L<B<ocsp>|ocsp(1)>
-
-Online Certificate Status Protocol utility.
-
-=item L<B<passwd>|passwd(1)>
-
-Generation of hashed passwords.
-
-=item L<B<pkcs12>|pkcs12(1)>
-
-PKCS#12 Data Management.
-
-=item L<B<pkcs7>|pkcs7(1)>
-
-PKCS#7 Data Management.
-
-=item L<B<pkey>|pkey(1)>
-
-Public and private key management.
-
-=item L<B<pkeyparam>|pkeyparam(1)>
-
-Public key algorithm parameter management.
-
-=item L<B<pkeyutl>|pkeyutl(1)>
-
-Public key algorithm cryptographic operation utility.
-
-=item L<B<rand>|rand(1)>
-
-Generate pseudo-random bytes.
-
-=item L<B<req>|req(1)>
-
-PKCS#10 X.509 Certificate Signing Request (CSR) Management.
-
-=item L<B<rsa>|rsa(1)>
-
-RSA key management.
-
-
-=item L<B<rsautl>|rsautl(1)>
-
-RSA utility for signing, verification, encryption, and decryption. Superseded
-by L<B<pkeyutl>|pkeyutl(1)>
-
-=item L<B<s_client>|s_client(1)>
-
-This implements a generic SSL/TLS client which can establish a transparent
-connection to a remote server speaking SSL/TLS. It's intended for testing
-purposes only and provides only rudimentary interface functionality but
-internally uses mostly all functionality of the OpenSSL B<ssl> library.
-
-=item L<B<s_server>|s_server(1)>
-
-This implements a generic SSL/TLS server which accepts connections from remote
-clients speaking SSL/TLS. It's intended for testing purposes only and provides
-only rudimentary interface functionality but internally uses mostly all
-functionality of the OpenSSL B<ssl> library. It provides both an own command
-line oriented protocol for testing SSL functions and a simple HTTP response
-facility to emulate an SSL/TLS-aware webserver.
-
-=item L<B<s_time>|s_time(1)>
-
-SSL Connection Timer.
-
-=item L<B<sess_id>|sess_id(1)>
-
-SSL Session Data Management.
-
-=item L<B<smime>|smime(1)>
-
-S/MIME mail processing.
-
-=item L<B<speed>|speed(1)>
-
-Algorithm Speed Measurement.
-
-=item L<B<spkac>|spkac(1)>
-
-SPKAC printing and generating utility
-
-=item L<B<ts>|ts(1)>
-
-Time Stamping Authority tool (client/server)
-
-=item L<B<verify>|verify(1)>
-
-X.509 Certificate Verification.
-
-=item L<B<version>|version(1)>
-
-OpenSSL Version Information.
-
-=item L<B<x509>|x509(1)>
-
-X.509 Certificate Data Management.
-
-=back
-
-=head2 Message Digest Commands
-
-=over 10
-
-=item B<md2>
-
-MD2 Digest
-
-=item B<md5>
-
-MD5 Digest
-
-=item B<mdc2>
-
-MDC2 Digest
-
-=item B<rmd160>
-
-RMD-160 Digest
-
-=item B<sha>
-
-SHA Digest
-
-=item B<sha1>
-
-SHA-1 Digest
-
-=item B<sha224>
-
-SHA-224 Digest
-
-=item B<sha256>
-
-SHA-256 Digest
-
-=item B<sha384>
-
-SHA-384 Digest
-
-=item B<sha512>
-
-SHA-512 Digest
-
-=back
-
-=head2 Encoding and Cipher Commands
-
-=over 10
-
-=item B<base64>
-
-Base64 Encoding
-
-=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb>
-
-Blowfish Cipher
-
-=item B<cast cast-cbc>
-
-CAST Cipher
-
-=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb>
-
-CAST5 Cipher
-
-=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb>
-
-DES Cipher
-
-=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb>
-
-Triple-DES Cipher
-
-=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb>
-
-IDEA Cipher
-
-=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb>
-
-RC2 Cipher
-
-=item B<rc4>
-
-RC4 Cipher
-
-=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb>
-
-RC5 Cipher
-
-=back
-
-=head1 COMMAND OPTIONS
-
-Details of which options are available depend on the specific command.
-This section describes some common options with common behavior.
-
-=head2 Common Options
-
-=over 10
-
-=item B<-help>
-
-Provides a terse summary of all options.
-
-=back
-
-=head2 Pass Phrase Options
-
-Several commands accept password arguments, typically using B<-passin>
-and B<-passout> for input and output passwords respectively. These allow
-the password to be obtained from a variety of sources. Both of these
-options take a single argument whose format is described below. If no
-password argument is given and a password is required then the user is
-prompted to enter one: this will typically be read from the current
-terminal with echoing turned off.
-
-=over 10
-
-=item B<pass:password>
-
-the actual password is B<password>. Since the password is visible
-to utilities (like 'ps' under Unix) this form should only be used
-where security is not important.
-
-=item B<env:var>
-
-obtain the password from the environment variable B<var>. Since
-the environment of other processes is visible on certain platforms
-(e.g. ps under certain Unix OSes) this option should be used with caution.
-
-=item B<file:pathname>
-
-the first line of B<pathname> is the password. If the same B<pathname>
-argument is supplied to B<-passin> and B<-passout> arguments then the first
-line will be used for the input password and the next line for the output
-password. B<pathname> need not refer to a regular file: it could for example
-refer to a device or named pipe.
-
-=item B<fd:number>
-
-read the password from the file descriptor B<number>. This can be used to
-send the data via a pipe for example.
-
-=item B<stdin>
-
-read the password from standard input.
-
-=back
-
-=head1 SEE ALSO
-
-L<asn1parse(1)>, L<ca(1)>, L<config(5)>,
-L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
-L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
-L<enc(1)>, L<engine(1)>, L<gendsa(1)>, L<genpkey(1)>,
-L<genrsa(1)>, L<nseq(1)>, L<openssl(1)>,
-L<passwd(1)>,
-L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,
-L<rand(1)>, L<req(1)>, L<rsa(1)>,
-L<rsautl(1)>, L<s_client(1)>,
-L<s_server(1)>, L<s_time(1)>,
-L<smime(1)>, L<spkac(1)>,
-L<verify(1)>, L<version(1)>, L<x509(1)>,
-L<crypto(3)>, L<ssl(3)>, L<x509v3_config(5)>
-
-=head1 HISTORY
-
-The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0;
-For notes on the availability of other commands, see their individual
-manual pages.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-passwd - compute password hashes
-
-=head1 SYNOPSIS
-
-B<openssl passwd>
-[B<-help>]
-[B<-crypt>]
-[B<-1>]
-[B<-apr1>]
-[B<-5>]
-[B<-6>]
-[B<-salt> I<string>]
-[B<-in> I<file>]
-[B<-stdin>]
-[B<-noverify>]
-[B<-quiet>]
-[B<-table>]
-{I<password>}
-
-=head1 DESCRIPTION
-
-The B<passwd> command computes the hash of a password typed at
-run-time or the hash of each password in a list. The password list is
-taken from the named file for option B<-in file>, from stdin for
-option B<-stdin>, or from the command line, or from the terminal otherwise.
-The Unix standard algorithm B<crypt> and the MD5-based BSD password
-algorithm B<1> and its Apache variant B<apr1> are available.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-crypt>
-
-Use the B<crypt> algorithm (default).
-
-=item B<-1>
-
-Use the MD5 based BSD password algorithm B<1>.
-
-=item B<-apr1>
-
-Use the B<apr1> algorithm (Apache variant of the BSD algorithm).
-
-=item B<-5>
-
-=item B<-6>
-
-Use the B<SHA256> / B<SHA512> based algorithms defined by Ulrich Drepper.
-See L<https://www.akkadia.org/drepper/SHA-crypt.txt>.
-
-=item B<-salt> I<string>
-
-Use the specified salt.
-When reading a password from the terminal, this implies B<-noverify>.
-
-=item B<-in> I<file>
-
-Read passwords from I<file>.
-
-=item B<-stdin>
-
-Read passwords from B<stdin>.
-
-=item B<-noverify>
-
-Don't verify when reading a password from the terminal.
-
-=item B<-quiet>
-
-Don't output warnings when passwords given at the command line are truncated.
-
-=item B<-table>
-
-In the output list, prepend the cleartext password and a TAB character
-to each password hash.
-
-=back
-
-=head1 EXAMPLES
-
-B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>.
-
-B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>.
-
-B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-pkcs12 - PKCS#12 file utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<pkcs12>
-[B<-help>]
-[B<-export>]
-[B<-chain>]
-[B<-inkey filename>]
-[B<-certfile filename>]
-[B<-name name>]
-[B<-caname name>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-noout>]
-[B<-nomacver>]
-[B<-nocerts>]
-[B<-clcerts>]
-[B<-cacerts>]
-[B<-nokeys>]
-[B<-info>]
-[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>]
-[B<-noiter>]
-[B<-maciter | -nomaciter | -nomac>]
-[B<-twopass>]
-[B<-descert>]
-[B<-certpbe cipher>]
-[B<-keypbe cipher>]
-[B<-macalg digest>]
-[B<-keyex>]
-[B<-keysig>]
-[B<-password arg>]
-[B<-passin arg>]
-[B<-passout arg>]
-[B<-rand file(s)>]
-[B<-CAfile file>]
-[B<-CApath dir>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-CSP name>]
-
-=head1 DESCRIPTION
-
-The B<pkcs12> command allows PKCS#12 files (sometimes referred to as
-PFX files) to be created and parsed. PKCS#12 files are used by several
-programs including Netscape, MSIE and MS Outlook.
-
-=head1 COMMAND OPTIONS
-
-There are a lot of options the meaning of some depends of whether a PKCS#12 file
-is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12
-file can be created by using the B<-export> option (see below).
-
-=head1 PARSING OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-in filename>
-
-This specifies filename of the PKCS#12 file to be parsed. Standard input is used
-by default.
-
-=item B<-out filename>
-
-The filename to write certificates and private keys to, standard output by
-default. They are all written in PEM format.
-
-=item B<-passin arg>
-
-the PKCS#12 file (i.e. input file) password source. For more information about
-the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
-L<openssl(1)>.
-
-=item B<-passout arg>
-
-pass phrase source to encrypt any outputted private keys with. For more
-information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section
-in L<openssl(1)>.
-
-=item B<-password arg>
-
-With -export, -password is equivalent to -passout.
-Otherwise, -password is equivalent to -passin.
-
-=item B<-noout>
-
-this option inhibits output of the keys and certificates to the output file
-version of the PKCS#12 file.
-
-=item B<-clcerts>
-
-only output client certificates (not CA certificates).
-
-=item B<-cacerts>
-
-only output CA certificates (not client certificates).
-
-=item B<-nocerts>
-
-no certificates at all will be output.
-
-=item B<-nokeys>
-
-no private keys will be output.
-
-=item B<-info>
-
-output additional information about the PKCS#12 file structure, algorithms used and
-iteration counts.
-
-=item B<-des>
-
-use DES to encrypt private keys before outputting.
-
-=item B<-des3>
-
-use triple DES to encrypt private keys before outputting, this is the default.
-
-=item B<-idea>
-
-use IDEA to encrypt private keys before outputting.
-
-=item B<-aes128>, B<-aes192>, B<-aes256>
-
-use AES to encrypt private keys before outputting.
-
-=item B<-camellia128>, B<-camellia192>, B<-camellia256>
-
-use Camellia to encrypt private keys before outputting.
-
-=item B<-nodes>
-
-don't encrypt the private keys at all.
-
-=item B<-nomacver>
-
-don't attempt to verify the integrity MAC before reading the file.
-
-=item B<-twopass>
-
-prompt for separate integrity and encryption passwords: most software
-always assumes these are the same so this option will render such
-PKCS#12 files unreadable.
-
-=back
-
-=head1 FILE CREATION OPTIONS
-
-=over 4
-
-=item B<-export>
-
-This option specifies that a PKCS#12 file will be created rather than
-parsed.
-
-=item B<-out filename>
-
-This specifies filename to write the PKCS#12 file to. Standard output is used
-by default.
-
-=item B<-in filename>
-
-The filename to read certificates and private keys from, standard input by
-default. They must all be in PEM format. The order doesn't matter but one
-private key and its corresponding certificate should be present. If additional
-certificates are present they will also be included in the PKCS#12 file.
-
-=item B<-inkey filename>
-
-file to read private key from. If not present then a private key must be present
-in the input file.
-
-=item B<-name friendlyname>
-
-This specifies the "friendly name" for the certificate and private key. This
-name is typically displayed in list boxes by software importing the file.
-
-=item B<-certfile filename>
-
-A filename to read additional certificates from.
-
-=item B<-caname friendlyname>
-
-This specifies the "friendly name" for other certificates. This option may be
-used multiple times to specify names for all certificates in the order they
-appear. Netscape ignores friendly names on other certificates whereas MSIE
-displays them.
-
-=item B<-pass arg>, B<-passout arg>
-
-the PKCS#12 file (i.e. output file) password source. For more information about
-the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
-L<openssl(1)>.
-
-=item B<-passin password>
-
-pass phrase source to decrypt any input private keys with. For more information
-about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
-L<openssl(1)>.
-
-=item B<-chain>
-
-if this option is present then an attempt is made to include the entire
-certificate chain of the user certificate. The standard CA store is used
-for this search. If the search fails it is considered a fatal error.
-
-=item B<-descert>
-
-encrypt the certificate using triple DES, this may render the PKCS#12
-file unreadable by some "export grade" software. By default the private
-key is encrypted using triple DES and the certificate using 40 bit RC2.
-
-=item B<-keypbe alg>, B<-certpbe alg>
-
-these options allow the algorithm used to encrypt the private key and
-certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name
-can be used (see B<NOTES> section for more information). If a cipher name
-(as output by the B<list-cipher-algorithms> command is specified then it
-is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only
-use PKCS#12 algorithms.
-
-=item B<-keyex|-keysig>
-
-specifies that the private key is to be used for key exchange or just signing.
-This option is only interpreted by MSIE and similar MS software. Normally
-"export grade" software will only allow 512 bit RSA keys to be used for
-encryption purposes but arbitrary length keys for signing. The B<-keysig>
-option marks the key for signing only. Signing only keys can be used for
-S/MIME signing, authenticode (ActiveX control signing) and SSL client
-authentication, however due to a bug only MSIE 5.0 and later support
-the use of signing only keys for SSL client authentication.
-
-=item B<-macalg digest>
-
-specify the MAC digest algorithm. If not included them SHA1 will be used.
-
-=item B<-nomaciter>, B<-noiter>
-
-these options affect the iteration counts on the MAC and key algorithms.
-Unless you wish to produce files compatible with MSIE 4.0 you should leave
-these options alone.
-
-To discourage attacks by using large dictionaries of common passwords the
-algorithm that derives keys from passwords can have an iteration count applied
-to it: this causes a certain part of the algorithm to be repeated and slows it
-down. The MAC is used to check the file integrity but since it will normally
-have the same password as the keys and certificates it could also be attacked.
-By default both MAC and encryption iteration counts are set to 2048, using
-these options the MAC and encryption iteration counts can be set to 1, since
-this reduces the file security you should not use these options unless you
-really have to. Most software supports both MAC and key iteration counts.
-MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter>
-option.
-
-=item B<-maciter>
-
-This option is included for compatibility with previous versions, it used
-to be needed to use MAC iterations counts but they are now used by default.
-
-=item B<-nomac>
-
-don't attempt to provide the MAC integrity.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-CAfile file>
-
-CA storage as a file.
-
-=item B<-CApath dir>
-
-CA storage as a directory. This directory must be a standard certificate
-directory: that is a hash of each subject name (using B<x509 -hash>) should be
-linked to each certificate.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-CSP name>
-
-write B<name> as a Microsoft CSP name.
-
-=back
-
-=head1 NOTES
-
-Although there are a large number of options most of them are very rarely
-used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
-for PKCS#12 file creation B<-export> and B<-name> are also used.
-
-If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present
-then all certificates will be output in the order they appear in the input
-PKCS#12 files. There is no guarantee that the first certificate present is
-the one corresponding to the private key. Certain software which requires
-a private key and certificate and assumes the first certificate in the
-file is the one corresponding to the private key: this may not always
-be the case. Using the B<-clcerts> option will solve this problem by only
-outputting the certificate corresponding to the private key. If the CA
-certificates are required then they can be output to a separate file using
-the B<-nokeys -cacerts> options to just output CA certificates.
-
-The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption
-algorithms for private keys and certificates to be specified. Normally
-the defaults are fine but occasionally software can't handle triple DES
-encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can
-be used to reduce the private key encryption to 40 bit RC2. A complete
-description of all algorithms is contained in the B<pkcs8> manual page.
-
-Prior 1.1 release passwords containing non-ASCII characters were encoded
-in non-compliant manner, which limited interoperability, in first hand
-with Windows. But switching to standard-compliant password encoding
-poses problem accessing old data protected with broken encoding. For
-this reason even legacy encodings is attempted when reading the
-data. If you use PKCS#12 files in production application you are advised
-to convert the data, because implemented heuristic approach is not
-MT-safe, its sole goal is to facilitate the data upgrade with this
-utility.
-
-=head1 EXAMPLES
-
-Parse a PKCS#12 file and output it to a file:
-
- openssl pkcs12 -in file.p12 -out file.pem
-
-Output only client certificates to a file:
-
- openssl pkcs12 -in file.p12 -clcerts -out file.pem
-
-Don't encrypt the private key:
-
- openssl pkcs12 -in file.p12 -out file.pem -nodes
-
-Print some info about a PKCS#12 file:
-
- openssl pkcs12 -in file.p12 -info -noout
-
-Create a PKCS#12 file:
-
- openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
-
-Include some extra certificates:
-
- openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
- -certfile othercerts.pem
-
-=head1 SEE ALSO
-
-L<pkcs8(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-pkcs7 - PKCS#7 utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<pkcs7>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-print_certs>]
-[B<-text>]
-[B<-noout>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. B<DER> format is DER encoded PKCS#7
-v1.5 structure.B<PEM> (the default) is a base64 encoded version of
-the DER form with header and footer lines.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read from or standard input if this
-option is not specified.
-
-=item B<-out filename>
-
-specifies the output filename to write to or standard output by
-default.
-
-=item B<-print_certs>
-
-prints out any certificates or CRLs contained in the file. They are
-preceded by their subject and issuer names in one line format.
-
-=item B<-text>
-
-prints out certificates details in full rather than just subject and
-issuer names.
-
-=item B<-noout>
-
-don't output the encoded version of the PKCS#7 structure (or certificates
-is B<-print_certs> is set).
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<pkcs7>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 EXAMPLES
-
-Convert a PKCS#7 file from PEM to DER:
-
- openssl pkcs7 -in file.pem -outform DER -out file.der
-
-Output all certificates in a file:
-
- openssl pkcs7 -in file.pem -print_certs -out certs.pem
-
-=head1 NOTES
-
-The PEM PKCS#7 format uses the header and footer lines:
-
- -----BEGIN PKCS7-----
- -----END PKCS7-----
-
-For compatibility with some CAs it will also accept:
-
- -----BEGIN CERTIFICATE-----
- -----END CERTIFICATE-----
-
-=head1 RESTRICTIONS
-
-There is no option to print out all the fields of a PKCS#7 file.
-
-This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
-cannot currently parse, for example, the new CMS as described in RFC2630.
-
-=head1 SEE ALSO
-
-L<crl2pkcs7(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-pkcs8 - PKCS#8 format private key conversion tool
-
-=head1 SYNOPSIS
-
-B<openssl> B<pkcs8>
-[B<-help>]
-[B<-topk8>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-in filename>]
-[B<-passin arg>]
-[B<-out filename>]
-[B<-passout arg>]
-[B<-iter count>]
-[B<-noiter>]
-[B<-nocrypt>]
-[B<-traditional>]
-[B<-v2 alg>]
-[B<-v2prf alg>]
-[B<-v1 alg>]
-[B<-engine id>]
-[B<-scrypt>]
-[B<-scrypt_N N>]
-[B<-scrypt_r r>]
-[B<-scrypt_p p>]
-
-=head1 DESCRIPTION
-
-The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
-both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
-format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-topk8>
-
-Normally a PKCS#8 private key is expected on input and a private key will be
-written to the output file. With the B<-topk8> option the situation is
-reversed: it reads a private key and writes a PKCS#8 format key.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format: see L<KEY FORMATS> for more details.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format: see L<KEY FORMATS> for more details.
-
-=item B<-traditional>
-
-When this option is present and B<-topk8> is not a traditional format private
-key is written.
-
-=item B<-in filename>
-
-This specifies the input filename to read a key from or standard input if this
-option is not specified. If the key is encrypted a pass phrase will be
-prompted for.
-
-=item B<-passin arg>
-
-the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-out filename>
-
-This specifies the output filename to write a key to or standard output by
-default. If any encryption options are set then a pass phrase will be
-prompted for. The output filename should B<not> be the same as the input
-filename.
-
-=item B<-passout arg>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-iter count>
-
-When creating new PKCS#8 containers, use a given number of iterations on
-the password in deriving the encryption key for the PKCS#8 output.
-High values increase the time required to brute-force a PKCS#8 container.
-
-=item B<-nocrypt>
-
-PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
-structures using an appropriate password based encryption algorithm. With
-this option an unencrypted PrivateKeyInfo structure is expected or output.
-This option does not encrypt private keys at all and should only be used
-when absolutely necessary. Certain software such as some versions of Java
-code signing software used unencrypted private keys.
-
-=item B<-v2 alg>
-
-This option sets the PKCS#5 v2.0 algorithm.
-
-The B<alg> argument is the encryption algorithm to use, valid values include
-B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256>
-is used.
-
-=item B<-v2prf alg>
-
-This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
-value would be B<hmacWithSHA256>. If this option isn't set then the default
-for the cipher is used or B<hmacWithSHA256> if there is no default.
-
-Some implementations may not support custom PRF algorithms and may require
-the B<hmacWithSHA1> option to work.
-
-=item B<-v1 alg>
-
-This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some
-older implementations may not support PKCS#5 v2.0 and may require this option.
-If not specified PKCS#5 v2.0 form is used.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<pkcs8>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<-scrypt>
-
-uses the B<scrypt> algorithm for private key encryption using default
-parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
-key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>,
-B<-scrypt_p> and B<-v2> options.
-
-B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p>
-
-sets the scrypt B<N>, B<r> or B<p> parameters.
-
-=back
-
-=head1 KEY FORMATS
-
-Various different formats are used by the pkcs8 utility. These are detailed
-below.
-
-If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is
-not used) then the input file must be in PKCS#8 format. An encrypted
-key is expected unless B<-nocrypt> is included.
-
-If B<-topk8> is not used and B<PEM> mode is set the output file will be an
-unencrypted private key in PKCS#8 format. If the B<-traditional> option is
-used then a traditional format private key is written instead.
-
-If B<-topk8> is not used and B<DER> mode is set the output file will be an
-unencrypted private key in traditional DER format.
-
-If B<-topk8> is used then any supported private key can be used for the input
-file in a format specified by B<-inform>. The output file will be encrypted
-PKCS#8 format using the specified encryption parameters unless B<-nocrypt>
-is included.
-
-=head1 NOTES
-
-By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
-AES with HMAC and SHA256 is used.
-
-Some older implementations do not support PKCS#5 v2.0 format and require
-the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
-encryption algorithms such as 56 bit DES.
-
-The encrypted form of a PEM encode PKCS#8 files uses the following
-headers and footers:
-
- -----BEGIN ENCRYPTED PRIVATE KEY-----
- -----END ENCRYPTED PRIVATE KEY-----
-
-The unencrypted form uses:
-
- -----BEGIN PRIVATE KEY-----
- -----END PRIVATE KEY-----
-
-Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
-counts are more secure that those encrypted using the traditional
-SSLeay compatible formats. So if additional security is considered
-important the keys should be converted.
-
-It is possible to write out DER encoded encrypted private keys in
-PKCS#8 format because the encryption details are included at an ASN1
-level whereas the traditional format includes them at a PEM level.
-
-=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
-
-Various algorithms can be used with the B<-v1> command line option,
-including PKCS#5 v1.5 and PKCS#12. These are described in more detail
-below.
-
-=over 4
-
-=item B<PBE-MD2-DES PBE-MD5-DES>
-
-These algorithms were included in the original PKCS#5 v1.5 specification.
-They only offer 56 bits of protection since they both use DES.
-
-=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES>
-
-These algorithms are not mentioned in the original PKCS#5 v1.5 specification
-but they use the same key derivation algorithm and are supported by some
-software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
-56 bit DES.
-
-=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40>
-
-These algorithms use the PKCS#12 password based encryption algorithm and
-allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
-
-=back
-
-=head1 EXAMPLES
-
-Convert a private key to PKCS#8 format using default parameters (AES with
-256 bit key and B<hmacWithSHA256>):
-
- openssl pkcs8 -in key.pem -topk8 -out enckey.pem
-
-Convert a private key to PKCS#8 unencrypted format:
-
- openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
-
-Convert a private key to PKCS#5 v2.0 format using triple DES:
-
- openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
-
-Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
-mode and B<hmacWithSHA512> PRF:
-
- openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem
-
-Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
-(DES):
-
- openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem
-
-Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
-(3DES):
-
- openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
-
-Read a DER unencrypted PKCS#8 format private key:
-
- openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
-
-Convert a private key from any PKCS#8 encrypted format to traditional format:
-
- openssl pkcs8 -in pk8.pem -traditional -out key.pem
-
-Convert a private key to PKCS#8 format, encrypting with AES-256 and with
-one million iterations of the password:
-
- openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
-
-=head1 STANDARDS
-
-Test vectors from this PKCS#5 v2.0 implementation were posted to the
-pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
-counts, several people confirmed that they could decrypt the private
-keys produced and Therefore it can be assumed that the PKCS#5 v2.0
-implementation is reasonably accurate at least as far as these
-algorithms are concerned.
-
-The format of PKCS#8 DSA (and other) private keys is not well documented:
-it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
-PKCS#8 private key format complies with this standard.
-
-=head1 BUGS
-
-There should be an option that prints out the encryption algorithm
-in use and other details such as the iteration count.
-
-=head1 SEE ALSO
-
-L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
-L<gendsa(1)>
-
-=head1 HISTORY
-
-The B<-iter> option was added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-pkey - public or private key processing tool
-
-=head1 SYNOPSIS
-
-B<openssl> B<pkey>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-in filename>]
-[B<-passin arg>]
-[B<-out filename>]
-[B<-passout arg>]
-[B<-traditional>]
-[B<-cipher>]
-[B<-text>]
-[B<-text_pub>]
-[B<-noout>]
-[B<-pubin>]
-[B<-pubout>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<pkey> command processes public or private keys. They can be converted
-between various forms and their components printed out.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format DER or PEM.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read a key from or standard input if this
-option is not specified. If the key is encrypted a pass phrase will be
-prompted for.
-
-=item B<-passin arg>
-
-the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-out filename>
-
-This specifies the output filename to write a key to or standard output if this
-option is not specified. If any encryption options are set then a pass phrase
-will be prompted for. The output filename should B<not> be the same as the input
-filename.
-
-=item B<-passout password>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-traditional>
-
-normally a private key is written using standard format: this is PKCS#8 form
-with the appropriate encryption algorithm (if any). If the B<-traditional>
-option is specified then the older "traditional" format is used instead.
-
-=item B<-cipher>
-
-These options encrypt the private key with the supplied cipher. Any algorithm
-name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
-
-=item B<-text>
-
-prints out the various public or private key components in
-plain text in addition to the encoded version.
-
-=item B<-text_pub>
-
-print out only public key components even if a private key is being processed.
-
-=item B<-noout>
-
-do not output the encoded version of the key.
-
-=item B<-pubin>
-
-by default a private key is read from the input file: with this
-option a public key is read instead.
-
-=item B<-pubout>
-
-by default a private key is output: with this option a public
-key will be output instead. This option is automatically set if
-the input is a public key.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<pkey>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 EXAMPLES
-
-To remove the pass phrase on an RSA private key:
-
- openssl pkey -in key.pem -out keyout.pem
-
-To encrypt a private key using triple DES:
-
- openssl pkey -in key.pem -des3 -out keyout.pem
-
-To convert a private key from PEM to DER format:
-
- openssl pkey -in key.pem -outform DER -out keyout.der
-
-To print out the components of a private key to standard output:
-
- openssl pkey -in key.pem -text -noout
-
-To print out the public components of a private key to standard output:
-
- openssl pkey -in key.pem -text_pub -noout
-
-To just output the public part of a private key:
-
- openssl pkey -in key.pem -pubout -out pubkey.pem
-
-=head1 SEE ALSO
-
-L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
-L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-pkeyparam - public key algorithm parameter processing tool
-
-=head1 SYNOPSIS
-
-B<openssl> B<pkeyparam>
-[B<-help>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-text>]
-[B<-noout>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<pkey> command processes public or private keys. They can be converted
-between various forms and their components printed out.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-in filename>
-
-This specifies the input filename to read parameters from or standard input if
-this option is not specified.
-
-=item B<-out filename>
-
-This specifies the output filename to write parameters to or standard output if
-this option is not specified.
-
-=item B<-text>
-
-prints out the parameters in plain text in addition to the encoded version.
-
-=item B<-noout>
-
-do not output the encoded version of the parameters.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<pkeyparam>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 EXAMPLE
-
-Print out text version of parameters:
-
- openssl pkeyparam -in param.pem -text
-
-=head1 NOTES
-
-There are no B<-inform> or B<-outform> options for this command because only
-PEM format is supported because the key type is determined by the PEM headers.
-
-=head1 SEE ALSO
-
-L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
-L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-pkeyutl - public key algorithm utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<pkeyutl>
-[B<-help>]
-[B<-in file>]
-[B<-out file>]
-[B<-sigfile file>]
-[B<-inkey file>]
-[B<-keyform PEM|DER|ENGINE>]
-[B<-passin arg>]
-[B<-peerkey file>]
-[B<-peerform PEM|DER|ENGINE>]
-[B<-pubin>]
-[B<-certin>]
-[B<-rev>]
-[B<-sign>]
-[B<-verify>]
-[B<-verifyrecover>]
-[B<-encrypt>]
-[B<-decrypt>]
-[B<-derive>]
-[B<-kdf algorithm>]
-[B<-kdflen length>]
-[B<-pkeyopt opt:value>]
-[B<-hexdump>]
-[B<-asn1parse>]
-[B<-engine id>]
-[B<-engine_impl>]
-
-=head1 DESCRIPTION
-
-The B<pkeyutl> command can be used to perform public key operations using
-any supported algorithm.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-in filename>
-
-This specifies the input filename to read data from or standard input
-if this option is not specified.
-
-=item B<-out filename>
-
-specifies the output filename to write to or standard output by
-default.
-
-=item B<-sigfile file>
-
-Signature file, required for B<verify> operations only
-
-=item B<-inkey file>
-
-the input key file, by default it should be a private key.
-
-=item B<-keyform PEM|DER|ENGINE>
-
-the key format PEM, DER or ENGINE. Default is PEM.
-
-=item B<-passin arg>
-
-the input key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-
-=item B<-peerkey file>
-
-the peer key file, used by key derivation (agreement) operations.
-
-=item B<-peerform PEM|DER|ENGINE>
-
-the peer key format PEM, DER or ENGINE. Default is PEM.
-
-=item B<-pubin>
-
-the input file is a public key.
-
-=item B<-certin>
-
-the input is a certificate containing a public key.
-
-=item B<-rev>
-
-reverse the order of the input buffer. This is useful for some libraries
-(such as CryptoAPI) which represent the buffer in little endian format.
-
-=item B<-sign>
-
-sign the input data and output the signed result. This requires
-a private key.
-
-=item B<-verify>
-
-verify the input data against the signature file and indicate if the
-verification succeeded or failed.
-
-=item B<-verifyrecover>
-
-verify the input data and output the recovered data.
-
-=item B<-encrypt>
-
-encrypt the input data using a public key.
-
-=item B<-decrypt>
-
-decrypt the input data using a private key.
-
-=item B<-derive>
-
-derive a shared secret using the peer key.
-
-=item B<-kdf algorithm>
-
-Use key derivation function B<algorithm>. The supported algorithms are
-at present B<TLS1-PRF> and B<HKDF>.
-Note: additional parameters and the KDF output length will normally have to be
-set for this to work. See L<EVP_PKEY_HKDF(3)> and L<EVP_PKEY_TLS1_PRF(3)>
-for the supported string parameters of each algorithm.
-
-=item B<-kdflen length>
-
-Set the output length for KDF.
-
-=item B<-pkeyopt opt:value>
-
-Public key options specified as opt:value. See NOTES below for more details.
-
-=item B<-hexdump>
-
-hex dump the output data.
-
-=item B<-asn1parse>
-
-asn1parse the output data, this is useful when combined with the
-B<-verifyrecover> option when an ASN1 structure is signed.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<-engine_impl>
-
-When used with the B<-engine> option, it specifies to also use
-engine B<id> for crypto operations.
-
-=back
-
-=head1 NOTES
-
-The operations and options supported vary according to the key algorithm
-and its implementation. The OpenSSL operations and options are indicated below.
-
-Unless otherwise mentioned all algorithms support the B<digest:alg> option
-which specifies the digest in use for sign, verify and verifyrecover operations.
-The value B<alg> should represent a digest name as used in the
-EVP_get_digestbyname() function for example B<sha1>.
-This value is used only for sanity-checking the lengths of data passed in to
-the B<pkeyutl> and for creating the structures that make up the signature
-(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
-In case of RSA, ECDSA and DSA signatures, this utility
-will not perform hashing on input data but rather use the data directly as
-input of signature algorithm. Depending on key type, signature type and mode
-of padding, the maximum acceptable lengths of input data differ. In general,
-with RSA the signed data can't be longer than the key modulus, in case of ECDSA
-and DSA the data shouldn't be longer than field size, otherwise it will be
-silently truncated to field size.
-
-In other words, if the value of digest is B<sha1> the input should be 20 bytes
-long binary encoding of SHA-1 hash function output.
-
-=head1 RSA ALGORITHM
-
-The RSA algorithm generally supports the encrypt, decrypt, sign,
-verify and verifyrecover operations. However, some padding modes
-support only a subset of these operations. The following additional
-B<pkeyopt> values are supported:
-
-=over 4
-
-=item B<rsa_padding_mode:mode>
-
-This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for
-PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep>
-for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
-
-In PKCS#1 padding if the message digest is not set then the supplied data is
-signed or verified directly instead of using a B<DigestInfo> structure. If a
-digest is set then the a B<DigestInfo> structure is used and its the length
-must correspond to the digest type.
-
-For B<oaep> mode only encryption and decryption is supported.
-
-For B<x931> if the digest type is set it is used to format the block data
-otherwise the first byte is used to specify the X9.31 digest ID. Sign,
-verify and verifyrecover are can be performed in this mode.
-
-For B<pss> mode only sign and verify are supported and the digest type must be
-specified.
-
-=item B<rsa_pss_saltlen:len>
-
-For B<pss> mode only this option specifies the salt length. Two special values
-are supported: -1 sets the salt length to the digest length. When signing -2
-sets the salt length to the maximum permissible value. When verifying -2 causes
-the salt length to be automatically determined based on the B<PSS> block
-structure.
-
-=back
-
-=head1 DSA ALGORITHM
-
-The DSA algorithm supports signing and verification operations only. Currently
-there are no additional options other than B<digest>. Only the SHA1
-digest can be used and this digest is assumed by default.
-
-=head1 DH ALGORITHM
-
-The DH algorithm only supports the derivation operation and no additional
-options.
-
-=head1 EC ALGORITHM
-
-The EC algorithm supports sign, verify and derive operations. The sign and
-verify operations use ECDSA and derive uses ECDH. Currently there are no
-additional options other than B<digest>. Only the SHA1 digest can be used and
-this digest is assumed by default.
-
-=head1 X25519 ALGORITHM
-
-The X25519 algorithm supports key derivation only. Currently there are no
-additional options.
-
-=head1 EXAMPLES
-
-Sign some data using a private key:
-
- openssl pkeyutl -sign -in file -inkey key.pem -out sig
-
-Recover the signed data (e.g. if an RSA key is used):
-
- openssl pkeyutl -verifyrecover -in sig -inkey key.pem
-
-Verify the signature (e.g. a DSA key):
-
- openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
-
-Sign data using a message digest value (this is currently only valid for RSA):
-
- openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
-
-Derive a shared secret value:
-
- openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
-
-Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and
-seed consisting of the single byte 0xFF:
-
- openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
- -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
-
-=head1 SEE ALSO
-
-L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
-L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
-L<EVP_PKEY_HKDF(3)>, L<EVP_PKEY_TLS1_PRF(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-rand - generate pseudo-random bytes
-
-=head1 SYNOPSIS
-
-B<openssl rand>
-[B<-help>]
-[B<-out> I<file>]
-[B<-rand> I<file(s)>]
-[B<-base64>]
-[B<-hex>]
-I<num>
-
-=head1 DESCRIPTION
-
-The B<rand> command outputs I<num> pseudo-random bytes after seeding
-the random number generator once. As in other B<openssl> command
-line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd>
-in addition to the files given in the B<-rand> option. A new
-I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough
-seeding was obtained from these sources.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-out> I<file>
-
-Write to I<file> instead of standard output.
-
-=item B<-rand> I<file(s)>
-
-Use specified file or files or EGD socket (see L<RAND_egd(3)>)
-for seeding the random number generator.
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-base64>
-
-Perform base64 encoding on the output.
-
-=item B<-hex>
-
-Show the output as a hex string.
-
-=back
-
-=head1 SEE ALSO
-
-L<RAND_bytes(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment
-Original text by James Westby, contributed under the OpenSSL license.
-
-=head1 NAME
-
-c_rehash, rehash - Create symbolic links to files named by the hash values
-
-=head1 SYNOPSIS
-
-B<openssl>
-B<rehash>
-B<[-h]>
-B<[-help]>
-B<[-old]>
-B<[-n]>
-B<[-v]>
-[ I<directory>...]
-
-B<c_rehash>
-I<flags...>
-
-=head1 DESCRIPTION
-
-On some platforms, the OpenSSL B<rehash> command is available as
-an external script called B<c_rehash>. They are functionally equivalent,
-except for minor differences noted below.
-
-B<rehash> scans directories and calculates a hash value of each
-C<.pem>, C<.crt>, C<.cer>, or C<.crl>
-file in the specified directory list and creates symbolic links
-for each file, where the name of the link is the hash value.
-(If the platform does not support symbolic links, a copy is made.)
-This utility is useful as many programs that use OpenSSL require
-directories to be set up like this in order to find certificates.
-
-If any directories are named on the command line, then those are
-processed in turn. If not, then the B<SSL_CERT_DIR> environment variable
-is consulted; this should be a colon-separated list of directories,
-like the Unix B<PATH> variable.
-If that is not set then the default directory (installation-specific
-but often B</usr/local/ssl/certs>) is processed.
-
-In order for a directory to be processed, the user must have write
-permissions on that directory, otherwise an error will be generated.
-
-The links created are of the form C<HHHHHHHH.D>, where each B<H>
-is a hexadecimal character and B<D> is a single decimal digit.
-When processing a directory, B<rehash> will first remove all links
-that have a name in that syntax, even if they are being used for some
-other purpose.
-To skip the removal step, use the B<-n> flag.
-Hashes for CRL's look similar except the letter B<r> appears after
-the period, like this: C<HHHHHHHH.rD>.
-
-Multiple objects may have the same hash; they will be indicated by
-incrementing the B<D> value. Duplicates are found by comparing the
-full SHA-1 fingerprint. A warning will be displayed if a duplicate
-is found.
-
-A warning will also be displayed if there are files that
-cannot be parsed as either a certificate or a CRL or if
-more than one such object appears in the file.
-
-=head2 Script Configuration
-
-The B<c_rehash> script
-uses the B<openssl> program to compute the hashes and
-fingerprints. If not found in the user's B<PATH>, then set the
-B<OPENSSL> environment variable to the full pathname.
-Any program can be used, it will be invoked as follows for either
-a certificate or CRL:
-
- $OPENSSL x509 -hash -fingerprint -noout -in FILENAME
- $OPENSSL crl -hash -fingerprint -noout -in FILENAME
-
-where B<FILENAME> is the filename. It must output the hash of the
-file on the first line, and the fingerprint on the second,
-optionally prefixed with some text and an equals sign.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help> B<-h>
-
-Display a brief usage message.
-
-=item B<-old>
-
-Use old-style hashing (MD5, as opposed to SHA-1) for generating
-links to be used for releases before 1.0.0.
-Note that current versions will not use the old style.
-
-=item B<-n>
-
-Do not remove existing links.
-This is needed when keeping new and old-style links in the same directory.
-
-=item B<-v>
-
-Print messages about old links removed and new links created.
-By default, B<rehash> only lists each directory as it is processed.
-
-=back
-
-=head1 ENVIRONMENT
-
-=over
-
-=item B<OPENSSL>
-
-The path to an executable to use to generate hashes and
-fingerprints (see above).
-
-=item B<SSL_CERT_DIR>
-
-Colon separated list of directories to operate on.
-Ignored if directories are listed on the command line.
-
-=back
-
-=head1 SEE ALSO
-
-L<openssl(1)>,
-L<crl(1)>.
-L<x509(1)>.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-req - PKCS#10 certificate request and certificate generating utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<req>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER>]
-[B<-in filename>]
-[B<-passin arg>]
-[B<-out filename>]
-[B<-passout arg>]
-[B<-text>]
-[B<-pubkey>]
-[B<-noout>]
-[B<-verify>]
-[B<-modulus>]
-[B<-new>]
-[B<-rand file(s)>]
-[B<-newkey rsa:bits>]
-[B<-newkey alg:file>]
-[B<-nodes>]
-[B<-key filename>]
-[B<-keyform PEM|DER>]
-[B<-keyout filename>]
-[B<-keygen_engine id>]
-[B<-[digest]>]
-[B<-config filename>]
-[B<-multivalue-rdn>]
-[B<-x509>]
-[B<-days n>]
-[B<-set_serial n>]
-[B<-newhdr>]
-[B<-extensions section>]
-[B<-reqexts section>]
-[B<-utf8>]
-[B<-nameopt>]
-[B<-reqopt>]
-[B<-subject>]
-[B<-subj arg>]
-[B<-batch>]
-[B<-verbose>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<req> command primarily creates and processes certificate requests
-in PKCS#10 format. It can additionally create self signed certificates
-for use as root CAs for example.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. The B<DER> option uses an ASN1 DER encoded
-form compatible with the PKCS#10. The B<PEM> form is the default format: it
-consists of the B<DER> format base64 encoded with additional header and
-footer lines.
-
-=item B<-outform DER|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read a request from or standard input
-if this option is not specified. A request is only read if the creation
-options (B<-new> and B<-newkey>) are not specified.
-
-=item B<-passin arg>
-
-the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-out filename>
-
-This specifies the output filename to write to or standard output by
-default.
-
-=item B<-passout arg>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-text>
-
-prints out the certificate request in text form.
-
-=item B<-subject>
-
-prints out the request subject (or certificate subject if B<-x509> is
-specified)
-
-=item B<-pubkey>
-
-outputs the public key.
-
-=item B<-noout>
-
-this option prevents output of the encoded version of the request.
-
-=item B<-modulus>
-
-this option prints out the value of the modulus of the public key
-contained in the request.
-
-=item B<-verify>
-
-verifies the signature on the request.
-
-=item B<-new>
-
-this option generates a new certificate request. It will prompt
-the user for the relevant field values. The actual fields
-prompted for and their maximum and minimum sizes are specified
-in the configuration file and any requested extensions.
-
-If the B<-key> option is not used it will generate a new RSA private
-key using information specified in the configuration file.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-newkey arg>
-
-this option creates a new certificate request and a new private
-key. The argument takes one of several forms. B<rsa:nbits>, where
-B<nbits> is the number of bits, generates an RSA key B<nbits>
-in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified,
-the default key size, specified in the configuration file is used.
-
-All other algorithms support the B<-newkey alg:file> form, where file may be
-an algorithm parameter file, created by the B<genpkey -genparam> command
-or and X.509 certificate for a key with appropriate algorithm.
-
-B<param:file> generates a key using the parameter file or certificate B<file>,
-the algorithm is determined by the parameters. B<algname:file> use algorithm
-B<algname> and parameter file B<file>: the two algorithms must match or an
-error occurs. B<algname> just uses algorithm B<algname>, and parameters,
-if necessary should be specified via B<-pkeyopt> parameter.
-
-B<dsa:filename> generates a DSA key using the parameters
-in the file B<filename>. B<ec:filename> generates EC key (usable both with
-ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R
-34.10-2001 key (requires B<ccgost> engine configured in the configuration
-file). If just B<gost2001> is specified a parameter set should be
-specified by B<-pkeyopt paramset:X>
-
-
-=item B<-pkeyopt opt:value>
-
-set the public key algorithm option B<opt> to B<value>. The precise set of
-options supported depends on the public key algorithm used and its
-implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page
-for more details.
-
-=item B<-key filename>
-
-This specifies the file to read the private key from. It also
-accepts PKCS#8 format private keys for PEM format files.
-
-=item B<-keyform PEM|DER>
-
-the format of the private key file specified in the B<-key>
-argument. PEM is the default.
-
-=item B<-keyout filename>
-
-this gives the filename to write the newly created private key to.
-If this option is not specified then the filename present in the
-configuration file is used.
-
-=item B<-nodes>
-
-if this option is specified then if a private key is created it
-will not be encrypted.
-
-=item B<-[digest]>
-
-this specifies the message digest to sign the request.
-Any digest supported by the OpenSSL B<dgst> command can be used.
-This overrides the digest algorithm specified in
-the configuration file.
-
-Some public key algorithms may override this choice. For instance, DSA
-signatures always use SHA1, GOST R 34.10 signatures always use
-GOST R 34.11-94 (B<-md_gost94>).
-
-=item B<-config filename>
-
-this allows an alternative configuration file to be specified,
-this overrides the compile time filename or any specified in
-the B<OPENSSL_CONF> environment variable.
-
-=item B<-subj arg>
-
-sets subject name for new request or supersedes the subject name
-when processing a request.
-The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by \ (backslash), no spaces are skipped.
-
-=item B<-multivalue-rdn>
-
-this option causes the -subj argument to be interpreted with full
-support for multivalued RDNs. Example:
-
-I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
-
-If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
-
-=item B<-x509>
-
-this option outputs a self signed certificate instead of a certificate
-request. This is typically used to generate a test certificate or
-a self signed root CA. The extensions added to the certificate
-(if any) are specified in the configuration file. Unless specified
-using the B<set_serial> option, a large random number will be used for
-the serial number.
-
-=item B<-days n>
-
-when the B<-x509> option is being used this specifies the number of
-days to certify the certificate for. The default is 30 days.
-
-=item B<-set_serial n>
-
-serial number to use when outputting a self signed certificate. This
-may be specified as a decimal value or a hex value if preceded by B<0x>.
-It is possible to use negative serial numbers but this is not recommended.
-
-=item B<-extensions section>
-
-=item B<-reqexts section>
-
-these options specify alternative sections to include certificate
-extensions (if the B<-x509> option is present) or certificate
-request extensions. This allows several different sections to
-be used in the same configuration file to specify requests for
-a variety of purposes.
-
-=item B<-utf8>
-
-this option causes field values to be interpreted as UTF8 strings, by
-default they are interpreted as ASCII. This means that the field
-values, whether prompted from a terminal or obtained from a
-configuration file, must be valid UTF8 strings.
-
-=item B<-nameopt option>
-
-option which determines how the subject or issuer names are displayed. The
-B<option> argument can be a single option or multiple options separated by
-commas. Alternatively the B<-nameopt> switch may be used more than once to
-set multiple options. See the L<x509(1)> manual page for details.
-
-=item B<-reqopt>
-
-customise the output format used with B<-text>. The B<option> argument can be
-a single option or multiple options separated by commas.
-
-See discussion of the B<-certopt> parameter in the L<x509(1)>
-command.
-
-=item B<-newhdr>
-
-Adds the word B<NEW> to the PEM file header and footer lines on the outputted
-request. Some software (Netscape certificate server) and some CAs need this.
-
-=item B<-batch>
-
-non-interactive mode.
-
-=item B<-verbose>
-
-print extra details about the operations being performed.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<req>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<-keygen_engine id>
-
-specifies an engine (by its unique B<id> string) which would be used
-for key generation operations.
-
-=back
-
-=head1 CONFIGURATION FILE FORMAT
-
-The configuration options are specified in the B<req> section of
-the configuration file. As with all configuration files if no
-value is specified in the specific section (i.e. B<req>) then
-the initial unnamed or B<default> section is searched too.
-
-The options available are described in detail below.
-
-=over 4
-
-=item B<input_password output_password>
-
-The passwords for the input private key file (if present) and
-the output private key file (if one will be created). The
-command line options B<passin> and B<passout> override the
-configuration file values.
-
-=item B<default_bits>
-
-Specifies the default key size in bits.
-
-This option is used in conjunction with the B<-new> option to generate
-a new key. It can be overridden by specifying an explicit key size in
-the B<-newkey> option. The smallest accepted key size is 512 bits. If
-no key size is specified then 2048 bits is used.
-
-=item B<default_keyfile>
-
-This is the default filename to write a private key to. If not
-specified the key is written to standard output. This can be
-overridden by the B<-keyout> option.
-
-=item B<oid_file>
-
-This specifies a file containing additional B<OBJECT IDENTIFIERS>.
-Each line of the file should consist of the numerical form of the
-object identifier followed by white space then the short name followed
-by white space and finally the long name.
-
-=item B<oid_section>
-
-This specifies a section in the configuration file containing extra
-object identifiers. Each line should consist of the short name of the
-object identifier followed by B<=> and the numerical form. The short
-and long names are the same when this option is used.
-
-=item B<RANDFILE>
-
-This specifies a filename in which random number seed information is
-placed and read from, or an EGD socket (see L<RAND_egd(3)>).
-It is used for private key generation.
-
-=item B<encrypt_key>
-
-If this is set to B<no> then if a private key is generated it is
-B<not> encrypted. This is equivalent to the B<-nodes> command line
-option. For compatibility B<encrypt_rsa_key> is an equivalent option.
-
-=item B<default_md>
-
-This option specifies the digest algorithm to use.
-Any digest supported by the OpenSSL B<dgst> command can be used.
-If not present then MD5 is used.
-This option can be overridden on the command line.
-
-=item B<string_mask>
-
-This option masks out the use of certain string types in certain
-fields. Most users will not need to change this option.
-
-It can be set to several values B<default> which is also the default
-option uses PrintableStrings, T61Strings and BMPStrings if the
-B<pkix> value is used then only PrintableStrings and BMPStrings will
-be used. This follows the PKIX recommendation in RFC2459. If the
-B<utf8only> option is used then only UTF8Strings will be used: this
-is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
-option just uses PrintableStrings and T61Strings: certain software has
-problems with BMPStrings and UTF8Strings: in particular Netscape.
-
-=item B<req_extensions>
-
-this specifies the configuration file section containing a list of
-extensions to add to the certificate request. It can be overridden
-by the B<-reqexts> command line switch. See the
-L<x509v3_config(5)> manual page for details of the
-extension section format.
-
-=item B<x509_extensions>
-
-this specifies the configuration file section containing a list of
-extensions to add to certificate generated when the B<-x509> switch
-is used. It can be overridden by the B<-extensions> command line switch.
-
-=item B<prompt>
-
-if set to the value B<no> this disables prompting of certificate fields
-and just takes values from the config file directly. It also changes the
-expected format of the B<distinguished_name> and B<attributes> sections.
-
-=item B<utf8>
-
-if set to the value B<yes> then field values to be interpreted as UTF8
-strings, by default they are interpreted as ASCII. This means that
-the field values, whether prompted from a terminal or obtained from a
-configuration file, must be valid UTF8 strings.
-
-=item B<attributes>
-
-this specifies the section containing any request attributes: its format
-is the same as B<distinguished_name>. Typically these may contain the
-challengePassword or unstructuredName types. They are currently ignored
-by OpenSSL's request signing utilities but some CAs might want them.
-
-=item B<distinguished_name>
-
-This specifies the section containing the distinguished name fields to
-prompt for when generating a certificate or certificate request. The format
-is described in the next section.
-
-=back
-
-=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
-
-There are two separate formats for the distinguished name and attribute
-sections. If the B<prompt> option is set to B<no> then these sections
-just consist of field names and values: for example,
-
- CN=My Name
- OU=My Organization
- emailAddress=someone@somewhere.org
-
-This allows external programs (e.g. GUI based) to generate a template file
-with all the field names and values and just pass it to B<req>. An example
-of this kind of configuration file is contained in the B<EXAMPLES> section.
-
-Alternatively if the B<prompt> option is absent or not set to B<no> then the
-file contains field prompting information. It consists of lines of the form:
-
- fieldName="prompt"
- fieldName_default="default field value"
- fieldName_min= 2
- fieldName_max= 4
-
-"fieldName" is the field name being used, for example commonName (or CN).
-The "prompt" string is used to ask the user to enter the relevant
-details. If the user enters nothing then the default value is used if no
-default value is present then the field is omitted. A field can
-still be omitted if a default value is present if the user just
-enters the '.' character.
-
-The number of characters entered must be between the fieldName_min and
-fieldName_max limits: there may be additional restrictions based
-on the field being used (for example countryName can only ever be
-two characters long and must fit in a PrintableString).
-
-Some fields (such as organizationName) can be used more than once
-in a DN. This presents a problem because configuration files will
-not recognize the same name occurring twice. To avoid this problem
-if the fieldName contains some characters followed by a full stop
-they will be ignored. So for example a second organizationName can
-be input by calling it "1.organizationName".
-
-The actual permitted field names are any object identifier short or
-long names. These are compiled into OpenSSL and include the usual
-values such as commonName, countryName, localityName, organizationName,
-organizationalUnitName, stateOrProvinceName. Additionally emailAddress
-is include as well as name, surname, givenName initials and dnQualifier.
-
-Additional object identifiers can be defined with the B<oid_file> or
-B<oid_section> options in the configuration file. Any additional fields
-will be treated as though they were a DirectoryString.
-
-
-=head1 EXAMPLES
-
-Examine and verify certificate request:
-
- openssl req -in req.pem -text -verify -noout
-
-Create a private key and then generate a certificate request from it:
-
- openssl genrsa -out key.pem 2048
- openssl req -new -key key.pem -out req.pem
-
-The same but just using req:
-
- openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
-
-Generate a self signed root certificate:
-
- openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
-
-Example of a file pointed to by the B<oid_file> option:
-
- 1.2.3.4 shortName A longer Name
- 1.2.3.6 otherName Other longer Name
-
-Example of a section pointed to by B<oid_section> making use of variable
-expansion:
-
- testoid1=1.2.3.5
- testoid2=${testoid1}.6
-
-Sample configuration file prompting for field values:
-
- [ req ]
- default_bits = 2048
- default_keyfile = privkey.pem
- distinguished_name = req_distinguished_name
- attributes = req_attributes
- req_extensions = v3_ca
-
- dirstring_type = nobmp
-
- [ req_distinguished_name ]
- countryName = Country Name (2 letter code)
- countryName_default = AU
- countryName_min = 2
- countryName_max = 2
-
- localityName = Locality Name (eg, city)
-
- organizationalUnitName = Organizational Unit Name (eg, section)
-
- commonName = Common Name (eg, YOUR name)
- commonName_max = 64
-
- emailAddress = Email Address
- emailAddress_max = 40
-
- [ req_attributes ]
- challengePassword = A challenge password
- challengePassword_min = 4
- challengePassword_max = 20
-
- [ v3_ca ]
-
- subjectKeyIdentifier=hash
- authorityKeyIdentifier=keyid:always,issuer:always
- basicConstraints = critical, CA:true
-
-Sample configuration containing all field values:
-
-
- RANDFILE = $ENV::HOME/.rnd
-
- [ req ]
- default_bits = 2048
- default_keyfile = keyfile.pem
- distinguished_name = req_distinguished_name
- attributes = req_attributes
- prompt = no
- output_password = mypass
-
- [ req_distinguished_name ]
- C = GB
- ST = Test State or Province
- L = Test Locality
- O = Organization Name
- OU = Organizational Unit Name
- CN = Common Name
- emailAddress = test@email.address
-
- [ req_attributes ]
- challengePassword = A challenge password
-
-
-=head1 NOTES
-
-The header and footer lines in the B<PEM> format are normally:
-
- -----BEGIN CERTIFICATE REQUEST-----
- -----END CERTIFICATE REQUEST-----
-
-some software (some versions of Netscape certificate server) instead needs:
-
- -----BEGIN NEW CERTIFICATE REQUEST-----
- -----END NEW CERTIFICATE REQUEST-----
-
-which is produced with the B<-newhdr> option but is otherwise compatible.
-Either form is accepted transparently on input.
-
-The certificate requests generated by B<Xenroll> with MSIE have extensions
-added. It includes the B<keyUsage> extension which determines the type of
-key (signature only or general purpose) and any additional OIDs entered
-by the script in an extendedKeyUsage extension.
-
-=head1 DIAGNOSTICS
-
-The following messages are frequently asked about:
-
- Using configuration from /some/path/openssl.cnf
- Unable to load config info
-
-This is followed some time later by...
-
- unable to find 'distinguished_name' in config
- problems making Certificate Request
-
-The first error message is the clue: it can't find the configuration
-file! Certain operations (like examining a certificate request) don't
-need a configuration file so its use isn't enforced. Generation of
-certificates or requests however does need a configuration file. This
-could be regarded as a bug.
-
-Another puzzling message is this:
-
- Attributes:
- a0:00
-
-this is displayed when no attributes are present and the request includes
-the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
-0x00). If you just see:
-
- Attributes:
-
-then the B<SET OF> is missing and the encoding is technically invalid (but
-it is tolerated). See the description of the command line option B<-asn1-kludge>
-for more information.
-
-=head1 ENVIRONMENT VARIABLES
-
-The variable B<OPENSSL_CONF> if defined allows an alternative configuration
-file location to be specified, it will be overridden by the B<-config> command
-line switch if it is present.
-
-=head1 BUGS
-
-OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
-treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
-This can cause problems if you need characters that aren't available in
-PrintableStrings and you don't want to or can't use BMPStrings.
-
-As a consequence of the T61String handling the only correct way to represent
-accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
-currently chokes on these. If you have to use accented characters with Netscape
-and MSIE then you currently need to use the invalid T61String form.
-
-The current prompting is not very friendly. It doesn't allow you to confirm what
-you've just entered. Other things like extensions in certificate requests are
-statically defined in the configuration file. Some of these: like an email
-address in subjectAltName should be input by the user.
-
-=head1 SEE ALSO
-
-L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
-L<gendsa(1)>, L<config(5)>,
-L<x509v3_config(5)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-rsa - RSA key processing tool
-
-=head1 SYNOPSIS
-
-B<openssl> B<rsa>
-[B<-help>]
-[B<-inform PEM|NET|DER>]
-[B<-outform PEM|NET|DER>]
-[B<-in filename>]
-[B<-passin arg>]
-[B<-out filename>]
-[B<-passout arg>]
-[B<-aes128>]
-[B<-aes192>]
-[B<-aes256>]
-[B<-camellia128>]
-[B<-camellia192>]
-[B<-camellia256>]
-[B<-des>]
-[B<-des3>]
-[B<-idea>]
-[B<-text>]
-[B<-noout>]
-[B<-modulus>]
-[B<-check>]
-[B<-pubin>]
-[B<-pubout>]
-[B<-RSAPublicKey_in>]
-[B<-RSAPublicKey_out>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<rsa> command processes RSA keys. They can be converted between various
-forms and their components printed out. B<Note> this command uses the
-traditional SSLeay compatible format for private key encryption: newer
-applications should use the more secure PKCS#8 format using the B<pkcs8>
-utility.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|NET|PEM>
-
-This specifies the input format. The B<DER> option uses an ASN1 DER encoded
-form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format.
-The B<PEM> form is the default format: it consists of the B<DER> format base64
-encoded with additional header and footer lines. On input PKCS#8 format private
-keys are also accepted. The B<NET> form is a format is described in the B<NOTES>
-section.
-
-=item B<-outform DER|NET|PEM>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read a key from or standard input if this
-option is not specified. If the key is encrypted a pass phrase will be
-prompted for.
-
-=item B<-passin arg>
-
-the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-out filename>
-
-This specifies the output filename to write a key to or standard output if this
-option is not specified. If any encryption options are set then a pass phrase
-will be prompted for. The output filename should B<not> be the same as the input
-filename.
-
-=item B<-passout password>
-
-the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
-
-These options encrypt the private key with the specified
-cipher before outputting it. A pass phrase is prompted for.
-If none of these options is specified the key is written in plain text. This
-means that using the B<rsa> utility to read in an encrypted key with no
-encryption option can be used to remove the pass phrase from a key, or by
-setting the encryption options it can be use to add or change the pass phrase.
-These options can only be used with PEM format output files.
-
-=item B<-text>
-
-prints out the various public or private key components in
-plain text in addition to the encoded version.
-
-=item B<-noout>
-
-this option prevents output of the encoded version of the key.
-
-=item B<-modulus>
-
-this option prints out the value of the modulus of the key.
-
-=item B<-check>
-
-this option checks the consistency of an RSA private key.
-
-=item B<-pubin>
-
-by default a private key is read from the input file: with this
-option a public key is read instead.
-
-=item B<-pubout>
-
-by default a private key is output: with this option a public
-key will be output instead. This option is automatically set if
-the input is a public key.
-
-=item B<-RSAPublicKey_in>, B<-RSAPublicKey_out>
-
-like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<rsa>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 NOTES
-
-The PEM private key format uses the header and footer lines:
-
- -----BEGIN RSA PRIVATE KEY-----
- -----END RSA PRIVATE KEY-----
-
-The PEM public key format uses the header and footer lines:
-
- -----BEGIN PUBLIC KEY-----
- -----END PUBLIC KEY-----
-
-The PEM B<RSAPublicKey> format uses the header and footer lines:
-
- -----BEGIN RSA PUBLIC KEY-----
- -----END RSA PUBLIC KEY-----
-
-The B<NET> form is a format compatible with older Netscape servers
-and Microsoft IIS .key files, this uses unsalted RC4 for its encryption.
-It is not very secure and so should only be used when necessary.
-
-Some newer version of IIS have additional data in the exported .key
-files. To use these with the utility, view the file with a binary editor
-and look for the string "private-key", then trace back to the byte
-sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data
-from this point onwards to another file and use that as the input
-to the B<rsa> utility with the B<-inform NET> option.
-
-=head1 EXAMPLES
-
-To remove the pass phrase on an RSA private key:
-
- openssl rsa -in key.pem -out keyout.pem
-
-To encrypt a private key using triple DES:
-
- openssl rsa -in key.pem -des3 -out keyout.pem
-
-To convert a private key from PEM to DER format:
-
- openssl rsa -in key.pem -outform DER -out keyout.der
-
-To print out the components of a private key to standard output:
-
- openssl rsa -in key.pem -text -noout
-
-To just output the public part of a private key:
-
- openssl rsa -in key.pem -pubout -out pubkey.pem
-
-Output the public part of a private key in B<RSAPublicKey> format:
-
- openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem
-
-=head1 BUGS
-
-The command line password arguments don't currently work with
-B<NET> format.
-
-There should be an option that automatically handles .key files,
-without having to manually edit them.
-
-=head1 SEE ALSO
-
-L<pkcs8(1)>, L<dsa(1)>, L<genrsa(1)>,
-L<gendsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-rsautl - RSA utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<rsautl>
-[B<-help>]
-[B<-in file>]
-[B<-out file>]
-[B<-inkey file>]
-[B<-keyform PEM|DER|ENGINE>]
-[B<-pubin>]
-[B<-certin>]
-[B<-sign>]
-[B<-verify>]
-[B<-encrypt>]
-[B<-decrypt>]
-[B<-pkcs>]
-[B<-ssl>]
-[B<-raw>]
-[B<-hexdump>]
-[B<-asn1parse>]
-
-=head1 DESCRIPTION
-
-The B<rsautl> command can be used to sign, verify, encrypt and decrypt
-data using the RSA algorithm.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-in filename>
-
-This specifies the input filename to read data from or standard input
-if this option is not specified.
-
-=item B<-out filename>
-
-specifies the output filename to write to or standard output by
-default.
-
-=item B<-inkey file>
-
-the input key file, by default it should be an RSA private key.
-
-=item B<-keyform PEM|DER|ENGINE>
-
-the key format PEM, DER or ENGINE.
-
-=item B<-pubin>
-
-the input file is an RSA public key.
-
-=item B<-certin>
-
-the input is a certificate containing an RSA public key.
-
-=item B<-sign>
-
-sign the input data and output the signed result. This requires
-an RSA private key.
-
-=item B<-verify>
-
-verify the input data and output the recovered data.
-
-=item B<-encrypt>
-
-encrypt the input data using an RSA public key.
-
-=item B<-decrypt>
-
-decrypt the input data using an RSA private key.
-
-=item B<-pkcs, -oaep, -ssl, -raw>
-
-the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
-special padding used in SSL v2 backwards compatible handshakes,
-or no padding, respectively.
-For signatures, only B<-pkcs> and B<-raw> can be used.
-
-=item B<-hexdump>
-
-hex dump the output data.
-
-=item B<-asn1parse>
-
-asn1parse the output data, this is useful when combined with the
-B<-verify> option.
-
-=back
-
-=head1 NOTES
-
-B<rsautl> because it uses the RSA algorithm directly can only be
-used to sign or verify small pieces of data.
-
-=head1 EXAMPLES
-
-Sign some data using a private key:
-
- openssl rsautl -sign -in file -inkey key.pem -out sig
-
-Recover the signed data
-
- openssl rsautl -verify -in sig -inkey key.pem
-
-Examine the raw signed data:
-
- openssl rsautl -verify -in file -inkey key.pem -raw -hexdump
-
- 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
- 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
- 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
- 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
- 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
- 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
- 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
- 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world
-
-The PKCS#1 block formatting is evident from this. If this was done using
-encrypt and decrypt the block would have been of type 2 (the second byte)
-and random padding data visible instead of the 0xff bytes.
-
-It is possible to analyse the signature of certificates using this
-utility in conjunction with B<asn1parse>. Consider the self signed
-example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
-
- openssl asn1parse -in pca-cert.pem
-
- 0:d=0 hl=4 l= 742 cons: SEQUENCE
- 4:d=1 hl=4 l= 591 cons: SEQUENCE
- 8:d=2 hl=2 l= 3 cons: cont [ 0 ]
- 10:d=3 hl=2 l= 1 prim: INTEGER :02
- 13:d=2 hl=2 l= 1 prim: INTEGER :00
- 16:d=2 hl=2 l= 13 cons: SEQUENCE
- 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
- 29:d=3 hl=2 l= 0 prim: NULL
- 31:d=2 hl=2 l= 92 cons: SEQUENCE
- 33:d=3 hl=2 l= 11 cons: SET
- 35:d=4 hl=2 l= 9 cons: SEQUENCE
- 37:d=5 hl=2 l= 3 prim: OBJECT :countryName
- 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU
- ....
- 599:d=1 hl=2 l= 13 cons: SEQUENCE
- 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
- 612:d=2 hl=2 l= 0 prim: NULL
- 614:d=1 hl=3 l= 129 prim: BIT STRING
-
-
-The final BIT STRING contains the actual signature. It can be extracted with:
-
- openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
-
-The certificate public key can be extracted with:
-
- openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
-
-The signature can be analysed with:
-
- openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
-
- 0:d=0 hl=2 l= 32 cons: SEQUENCE
- 2:d=1 hl=2 l= 12 cons: SEQUENCE
- 4:d=2 hl=2 l= 8 prim: OBJECT :md5
- 14:d=2 hl=2 l= 0 prim: NULL
- 16:d=1 hl=2 l= 16 prim: OCTET STRING
- 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%..
-
-This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
-the digest used was md5. The actual part of the certificate that was signed can
-be extracted with:
-
- openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
-
-and its digest computed with:
-
- openssl md5 -c tbs
- MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
-
-which it can be seen agrees with the recovered value above.
-
-=head1 SEE ALSO
-
-L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-s_client - SSL/TLS client program
-
-=head1 SYNOPSIS
-
-B<openssl> B<s_client>
-[B<-help>]
-[B<-connect host:port>]
-[B<-proxy host:port>]
-[B<-servername name>]
-[B<-verify depth>]
-[B<-verify_return_error>]
-[B<-cert filename>]
-[B<-certform DER|PEM>]
-[B<-key filename>]
-[B<-keyform DER|PEM>]
-[B<-pass arg>]
-[B<-CApath directory>]
-[B<-CAfile filename>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-dane_tlsa_domain domain>]
-[B<-dane_tlsa_rrdata rrdata>]
-[B<-dane_ee_no_namechecks>]
-[B<-attime timestamp>]
-[B<-check_ss_sig>]
-[B<-crl_check>]
-[B<-crl_check_all>]
-[B<-explicit_policy>]
-[B<-extended_crl>]
-[B<-ignore_critical>]
-[B<-inhibit_any>]
-[B<-inhibit_map>]
-[B<-no_check_time>]
-[B<-partial_chain>]
-[B<-policy arg>]
-[B<-policy_check>]
-[B<-policy_print>]
-[B<-purpose purpose>]
-[B<-suiteB_128>]
-[B<-suiteB_128_only>]
-[B<-suiteB_192>]
-[B<-trusted_first>]
-[B<-no_alt_chains>]
-[B<-use_deltas>]
-[B<-auth_level num>]
-[B<-verify_depth num>]
-[B<-verify_email email>]
-[B<-verify_hostname hostname>]
-[B<-verify_ip ip>]
-[B<-verify_name name>]
-[B<-x509_strict>]
-[B<-reconnect>]
-[B<-showcerts>]
-[B<-debug>]
-[B<-msg>]
-[B<-nbio_test>]
-[B<-state>]
-[B<-nbio>]
-[B<-crlf>]
-[B<-ign_eof>]
-[B<-no_ign_eof>]
-[B<-quiet>]
-[B<-ssl3>]
-[B<-tls1>]
-[B<-tls1_1>]
-[B<-tls1_2>]
-[B<-no_ssl3>]
-[B<-no_tls1>]
-[B<-no_tls1_1>]
-[B<-no_tls1_2>]
-[B<-dtls>]
-[B<-dtls1>]
-[B<-dtls1_2>]
-[B<-fallback_scsv>]
-[B<-async>]
-[B<-split_send_frag>]
-[B<-max_pipelines>]
-[B<-read_buf>]
-[B<-bugs>]
-[B<-comp>]
-[B<-no_comp>]
-[B<-cipher cipherlist>]
-[B<-serverpref>]
-[B<-starttls protocol>]
-[B<-xmpphost hostname>]
-[B<-engine id>]
-[B<-tlsextdebug>]
-[B<-no_ticket>]
-[B<-sess_out filename>]
-[B<-sess_in filename>]
-[B<-rand file(s)>]
-[B<-serverinfo types>]
-[B<-status>]
-[B<-alpn protocols>]
-[B<-nextprotoneg protocols>]
-[B<-ct|noct>]
-[B<-ctlogfile>]
-
-=head1 DESCRIPTION
-
-The B<s_client> command implements a generic SSL/TLS client which connects
-to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for
-SSL servers.
-
-=head1 OPTIONS
-
-In addition to the options below the B<s_client> utility also supports the
-common and client only options documented in the
-in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
-manual page.
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-connect host:port>
-
-This specifies the host and optional port to connect to. If not specified
-then an attempt is made to connect to the local host on port 4433.
-
-=item B<-proxy host:port>
-
-When used with the B<-connect> flag, the program uses the host and port
-specified with this flag and issues an HTTP CONNECT command to connect
-to the desired server.
-
-=item B<-servername name>
-
-Set the TLS SNI (Server Name Indication) extension in the ClientHello message.
-
-=item B<-cert certname>
-
-The certificate to use, if one is requested by the server. The default is
-not to use a certificate.
-
-=item B<-certform format>
-
-The certificate format to use: DER or PEM. PEM is the default.
-
-=item B<-key keyfile>
-
-The private key to use. If not specified then the certificate file will
-be used.
-
-=item B<-keyform format>
-
-The private format to use: DER or PEM. PEM is the default.
-
-=item B<-pass arg>
-
-the private key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-verify depth>
-
-The verify depth to use. This specifies the maximum length of the
-server certificate chain and turns on server certificate verification.
-Currently the verify operation continues after errors so all the problems
-with a certificate chain can be seen. As a side effect the connection
-will never fail due to a server certificate verify failure.
-
-=item B<-verify_return_error>
-
-Return verification errors instead of continuing. This will typically
-abort the handshake with a fatal error.
-
-=item B<-CApath directory>
-
-The directory to use for server certificate verification. This directory
-must be in "hash format", see B<verify> for more information. These are
-also used when building the client certificate chain.
-
-=item B<-CAfile file>
-
-A file containing trusted certificates to use during server authentication
-and to use when attempting to build the client certificate chain.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-dane_tlsa_domain domain>
-
-Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
-TLSA base domain which becomes the default SNI hint and the primary
-reference identifier for hostname checks. This must be used in
-combination with at least one instance of the B<-dane_tlsa_rrdata>
-option below.
-
-When DANE authentication succeeds, the diagnostic output will include
-the lowest (closest to 0) depth at which a TLSA record authenticated
-a chain certificate. When that TLSA record is a "2 1 0" trust
-anchor public key that signed (rather than matched) the top-most
-certificate of the chain, the result is reported as "TA public key
-verified". Otherwise, either the TLSA record "matched TA certificate"
-at a positive depth or else "matched EE certificate" at depth 0.
-
-=item B<-dane_tlsa_rrdata rrdata>
-
-Use one or more times to specify the RRDATA fields of the DANE TLSA
-RRset associated with the target service. The B<rrdata> value is
-specied in "presentation form", that is four whitespace separated
-fields that specify the usage, selector, matching type and associated
-data, with the last of these encoded in hexadecimal. Optional
-whitespace is ignored in the associated data field. For example:
-
- $ openssl s_client -brief -starttls smtp \
- -connect smtp.example.com:25 \
- -dane_tlsa_domain smtp.example.com \
- -dane_tlsa_rrdata "2 1 1
- B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \
- -dane_tlsa_rrdata "2 1 1
- 60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18"
- ...
- Verification: OK
- Verified peername: smtp.example.com
- DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1
- ...
-
-=item B<-dane_ee_no_namechecks>
-
-This disables server name checks when authenticating via DANE-EE(3) TLSA
-records.
-For some applications, primarily web browsers, it is not safe to disable name
-checks due to "unknown key share" attacks, in which a malicious server can
-convince a client that a connection to a victim server is instead a secure
-connection to the malicious server.
-The malicious server may then be able to violate cross-origin scripting
-restrictions.
-Thus, despite the text of RFC7671, name checks are by default enabled for
-DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
-to do so.
-In particular, SMTP and XMPP clients should set this option as SRV and MX
-records already make it possible for a remote domain to redirect client
-connections to any server of its choice, and in any case SMTP and XMPP clients
-do not execute scripts downloaded from remote servers.
-
-=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
-B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
-B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
-B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
-B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
-B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
-B<-verify_ip>, B<-verify_name>, B<-x509_strict>
-
-Set various certificate chain validation options. See the
-L<verify(1)> manual page for details.
-
-=item B<-reconnect>
-
-reconnects to the same server 5 times using the same session ID, this can
-be used as a test that session caching is working.
-
-=item B<-showcerts>
-
-display the whole server certificate chain: normally only the server
-certificate itself is displayed.
-
-=item B<-prexit>
-
-print session information when the program exits. This will always attempt
-to print out information even if the connection fails. Normally information
-will only be printed out once if the connection succeeds. This option is useful
-because the cipher in use may be renegotiated or the connection may fail
-because a client certificate is required or is requested only after an
-attempt is made to access a certain URL. Note: the output produced by this
-option is not always accurate because a connection might never have been
-established.
-
-=item B<-state>
-
-prints out the SSL session states.
-
-=item B<-debug>
-
-print extensive debugging information including a hex dump of all traffic.
-
-=item B<-msg>
-
-show all protocol messages with hex dump.
-
-=item B<-trace>
-
-show verbose trace output of protocol messages. OpenSSL needs to be compiled
-with B<enable-ssl-trace> for this option to work.
-
-=item B<-msgfile>
-
-file to send output of B<-msg> or B<-trace> to, default standard output.
-
-=item B<-nbio_test>
-
-tests non-blocking I/O
-
-=item B<-nbio>
-
-turns on non-blocking I/O
-
-=item B<-crlf>
-
-this option translated a line feed from the terminal into CR+LF as required
-by some servers.
-
-=item B<-ign_eof>
-
-inhibit shutting down the connection when end of file is reached in the
-input.
-
-=item B<-quiet>
-
-inhibit printing of session and certificate information. This implicitly
-turns on B<-ign_eof> as well.
-
-=item B<-no_ign_eof>
-
-shut down the connection when end of file is reached in the input.
-Can be used to override the implicit B<-ign_eof> after B<-quiet>.
-
-=item B<-psk_identity identity>
-
-Use the PSK identity B<identity> when using a PSK cipher suite.
-
-=item B<-psk key>
-
-Use the PSK key B<key> when using a PSK cipher suite. The key is
-given as a hexadecimal number without leading 0x, for example -psk
-1a2b3c4d.
-
-=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
-
-These options require or disable the use of the specified SSL or TLS protocols.
-By default B<s_client> will negotiate the highest mutually supported protocol
-version.
-When a specific TLS version is required, only that version will be offered to
-and accepted from the server.
-
-=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
-
-These options make B<s_client> use DTLS protocols instead of TLS.
-With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version,
-whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2
-respectively.
-
-=item B<-fallback_scsv>
-
-Send TLS_FALLBACK_SCSV in the ClientHello.
-
-=item B<-async>
-
-switch on asynchronous mode. Cryptographic operations will be performed
-asynchronously. This will only have an effect if an asynchronous capable engine
-is also used via the B<-engine> option. For test purposes the dummy async engine
-(dasync) can be used (if available).
-
-=item B<-split_send_frag int>
-
-The size used to split data for encrypt pipelines. If more data is written in
-one go than this value then it will be split into multiple pipelines, up to the
-maximum number of pipelines defined by max_pipelines. This only has an effect if
-a suitable ciphersuite has been negotiated, an engine that supports pipelining
-has been loaded, and max_pipelines is greater than 1. See
-L<SSL_CTX_set_split_send_fragment(3)> for further information.
-
-=item B<-max_pipelines int>
-
-The maximum number of encrypt/decrypt pipelines to be used. This will only have
-an effect if an engine has been loaded that supports pipelining (e.g. the dasync
-engine) and a suitable ciphersuite has been negotiated. The default value is 1.
-See L<SSL_CTX_set_max_pipelines(3)> for further information.
-
-=item B<-read_buf int>
-
-The default read buffer size to be used for connections. This will only have an
-effect if the buffer size is larger than the size that would otherwise be used
-and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
-further information).
-
-=item B<-bugs>
-
-there are several known bug in SSL and TLS implementations. Adding this
-option enables various workarounds.
-
-=item B<-comp>
-
-Enables support for SSL/TLS compression.
-This option was introduced in OpenSSL 1.1.0.
-TLS compression is not recommended and is off by default as of
-OpenSSL 1.1.0.
-
-=item B<-no_comp>
-
-Disables support for SSL/TLS compression.
-TLS compression is not recommended and is off by default as of
-OpenSSL 1.1.0.
-
-=item B<-brief>
-
-only provide a brief summary of connection parameters instead of the
-normal verbose output.
-
-=item B<-cipher cipherlist>
-
-this allows the cipher list sent by the client to be modified. Although
-the server determines which cipher suite is used it should take the first
-supported cipher in the list sent by the client. See the B<ciphers>
-command for more information.
-
-=item B<-starttls protocol>
-
-send the protocol-specific message(s) to switch to TLS for communication.
-B<protocol> is a keyword for the intended protocol. Currently, the only
-supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server",
-"irc" and "postgres."
-
-=item B<-xmpphost hostname>
-
-This option, when used with "-starttls xmpp" or "-starttls xmpp-server",
-specifies the host for the "to" attribute of the stream element.
-If this option is not specified, then the host specified with "-connect"
-will be used.
-
-=item B<-tlsextdebug>
-
-print out a hex dump of any TLS extensions received from the server.
-
-=item B<-no_ticket>
-
-disable RFC4507bis session ticket support.
-
-=item B<-sess_out filename>
-
-output SSL session to B<filename>
-
-=item B<-sess_in sess.pem>
-
-load SSL session from B<filename>. The client will attempt to resume a
-connection from this session.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<s_client>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-serverinfo types>
-
-a list of comma-separated TLS Extension Types (numbers between 0 and
-65535). Each type will be sent as an empty ClientHello TLS Extension.
-The server's response (if any) will be encoded and displayed as a PEM
-file.
-
-=item B<-status>
-
-sends a certificate status request to the server (OCSP stapling). The server
-response (if any) is printed out.
-
-=item B<-alpn protocols>, B<-nextprotoneg protocols>
-
-these flags enable the
-Enable the Application-Layer Protocol Negotiation or Next Protocol
-Negotiation extension, respectively. ALPN is the IETF standard and
-replaces NPN.
-The B<protocols> list is a
-comma-separated protocol names that the client should advertise
-support for. The list should contain most wanted protocols first.
-Protocol names are printable ASCII strings, for example "http/1.1" or
-"spdy/3".
-Empty list of protocols is treated specially and will cause the client to
-advertise support for the TLS extension but disconnect just after
-receiving ServerHello with a list of server supported protocols.
-
-=item B<-ct|noct>
-
-Use one of these two options to control whether Certificate Transparency (CT)
-is enabled (B<-ct>) or disabled (B<-noct>).
-If CT is enabled, signed certificate timestamps (SCTs) will be requested from
-the server and reported at handshake completion.
-
-Enabling CT also enables OCSP stapling, as this is one possible delivery method
-for SCTs.
-
-=item B<-ctlogfile>
-
-A file containing a list of known Certificate Transparency logs. See
-L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format.
-
-=back
-
-=head1 CONNECTED COMMANDS
-
-If a connection is established with an SSL server then any data received
-from the server is displayed and any key presses will be sent to the
-server. When used interactively (which means neither B<-quiet> nor B<-ign_eof>
-have been given), the session will be renegotiated if the line begins with an
-B<R>, and if the line begins with a B<Q> or if end of file is reached, the
-connection will be closed down.
-
-=head1 NOTES
-
-B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP
-server the command:
-
- openssl s_client -connect servername:443
-
-would typically be used (https uses port 443). If the connection succeeds
-then an HTTP command can be given such as "GET /" to retrieve a web page.
-
-If the handshake fails then there are several possible causes, if it is
-nothing obvious like no client certificate then the B<-bugs>,
-B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1> options can be tried
-in case it is a buggy server. In particular you should play with these
-options B<before> submitting a bug report to an OpenSSL mailing list.
-
-A frequent problem when attempting to get client certificates working
-is that a web client complains it has no certificates or gives an empty
-list to choose from. This is normally because the server is not sending
-the clients certificate authority in its "acceptable CA list" when it
-requests a certificate. By using B<s_client> the CA list can be viewed
-and checked. However some servers only request client authentication
-after a specific URL is requested. To obtain the list in this case it
-is necessary to use the B<-prexit> option and send an HTTP request
-for an appropriate page.
-
-If a certificate is specified on the command line using the B<-cert>
-option it will not be used unless the server specifically requests
-a client certificate. Therefor merely including a client certificate
-on the command line is no guarantee that the certificate works.
-
-If there are problems verifying a server certificate then the
-B<-showcerts> option can be used to show the whole chain.
-
-The B<s_client> utility is a test tool and is designed to continue the
-handshake after any certificate verification errors. As a result it will
-accept any certificate chain (trusted or not) sent by the peer. None test
-applications should B<not> do this as it makes them vulnerable to a MITM
-attack. This behaviour can be changed by with the B<-verify_return_error>
-option: any verify errors are then returned aborting the handshake.
-
-=head1 BUGS
-
-Because this program has a lot of options and also because some of the
-techniques used are rather old, the C source of B<s_client> is rather hard to
-read and not a model of how things should be done.
-A typical SSL client program would be much simpler.
-
-The B<-prexit> option is a bit of a hack. We should really report
-information whenever a session is renegotiated.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_cmd(3)>,
-L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>
-
-=head1 HISTORY
-
-The -no_alt_chains options was first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-s_server - SSL/TLS server program
-
-=head1 SYNOPSIS
-
-B<openssl> B<s_server>
-[B<-help>]
-[B<-accept port>]
-[B<-naccept count>]
-[B<-context id>]
-[B<-verify depth>]
-[B<-Verify depth>]
-[B<-crl_check>]
-[B<-crl_check_all>]
-[B<-cert filename>]
-[B<-certform DER|PEM>]
-[B<-key keyfile>]
-[B<-keyform DER|PEM>]
-[B<-pass arg>]
-[B<-dcert filename>]
-[B<-dcertform DER|PEM>]
-[B<-dkey keyfile>]
-[B<-dkeyform DER|PEM>]
-[B<-dpass arg>]
-[B<-dhparam filename>]
-[B<-nbio>]
-[B<-nbio_test>]
-[B<-crlf>]
-[B<-debug>]
-[B<-msg>]
-[B<-state>]
-[B<-CApath directory>]
-[B<-CAfile filename>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-attime timestamp>]
-[B<-check_ss_sig>]
-[B<-explicit_policy>]
-[B<-extended_crl>]
-[B<-ignore_critical>]
-[B<-inhibit_any>]
-[B<-inhibit_map>]
-[B<-no_check_time>]
-[B<-partial_chain>]
-[B<-policy arg>]
-[B<-policy_check>]
-[B<-policy_print>]
-[B<-purpose purpose>]
-[B<-suiteB_128>]
-[B<-suiteB_128_only>]
-[B<-suiteB_192>]
-[B<-trusted_first>]
-[B<-no_alt_chains>]
-[B<-use_deltas>]
-[B<-auth_level num>]
-[B<-verify_depth num>]
-[B<-verify_return_error>]
-[B<-verify_email email>]
-[B<-verify_hostname hostname>]
-[B<-verify_ip ip>]
-[B<-verify_name name>]
-[B<-x509_strict>]
-[B<-nocert>]
-[B<-cipher cipherlist>]
-[B<-serverpref>]
-[B<-quiet>]
-[B<-ssl3>]
-[B<-tls1>]
-[B<-dtls>]
-[B<-dtls1>]
-[B<-dtls1_2>]
-[B<-listen>]
-[B<-async>]
-[B<-split_send_frag>]
-[B<-max_pipelines>]
-[B<-read_buf>]
-[B<-no_ssl3>]
-[B<-no_tls1>]
-[B<-no_tls1_1>]
-[B<-no_tls1_2>]
-[B<-no_dhe>]
-[B<-bugs>]
-[B<-comp>]
-[B<-no_comp>]
-[B<-brief>]
-[B<-www>]
-[B<-WWW>]
-[B<-HTTP>]
-[B<-engine id>]
-[B<-tlsextdebug>]
-[B<-no_ticket>]
-[B<-id_prefix arg>]
-[B<-rand file(s)>]
-[B<-serverinfo file>]
-[B<-no_resumption_on_reneg>]
-[B<-status>]
-[B<-status_verbose>]
-[B<-status_timeout nsec>]
-[B<-status_url url>]
-[B<-alpn protocols>]
-[B<-nextprotoneg protocols>]
-
-=head1 DESCRIPTION
-
-The B<s_server> command implements a generic SSL/TLS server which listens
-for connections on a given port using SSL/TLS.
-
-=head1 OPTIONS
-
-In addition to the options below the B<s_server> utility also supports the
-common and server only options documented in the
-in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
-manual page.
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-accept port>
-
-The TCP port to listen on for connections. If not specified 4433 is used.
-
-=item B<-naccept count>
-
-The server will exit after receiving B<number> connections, default unlimited.
-
-=item B<-context id>
-
-Sets the SSL context id. It can be given any string value. If this option
-is not present a default value will be used.
-
-=item B<-cert certname>
-
-The certificate to use, most servers cipher suites require the use of a
-certificate and some require a certificate with a certain public key type:
-for example the DSS cipher suites require a certificate containing a DSS
-(DSA) key. If not specified then the filename "server.pem" will be used.
-
-=item B<-certform format>
-
-The certificate format to use: DER or PEM. PEM is the default.
-
-=item B<-key keyfile>
-
-The private key to use. If not specified then the certificate file will
-be used.
-
-=item B<-keyform format>
-
-The private format to use: DER or PEM. PEM is the default.
-
-=item B<-pass arg>
-
-The private key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-dcert filename>, B<-dkey keyname>
-
-Specify an additional certificate and private key, these behave in the
-same manner as the B<-cert> and B<-key> options except there is no default
-if they are not specified (no additional certificate and key is used). As
-noted above some cipher suites require a certificate containing a key of
-a certain type. Some cipher suites need a certificate carrying an RSA key
-and some a DSS (DSA) key. By using RSA and DSS certificates and keys
-a server can support clients which only support RSA or DSS cipher suites
-by using an appropriate certificate.
-
-=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
-
-Additional certificate and private key format and passphrase respectively.
-
-=item B<-nocert>
-
-If this option is set then no certificate is used. This restricts the
-cipher suites available to the anonymous ones (currently just anonymous
-DH).
-
-=item B<-dhparam filename>
-
-The DH parameter file to use. The ephemeral DH cipher suites generate keys
-using a set of DH parameters. If not specified then an attempt is made to
-load the parameters from the server certificate file.
-If this fails then a static set of parameters hard coded into the B<s_server>
-program will be used.
-
-=item B<-no_dhe>
-
-If this option is set then no DH parameters will be loaded effectively
-disabling the ephemeral DH cipher suites.
-
-=item B<-crl_check>, B<-crl_check_all>
-
-Check the peer certificate has not been revoked by its CA.
-The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
-option all CRLs of all CAs in the chain are checked.
-
-=item B<-CApath directory>
-
-The directory to use for client certificate verification. This directory
-must be in "hash format", see B<verify> for more information. These are
-also used when building the server certificate chain.
-
-=item B<-CAfile file>
-
-A file containing trusted certificates to use during client authentication
-and to use when attempting to build the server certificate chain. The list
-is also used in the list of acceptable client CAs passed to the client when
-a certificate is requested.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-verify depth>, B<-Verify depth>
-
-The verify depth to use. This specifies the maximum length of the
-client certificate chain and makes the server request a certificate from
-the client. With the B<-verify> option a certificate is requested but the
-client does not have to send one, with the B<-Verify> option the client
-must supply a certificate or an error occurs.
-
-If the ciphersuite cannot request a client certificate (for example an
-anonymous ciphersuite or PSK) this option has no effect.
-
-=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
-B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
-B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
-B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
-B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
-B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
-B<-verify_ip>, B<-verify_name>, B<-x509_strict>
-
-Set different peer certificate verification options.
-See the L<verify(1)> manual page for details.
-
-=item B<-verify_return_error>
-
-Verification errors normally just print a message but allow the
-connection to continue, for debugging purposes.
-If this option is used, then verification errors close the connection.
-
-=item B<-state>
-
-Prints the SSL session states.
-
-=item B<-debug>
-
-Print extensive debugging information including a hex dump of all traffic.
-
-=item B<-msg>
-
-Show all protocol messages with hex dump.
-
-=item B<-trace>
-
-Show verbose trace output of protocol messages. OpenSSL needs to be compiled
-with B<enable-ssl-trace> for this option to work.
-
-=item B<-msgfile>
-
-File to send output of B<-msg> or B<-trace> to, default standard output.
-
-=item B<-nbio_test>
-
-Tests non blocking I/O
-
-=item B<-nbio>
-
-Turns on non blocking I/O
-
-=item B<-crlf>
-
-This option translated a line feed from the terminal into CR+LF.
-
-=item B<-quiet>
-
-Inhibit printing of session and certificate information.
-
-=item B<-psk_hint hint>
-
-Use the PSK identity hint B<hint> when using a PSK cipher suite.
-
-=item B<-psk key>
-
-Use the PSK key B<key> when using a PSK cipher suite. The key is
-given as a hexadecimal number without leading 0x, for example -psk
-1a2b3c4d.
-
-=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
-
-These options require or disable the use of the specified SSL or TLS protocols.
-By default B<s_server> will negotiate the highest mutually supported protocol
-version.
-When a specific TLS version is required, only that version will be accepted
-from the client.
-
-=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
-
-These options make B<s_server> use DTLS protocols instead of TLS.
-With B<-dtls>, B<s_server> will negotiate any supported DTLS protocol version,
-whilst B<-dtls1> and B<-dtls1_2> will only support DTLSv1.0 and DTLSv1.2
-respectively.
-
-=item B<-listen>
-
-This option can only be used in conjunction with one of the DTLS options above.
-With this option B<s_server> will listen on a UDP port for incoming connections.
-Any ClientHellos that arrive will be checked to see if they have a cookie in
-them or not.
-Any without a cookie will be responded to with a HelloVerifyRequest.
-If a ClientHello with a cookie is received then B<s_server> will connect to
-that peer and complete the handshake.
-
-=item B<-async>
-
-Switch on asynchronous mode. Cryptographic operations will be performed
-asynchronously. This will only have an effect if an asynchronous capable engine
-is also used via the B<-engine> option. For test purposes the dummy async engine
-(dasync) can be used (if available).
-
-=item B<-split_send_frag int>
-
-The size used to split data for encrypt pipelines. If more data is written in
-one go than this value then it will be split into multiple pipelines, up to the
-maximum number of pipelines defined by max_pipelines. This only has an effect if
-a suitable ciphersuite has been negotiated, an engine that supports pipelining
-has been loaded, and max_pipelines is greater than 1. See
-L<SSL_CTX_set_split_send_fragment(3)> for further information.
-
-=item B<-max_pipelines int>
-
-The maximum number of encrypt/decrypt pipelines to be used. This will only have
-an effect if an engine has been loaded that supports pipelining (e.g. the dasync
-engine) and a suitable ciphersuite has been negotiated. The default value is 1.
-See L<SSL_CTX_set_max_pipelines(3)> for further information.
-
-=item B<-read_buf int>
-
-The default read buffer size to be used for connections. This will only have an
-effect if the buffer size is larger than the size that would otherwise be used
-and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
-further information).
-
-=item B<-bugs>
-
-There are several known bug in SSL and TLS implementations. Adding this
-option enables various workarounds.
-
-=item B<-comp>
-
-Enable negotiation of TLS compression.
-This option was introduced in OpenSSL 1.1.0.
-TLS compression is not recommended and is off by default as of
-OpenSSL 1.1.0.
-
-=item B<-no_comp>
-
-Disable negotiation of TLS compression.
-TLS compression is not recommended and is off by default as of
-OpenSSL 1.1.0.
-
-=item B<-brief>
-
-Provide a brief summary of connection parameters instead of the normal verbose
-output.
-
-=item B<-cipher cipherlist>
-
-This allows the cipher list used by the server to be modified. When
-the client sends a list of supported ciphers the first client cipher
-also included in the server list is used. Because the client specifies
-the preference order, the order of the server cipherlist irrelevant. See
-the B<ciphers> command for more information.
-
-=item B<-serverpref>
-
-Use the server's cipher preferences, rather than the client's preferences.
-
-=item B<-tlsextdebug>
-
-Print a hex dump of any TLS extensions received from the server.
-
-=item B<-no_ticket>
-
-Disable RFC4507bis session ticket support.
-
-=item B<-www>
-
-Sends a status message back to the client when it connects. This includes
-information about the ciphers used and various session parameters.
-The output is in HTML format so this option will normally be used with a
-web browser.
-
-=item B<-WWW>
-
-Emulates a simple web server. Pages will be resolved relative to the
-current directory, for example if the URL https://myhost/page.html is
-requested the file ./page.html will be loaded.
-
-=item B<-HTTP>
-
-Emulates a simple web server. Pages will be resolved relative to the
-current directory, for example if the URL https://myhost/page.html is
-requested the file ./page.html will be loaded. The files loaded are
-assumed to contain a complete and correct HTTP response (lines that
-are part of the HTTP response line and headers must end with CRLF).
-
-=item B<-rev>
-
-Simple test server which just reverses the text received from the client
-and sends it back to the server. Also sets B<-brief>.
-
-=item B<-engine id>
-
-Specifying an engine (by its unique B<id> string) will cause B<s_server>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<-id_prefix arg>
-
-Generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
-for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
-servers, when each of which might be generating a unique range of session
-IDs (eg. with a certain prefix).
-
-=item B<-rand file(s)>
-
-A file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<-serverinfo file>
-
-A file containing one or more blocks of PEM data. Each PEM block
-must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
-followed by "length" bytes of extension data). If the client sends
-an empty TLS ClientHello extension matching the type, the corresponding
-ServerHello extension will be returned.
-
-=item B<-no_resumption_on_reneg>
-
-Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option.
-
-=item B<-status>
-
-Enables certificate status request support (aka OCSP stapling).
-
-=item B<-status_verbose>
-
-Enables certificate status request support (aka OCSP stapling) and gives
-a verbose printout of the OCSP response.
-
-=item B<-status_timeout nsec>
-
-Sets the timeout for OCSP response to B<nsec> seconds.
-
-=item B<-status_url url>
-
-Sets a fallback responder URL to use if no responder URL is present in the
-server certificate. Without this option an error is returned if the server
-certificate does not contain a responder address.
-
-=item B<-alpn protocols>, B<-nextprotoneg protocols>
-
-these flags enable the
-Enable the Application-Layer Protocol Negotiation or Next Protocol
-Negotiation extension, respectively. ALPN is the IETF standard and
-replaces NPN.
-The B<protocols> list is a
-comma-separated list of supported protocol names.
-The list should contain most wanted protocols first.
-Protocol names are printable ASCII strings, for example "http/1.1" or
-"spdy/3".
-
-=back
-
-=head1 CONNECTED COMMANDS
-
-If a connection request is established with an SSL client and neither the
-B<-www> nor the B<-WWW> option has been used then normally any data received
-from the client is displayed and any key presses will be sent to the client.
-
-Certain single letter commands are also recognized which perform special
-operations: these are listed below.
-
-=over 4
-
-=item B<q>
-
-end the current SSL connection but still accept new connections.
-
-=item B<Q>
-
-end the current SSL connection and exit.
-
-=item B<r>
-
-renegotiate the SSL session.
-
-=item B<R>
-
-renegotiate the SSL session and request a client certificate.
-
-=item B<P>
-
-send some plain text down the underlying TCP connection: this should
-cause the client to disconnect due to a protocol violation.
-
-=item B<S>
-
-print out some session cache status information.
-
-=back
-
-=head1 NOTES
-
-B<s_server> can be used to debug SSL clients. To accept connections from
-a web browser the command:
-
- openssl s_server -accept 443 -www
-
-can be used for example.
-
-Most web browsers (in particular Netscape and MSIE) only support RSA cipher
-suites, so they cannot connect to servers which don't use a certificate
-carrying an RSA key or a version of OpenSSL with RSA disabled.
-
-Although specifying an empty list of CAs when requesting a client certificate
-is strictly speaking a protocol violation, some SSL clients interpret this to
-mean any CA is acceptable. This is useful for debugging purposes.
-
-The session parameters can printed out using the B<sess_id> program.
-
-=head1 BUGS
-
-Because this program has a lot of options and also because some of the
-techniques used are rather old, the C source of B<s_server> is rather hard to
-read and not a model of how things should be done.
-A typical SSL server program would be much simpler.
-
-The output of common ciphers is wrong: it just gives the list of ciphers that
-OpenSSL recognizes and the client supports.
-
-There should be a way for the B<s_server> program to print out details of any
-unknown cipher suites a client says it supports.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_cmd(3)>,
-L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)>
-
-=head1 HISTORY
-
-The -no_alt_chains options was first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-s_time - SSL/TLS performance timing program
-
-=head1 SYNOPSIS
-
-B<openssl> B<s_time>
-[B<-help>]
-[B<-connect host:port>]
-[B<-www page>]
-[B<-cert filename>]
-[B<-key filename>]
-[B<-CApath directory>]
-[B<-CAfile filename>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-reuse>]
-[B<-new>]
-[B<-verify depth>]
-[B<-nbio>]
-[B<-time seconds>]
-[B<-ssl3>]
-[B<-bugs>]
-[B<-cipher cipherlist>]
-
-=head1 DESCRIPTION
-
-The B<s_time> command implements a generic SSL/TLS client which connects to a
-remote host using SSL/TLS. It can request a page from the server and includes
-the time to transfer the payload data in its timing measurements. It measures
-the number of connections within a given timeframe, the amount of data
-transferred (if any), and calculates the average time spent for one connection.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-connect host:port>
-
-This specifies the host and optional port to connect to.
-
-=item B<-www page>
-
-This specifies the page to GET from the server. A value of '/' gets the
-index.htm[l] page. If this parameter is not specified, then B<s_time> will only
-perform the handshake to establish SSL connections but not transfer any
-payload data.
-
-=item B<-cert certname>
-
-The certificate to use, if one is requested by the server. The default is
-not to use a certificate. The file is in PEM format.
-
-=item B<-key keyfile>
-
-The private key to use. If not specified then the certificate file will
-be used. The file is in PEM format.
-
-=item B<-verify depth>
-
-The verify depth to use. This specifies the maximum length of the
-server certificate chain and turns on server certificate verification.
-Currently the verify operation continues after errors so all the problems
-with a certificate chain can be seen. As a side effect the connection
-will never fail due to a server certificate verify failure.
-
-=item B<-CApath directory>
-
-The directory to use for server certificate verification. This directory
-must be in "hash format", see B<verify> for more information. These are
-also used when building the client certificate chain.
-
-=item B<-CAfile file>
-
-A file containing trusted certificates to use during server authentication
-and to use when attempting to build the client certificate chain.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-new>
-
-performs the timing test using a new session ID for each connection.
-If neither B<-new> nor B<-reuse> are specified, they are both on by default
-and executed in sequence.
-
-=item B<-reuse>
-
-performs the timing test using the same session ID; this can be used as a test
-that session caching is working. If neither B<-new> nor B<-reuse> are
-specified, they are both on by default and executed in sequence.
-
-=item B<-nbio>
-
-turns on non-blocking I/O.
-
-=item B<-ssl3>
-
-these options disable the use of certain SSL or TLS protocols. By default
-the initial handshake uses a method which should be compatible with all
-servers and permit them to use SSL v3 or TLS as appropriate.
-The timing program is not as rich in options to turn protocols on and off as
-the L<s_client(1)> program and may not connect to all servers.
-
-Unfortunately there are a lot of ancient and broken servers in use which
-cannot handle this technique and will fail to connect. Some servers only
-work if TLS is turned off with the B<-ssl3> option.
-
-=item B<-bugs>
-
-there are several known bug in SSL and TLS implementations. Adding this
-option enables various workarounds.
-
-=item B<-cipher cipherlist>
-
-this allows the cipher list sent by the client to be modified. Although
-the server determines which cipher suite is used it should take the first
-supported cipher in the list sent by the client.
-See the L<ciphers(1)> command for more information.
-
-=item B<-time length>
-
-specifies how long (in seconds) B<s_time> should establish connections and
-optionally transfer payload data from a server. Server and client performance
-and the link speed determine how many connections B<s_time> can establish.
-
-=back
-
-=head1 NOTES
-
-B<s_time> can be used to measure the performance of an SSL connection.
-To connect to an SSL HTTP server and get the default page the command
-
- openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
-
-would typically be used (https uses port 443). 'commoncipher' is a cipher to
-which both client and server can agree, see the L<ciphers(1)> command
-for details.
-
-If the handshake fails then there are several possible causes, if it is
-nothing obvious like no client certificate then the B<-bugs> and
-B<-ssl3> options can be tried
-in case it is a buggy server. In particular you should play with these
-options B<before> submitting a bug report to an OpenSSL mailing list.
-
-A frequent problem when attempting to get client certificates working
-is that a web client complains it has no certificates or gives an empty
-list to choose from. This is normally because the server is not sending
-the clients certificate authority in its "acceptable CA list" when it
-requests a certificate. By using L<s_client(1)> the CA list can be
-viewed and checked. However some servers only request client authentication
-after a specific URL is requested. To obtain the list in this case it
-is necessary to use the B<-prexit> option of L<s_client(1)> and
-send an HTTP request for an appropriate page.
-
-If a certificate is specified on the command line using the B<-cert>
-option it will not be used unless the server specifically requests
-a client certificate. Therefor merely including a client certificate
-on the command line is no guarantee that the certificate works.
-
-=head1 BUGS
-
-Because this program does not have all the options of the
-L<s_client(1)> program to turn protocols on and off, you may not be
-able to measure the performance of all protocols with all servers.
-
-The B<-verify> option should really exit if the server verification
-fails.
-
-=head1 SEE ALSO
-
-L<s_client(1)>, L<s_server(1)>, L<ciphers(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-sess_id - SSL/TLS session handling utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<sess_id>
-[B<-help>]
-[B<-inform PEM|DER>]
-[B<-outform PEM|DER|NSS>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-text>]
-[B<-noout>]
-[B<-context ID>]
-
-=head1 DESCRIPTION
-
-The B<sess_id> process the encoded version of the SSL session structure
-and optionally prints out SSL session details (for example the SSL session
-master key) in human readable format. Since this is a diagnostic tool that
-needs some knowledge of the SSL protocol to use properly, most users will
-not need to use it.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM>
-
-This specifies the input format. The B<DER> option uses an ASN1 DER encoded
-format containing session details. The precise format can vary from one version
-to the next. The B<PEM> form is the default format: it consists of the B<DER>
-format base64 encoded with additional header and footer lines.
-
-=item B<-outform DER|PEM|NSS>
-
-This specifies the output format. The B<PEM> and B<DER> options have the same meaning
-as the B<-inform> option. The B<NSS> option outputs the session id and the master key
-in NSS keylog format.
-
-=item B<-in filename>
-
-This specifies the input filename to read session information from or standard
-input by default.
-
-=item B<-out filename>
-
-This specifies the output filename to write session information to or standard
-output if this option is not specified.
-
-=item B<-text>
-
-prints out the various public or private key components in
-plain text in addition to the encoded version.
-
-=item B<-cert>
-
-if a certificate is present in the session it will be output using this option,
-if the B<-text> option is also present then it will be printed out in text form.
-
-=item B<-noout>
-
-this option prevents output of the encoded version of the session.
-
-=item B<-context ID>
-
-this option can set the session id so the output session information uses the
-supplied ID. The ID can be any string of characters. This option won't normally
-be used.
-
-=back
-
-=head1 OUTPUT
-
-Typical output:
-
- SSL-Session:
- Protocol : TLSv1
- Cipher : 0016
- Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED
- Session-ID-ctx: 01000000
- Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD
- Key-Arg : None
- Start Time: 948459261
- Timeout : 300 (sec)
- Verify return code 0 (ok)
-
-Theses are described below in more detail.
-
-=over 4
-
-=item B<Protocol>
-
-this is the protocol in use TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
-
-=item B<Cipher>
-
-the cipher used this is the actual raw SSL or TLS cipher code, see the SSL
-or TLS specifications for more information.
-
-=item B<Session-ID>
-
-the SSL session ID in hex format.
-
-=item B<Session-ID-ctx>
-
-the session ID context in hex format.
-
-=item B<Master-Key>
-
-this is the SSL session master key.
-
-=item B<Start Time>
-
-this is the session start time represented as an integer in standard Unix format.
-
-=item B<Timeout>
-
-the timeout in seconds.
-
-=item B<Verify return code>
-
-this is the return code when an SSL client certificate is verified.
-
-=back
-
-=head1 NOTES
-
-The PEM encoded session format uses the header and footer lines:
-
- -----BEGIN SSL SESSION PARAMETERS-----
- -----END SSL SESSION PARAMETERS-----
-
-Since the SSL session output contains the master key it is possible to read the contents
-of an encrypted session using this information. Therefore appropriate security precautions
-should be taken if the information is being output by a "real" application. This is
-however strongly discouraged and should only be used for debugging purposes.
-
-=head1 BUGS
-
-The cipher and start time should be printed out in human readable form.
-
-=head1 SEE ALSO
-
-L<ciphers(1)>, L<s_server(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-smime - S/MIME utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<smime>
-[B<-help>]
-[B<-encrypt>]
-[B<-decrypt>]
-[B<-sign>]
-[B<-resign>]
-[B<-verify>]
-[B<-pk7out>]
-[B<-binary>]
-[B<-crlfeol>]
-[B<-[cipher]>]
-[B<-in file>]
-[B<-CAfile file>]
-[B<-CApath dir>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-attime timestamp>]
-[B<-check_ss_sig>]
-[B<-crl_check>]
-[B<-crl_check_all>]
-[B<-explicit_policy>]
-[B<-extended_crl>]
-[B<-ignore_critical>]
-[B<-inhibit_any>]
-[B<-inhibit_map>]
-[B<-partial_chain>]
-[B<-policy arg>]
-[B<-policy_check>]
-[B<-policy_print>]
-[B<-purpose purpose>]
-[B<-suiteB_128>]
-[B<-suiteB_128_only>]
-[B<-suiteB_192>]
-[B<-trusted_first>]
-[B<-no_alt_chains>]
-[B<-use_deltas>]
-[B<-auth_level num>]
-[B<-verify_depth num>]
-[B<-verify_email email>]
-[B<-verify_hostname hostname>]
-[B<-verify_ip ip>]
-[B<-verify_name name>]
-[B<-x509_strict>]
-[B<-certfile file>]
-[B<-signer file>]
-[B<-recip file>]
-[B<-inform SMIME|PEM|DER>]
-[B<-passin arg>]
-[B<-inkey file>]
-[B<-out file>]
-[B<-outform SMIME|PEM|DER>]
-[B<-content file>]
-[B<-to addr>]
-[B<-from ad>]
-[B<-subject s>]
-[B<-text>]
-[B<-indef>]
-[B<-noindef>]
-[B<-stream>]
-[B<-rand file(s)>]
-[B<-md digest>]
-[cert.pem]...
-
-=head1 DESCRIPTION
-
-The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
-verify S/MIME messages.
-
-=head1 COMMAND OPTIONS
-
-There are six operation options that set the type of operation to be performed.
-The meaning of the other options varies according to the operation type.
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-encrypt>
-
-encrypt mail for the given recipient certificates. Input file is the message
-to be encrypted. The output file is the encrypted mail in MIME format.
-
-Note that no revocation check is done for the recipient cert, so if that
-key has been compromised, others may be able to decrypt the text.
-
-=item B<-decrypt>
-
-decrypt mail using the supplied certificate and private key. Expects an
-encrypted mail message in MIME format for the input file. The decrypted mail
-is written to the output file.
-
-=item B<-sign>
-
-sign mail using the supplied certificate and private key. Input file is
-the message to be signed. The signed message in MIME format is written
-to the output file.
-
-=item B<-verify>
-
-verify signed mail. Expects a signed mail message on input and outputs
-the signed data. Both clear text and opaque signing is supported.
-
-=item B<-pk7out>
-
-takes an input message and writes out a PEM encoded PKCS#7 structure.
-
-=item B<-resign>
-
-resign a message: take an existing message and one or more new signers.
-
-=item B<-in filename>
-
-the input message to be encrypted or signed or the MIME message to
-be decrypted or verified.
-
-=item B<-inform SMIME|PEM|DER>
-
-this specifies the input format for the PKCS#7 structure. The default
-is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
-format change this to expect PEM and DER format PKCS#7 structures
-instead. This currently only affects the input format of the PKCS#7
-structure, if no PKCS#7 structure is being input (for example with
-B<-encrypt> or B<-sign>) this option has no effect.
-
-=item B<-out filename>
-
-the message text that has been decrypted or verified or the output MIME
-format message that has been signed or verified.
-
-=item B<-outform SMIME|PEM|DER>
-
-this specifies the output format for the PKCS#7 structure. The default
-is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
-format change this to write PEM and DER format PKCS#7 structures
-instead. This currently only affects the output format of the PKCS#7
-structure, if no PKCS#7 structure is being output (for example with
-B<-verify> or B<-decrypt>) this option has no effect.
-
-=item B<-stream -indef -noindef>
-
-the B<-stream> and B<-indef> options are equivalent and enable streaming I/O
-for encoding operations. This permits single pass processing of data without
-the need to hold the entire contents in memory, potentially supporting very
-large files. Streaming is automatically set for S/MIME signing with detached
-data if the output format is B<SMIME> it is currently off by default for all
-other operations.
-
-=item B<-noindef>
-
-disable streaming I/O where it would produce and indefinite length constructed
-encoding. This option currently has no effect. In future streaming will be
-enabled by default on all relevant operations and this option will disable it.
-
-=item B<-content filename>
-
-This specifies a file containing the detached content, this is only
-useful with the B<-verify> command. This is only usable if the PKCS#7
-structure is using the detached signature form where the content is
-not included. This option will override any content if the input format
-is S/MIME and it uses the multipart/signed MIME content type.
-
-=item B<-text>
-
-this option adds plain text (text/plain) MIME headers to the supplied
-message if encrypting or signing. If decrypting or verifying it strips
-off text headers: if the decrypted or verified message is not of MIME
-type text/plain then an error occurs.
-
-=item B<-CAfile file>
-
-a file containing trusted CA certificates, only used with B<-verify>.
-
-=item B<-CApath dir>
-
-a directory containing trusted CA certificates, only used with
-B<-verify>. This directory must be a standard certificate directory: that
-is a hash of each subject name (using B<x509 -hash>) should be linked
-to each certificate.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-md digest>
-
-digest algorithm to use when signing or resigning. If not present then the
-default digest algorithm for the signing key will be used (usually SHA1).
-
-=item B<-[cipher]>
-
-the encryption algorithm to use. For example DES (56 bits) - B<-des>,
-triple DES (168 bits) - B<-des3>,
-EVP_get_cipherbyname() function) can also be used preceded by a dash, for
-example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers
-supported by your version of OpenSSL.
-
-If not specified triple DES is used. Only used with B<-encrypt>.
-
-=item B<-nointern>
-
-when verifying a message normally certificates (if any) included in
-the message are searched for the signing certificate. With this option
-only the certificates specified in the B<-certfile> option are used.
-The supplied certificates can still be used as untrusted CAs however.
-
-=item B<-noverify>
-
-do not verify the signers certificate of a signed message.
-
-=item B<-nochain>
-
-do not do chain verification of signers certificates: that is don't
-use the certificates in the signed message as untrusted CAs.
-
-=item B<-nosigs>
-
-don't try to verify the signatures on the message.
-
-=item B<-nocerts>
-
-when signing a message the signer's certificate is normally included
-with this option it is excluded. This will reduce the size of the
-signed message but the verifier must have a copy of the signers certificate
-available locally (passed using the B<-certfile> option for example).
-
-=item B<-noattr>
-
-normally when a message is signed a set of attributes are included which
-include the signing time and supported symmetric algorithms. With this
-option they are not included.
-
-=item B<-binary>
-
-normally the input message is converted to "canonical" format which is
-effectively using CR and LF as end of line: as required by the S/MIME
-specification. When this option is present no translation occurs. This
-is useful when handling binary data which may not be in MIME format.
-
-=item B<-crlfeol>
-
-normally the output file uses a single B<LF> as end of line. When this
-option is present B<CRLF> is used instead.
-
-=item B<-nodetach>
-
-when signing a message use opaque signing: this form is more resistant
-to translation by mail relays but it cannot be read by mail agents that
-do not support S/MIME. Without this option cleartext signing with
-the MIME type multipart/signed is used.
-
-=item B<-certfile file>
-
-allows additional certificates to be specified. When signing these will
-be included with the message. When verifying these will be searched for
-the signers certificates. The certificates should be in PEM format.
-
-=item B<-signer file>
-
-a signing certificate when signing or resigning a message, this option can be
-used multiple times if more than one signer is required. If a message is being
-verified then the signers certificates will be written to this file if the
-verification was successful.
-
-=item B<-recip file>
-
-the recipients certificate when decrypting a message. This certificate
-must match one of the recipients of the message or an error occurs.
-
-=item B<-inkey file>
-
-the private key to use when signing or decrypting. This must match the
-corresponding certificate. If this option is not specified then the
-private key must be included in the certificate file specified with
-the B<-recip> or B<-signer> file. When signing this option can be used
-multiple times to specify successive keys.
-
-=item B<-passin arg>
-
-the private key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-rand file(s)>
-
-a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)>).
-Multiple files can be specified separated by an OS-dependent character.
-The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
-all others.
-
-=item B<cert.pem...>
-
-one or more certificates of message recipients: used when encrypting
-a message.
-
-=item B<-to, -from, -subject>
-
-the relevant mail headers. These are included outside the signed
-portion of a message so they may be included manually. If signing
-then many S/MIME mail clients check the signers certificate's email
-address matches that specified in the From: address.
-
-=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
-B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
-B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
-B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
-B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
-B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
-B<-verify_ip>, B<-verify_name>, B<-x509_strict>
-
-Set various options of certificate chain verification. See
-L<verify(1)> manual page for details.
-
-=back
-
-=head1 NOTES
-
-The MIME message must be sent without any blank lines between the
-headers and the output. Some mail programs will automatically add
-a blank line. Piping the mail directly to sendmail is one way to
-achieve the correct format.
-
-The supplied message to be signed or encrypted must include the
-necessary MIME headers or many S/MIME clients won't display it
-properly (if at all). You can use the B<-text> option to automatically
-add plain text headers.
-
-A "signed and encrypted" message is one where a signed message is
-then encrypted. This can be produced by encrypting an already signed
-message: see the examples section.
-
-This version of the program only allows one signer per message but it
-will verify multiple signers on received messages. Some S/MIME clients
-choke if a message contains multiple signers. It is possible to sign
-messages "in parallel" by signing an already signed message.
-
-The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
-clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
-encrypted data is used for other purposes.
-
-The B<-resign> option uses an existing message digest when adding a new
-signer. This means that attributes must be present in at least one existing
-signer using the same message digest or this operation will fail.
-
-The B<-stream> and B<-indef> options enable streaming I/O support.
-As a result the encoding is BER using indefinite length constructed encoding
-and no longer DER. Streaming is supported for the B<-encrypt> operation and the
-B<-sign> operation if the content is not detached.
-
-Streaming is always used for the B<-sign> operation with detached data but
-since the content is no longer part of the PKCS#7 structure the encoding
-remains DER.
-
-=head1 EXIT CODES
-
-=over 4
-
-=item Z<>0
-
-the operation was completely successfully.
-
-=item Z<>1
-
-an error occurred parsing the command options.
-
-=item Z<>2
-
-one of the input files could not be read.
-
-=item Z<>3
-
-an error occurred creating the PKCS#7 file or when reading the MIME
-message.
-
-=item Z<>4
-
-an error occurred decrypting or verifying the message.
-
-=item Z<>5
-
-the message was verified correctly but an error occurred writing out
-the signers certificates.
-
-=back
-
-=head1 EXAMPLES
-
-Create a cleartext signed message:
-
- openssl smime -sign -in message.txt -text -out mail.msg \
- -signer mycert.pem
-
-Create an opaque signed message:
-
- openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
- -signer mycert.pem
-
-Create a signed message, include some additional certificates and
-read the private key from another file:
-
- openssl smime -sign -in in.txt -text -out mail.msg \
- -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
-
-Create a signed message with two signers:
-
- openssl smime -sign -in message.txt -text -out mail.msg \
- -signer mycert.pem -signer othercert.pem
-
-Send a signed message under Unix directly to sendmail, including headers:
-
- openssl smime -sign -in in.txt -text -signer mycert.pem \
- -from steve@openssl.org -to someone@somewhere \
- -subject "Signed message" | sendmail someone@somewhere
-
-Verify a message and extract the signer's certificate if successful:
-
- openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
-
-Send encrypted mail using triple DES:
-
- openssl smime -encrypt -in in.txt -from steve@openssl.org \
- -to someone@somewhere -subject "Encrypted message" \
- -des3 user.pem -out mail.msg
-
-Sign and encrypt mail:
-
- openssl smime -sign -in ml.txt -signer my.pem -text \
- | openssl smime -encrypt -out mail.msg \
- -from steve@openssl.org -to someone@somewhere \
- -subject "Signed and Encrypted message" -des3 user.pem
-
-Note: the encryption command does not include the B<-text> option because the
-message being encrypted already has MIME headers.
-
-Decrypt mail:
-
- openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
-
-The output from Netscape form signing is a PKCS#7 structure with the
-detached signature format. You can use this program to verify the
-signature by line wrapping the base64 encoded structure and surrounding
-it with:
-
- -----BEGIN PKCS7-----
- -----END PKCS7-----
-
-and using the command:
-
- openssl smime -verify -inform PEM -in signature.pem -content content.txt
-
-Alternatively you can base64 decode the signature and use:
-
- openssl smime -verify -inform DER -in signature.der -content content.txt
-
-Create an encrypted message using 128 bit Camellia:
-
- openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
-
-Add a signer to an existing message:
-
- openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg
-
-=head1 BUGS
-
-The MIME parser isn't very clever: it seems to handle most messages that I've
-thrown at it but it may choke on others.
-
-The code currently will only write out the signer's certificate to a file: if
-the signer has a separate encryption certificate this must be manually
-extracted. There should be some heuristic that determines the correct
-encryption certificate.
-
-Ideally a database should be maintained of a certificates for each email
-address.
-
-The code doesn't currently take note of the permitted symmetric encryption
-algorithms as supplied in the SMIMECapabilities signed attribute. This means the
-user has to manually include the correct encryption algorithm. It should store
-the list of permitted ciphers in a database and only use those.
-
-No revocation checking is done on the signer's certificate.
-
-The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
-structures may cause parsing errors.
-
-=head1 HISTORY
-
-The use of multiple B<-signer> options and the B<-resign> command were first
-added in OpenSSL 1.0.0
-
-The -no_alt_chains options was first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-speed - test library performance
-
-=head1 SYNOPSIS
-
-B<openssl speed>
-[B<-help>]
-[B<-engine id>]
-[B<-elapsed>]
-[B<-evp algo>]
-[B<-decrypt>]
-[B<algorithm...>]
-
-=head1 DESCRIPTION
-
-This command is used to test the performance of cryptographic algorithms.
-To see the list of supported algorithms, use the I<list --digest-commands>
-or I<list --cipher-commands> command.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<speed>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=item B<-elapsed>
-
-Measure time in real time instead of CPU time. It can be useful when testing
-speed of hardware engines.
-
-=item B<-evp algo>
-
-Use the specified cipher or message digest algorithm via the EVP interface.
-
-=item B<-decrypt>
-
-Time the decryption instead of encryption. Affects only the EVP testing.
-
-=item B<[zero or more test algorithms]>
-
-If any options are given, B<speed> tests those algorithms, otherwise all of
-the above are tested.
-
-=back
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-spkac - SPKAC printing and generating utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<spkac>
-[B<-help>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-key keyfile>]
-[B<-passin arg>]
-[B<-challenge string>]
-[B<-pubkey>]
-[B<-spkac spkacname>]
-[B<-spksect section>]
-[B<-noout>]
-[B<-verify>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<spkac> command processes Netscape signed public key and challenge
-(SPKAC) files. It can print out their contents, verify the signature and
-produce its own SPKACs from a supplied private key.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-in filename>
-
-This specifies the input filename to read from or standard input if this
-option is not specified. Ignored if the B<-key> option is used.
-
-=item B<-out filename>
-
-specifies the output filename to write to or standard output by
-default.
-
-=item B<-key keyfile>
-
-create an SPKAC file using the private key in B<keyfile>. The
-B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
-present.
-
-=item B<-passin password>
-
-the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-challenge string>
-
-specifies the challenge string if an SPKAC is being created.
-
-=item B<-spkac spkacname>
-
-allows an alternative name form the variable containing the
-SPKAC. The default is "SPKAC". This option affects both
-generated and input SPKAC files.
-
-=item B<-spksect section>
-
-allows an alternative name form the section containing the
-SPKAC. The default is the default section.
-
-=item B<-noout>
-
-don't output the text version of the SPKAC (not used if an
-SPKAC is being created).
-
-=item B<-pubkey>
-
-output the public key of an SPKAC (not used if an SPKAC is
-being created).
-
-=item B<-verify>
-
-verifies the digital signature on the supplied SPKAC.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<spkac>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head1 EXAMPLES
-
-Print out the contents of an SPKAC:
-
- openssl spkac -in spkac.cnf
-
-Verify the signature of an SPKAC:
-
- openssl spkac -in spkac.cnf -noout -verify
-
-Create an SPKAC using the challenge string "hello":
-
- openssl spkac -key key.pem -challenge hello -out spkac.cnf
-
-Example of an SPKAC, (long lines split up for clarity):
-
- SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\
- PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\
- PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\
- 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\
- 4=
-
-=head1 NOTES
-
-A created SPKAC with suitable DN components appended can be fed into
-the B<ca> utility.
-
-SPKACs are typically generated by Netscape when a form is submitted
-containing the B<KEYGEN> tag as part of the certificate enrollment
-process.
-
-The challenge string permits a primitive form of proof of possession
-of private key. By checking the SPKAC signature and a random challenge
-string some guarantee is given that the user knows the private key
-corresponding to the public key being certified. This is important in
-some applications. Without this it is possible for a previous SPKAC
-to be used in a "replay attack".
-
-=head1 SEE ALSO
-
-L<ca(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ts - Time Stamping Authority tool (client/server)
-
-=head1 SYNOPSIS
-
-B<openssl> B<ts>
-B<-query>
-[B<-rand> file:file...]
-[B<-config> configfile]
-[B<-data> file_to_hash]
-[B<-digest> digest_bytes]
-[B<-[digest]>]
-[B<-tspolicy> object_id]
-[B<-no_nonce>]
-[B<-cert>]
-[B<-in> request.tsq]
-[B<-out> request.tsq]
-[B<-text>]
-
-B<openssl> B<ts>
-B<-reply>
-[B<-config> configfile]
-[B<-section> tsa_section]
-[B<-queryfile> request.tsq]
-[B<-passin> password_src]
-[B<-signer> tsa_cert.pem]
-[B<-inkey> private.pem]
-[B<-sha1|-sha224|-sha256|-sha384|-sha512>]
-[B<-chain> certs_file.pem]
-[B<-tspolicy> object_id]
-[B<-in> response.tsr]
-[B<-token_in>]
-[B<-out> response.tsr]
-[B<-token_out>]
-[B<-text>]
-[B<-engine> id]
-
-B<openssl> B<ts>
-B<-verify>
-[B<-data> file_to_hash]
-[B<-digest> digest_bytes]
-[B<-queryfile> request.tsq]
-[B<-in> response.tsr]
-[B<-token_in>]
-[B<-CApath> trusted_cert_path]
-[B<-CAfile> trusted_certs.pem]
-[B<-untrusted> cert_file.pem]
-[I<verify options>]
-
-I<verify options:>
-[-attime timestamp]
-[-check_ss_sig]
-[-crl_check]
-[-crl_check_all]
-[-explicit_policy]
-[-extended_crl]
-[-ignore_critical]
-[-inhibit_any]
-[-inhibit_map]
-[-issuer_checks]
-[-no_alt_chains]
-[-no_check_time]
-[-partial_chain]
-[-policy arg]
-[-policy_check]
-[-policy_print]
-[-purpose purpose]
-[-suiteB_128]
-[-suiteB_128_only]
-[-suiteB_192]
-[-trusted_first]
-[-use_deltas]
-[-auth_level num]
-[-verify_depth num]
-[-verify_email email]
-[-verify_hostname hostname]
-[-verify_ip ip]
-[-verify_name name]
-[-x509_strict]
-
-=head1 DESCRIPTION
-
-The B<ts> command is a basic Time Stamping Authority (TSA) client and server
-application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A
-TSA can be part of a PKI deployment and its role is to provide long
-term proof of the existence of a certain datum before a particular
-time. Here is a brief description of the protocol:
-
-=over 4
-
-=item 1.
-
-The TSA client computes a one-way hash value for a data file and sends
-the hash to the TSA.
-
-=item 2.
-
-The TSA attaches the current date and time to the received hash value,
-signs them and sends the time stamp token back to the client. By
-creating this token the TSA certifies the existence of the original
-data file at the time of response generation.
-
-=item 3.
-
-The TSA client receives the time stamp token and verifies the
-signature on it. It also checks if the token contains the same hash
-value that it had sent to the TSA.
-
-=back
-
-There is one DER encoded protocol data unit defined for transporting a time
-stamp request to the TSA and one for sending the time stamp response
-back to the client. The B<ts> command has three main functions:
-creating a time stamp request based on a data file,
-creating a time stamp response based on a request, verifying if a
-response corresponds to a particular request or a data file.
-
-There is no support for sending the requests/responses automatically
-over HTTP or TCP yet as suggested in RFC 3161. The users must send the
-requests either by ftp or e-mail.
-
-=head1 OPTIONS
-
-=head2 Time Stamp Request generation
-
-The B<-query> switch can be used for creating and printing a time stamp
-request with the following options:
-
-=over 4
-
-=item B<-rand> file:file...
-
-The files containing random data for seeding the random number
-generator. Multiple files can be specified, the separator is B<;> for
-MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
-
-=item B<-config> configfile
-
-The configuration file to use, this option overrides the
-B<OPENSSL_CONF> environment variable. Only the OID section
-of the config file is used with the B<-query> command. (Optional)
-
-=item B<-data> file_to_hash
-
-The data file for which the time stamp request needs to be
-created. stdin is the default if neither the B<-data> nor the B<-digest>
-parameter is specified. (Optional)
-
-=item B<-digest> digest_bytes
-
-It is possible to specify the message imprint explicitly without the data
-file. The imprint must be specified in a hexadecimal format, two characters
-per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
-1AF601...). The number of bytes must match the message digest algorithm
-in use. (Optional)
-
-=item B<-[digest]>
-
-The message digest to apply to the data file.
-Any digest supported by the OpenSSL B<dgst> command can be used.
-The default is SHA-1. (Optional)
-
-=item B<-tspolicy> object_id
-
-The policy that the client expects the TSA to use for creating the
-time stamp token. Either the dotted OID notation or OID names defined
-in the config file can be used. If no policy is requested the TSA will
-use its own default policy. (Optional)
-
-=item B<-no_nonce>
-
-No nonce is specified in the request if this option is
-given. Otherwise a 64 bit long pseudo-random none is
-included in the request. It is recommended to use nonce to
-protect against replay-attacks. (Optional)
-
-=item B<-cert>
-
-The TSA is expected to include its signing certificate in the
-response. (Optional)
-
-=item B<-in> request.tsq
-
-This option specifies a previously created time stamp request in DER
-format that will be printed into the output file. Useful when you need
-to examine the content of a request in human-readable
-
-format. (Optional)
-
-=item B<-out> request.tsq
-
-Name of the output file to which the request will be written. Default
-is stdout. (Optional)
-
-=item B<-text>
-
-If this option is specified the output is human-readable text format
-instead of DER. (Optional)
-
-=back
-
-=head2 Time Stamp Response generation
-
-A time stamp response (TimeStampResp) consists of a response status
-and the time stamp token itself (ContentInfo), if the token generation was
-successful. The B<-reply> command is for creating a time stamp
-response or time stamp token based on a request and printing the
-response/token in human-readable format. If B<-token_out> is not
-specified the output is always a time stamp response (TimeStampResp),
-otherwise it is a time stamp token (ContentInfo).
-
-=over 4
-
-=item B<-config> configfile
-
-The configuration file to use, this option overrides the
-B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE
-OPTIONS> for configurable variables. (Optional)
-
-=item B<-section> tsa_section
-
-The name of the config file section containing the settings for the
-response generation. If not specified the default TSA section is
-used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional)
-
-=item B<-queryfile> request.tsq
-
-The name of the file containing a DER encoded time stamp request. (Optional)
-
-=item B<-passin> password_src
-
-Specifies the password source for the private key of the TSA. See
-B<PASS PHRASE ARGUMENTS> in L<openssl(1)>. (Optional)
-
-=item B<-signer> tsa_cert.pem
-
-The signer certificate of the TSA in PEM format. The TSA signing
-certificate must have exactly one extended key usage assigned to it:
-timeStamping. The extended key usage must also be critical, otherwise
-the certificate is going to be refused. Overrides the B<signer_cert>
-variable of the config file. (Optional)
-
-=item B<-inkey> private.pem
-
-The signer private key of the TSA in PEM format. Overrides the
-B<signer_key> config file option. (Optional)
-
-=item B<-sha1|-sha224|-sha256|-sha384|-sha512>
-
-Signing digest to use. Overrides the B<signer_digest> config file
-option. (Optional)
-
-=item B<-chain> certs_file.pem
-
-The collection of certificates in PEM format that will all
-be included in the response in addition to the signer certificate if
-the B<-cert> option was used for the request. This file is supposed to
-contain the certificate chain for the signer certificate from its
-issuer upwards. The B<-reply> command does not build a certificate
-chain automatically. (Optional)
-
-=item B<-tspolicy> object_id
-
-The default policy to use for the response unless the client
-explicitly requires a particular TSA policy. The OID can be specified
-either in dotted notation or with its name. Overrides the
-B<default_policy> config file option. (Optional)
-
-=item B<-in> response.tsr
-
-Specifies a previously created time stamp response or time stamp token
-(if B<-token_in> is also specified) in DER format that will be written
-to the output file. This option does not require a request, it is
-useful e.g. when you need to examine the content of a response or
-token or you want to extract the time stamp token from a response. If
-the input is a token and the output is a time stamp response a default
-'granted' status info is added to the token. (Optional)
-
-=item B<-token_in>
-
-This flag can be used together with the B<-in> option and indicates
-that the input is a DER encoded time stamp token (ContentInfo) instead
-of a time stamp response (TimeStampResp). (Optional)
-
-=item B<-out> response.tsr
-
-The response is written to this file. The format and content of the
-file depends on other options (see B<-text>, B<-token_out>). The default is
-stdout. (Optional)
-
-=item B<-token_out>
-
-The output is a time stamp token (ContentInfo) instead of time stamp
-response (TimeStampResp). (Optional)
-
-=item B<-text>
-
-If this option is specified the output is human-readable text format
-instead of DER. (Optional)
-
-=item B<-engine> id
-
-Specifying an engine (by its unique B<id> string) will cause B<ts>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms. Default is builtin. (Optional)
-
-=back
-
-=head2 Time Stamp Response verification
-
-The B<-verify> command is for verifying if a time stamp response or time
-stamp token is valid and matches a particular time stamp request or
-data file. The B<-verify> command does not use the configuration file.
-
-=over 4
-
-=item B<-data> file_to_hash
-
-The response or token must be verified against file_to_hash. The file
-is hashed with the message digest algorithm specified in the token.
-The B<-digest> and B<-queryfile> options must not be specified with this one.
-(Optional)
-
-=item B<-digest> digest_bytes
-
-The response or token must be verified against the message digest specified
-with this option. The number of bytes must match the message digest algorithm
-specified in the token. The B<-data> and B<-queryfile> options must not be
-specified with this one. (Optional)
-
-=item B<-queryfile> request.tsq
-
-The original time stamp request in DER format. The B<-data> and B<-digest>
-options must not be specified with this one. (Optional)
-
-=item B<-in> response.tsr
-
-The time stamp response that needs to be verified in DER format. (Mandatory)
-
-=item B<-token_in>
-
-This flag can be used together with the B<-in> option and indicates
-that the input is a DER encoded time stamp token (ContentInfo) instead
-of a time stamp response (TimeStampResp). (Optional)
-
-=item B<-CApath> trusted_cert_path
-
-The name of the directory containing the trusted CA certificates of the
-client. See the similar option of L<verify(1)> for additional
-details. Either this option or B<-CAfile> must be specified. (Optional)
-
-
-=item B<-CAfile> trusted_certs.pem
-
-The name of the file containing a set of trusted self-signed CA
-certificates in PEM format. See the similar option of
-L<verify(1)> for additional details. Either this option
-or B<-CApath> must be specified.
-(Optional)
-
-=item B<-untrusted> cert_file.pem
-
-Set of additional untrusted certificates in PEM format which may be
-needed when building the certificate chain for the TSA's signing
-certificate. This file must contain the TSA signing certificate and
-all intermediate CA certificates unless the response includes them.
-(Optional)
-
-=item I<verify options>
-
-The options B<-attime timestamp>, B<-check_ss_sig>, B<-crl_check>,
-B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>,
-B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>,
-B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>,
-B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>,
-B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>,
-B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>,
-B<-verify_name>, and B<-x509_strict> can be used to control timestamp
-verification. See L<verify(1)>.
-
-=back
-
-=head1 CONFIGURATION FILE OPTIONS
-
-The B<-query> and B<-reply> commands make use of a configuration file
-defined by the B<OPENSSL_CONF> environment variable. See L<config(5)>
-for a general description of the syntax of the config file. The
-B<-query> command uses only the symbolic OID names section
-and it can work without it. However, the B<-reply> command needs the
-config file for its operation.
-
-When there is a command line switch equivalent of a variable the
-switch always overrides the settings in the config file.
-
-=over 4
-
-=item B<tsa> section, B<default_tsa>
-
-This is the main section and it specifies the name of another section
-that contains all the options for the B<-reply> command. This default
-section can be overridden with the B<-section> command line switch. (Optional)
-
-=item B<oid_file>
-
-See L<ca(1)> for description. (Optional)
-
-=item B<oid_section>
-
-See L<ca(1)> for description. (Optional)
-
-=item B<RANDFILE>
-
-See L<ca(1)> for description. (Optional)
-
-=item B<serial>
-
-The name of the file containing the hexadecimal serial number of the
-last time stamp response created. This number is incremented by 1 for
-each response. If the file does not exist at the time of response
-generation a new file is created with serial number 1. (Mandatory)
-
-=item B<crypto_device>
-
-Specifies the OpenSSL engine that will be set as the default for
-all available algorithms. The default value is builtin, you can specify
-any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM).
-(Optional)
-
-=item B<signer_cert>
-
-TSA signing certificate in PEM format. The same as the B<-signer>
-command line option. (Optional)
-
-=item B<certs>
-
-A file containing a set of PEM encoded certificates that need to be
-included in the response. The same as the B<-chain> command line
-option. (Optional)
-
-=item B<signer_key>
-
-The private key of the TSA in PEM format. The same as the B<-inkey>
-command line option. (Optional)
-
-=item B<signer_digest>
-
-Signing digest to use. The same as the
-B<-sha1|-sha224|-sha256|-sha384|-sha512> command line option. (Optional)
-
-=item B<default_policy>
-
-The default policy to use when the request does not mandate any
-policy. The same as the B<-tspolicy> command line option. (Optional)
-
-=item B<other_policies>
-
-Comma separated list of policies that are also acceptable by the TSA
-and used only if the request explicitly specifies one of them. (Optional)
-
-=item B<digests>
-
-The list of message digest algorithms that the TSA accepts. At least
-one algorithm must be specified. (Mandatory)
-
-=item B<accuracy>
-
-The accuracy of the time source of the TSA in seconds, milliseconds
-and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
-the components is missing zero is assumed for that field. (Optional)
-
-=item B<clock_precision_digits>
-
-Specifies the maximum number of digits, which represent the fraction of
-seconds, that need to be included in the time field. The trailing zeroes
-must be removed from the time, so there might actually be fewer digits,
-or no fraction of seconds at all. Supported only on UNIX platforms.
-The maximum value is 6, default is 0.
-(Optional)
-
-=item B<ordering>
-
-If this option is yes the responses generated by this TSA can always
-be ordered, even if the time difference between two responses is less
-than the sum of their accuracies. Default is no. (Optional)
-
-=item B<tsa_name>
-
-Set this option to yes if the subject name of the TSA must be included in
-the TSA name field of the response. Default is no. (Optional)
-
-=item B<ess_cert_id_chain>
-
-The SignedData objects created by the TSA always contain the
-certificate identifier of the signing certificate in a signed
-attribute (see RFC 2634, Enhanced Security Services). If this option
-is set to yes and either the B<certs> variable or the B<-chain> option
-is specified then the certificate identifiers of the chain will also
-be included in the SigningCertificate signed attribute. If this
-variable is set to no, only the signing certificate identifier is
-included. Default is no. (Optional)
-
-=back
-
-=head1 ENVIRONMENT VARIABLES
-
-B<OPENSSL_CONF> contains the path of the configuration file and can be
-overridden by the B<-config> command line option.
-
-=head1 EXAMPLES
-
-All the examples below presume that B<OPENSSL_CONF> is set to a proper
-configuration file, e.g. the example configuration file
-openssl/apps/openssl.cnf will do.
-
-=head2 Time Stamp Request
-
-To create a time stamp request for design1.txt with SHA-1
-without nonce and policy and no certificate is required in the response:
-
- openssl ts -query -data design1.txt -no_nonce \
- -out design1.tsq
-
-To create a similar time stamp request with specifying the message imprint
-explicitly:
-
- openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
- -no_nonce -out design1.tsq
-
-To print the content of the previous request in human readable format:
-
- openssl ts -query -in design1.tsq -text
-
-To create a time stamp request which includes the MD-5 digest
-of design2.txt, requests the signer certificate and nonce,
-specifies a policy id (assuming the tsa_policy1 name is defined in the
-OID section of the config file):
-
- openssl ts -query -data design2.txt -md5 \
- -tspolicy tsa_policy1 -cert -out design2.tsq
-
-=head2 Time Stamp Response
-
-Before generating a response a signing certificate must be created for
-the TSA that contains the B<timeStamping> critical extended key usage extension
-without any other key usage extensions. You can add the
-'extendedKeyUsage = critical,timeStamping' line to the user certificate section
-of the config file to generate a proper certificate. See L<req(1)>,
-L<ca(1)>, L<x509(1)> for instructions. The examples
-below assume that cacert.pem contains the certificate of the CA,
-tsacert.pem is the signing certificate issued by cacert.pem and
-tsakey.pem is the private key of the TSA.
-
-To create a time stamp response for a request:
-
- openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
- -signer tsacert.pem -out design1.tsr
-
-If you want to use the settings in the config file you could just write:
-
- openssl ts -reply -queryfile design1.tsq -out design1.tsr
-
-To print a time stamp reply to stdout in human readable format:
-
- openssl ts -reply -in design1.tsr -text
-
-To create a time stamp token instead of time stamp response:
-
- openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
-
-To print a time stamp token to stdout in human readable format:
-
- openssl ts -reply -in design1_token.der -token_in -text -token_out
-
-To extract the time stamp token from a response:
-
- openssl ts -reply -in design1.tsr -out design1_token.der -token_out
-
-To add 'granted' status info to a time stamp token thereby creating a
-valid response:
-
- openssl ts -reply -in design1_token.der -token_in -out design1.tsr
-
-=head2 Time Stamp Verification
-
-To verify a time stamp reply against a request:
-
- openssl ts -verify -queryfile design1.tsq -in design1.tsr \
- -CAfile cacert.pem -untrusted tsacert.pem
-
-To verify a time stamp reply that includes the certificate chain:
-
- openssl ts -verify -queryfile design2.tsq -in design2.tsr \
- -CAfile cacert.pem
-
-To verify a time stamp token against the original data file:
- openssl ts -verify -data design2.txt -in design2.tsr \
- -CAfile cacert.pem
-
-To verify a time stamp token against a message imprint:
- openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
- -in design2.tsr -CAfile cacert.pem
-
-You could also look at the 'test' directory for more examples.
-
-=head1 BUGS
-
-If you find any bugs or you have suggestions please write to
-Zoltan Glozik <zglozik@opentsa.org>. Known issues:
-
-=over 4
-
-=item * No support for time stamps over SMTP, though it is quite easy
-to implement an automatic e-mail based TSA with L<procmail(1)>
-and L<perl(1)>. HTTP server support is provided in the form of
-a separate apache module. HTTP client support is provided by
-L<tsget(1)>. Pure TCP/IP protocol is not supported.
-
-=item * The file containing the last serial number of the TSA is not
-locked when being read or written. This is a problem if more than one
-instance of L<openssl(1)> is trying to create a time stamp
-response at the same time. This is not an issue when using the apache
-server module, it does proper locking.
-
-=item * Look for the FIXME word in the source files.
-
-=item * The source code should really be reviewed by somebody else, too.
-
-=item * More testing is needed, I have done only some basic tests (see
-test/testtsa).
-
-=back
-
-=head1 SEE ALSO
-
-L<tsget(1)>, L<openssl(1)>, L<req(1)>,
-L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
-L<config(5)>
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-tsget - Time Stamping HTTP/HTTPS client
-
-=head1 SYNOPSIS
-
-B<tsget>
-B<-h> server_url
-[B<-e> extension]
-[B<-o> output]
-[B<-v>]
-[B<-d>]
-[B<-k> private_key.pem]
-[B<-p> key_password]
-[B<-c> client_cert.pem]
-[B<-C> CA_certs.pem]
-[B<-P> CA_path]
-[B<-r> file:file...]
-[B<-g> EGD_socket]
-[request]...
-
-=head1 DESCRIPTION
-
-The B<tsget> command can be used for sending a time stamp request, as
-specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing
-the time stamp response in a file. This tool cannot be used for creating the
-requests and verifying responses, you can use the OpenSSL B<ts(1)> command to
-do that. B<tsget> can send several requests to the server without closing
-the TCP connection if more than one requests are specified on the command
-line.
-
-The tool sends the following HTTP request for each time stamp request:
-
- POST url HTTP/1.1
- User-Agent: OpenTSA tsget.pl/<version>
- Host: <host>:<port>
- Pragma: no-cache
- Content-Type: application/timestamp-query
- Accept: application/timestamp-reply
- Content-Length: length of body
-
- ...binary request specified by the user...
-
-B<tsget> expects a response of type application/timestamp-reply, which is
-written to a file without any interpretation.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-h> server_url
-
-The URL of the HTTP/HTTPS server listening for time stamp requests.
-
-=item B<-e> extension
-
-If the B<-o> option is not given this argument specifies the extension of the
-output files. The base name of the output file will be the same as those of
-the input files. Default extension is '.tsr'. (Optional)
-
-=item B<-o> output
-
-This option can be specified only when just one request is sent to the
-server. The time stamp response will be written to the given output file. '-'
-means standard output. In case of multiple time stamp requests or the absence
-of this argument the names of the output files will be derived from the names
-of the input files and the default or specified extension argument. (Optional)
-
-=item B<-v>
-
-The name of the currently processed request is printed on standard
-error. (Optional)
-
-=item B<-d>
-
-Switches on verbose mode for the underlying B<curl> library. You can see
-detailed debug messages for the connection. (Optional)
-
-=item B<-k> private_key.pem
-
-(HTTPS) In case of certificate-based client authentication over HTTPS
-<private_key.pem> must contain the private key of the user. The private key
-file can optionally be protected by a passphrase. The B<-c> option must also
-be specified. (Optional)
-
-=item B<-p> key_password
-
-(HTTPS) Specifies the passphrase for the private key specified by the B<-k>
-argument. If this option is omitted and the key is passphrase protected B<tsget>
-will ask for it. (Optional)
-
-=item B<-c> client_cert.pem
-
-(HTTPS) In case of certificate-based client authentication over HTTPS
-<client_cert.pem> must contain the X.509 certificate of the user. The B<-k>
-option must also be specified. If this option is not specified no
-certificate-based client authentication will take place. (Optional)
-
-=item B<-C> CA_certs.pem
-
-(HTTPS) The trusted CA certificate store. The certificate chain of the peer's
-certificate must include one of the CA certificates specified in this file.
-Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional)
-
-=item B<-P> CA_path
-
-(HTTPS) The path containing the trusted CA certificates to verify the peer's
-certificate. The directory must be prepared with the B<c_rehash>
-OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of
-HTTPS. (Optional)
-
-=item B<-rand> file:file...
-
-The files containing random data for seeding the random number
-generator. Multiple files can be specified, the separator is B<;> for
-MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
-
-=item B<-g> EGD_socket
-
-The name of an EGD socket to get random data from. (Optional)
-
-=item [request]...
-
-List of files containing B<RFC 3161> DER-encoded time stamp requests. If no
-requests are specified only one request will be sent to the server and it will be
-read from the standard input. (Optional)
-
-=back
-
-=head1 ENVIRONMENT VARIABLES
-
-The B<TSGET> environment variable can optionally contain default
-arguments. The content of this variable is added to the list of command line
-arguments.
-
-=head1 EXAMPLES
-
-The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid
-time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
-and at port 8443 for HTTPS requests, the TSA service is available at the /tsa
-absolute path.
-
-Get a time stamp response for file1.tsq over HTTP, output is written to
-file1.tsr:
-
- tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq
-
-Get a time stamp response for file1.tsq and file2.tsq over HTTP showing
-progress, output is written to file1.reply and file2.reply respectively:
-
- tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \
- file1.tsq file2.tsq
-
-Create a time stamp request, write it to file3.tsq, send it to the server and
-write the response to file3.tsr:
-
- openssl ts -query -data file3.txt -cert | tee file3.tsq \
- | tsget -h http://tsa.opentsa.org:8080/tsa \
- -o file3.tsr
-
-Get a time stamp response for file1.tsq over HTTPS without client
-authentication:
-
- tsget -h https://tsa.opentsa.org:8443/tsa \
- -C cacerts.pem file1.tsq
-
-Get a time stamp response for file1.tsq over HTTPS with certificate-based
-client authentication (it will ask for the passphrase if client_key.pem is
-protected):
-
- tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
- -k client_key.pem -c client_cert.pem file1.tsq
-
-You can shorten the previous command line if you make use of the B<TSGET>
-environment variable. The following commands do the same as the previous
-example:
-
- TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
- -k client_key.pem -c client_cert.pem'
- export TSGET
- tsget file1.tsq
-
-=head1 SEE ALSO
-
-L<openssl(1)>, L<ts(1)>, L<curl(1)>,
-B<RFC 3161>
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-verify - Utility to verify certificates
-
-=head1 SYNOPSIS
-
-B<openssl> B<verify>
-[B<-help>]
-[B<-CAfile file>]
-[B<-CApath directory>]
-[B<-no-CAfile>]
-[B<-no-CApath>]
-[B<-allow_proxy_certs>]
-[B<-attime timestamp>]
-[B<-check_ss_sig>]
-[B<-CRLfile file>]
-[B<-crl_download>]
-[B<-crl_check>]
-[B<-crl_check_all>]
-[B<-engine id>]
-[B<-explicit_policy>]
-[B<-extended_crl>]
-[B<-ignore_critical>]
-[B<-inhibit_any>]
-[B<-inhibit_map>]
-[B<-no_check_time>]
-[B<-partial_chain>]
-[B<-policy arg>]
-[B<-policy_check>]
-[B<-policy_print>]
-[B<-purpose purpose>]
-[B<-suiteB_128>]
-[B<-suiteB_128_only>]
-[B<-suiteB_192>]
-[B<-trusted_first>]
-[B<-no_alt_chains>]
-[B<-untrusted file>]
-[B<-trusted file>]
-[B<-use_deltas>]
-[B<-verbose>]
-[B<-auth_level level>]
-[B<-verify_depth num>]
-[B<-verify_email email>]
-[B<-verify_hostname hostname>]
-[B<-verify_ip ip>]
-[B<-verify_name name>]
-[B<-x509_strict>]
-[B<-show_chain>]
-[B<->]
-[certificates]
-
-=head1 DESCRIPTION
-
-The B<verify> command verifies certificate chains.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-CAfile file>
-
-A B<file> of trusted certificates.
-The file should contain one or more certificates in PEM format.
-
-=item B<-CApath directory>
-
-A directory of trusted certificates. The certificates should have names
-of the form: hash.0 or have symbolic links to them of this
-form ("hash" is the hashed certificate subject name: see the B<-hash> option
-of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
-create symbolic links to a directory of certificates.
-
-=item B<-no-CAfile>
-
-Do not load the trusted CA certificates from the default file location
-
-=item B<-no-CApath>
-
-Do not load the trusted CA certificates from the default directory location
-
-=item B<-allow_proxy_certs>
-
-Allow the verification of proxy certificates
-
-=item B<-attime timestamp>
-
-Perform validation checks using time specified by B<timestamp> and not
-current system time. B<timestamp> is the number of seconds since
-01.01.1970 (UNIX time).
-
-=item B<-check_ss_sig>
-
-Verify the signature on the self-signed root CA. This is disabled by default
-because it doesn't add any security.
-
-=item B<-CRLfile file>
-
-The B<file> should contain one or more CRLs in PEM format.
-This option can be specified more than once to include CRLs from multiple
-B<files>.
-
-=item B<-crl_download>
-
-Attempt to download CRL information for this certificate.
-
-=item B<-crl_check>
-
-Checks end entity certificate validity by attempting to look up a valid CRL.
-If a valid CRL cannot be found an error occurs.
-
-=item B<-crl_check_all>
-
-Checks the validity of B<all> certificates in the chain by attempting
-to look up valid CRLs.
-
-=item B<-engine id>
-
-Specifying an engine B<id> will cause L<verify(1)> to attempt to load the
-specified engine.
-The engine will then be set as the default for all its supported algorithms.
-If you want to load certificates or CRLs that require engine support via any of
-the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
-must be specified before those options.
-
-=item B<-explicit_policy>
-
-Set policy variable require-explicit-policy (see RFC5280).
-
-=item B<-extended_crl>
-
-Enable extended CRL features such as indirect CRLs and alternate CRL
-signing keys.
-
-=item B<-ignore_critical>
-
-Normally if an unhandled critical extension is present which is not
-supported by OpenSSL the certificate is rejected (as required by RFC5280).
-If this option is set critical extensions are ignored.
-
-=item B<-inhibit_any>
-
-Set policy variable inhibit-any-policy (see RFC5280).
-
-=item B<-inhibit_map>
-
-Set policy variable inhibit-policy-mapping (see RFC5280).
-
-=item B<-no_check_time>
-
-This option suppresses checking the validity period of certificates and CRLs
-against the current time. If option B<-attime timestamp> is used to specify
-a verification time, the check is not suppressed.
-
-=item B<-partial_chain>
-
-Allow verification to succeed even if a I<complete> chain cannot be built to a
-self-signed trust-anchor, provided it is possible to construct a chain to a
-trusted certificate that might not be self-signed.
-
-=item B<-policy arg>
-
-Enable policy processing and add B<arg> to the user-initial-policy-set (see
-RFC5280). The policy B<arg> can be an object name an OID in numeric form.
-This argument can appear more than once.
-
-=item B<-policy_check>
-
-Enables certificate policy processing.
-
-=item B<-policy_print>
-
-Print out diagnostics related to policy processing.
-
-=item B<-purpose purpose>
-
-The intended use for the certificate. If this option is not specified,
-B<verify> will not consider certificate purpose during chain verification.
-Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
-B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more
-information.
-
-=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
-
-enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
-192 bit, or only 192 bit Level of Security respectively.
-See RFC6460 for details. In particular the supported signature algorithms are
-reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
-P-256 and P-384.
-
-=item B<-trusted_first>
-
-When constructing the certificate chain, use the trusted certificates specified
-via B<-CAfile>, B<-CApath> or B<-trusted> before any certificates specified via
-B<-untrusted>.
-This can be useful in environments with Bridge or Cross-Certified CAs.
-As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
-
-=item B<-no_alt_chains>
-
-By default, unless B<-trusted_first> is specified, when building a certificate
-chain, if the first certificate chain found is not trusted, then OpenSSL will
-attempt to replace untrusted issuer certificates with certificates from the
-trust store to see if an alternative chain can be found that is trusted.
-As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
-effect.
-
-=item B<-untrusted file>
-
-A B<file> of additional untrusted certificates (intermediate issuer CAs) used
-to construct a certificate chain from the subject certificate to a trust-anchor.
-The B<file> should contain one or more certificates in PEM format.
-This option can be specified more than once to include untrusted certificates
-from multiple B<files>.
-
-=item B<-trusted file>
-
-A B<file> of trusted certificates, which must be self-signed, unless the
-B<-partial_chain> option is specified.
-The B<file> contains one or more certificates in PEM format.
-With this option, no additional (e.g., default) certificate lists are
-consulted.
-That is, the only trust-anchors are those listed in B<file>.
-This option can be specified more than once to include trusted certificates
-from multiple B<files>.
-This option implies the B<-no-CAfile> and B<-no-CApath> options.
-This option cannot be used in combination with either of the B<-CAfile> or
-B<-CApath> options.
-
-=item B<-use_deltas>
-
-Enable support for delta CRLs.
-
-=item B<-verbose>
-
-Print extra information about the operations being performed.
-
-=item B<-auth_level level>
-
-Set the certificate chain authentication security level to B<level>.
-The authentication security level determines the acceptable signature and
-public key strength when verifying certificate chains.
-For a certificate chain to validate, the public keys of all the certificates
-must meet the specified security B<level>.
-The signature algorithm security level is enforced for all the certificates in
-the chain except for the chain's I<trust anchor>, which is either directly
-trusted or validated by means other than its signature.
-See L<SSL_CTX_set_security_level(3)> for the definitions of the available
-levels.
-The default security level is -1, or "not set".
-At security level 0 or lower all algorithms are acceptable.
-Security level 1 requires at least 80-bit-equivalent security and is broadly
-interoperable, though it will, for example, reject MD5 signatures or RSA keys
-shorter than 1024 bits.
-
-=item B<-verify_depth num>
-
-Limit the certificate chain to B<num> intermediate CA certificates.
-A maximal depth chain can have up to B<num+2> certificates, since neither the
-end-entity certificate nor the trust-anchor certificate count against the
-B<-verify_depth> limit.
-
-=item B<-verify_email email>
-
-Verify if the B<email> matches the email address in Subject Alternative Name or
-the email in the subject Distinguished Name.
-
-=item B<-verify_hostname hostname>
-
-Verify if the B<hostname> matches DNS name in Subject Alternative Name or
-Common Name in the subject certificate.
-
-=item B<-verify_ip ip>
-
-Verify if the B<ip> matches the IP address in Subject Alternative Name of
-the subject certificate.
-
-=item B<-verify_name name>
-
-Use default verification policies like trust model and required certificate
-policies identified by B<name>.
-The trust model determines which auxiliary trust or reject OIDs are applicable
-to verifying the given certificate chain.
-See the B<-addtrust> and B<-addreject> options of the L<x509(1)> command-line
-utility.
-Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
-B<ssl_client>, B<ssl_server>.
-These mimics the combinations of purpose and trust settings used in SSL, CMS
-and S/MIME.
-As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
-specified, so the B<-verify_name> options are functionally equivalent to the
-corresponding B<-purpose> settings.
-
-=item B<-x509_strict>
-
-For strict X.509 compliance, disable non-compliant workarounds for broken
-certificates.
-
-=item B<-show_chain>
-
-Display information about the certificate chain that has been built (if
-successful). Certificates in the chain that came from the untrusted list will be
-flagged as "untrusted".
-
-=item B<->
-
-Indicates the last option. All arguments following this are assumed to be
-certificate files. This is useful if the first certificate filename begins
-with a B<->.
-
-=item B<certificates>
-
-One or more certificates to verify. If no certificates are given, B<verify>
-will attempt to read a certificate from standard input. Certificates must be
-in PEM format.
-
-=back
-
-=head1 VERIFY OPERATION
-
-The B<verify> program uses the same functions as the internal SSL and S/MIME
-verification, therefore this description applies to these verify operations
-too.
-
-There is one crucial difference between the verify operations performed
-by the B<verify> program: wherever possible an attempt is made to continue
-after an error whereas normally the verify operation would halt on the
-first error. This allows all the problems with a certificate chain to be
-determined.
-
-The verify operation consists of a number of separate steps.
-
-Firstly a certificate chain is built up starting from the supplied certificate
-and ending in the root CA.
-It is an error if the whole chain cannot be built up.
-The chain is built up by looking up the issuers certificate of the current
-certificate.
-If a certificate is found which is its own issuer it is assumed to be the root
-CA.
-
-The process of 'looking up the issuers certificate' itself involves a number of
-steps.
-After all certificates whose subject name matches the issuer name of the current
-certificate are subject to further tests.
-The relevant authority key identifier components of the current certificate (if
-present) must match the subject key identifier (if present) and issuer and
-serial number of the candidate issuer, in addition the keyUsage extension of
-the candidate issuer (if present) must permit certificate signing.
-
-The lookup first looks in the list of untrusted certificates and if no match
-is found the remaining lookups are from the trusted certificates. The root CA
-is always looked up in the trusted certificate list: if the certificate to
-verify is a root certificate then an exact match must be found in the trusted
-list.
-
-The second operation is to check every untrusted certificate's extensions for
-consistency with the supplied purpose. If the B<-purpose> option is not included
-then no checks are done. The supplied or "leaf" certificate must have extensions
-compatible with the supplied purpose and all other certificates must also be valid
-CA certificates. The precise extensions required are described in more detail in
-the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
-
-The third operation is to check the trust settings on the root CA. The root CA
-should be trusted for the supplied purpose.
-For compatibility with previous versions of OpenSSL, a certificate with no
-trust settings is considered to be valid for all purposes.
-
-The final operation is to check the validity of the certificate chain. The validity
-period is checked against the current system time and the notBefore and notAfter
-dates in the certificate. The certificate signatures are also checked at this
-point.
-
-If all operations complete successfully then certificate is considered valid. If
-any operation fails then the certificate is not valid.
-
-=head1 DIAGNOSTICS
-
-When a verify operation fails the output messages can be somewhat cryptic. The
-general form of the error message is:
-
- server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
- error 24 at 1 depth lookup:invalid CA certificate
-
-The first line contains the name of the certificate being verified followed by
-the subject name of the certificate. The second line contains the error number
-and the depth. The depth is number of the certificate being verified when a
-problem was detected starting with zero for the certificate being verified itself
-then 1 for the CA that signed the certificate and so on. Finally a text version
-of the error number is presented.
-
-A partial list of the error codes and messages is shown below, this also
-includes the name of the error code as defined in the header file x509_vfy.h
-Some of the error codes are defined but never returned: these are described
-as "unused".
-
-=over 4
-
-=item B<X509_V_OK>
-
-The operation was successful.
-
-=item B<X509_V_ERR_UNSPECIFIED>
-
-Unspecified error; should not happen.
-
-=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT>
-
-The issuer certificate of a looked up certificate could not be found. This
-normally means the list of trusted certificates is not complete.
-
-=item B<X509_V_ERR_UNABLE_TO_GET_CRL>
-
-The CRL of a certificate could not be found.
-
-=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
-
-The certificate signature could not be decrypted. This means that the actual signature value
-could not be determined rather than it not matching the expected value, this is only
-meaningful for RSA keys.
-
-=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
-
-The CRL signature could not be decrypted: this means that the actual signature value
-could not be determined rather than it not matching the expected value. Unused.
-
-=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
-
-The public key in the certificate SubjectPublicKeyInfo could not be read.
-
-=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
-
-The signature of the certificate is invalid.
-
-=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
-
-The signature of the certificate is invalid.
-
-=item B<X509_V_ERR_CERT_NOT_YET_VALID>
-
-The certificate is not yet valid: the notBefore date is after the current time.
-
-=item B<X509_V_ERR_CERT_HAS_EXPIRED>
-
-The certificate has expired: that is the notAfter date is before the current time.
-
-=item B<X509_V_ERR_CRL_NOT_YET_VALID>
-
-The CRL is not yet valid.
-
-=item B<X509_V_ERR_CRL_HAS_EXPIRED>
-
-The CRL has expired.
-
-=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
-
-The certificate notBefore field contains an invalid time.
-
-=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
-
-The certificate notAfter field contains an invalid time.
-
-=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
-
-The CRL lastUpdate field contains an invalid time.
-
-=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
-
-The CRL nextUpdate field contains an invalid time.
-
-=item B<X509_V_ERR_OUT_OF_MEM>
-
-An error occurred trying to allocate memory. This should never happen.
-
-=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT>
-
-The passed certificate is self-signed and the same certificate cannot be found in the list of
-trusted certificates.
-
-=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN>
-
-The certificate chain could be built up using the untrusted certificates but the root could not
-be found locally.
-
-=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
-
-The issuer certificate could not be found: this occurs if the issuer
-certificate of an untrusted certificate cannot be found.
-
-=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE>
-
-No signatures could be verified because the chain contains only one certificate and it is not
-self signed.
-
-=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
-
-The certificate chain length is greater than the supplied maximum depth. Unused.
-
-=item B<X509_V_ERR_CERT_REVOKED>
-
-The certificate has been revoked.
-
-=item B<X509_V_ERR_INVALID_CA>
-
-A CA certificate is invalid. Either it is not a CA or its extensions are not consistent
-with the supplied purpose.
-
-=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
-
-The basicConstraints pathlength parameter has been exceeded.
-
-=item B<X509_V_ERR_INVALID_PURPOSE>
-
-The supplied certificate cannot be used for the specified purpose.
-
-=item B<X509_V_ERR_CERT_UNTRUSTED>
-
-the root CA is not marked as trusted for the specified purpose.
-
-=item B<X509_V_ERR_CERT_REJECTED>
-
-The root CA is marked to reject the specified purpose.
-
-=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH>
-
-not used as of OpenSSL 1.1.0 as a result of the deprecation of the
-B<-issuer_checks> option.
-
-=item B<X509_V_ERR_AKID_SKID_MISMATCH>
-
-Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
-B<-issuer_checks> option.
-
-=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH>
-
-Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
-B<-issuer_checks> option.
-
-=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
-
-Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
-B<-issuer_checks> option.
-
-=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
-
-Unable to get CRL issuer certificate.
-
-=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION>
-
-Unhandled critical extension.
-
-=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN>
-
-Key usage does not include CRL signing.
-
-=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION>
-
-Unhandled critical CRL extension.
-
-=item B<X509_V_ERR_INVALID_NON_CA>
-
-Invalid non-CA certificate has CA markings.
-
-=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED>
-
-Proxy path length constraint exceeded.
-
-=item B<X509_V_ERR_PROXY_SUBJECT_INVALID>
-
-Proxy certificate subject is invalid. It MUST be the same as the issuer
-with a single CN component added.
-
-=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE>
-
-Key usage does not include digital signature.
-
-=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED>
-
-Proxy certificates not allowed, please use B<-allow_proxy_certs>.
-
-=item B<X509_V_ERR_INVALID_EXTENSION>
-
-Invalid or inconsistent certificate extension.
-
-=item B<X509_V_ERR_INVALID_POLICY_EXTENSION>
-
-Invalid or inconsistent certificate policy extension.
-
-=item B<X509_V_ERR_NO_EXPLICIT_POLICY>
-
-No explicit policy.
-
-=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE>
-
-Different CRL scope.
-
-=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE>
-
-Unsupported extension feature.
-
-=item B<X509_V_ERR_UNNESTED_RESOURCE>
-
-RFC 3779 resource not subset of parent's resources.
-
-=item B<X509_V_ERR_PERMITTED_VIOLATION>
-
-Permitted subtree violation.
-
-=item B<X509_V_ERR_EXCLUDED_VIOLATION>
-
-Excluded subtree violation.
-
-=item B<X509_V_ERR_SUBTREE_MINMAX>
-
-Name constraints minimum and maximum not supported.
-
-=item B<X509_V_ERR_APPLICATION_VERIFICATION>
-
-Application verification failure. Unused.
-
-=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>
-
-Unsupported name constraint type.
-
-=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX>
-
-Unsupported or invalid name constraint syntax.
-
-=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>
-
-Unsupported or invalid name syntax.
-
-=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR>
-
-CRL path validation error.
-
-=item B<X509_V_ERR_PATH_LOOP>
-
-Path loop.
-
-=item B<X509_V_ERR_SUITE_B_INVALID_VERSION>
-
-Suite B: certificate version invalid.
-
-=item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM>
-
-Suite B: invalid public key algorithm.
-
-=item B<X509_V_ERR_SUITE_B_INVALID_CURVE>
-
-Suite B: invalid ECC curve.
-
-=item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM>
-
-Suite B: invalid signature algorithm.
-
-=item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED>
-
-Suite B: curve not allowed for this LOS.
-
-=item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256>
-
-Suite B: cannot sign P-384 with P-256.
-
-=item B<X509_V_ERR_HOSTNAME_MISMATCH>
-
-Hostname mismatch.
-
-=item B<X509_V_ERR_EMAIL_MISMATCH>
-
-Email address mismatch.
-
-=item B<X509_V_ERR_IP_ADDRESS_MISMATCH>
-
-IP address mismatch.
-
-=item B<X509_V_ERR_DANE_NO_MATCH>
-
-DANE TLSA authentication is enabled, but no TLSA records matched the
-certificate chain.
-This error is only possible in L<s_client(1)>.
-
-=back
-
-=head1 BUGS
-
-Although the issuer checks are a considerable improvement over the old technique they still
-suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
-trusted certificates with matching subject name must either appear in a file (as specified by the
-B<-CAfile> option) or a directory (as specified by B<-CApath>). If they occur in both then only
-the certificates in the file will be recognised.
-
-Previous versions of OpenSSL assume certificates with matching subject name are identical and
-mishandled them.
-
-Previous versions of this documentation swapped the meaning of the
-B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
-B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
-
-=head1 SEE ALSO
-
-L<x509(1)>
-
-=head1 HISTORY
-
-The B<-show_chain> option was first added to OpenSSL 1.1.0.
-
-The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
-is silently ignored.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-version - print OpenSSL version information
-
-=head1 SYNOPSIS
-
-B<openssl version>
-[B<-help>]
-[B<-a>]
-[B<-v>]
-[B<-b>]
-[B<-o>]
-[B<-f>]
-[B<-p>]
-[B<-d>]
-[B<-e>]
-
-=head1 DESCRIPTION
-
-This command is used to print out version information about OpenSSL.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-a>
-
-all information, this is the same as setting all the other flags.
-
-=item B<-v>
-
-the current OpenSSL version.
-
-=item B<-b>
-
-the date the current version of OpenSSL was built.
-
-=item B<-o>
-
-option information: various options set when the library was built.
-
-=item B<-f>
-
-compilation flags.
-
-=item B<-p>
-
-platform setting.
-
-=item B<-d>
-
-OPENSSLDIR setting.
-
-=item B<-e>
-
-ENGINESDIR setting.
-
-=back
-
-=head1 NOTES
-
-The output of B<openssl version -a> would typically be used when sending
-in a bug report.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-x509 - Certificate display and signing utility
-
-=head1 SYNOPSIS
-
-B<openssl> B<x509>
-[B<-help>]
-[B<-inform DER|PEM|NET>]
-[B<-outform DER|PEM|NET>]
-[B<-keyform DER|PEM>]
-[B<-CAform DER|PEM>]
-[B<-CAkeyform DER|PEM>]
-[B<-in filename>]
-[B<-out filename>]
-[B<-serial>]
-[B<-hash>]
-[B<-subject_hash>]
-[B<-issuer_hash>]
-[B<-ocspid>]
-[B<-subject>]
-[B<-issuer>]
-[B<-nameopt option>]
-[B<-email>]
-[B<-ocsp_uri>]
-[B<-startdate>]
-[B<-enddate>]
-[B<-purpose>]
-[B<-dates>]
-[B<-checkend num>]
-[B<-modulus>]
-[B<-pubkey>]
-[B<-fingerprint>]
-[B<-alias>]
-[B<-noout>]
-[B<-trustout>]
-[B<-clrtrust>]
-[B<-clrreject>]
-[B<-addtrust arg>]
-[B<-addreject arg>]
-[B<-setalias arg>]
-[B<-days arg>]
-[B<-set_serial n>]
-[B<-signkey filename>]
-[B<-passin arg>]
-[B<-x509toreq>]
-[B<-req>]
-[B<-CA filename>]
-[B<-CAkey filename>]
-[B<-CAcreateserial>]
-[B<-CAserial filename>]
-[B<-force_pubkey key>]
-[B<-text>]
-[B<-certopt option>]
-[B<-C>]
-[B<-[digest]>]
-[B<-clrext>]
-[B<-extfile filename>]
-[B<-extensions section>]
-[B<-engine id>]
-
-=head1 DESCRIPTION
-
-The B<x509> command is a multi purpose certificate utility. It can be
-used to display certificate information, convert certificates to
-various forms, sign certificate requests like a "mini CA" or edit
-certificate trust settings.
-
-Since there are a large number of options they will split up into
-various sections.
-
-=head1 OPTIONS
-
-=head2 Input, Output, and General Purpose Options
-
-=over 4
-
-=item B<-help>
-
-Print out a usage message.
-
-=item B<-inform DER|PEM|NET>
-
-This specifies the input format normally the command will expect an X509
-certificate but this can change if other options such as B<-req> are
-present. The DER format is the DER encoding of the certificate and PEM
-is the base64 encoding of the DER encoding with header and footer lines
-added. The NET option is an obscure Netscape server format that is now
-obsolete.
-
-=item B<-outform DER|PEM|NET>
-
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
-
-=item B<-in filename>
-
-This specifies the input filename to read a certificate from or standard input
-if this option is not specified.
-
-=item B<-out filename>
-
-This specifies the output filename to write to or standard output by
-default.
-
-=item B<-[digest]>
-
-the digest to use.
-This affects any signing or display option that uses a message
-digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options.
-Any digest supported by the OpenSSL B<dgst> command can be used.
-If not specified then SHA1 is used with B<-fingerprint> or
-the default digest for the signing algorithm is used, typically SHA256.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<x509>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
-
-=back
-
-=head2 Display Options
-
-Note: the B<-alias> and B<-purpose> options are also display options
-but are described in the B<TRUST SETTINGS> section.
-
-=over 4
-
-=item B<-text>
-
-prints out the certificate in text form. Full details are output including the
-public key, signature algorithms, issuer and subject names, serial number
-any extensions present and any trust settings.
-
-=item B<-certopt option>
-
-customise the output format used with B<-text>. The B<option> argument can be
-a single option or multiple options separated by commas. The B<-certopt> switch
-may be also be used more than once to set multiple options. See the B<TEXT OPTIONS>
-section for more information.
-
-=item B<-noout>
-
-this option prevents output of the encoded version of the request.
-
-=item B<-pubkey>
-
-outputs the certificate's SubjectPublicKeyInfo block in PEM format.
-
-=item B<-modulus>
-
-this option prints out the value of the modulus of the public key
-contained in the certificate.
-
-=item B<-serial>
-
-outputs the certificate serial number.
-
-=item B<-subject_hash>
-
-outputs the "hash" of the certificate subject name. This is used in OpenSSL to
-form an index to allow certificates in a directory to be looked up by subject
-name.
-
-=item B<-issuer_hash>
-
-outputs the "hash" of the certificate issuer name.
-
-=item B<-ocspid>
-
-outputs the OCSP hash values for the subject name and public key.
-
-=item B<-hash>
-
-synonym for "-subject_hash" for backward compatibility reasons.
-
-=item B<-subject_hash_old>
-
-outputs the "hash" of the certificate subject name using the older algorithm
-as used by OpenSSL versions before 1.0.0.
-
-=item B<-issuer_hash_old>
-
-outputs the "hash" of the certificate issuer name using the older algorithm
-as used by OpenSSL versions before 1.0.0.
-
-=item B<-subject>
-
-outputs the subject name.
-
-=item B<-issuer>
-
-outputs the issuer name.
-
-=item B<-nameopt option>
-
-option which determines how the subject or issuer names are displayed. The
-B<option> argument can be a single option or multiple options separated by
-commas. Alternatively the B<-nameopt> switch may be used more than once to
-set multiple options. See the B<NAME OPTIONS> section for more information.
-
-=item B<-email>
-
-outputs the email address(es) if any.
-
-=item B<-ocsp_uri>
-
-outputs the OCSP responder address(es) if any.
-
-=item B<-startdate>
-
-prints out the start date of the certificate, that is the notBefore date.
-
-=item B<-enddate>
-
-prints out the expiry date of the certificate, that is the notAfter date.
-
-=item B<-dates>
-
-prints out the start and expiry dates of a certificate.
-
-=item B<-checkend arg>
-
-checks if the certificate expires within the next B<arg> seconds and exits
-non-zero if yes it will expire or zero if not.
-
-=item B<-fingerprint>
-
-prints out the digest of the DER encoded version of the whole certificate
-(see digest options).
-
-=item B<-C>
-
-this outputs the certificate in the form of a C source file.
-
-=back
-
-=head2 Trust Settings
-
-A B<trusted certificate> is an ordinary certificate which has several
-additional pieces of information attached to it such as the permitted
-and prohibited uses of the certificate and an "alias".
-
-Normally when a certificate is being verified at least one certificate
-must be "trusted". By default a trusted certificate must be stored
-locally and must be a root CA: any certificate chain ending in this CA
-is then usable for any purpose.
-
-Trust settings currently are only used with a root CA. They allow a finer
-control over the purposes the root CA can be used for. For example a CA
-may be trusted for SSL client but not SSL server use.
-
-See the description of the B<verify> utility for more information on the
-meaning of trust settings.
-
-Future versions of OpenSSL will recognize trust settings on any
-certificate: not just root CAs.
-
-
-=over 4
-
-=item B<-trustout>
-
-this causes B<x509> to output a B<trusted> certificate. An ordinary
-or trusted certificate can be input but by default an ordinary
-certificate is output and any trust settings are discarded. With the
-B<-trustout> option a trusted certificate is output. A trusted
-certificate is automatically output if any trust settings are modified.
-
-=item B<-setalias arg>
-
-sets the alias of the certificate. This will allow the certificate
-to be referred to using a nickname for example "Steve's Certificate".
-
-=item B<-alias>
-
-outputs the certificate alias, if any.
-
-=item B<-clrtrust>
-
-clears all the permitted or trusted uses of the certificate.
-
-=item B<-clrreject>
-
-clears all the prohibited or rejected uses of the certificate.
-
-=item B<-addtrust arg>
-
-adds a trusted certificate use.
-Any object name can be used here but currently only B<clientAuth> (SSL client
-use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and
-B<anyExtendedKeyUsage> are used.
-As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
-enables all purposes when trusted.
-Other OpenSSL applications may define additional uses.
-
-=item B<-addreject arg>
-
-adds a prohibited use. It accepts the same values as the B<-addtrust>
-option.
-
-=item B<-purpose>
-
-this option performs tests on the certificate extensions and outputs
-the results. For a more complete description see the B<CERTIFICATE
-EXTENSIONS> section.
-
-=back
-
-=head2 Signing Options
-
-The B<x509> utility can be used to sign certificates and requests: it
-can thus behave like a "mini CA".
-
-=over 4
-
-=item B<-signkey filename>
-
-this option causes the input file to be self signed using the supplied
-private key.
-
-If the input file is a certificate it sets the issuer name to the
-subject name (i.e. makes it self signed) changes the public key to the
-supplied value and changes the start and end dates. The start date is
-set to the current time and the end date is set to a value determined
-by the B<-days> option. Any certificate extensions are retained unless
-the B<-clrext> option is supplied; this includes, for example, any existing
-key identifier extensions.
-
-If the input is a certificate request then a self signed certificate
-is created using the supplied private key using the subject name in
-the request.
-
-=item B<-passin arg>
-
-the key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-
-=item B<-clrext>
-
-delete any extensions from a certificate. This option is used when a
-certificate is being created from another certificate (for example with
-the B<-signkey> or the B<-CA> options). Normally all extensions are
-retained.
-
-=item B<-keyform PEM|DER>
-
-specifies the format (DER or PEM) of the private key file used in the
-B<-signkey> option.
-
-=item B<-days arg>
-
-specifies the number of days to make a certificate valid for. The default
-is 30 days.
-
-=item B<-x509toreq>
-
-converts a certificate into a certificate request. The B<-signkey> option
-is used to pass the required private key.
-
-=item B<-req>
-
-by default a certificate is expected on input. With this option a
-certificate request is expected instead.
-
-=item B<-set_serial n>
-
-specifies the serial number to use. This option can be used with either
-the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
-option the serial number file (as specified by the B<-CAserial> or
-B<-CAcreateserial> options) is not used.
-
-The serial number can be decimal or hex (if preceded by B<0x>).
-
-=item B<-CA filename>
-
-specifies the CA certificate to be used for signing. When this option is
-present B<x509> behaves like a "mini CA". The input file is signed by this
-CA using this option: that is its issuer name is set to the subject name
-of the CA and it is digitally signed using the CAs private key.
-
-This option is normally combined with the B<-req> option. Without the
-B<-req> option the input is a certificate which must be self signed.
-
-=item B<-CAkey filename>
-
-sets the CA private key to sign a certificate with. If this option is
-not specified then it is assumed that the CA private key is present in
-the CA certificate file.
-
-=item B<-CAserial filename>
-
-sets the CA serial number file to use.
-
-When the B<-CA> option is used to sign a certificate it uses a serial
-number specified in a file. This file consist of one line containing
-an even number of hex digits with the serial number to use. After each
-use the serial number is incremented and written out to the file again.
-
-The default filename consists of the CA certificate file base name with
-".srl" appended. For example if the CA certificate file is called
-"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
-
-=item B<-CAcreateserial>
-
-with this option the CA serial number file is created if it does not exist:
-it will contain the serial number "02" and the certificate being signed will
-have the 1 as its serial number. If the B<-CA> option is specified
-and the serial number file does not exist a random number is generated;
-this is the recommended practice.
-
-=item B<-extfile filename>
-
-file containing certificate extensions to use. If not specified then
-no extensions are added to the certificate.
-
-=item B<-extensions section>
-
-the section to add certificate extensions from. If this option is not
-specified then the extensions should either be contained in the unnamed
-(default) section or the default section should contain a variable called
-"extensions" which contains the section to use. See the
-L<x509v3_config(5)> manual page for details of the
-extension section format.
-
-=item B<-force_pubkey key>
-
-when a certificate is created set its public key to B<key> instead of the
-key in the certificate or certificate request. This option is useful for
-creating certificates where the algorithm can't normally sign requests, for
-example DH.
-
-The format or B<key> can be specified using the B<-keyform> option.
-
-=back
-
-=head2 Name Options
-
-The B<nameopt> command line switch determines how the subject and issuer
-names are displayed. If no B<nameopt> switch is present the default "oneline"
-format is used which is compatible with previous versions of OpenSSL.
-Each option is described in detail below, all options can be preceded by
-a B<-> to turn the option off. Only the first four will normally be used.
-
-=over 4
-
-=item B<compat>
-
-use the old format.
-
-=item B<RFC2253>
-
-displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
-B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
-B<sep_comma_plus>, B<dn_rev> and B<sname>.
-
-=item B<oneline>
-
-a oneline format which is more readable than RFC2253. It is equivalent to
-specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
-B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
-options. This is the I<default> of no name options are given explicitly.
-
-=item B<multiline>
-
-a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
-B<space_eq>, B<lname> and B<align>.
-
-=item B<esc_2253>
-
-escape the "special" characters required by RFC2253 in a field. That is
-B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
-and a space character at the beginning or end of a string.
-
-=item B<esc_2254>
-
-escape the "special" characters required by RFC2254 in a field. That is
-the B<NUL> character as well as and B<()*>.
-
-=item B<esc_ctrl>
-
-escape control characters. That is those with ASCII values less than
-0x20 (space) and the delete (0x7f) character. They are escaped using the
-RFC2253 \XX notation (where XX are two hex digits representing the
-character value).
-
-=item B<esc_msb>
-
-escape characters with the MSB set, that is with ASCII values larger than
-127.
-
-=item B<use_quote>
-
-escapes some characters by surrounding the whole string with B<"> characters,
-without the option all escaping is done with the B<\> character.
-
-=item B<utf8>
-
-convert all strings to UTF8 format first. This is required by RFC2253. If
-you are lucky enough to have a UTF8 compatible terminal then the use
-of this option (and B<not> setting B<esc_msb>) may result in the correct
-display of multibyte (international) characters. Is this option is not
-present then multibyte characters larger than 0xff will be represented
-using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
-Also if this option is off any UTF8Strings will be converted to their
-character form first.
-
-=item B<ignore_type>
-
-this option does not attempt to interpret multibyte characters in any
-way. That is their content octets are merely dumped as though one octet
-represents each character. This is useful for diagnostic purposes but
-will result in rather odd looking output.
-
-=item B<show_type>
-
-show the type of the ASN1 character string. The type precedes the
-field contents. For example "BMPSTRING: Hello World".
-
-=item B<dump_der>
-
-when this option is set any fields that need to be hexdumped will
-be dumped using the DER encoding of the field. Otherwise just the
-content octets will be displayed. Both options use the RFC2253
-B<#XXXX...> format.
-
-=item B<dump_nostr>
-
-dump non character string types (for example OCTET STRING) if this
-option is not set then non character string types will be displayed
-as though each content octet represents a single character.
-
-=item B<dump_all>
-
-dump all fields. This option when used with B<dump_der> allows the
-DER encoding of the structure to be unambiguously determined.
-
-=item B<dump_unknown>
-
-dump any field whose OID is not recognised by OpenSSL.
-
-=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
-B<sep_multiline>
-
-these options determine the field separators. The first character is
-between RDNs and the second between multiple AVAs (multiple AVAs are
-very rare and their use is discouraged). The options ending in
-"space" additionally place a space after the separator to make it
-more readable. The B<sep_multiline> uses a linefeed character for
-the RDN separator and a spaced B<+> for the AVA separator. It also
-indents the fields by four characters. If no field separator is specified
-then B<sep_comma_plus_space> is used by default.
-
-=item B<dn_rev>
-
-reverse the fields of the DN. This is required by RFC2253. As a side
-effect this also reverses the order of multiple AVAs but this is
-permissible.
-
-=item B<nofname>, B<sname>, B<lname>, B<oid>
-
-these options alter how the field name is displayed. B<nofname> does
-not display the field at all. B<sname> uses the "short name" form
-(CN for commonName for example). B<lname> uses the long form.
-B<oid> represents the OID in numerical form and is useful for
-diagnostic purpose.
-
-=item B<align>
-
-align field values for a more readable output. Only usable with
-B<sep_multiline>.
-
-=item B<space_eq>
-
-places spaces round the B<=> character which follows the field
-name.
-
-=back
-
-=head2 Text Options
-
-As well as customising the name output format, it is also possible to
-customise the actual fields printed using the B<certopt> options when
-the B<text> option is present. The default behaviour is to print all fields.
-
-=over 4
-
-=item B<compatible>
-
-use the old format. This is equivalent to specifying no output options at all.
-
-=item B<no_header>
-
-don't print header information: that is the lines saying "Certificate" and "Data".
-
-=item B<no_version>
-
-don't print out the version number.
-
-=item B<no_serial>
-
-don't print out the serial number.
-
-=item B<no_signame>
-
-don't print out the signature algorithm used.
-
-=item B<no_validity>
-
-don't print the validity, that is the B<notBefore> and B<notAfter> fields.
-
-=item B<no_subject>
-
-don't print out the subject name.
-
-=item B<no_issuer>
-
-don't print out the issuer name.
-
-=item B<no_pubkey>
-
-don't print out the public key.
-
-=item B<no_sigdump>
-
-don't give a hexadecimal dump of the certificate signature.
-
-=item B<no_aux>
-
-don't print out certificate trust information.
-
-=item B<no_extensions>
-
-don't print out any X509V3 extensions.
-
-=item B<ext_default>
-
-retain default extension behaviour: attempt to print out unsupported certificate extensions.
-
-=item B<ext_error>
-
-print an error message for unsupported certificate extensions.
-
-=item B<ext_parse>
-
-ASN1 parse unsupported extensions.
-
-=item B<ext_dump>
-
-hex dump unsupported extensions.
-
-=item B<ca_default>
-
-the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>,
-B<no_header>, and B<no_version>.
-
-=back
-
-=head1 EXAMPLES
-
-Note: in these examples the '\' means the example should be all on one
-line.
-
-Display the contents of a certificate:
-
- openssl x509 -in cert.pem -noout -text
-
-Display the certificate serial number:
-
- openssl x509 -in cert.pem -noout -serial
-
-Display the certificate subject name:
-
- openssl x509 -in cert.pem -noout -subject
-
-Display the certificate subject name in RFC2253 form:
-
- openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
-
-Display the certificate subject name in oneline form on a terminal
-supporting UTF8:
-
- openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
-
-Display the certificate MD5 fingerprint:
-
- openssl x509 -in cert.pem -noout -fingerprint
-
-Display the certificate SHA1 fingerprint:
-
- openssl x509 -sha1 -in cert.pem -noout -fingerprint
-
-Convert a certificate from PEM to DER format:
-
- openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
-
-Convert a certificate to a certificate request:
-
- openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
-
-Convert a certificate request into a self signed certificate using
-extensions for a CA:
-
- openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
- -signkey key.pem -out cacert.pem
-
-Sign a certificate request using the CA certificate above and add user
-certificate extensions:
-
- openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
- -CA cacert.pem -CAkey key.pem -CAcreateserial
-
-
-Set a certificate to be trusted for SSL client use and change set its alias to
-"Steve's Class 1 CA"
-
- openssl x509 -in cert.pem -addtrust clientAuth \
- -setalias "Steve's Class 1 CA" -out trust.pem
-
-=head1 NOTES
-
-The PEM format uses the header and footer lines:
-
- -----BEGIN CERTIFICATE-----
- -----END CERTIFICATE-----
-
-it will also handle files containing:
-
- -----BEGIN X509 CERTIFICATE-----
- -----END X509 CERTIFICATE-----
-
-Trusted certificates have the lines
-
- -----BEGIN TRUSTED CERTIFICATE-----
- -----END TRUSTED CERTIFICATE-----
-
-The conversion to UTF8 format used with the name options assumes that
-T61Strings use the ISO8859-1 character set. This is wrong but Netscape
-and MSIE do this as do many certificates. So although this is incorrect
-it is more likely to display the majority of certificates correctly.
-
-The B<-fingerprint> option takes the digest of the DER encoded certificate.
-This is commonly called a "fingerprint". Because of the nature of message
-digests the fingerprint of a certificate is unique to that certificate and
-two certificates with the same fingerprint can be considered to be the same.
-
-The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
-
-The B<-email> option searches the subject name and the subject alternative
-name extension. Only unique email addresses will be printed out: it will
-not print the same address more than once.
-
-=head1 CERTIFICATE EXTENSIONS
-
-The B<-purpose> option checks the certificate extensions and determines
-what the certificate can be used for. The actual checks done are rather
-complex and include various hacks and workarounds to handle broken
-certificates and software.
-
-The same code is used when verifying untrusted certificates in chains
-so this section is useful if a chain is rejected by the verify code.
-
-The basicConstraints extension CA flag is used to determine whether the
-certificate can be used as a CA. If the CA flag is true then it is a CA,
-if the CA flag is false then it is not a CA. B<All> CAs should have the
-CA flag set to true.
-
-If the basicConstraints extension is absent then the certificate is
-considered to be a "possible CA" other extensions are checked according
-to the intended use of the certificate. A warning is given in this case
-because the certificate should really not be regarded as a CA: however
-it is allowed to be a CA to work around some broken software.
-
-If the certificate is a V1 certificate (and thus has no extensions) and
-it is self signed it is also assumed to be a CA but a warning is again
-given: this is to work around the problem of Verisign roots which are V1
-self signed certificates.
-
-If the keyUsage extension is present then additional restraints are
-made on the uses of the certificate. A CA certificate B<must> have the
-keyCertSign bit set if the keyUsage extension is present.
-
-The extended key usage extension places additional restrictions on the
-certificate uses. If this extension is present (whether critical or not)
-the key can only be used for the purposes specified.
-
-A complete description of each test is given below. The comments about
-basicConstraints and keyUsage and V1 certificates above apply to B<all>
-CA certificates.
-
-
-=over 4
-
-=item B<SSL Client>
-
-The extended key usage extension must be absent or include the "web client
-authentication" OID. keyUsage must be absent or it must have the
-digitalSignature bit set. Netscape certificate type must be absent or it must
-have the SSL client bit set.
-
-=item B<SSL Client CA>
-
-The extended key usage extension must be absent or include the "web client
-authentication" OID. Netscape certificate type must be absent or it must have
-the SSL CA bit set: this is used as a work around if the basicConstraints
-extension is absent.
-
-=item B<SSL Server>
-
-The extended key usage extension must be absent or include the "web server
-authentication" and/or one of the SGC OIDs. keyUsage must be absent or it
-must have the digitalSignature, the keyEncipherment set or both bits set.
-Netscape certificate type must be absent or have the SSL server bit set.
-
-=item B<SSL Server CA>
-
-The extended key usage extension must be absent or include the "web server
-authentication" and/or one of the SGC OIDs. Netscape certificate type must
-be absent or the SSL CA bit must be set: this is used as a work around if the
-basicConstraints extension is absent.
-
-=item B<Netscape SSL Server>
-
-For Netscape SSL clients to connect to an SSL server it must have the
-keyEncipherment bit set if the keyUsage extension is present. This isn't
-always valid because some cipher suites use the key for digital signing.
-Otherwise it is the same as a normal SSL server.
-
-=item B<Common S/MIME Client Tests>
-
-The extended key usage extension must be absent or include the "email
-protection" OID. Netscape certificate type must be absent or should have the
-S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type
-then the SSL client bit is tolerated as an alternative but a warning is shown:
-this is because some Verisign certificates don't set the S/MIME bit.
-
-=item B<S/MIME Signing>
-
-In addition to the common S/MIME client tests the digitalSignature bit must
-be set if the keyUsage extension is present.
-
-=item B<S/MIME Encryption>
-
-In addition to the common S/MIME tests the keyEncipherment bit must be set
-if the keyUsage extension is present.
-
-=item B<S/MIME CA>
-
-The extended key usage extension must be absent or include the "email
-protection" OID. Netscape certificate type must be absent or must have the
-S/MIME CA bit set: this is used as a work around if the basicConstraints
-extension is absent.
-
-=item B<CRL Signing>
-
-The keyUsage extension must be absent or it must have the CRL signing bit
-set.
-
-=item B<CRL Signing CA>
-
-The normal CA tests apply. Except in this case the basicConstraints extension
-must be present.
-
-=back
-
-=head1 BUGS
-
-Extensions in certificates are not transferred to certificate requests and
-vice versa.
-
-It is possible to produce invalid certificates or requests by specifying the
-wrong private key or using inconsistent options in some cases: these should
-be checked.
-
-There should be options to explicitly set such things as start and end
-dates rather than an offset from the current time.
-
-=head1 SEE ALSO
-
-L<req(1)>, L<ca(1)>, L<genrsa(1)>,
-L<gendsa(1)>, L<verify(1)>,
-L<x509v3_config(5)>
-
-=head1 HISTORY
-
-The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
-before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
-of the distinguished name. In OpenSSL 1.0.0 and later it is based on a
-canonical version of the DN using SHA1. This means that any directories using
-the old form must have their links rebuilt using B<c_rehash> or similar.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:5
-
-=head1 NAME
-
-x509v3_config - X509 V3 certificate extension configuration format
-
-=head1 DESCRIPTION
-
-Several of the OpenSSL utilities can add extensions to a certificate or
-certificate request based on the contents of a configuration file.
-
-Typically the application will contain an option to point to an extension
-section. Each line of the extension section takes the form:
-
- extension_name=[critical,] extension_options
-
-If B<critical> is present then the extension will be critical.
-
-The format of B<extension_options> depends on the value of B<extension_name>.
-
-There are four main types of extension: I<string> extensions, I<multi-valued>
-extensions, I<raw> and I<arbitrary> extensions.
-
-String extensions simply have a string which contains either the value itself
-or how it is obtained.
-
-For example:
-
- nsComment="This is a Comment"
-
-Multi-valued extensions have a short form and a long form. The short form
-is a list of names and values:
-
- basicConstraints=critical,CA:true,pathlen:1
-
-The long form allows the values to be placed in a separate section:
-
- basicConstraints=critical,@bs_section
-
- [bs_section]
-
- CA=true
- pathlen=1
-
-Both forms are equivalent.
-
-The syntax of raw extensions is governed by the extension code: it can
-for example contain data in multiple sections. The correct syntax to
-use is defined by the extension code itself: check out the certificate
-policies extension for an example.
-
-If an extension type is unsupported then the I<arbitrary> extension syntax
-must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details.
-
-=head1 STANDARD EXTENSIONS
-
-The following sections describe each supported extension in detail.
-
-=head2 Basic Constraints.
-
-This is a multi valued extension which indicates whether a certificate is
-a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
-B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an
-non-negative value can be included.
-
-For example:
-
- basicConstraints=CA:TRUE
-
- basicConstraints=CA:FALSE
-
- basicConstraints=critical,CA:TRUE, pathlen:0
-
-A CA certificate B<must> include the basicConstraints value with the CA field
-set to TRUE. An end user certificate must either set CA to FALSE or exclude the
-extension entirely. Some software may require the inclusion of basicConstraints
-with CA set to FALSE for end entity certificates.
-
-The pathlen parameter indicates the maximum number of CAs that can appear
-below this one in a chain. So if you have a CA with a pathlen of zero it can
-only be used to sign end user certificates and not further CAs.
-
-
-=head2 Key Usage.
-
-Key usage is a multi valued extension consisting of a list of names of the
-permitted key usages.
-
-The supported names are: digitalSignature, nonRepudiation, keyEncipherment,
-dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
-and decipherOnly.
-
-Examples:
-
- keyUsage=digitalSignature, nonRepudiation
-
- keyUsage=critical, keyCertSign
-
-
-=head2 Extended Key Usage.
-
-This extensions consists of a list of usages indicating purposes for which
-the certificate public key can be used for,
-
-These can either be object short names or the dotted numerical form of OIDs.
-While any OID can be used only certain values make sense. In particular the
-following PKIX, NS and MS values are meaningful:
-
- Value Meaning
- ----- -------
- serverAuth SSL/TLS Web Server Authentication.
- clientAuth SSL/TLS Web Client Authentication.
- codeSigning Code signing.
- emailProtection E-mail Protection (S/MIME).
- timeStamping Trusted Timestamping
- OCSPSigning OCSP Signing
- ipsecIKE ipsec Internet Key Exchange
- msCodeInd Microsoft Individual Code Signing (authenticode)
- msCodeCom Microsoft Commercial Code Signing (authenticode)
- msCTLSign Microsoft Trust List Signing
- msEFS Microsoft Encrypted File System
-
-Examples:
-
- extendedKeyUsage=critical,codeSigning,1.2.3.4
- extendedKeyUsage=serverAuth,clientAuth
-
-
-=head2 Subject Key Identifier.
-
-This is really a string extension and can take two possible values. Either
-the word B<hash> which will automatically follow the guidelines in RFC3280
-or a hex string giving the extension value to include. The use of the hex
-string is strongly discouraged.
-
-Example:
-
- subjectKeyIdentifier=hash
-
-
-=head2 Authority Key Identifier.
-
-The authority key identifier extension permits two options. keyid and issuer:
-both can take the optional value "always".
-
-If the keyid option is present an attempt is made to copy the subject key
-identifier from the parent certificate. If the value "always" is present
-then an error is returned if the option fails.
-
-The issuer option copies the issuer and serial number from the issuer
-certificate. This will only be done if the keyid option fails or
-is not included unless the "always" flag will always include the value.
-
-Example:
-
- authorityKeyIdentifier=keyid,issuer
-
-
-=head2 Subject Alternative Name.
-
-The subject alternative name extension allows various literal values to be
-included in the configuration file. These include B<email> (an email address)
-B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
-registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
-(a distinguished name) and otherName.
-
-The email option include a special 'copy' value. This will automatically
-include and email addresses contained in the certificate subject name in
-the extension.
-
-The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
-
-The value of B<dirName> should point to a section containing the distinguished
-name to use as a set of name value pairs. Multi values AVAs can be formed by
-prefacing the name with a B<+> character.
-
-otherName can include arbitrary data associated with an OID: the value
-should be the OID followed by a semicolon and the content in standard
-L<ASN1_generate_nconf(3)> format.
-
-Examples:
-
- subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
- subjectAltName=IP:192.168.7.1
- subjectAltName=IP:13::17
- subjectAltName=email:my@other.address,RID:1.2.3.4
- subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
-
- subjectAltName=dirName:dir_sect
-
- [dir_sect]
- C=UK
- O=My Organization
- OU=My Unit
- CN=My Name
-
-
-=head2 Issuer Alternative Name.
-
-The issuer alternative name option supports all the literal options of
-subject alternative name. It does B<not> support the email:copy option because
-that would not make sense. It does support an additional issuer:copy option
-that will copy all the subject alternative name values from the issuer
-certificate (if possible).
-
-Example:
-
- issuserAltName = issuer:copy
-
-
-=head2 Authority Info Access.
-
-The authority information access extension gives details about how to access
-certain information relating to the CA. Its syntax is accessOID;location
-where I<location> has the same syntax as subject alternative name (except
-that email:copy is not supported). accessOID can be any valid OID but only
-certain values are meaningful, for example OCSP and caIssuers.
-
-Example:
-
- authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
- authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
-
-
-=head2 CRL distribution points
-
-This is a multi-valued extension whose options can be either in name:value pair
-using the same form as subject alternative name or a single value representing
-a section name containing all the distribution point fields.
-
-For a name:value pair a new DistributionPoint with the fullName field set to
-the given value both the cRLissuer and reasons fields are omitted in this case.
-
-In the single option case the section indicated contains values for each
-field. In this section:
-
-If the name is "fullname" the value field should contain the full name
-of the distribution point in the same format as subject alternative name.
-
-If the name is "relativename" then the value field should contain a section
-name whose contents represent a DN fragment to be placed in this field.
-
-The name "CRLIssuer" if present should contain a value for this field in
-subject alternative name format.
-
-If the name is "reasons" the value field should consist of a comma
-separated field containing the reasons. Valid reasons are: "keyCompromise",
-"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation",
-"certificateHold", "privilegeWithdrawn" and "AACompromise".
-
-
-Simple examples:
-
- crlDistributionPoints=URI:http://myhost.com/myca.crl
- crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
-
-Full distribution point example:
-
- crlDistributionPoints=crldp1_section
-
- [crldp1_section]
-
- fullname=URI:http://myhost.com/myca.crl
- CRLissuer=dirName:issuer_sect
- reasons=keyCompromise, CACompromise
-
- [issuer_sect]
- C=UK
- O=Organisation
- CN=Some Name
-
-=head2 Issuing Distribution Point
-
-This extension should only appear in CRLs. It is a multi valued extension
-whose syntax is similar to the "section" pointed to by the CRL distribution
-points extension with a few differences.
-
-The names "reasons" and "CRLissuer" are not recognized.
-
-The name "onlysomereasons" is accepted which sets this field. The value is
-in the same format as the CRL distribution point "reasons" field.
-
-The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted
-the values should be a boolean value (TRUE or FALSE) to indicate the value of
-the corresponding field.
-
-Example:
-
- issuingDistributionPoint=critical, @idp_section
-
- [idp_section]
-
- fullname=URI:http://myhost.com/myca.crl
- indirectCRL=TRUE
- onlysomereasons=keyCompromise, CACompromise
-
- [issuer_sect]
- C=UK
- O=Organisation
- CN=Some Name
-
-
-=head2 Certificate Policies.
-
-This is a I<raw> extension. All the fields of this extension can be set by
-using the appropriate syntax.
-
-If you follow the PKIX recommendations and just using one OID then you just
-include the value of that OID. Multiple OIDs can be set separated by commas,
-for example:
-
- certificatePolicies= 1.2.4.5, 1.1.3.4
-
-If you wish to include qualifiers then the policy OID and qualifiers need to
-be specified in a separate section: this is done by using the @section syntax
-instead of a literal OID value.
-
-The section referred to must include the policy OID using the name
-policyIdentifier, cPSuri qualifiers can be included using the syntax:
-
- CPS.nnn=value
-
-userNotice qualifiers can be set using the syntax:
-
- userNotice.nnn=@notice
-
-The value of the userNotice qualifier is specified in the relevant section.
-This section can include explicitText, organization and noticeNumbers
-options. explicitText and organization are text strings, noticeNumbers is a
-comma separated list of numbers. The organization and noticeNumbers options
-(if included) must BOTH be present. If you use the userNotice option with IE5
-then you need the 'ia5org' option at the top level to modify the encoding:
-otherwise it will not be interpreted properly.
-
-Example:
-
- certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
-
- [polsect]
-
- policyIdentifier = 1.3.5.8
- CPS.1="http://my.host.name/"
- CPS.2="http://my.your.name/"
- userNotice.1=@notice
-
- [notice]
-
- explicitText="Explicit Text Here"
- organization="Organisation Name"
- noticeNumbers=1,2,3,4
-
-The B<ia5org> option changes the type of the I<organization> field. In RFC2459
-it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible.
-Some software (for example some versions of MSIE) may require ia5org.
-
-=head2 Policy Constraints
-
-This is a multi-valued extension which consisting of the names
-B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
-value. At least one component must be present.
-
-Example:
-
- policyConstraints = requireExplicitPolicy:3
-
-
-=head2 Inhibit Any Policy
-
-This is a string extension whose value must be a non negative integer.
-
-Example:
-
- inhibitAnyPolicy = 2
-
-
-=head2 Name Constraints
-
-The name constraints extension is a multi-valued extension. The name should
-begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
-the name and the value follows the syntax of subjectAltName except email:copy
-is not supported and the B<IP> form should consist of an IP addresses and
-subnet mask separated by a B</>.
-
-Examples:
-
- nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
-
- nameConstraints=permitted;email:.somedomain.com
-
- nameConstraints=excluded;email:.com
-
-
-=head2 OCSP No Check
-
-The OCSP No Check extension is a string extension but its value is ignored.
-
-Example:
-
- noCheck = ignored
-
-
-=head2 TLS Feature (aka Must Staple)
-
-This is a multi-valued extension consisting of a list of TLS extension
-identifiers. Each identifier may be a number (0..65535) or a supported name.
-When a TLS client sends a listed extension, the TLS server is expected to
-include that extension in its reply.
-
-The supported names are: B<status_request> and B<status_request_v2>.
-
-Example:
-
- tlsfeature = status_request
-
-
-=head1 DEPRECATED EXTENSIONS
-
-The following extensions are non standard, Netscape specific and largely
-obsolete. Their use in new applications is discouraged.
-
-=head2 Netscape String extensions.
-
-Netscape Comment (B<nsComment>) is a string extension containing a comment
-which will be displayed when the certificate is viewed in some browsers.
-
-Example:
-
- nsComment = "Some Random Comment"
-
-Other supported extensions in this category are: B<nsBaseUrl>,
-B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
-and B<nsSslServerName>.
-
-
-=head2 Netscape Certificate Type
-
-This is a multi-valued extensions which consists of a list of flags to be
-included. It was used to indicate the purposes for which a certificate could
-be used. The basicConstraints, keyUsage and extended key usage extensions are
-now used instead.
-
-Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
-B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
-
-
-=head1 ARBITRARY EXTENSIONS
-
-If an extension is not supported by the OpenSSL code then it must be encoded
-using the arbitrary extension format. It is also possible to use the arbitrary
-format for supported extensions. Extreme care should be taken to ensure that
-the data is formatted correctly for the given extension type.
-
-There are two ways to encode arbitrary extensions.
-
-The first way is to use the word ASN1 followed by the extension content
-using the same syntax as L<ASN1_generate_nconf(3)>.
-For example:
-
- 1.2.3.4=critical,ASN1:UTF8String:Some random data
-
- 1.2.3.4=ASN1:SEQUENCE:seq_sect
-
- [seq_sect]
-
- field1 = UTF8:field1
- field2 = UTF8:field2
-
-It is also possible to use the word DER to include the raw encoded data in any
-extension.
-
- 1.2.3.4=critical,DER:01:02:03:04
- 1.2.3.4=DER:01020304
-
-The value following DER is a hex dump of the DER encoding of the extension
-Any extension can be placed in this form to override the default behaviour.
-For example:
-
- basicConstraints=critical,DER:00:01:02:03
-
-=head1 WARNING
-
-There is no guarantee that a specific implementation will process a given
-extension. It may therefore be sometimes possible to use certificates for
-purposes prohibited by their extensions because a specific application does
-not recognize or honour the values of the relevant extensions.
-
-The DER and ASN1 options should be used with caution. It is possible to create
-totally invalid extensions if they are not used carefully.
-
-
-=head1 NOTES
-
-If an extension is multi-value and a field value must contain a comma the long
-form must be used otherwise the comma would be misinterpreted as a field
-separator. For example:
-
- subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
-
-will produce an error but the equivalent form:
-
- subjectAltName=@subject_alt_section
-
- [subject_alt_section]
- subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
-
-is valid.
-
-Due to the behaviour of the OpenSSL B<conf> library the same field name
-can only occur once in a section. This means that:
-
- subjectAltName=@alt_section
-
- [alt_section]
-
- email=steve@here
- email=steve@there
-
-will only recognize the last value. This can be worked around by using the form:
-
- [alt_section]
-
- email.1=steve@here
- email.2=steve@there
-
-=head1 SEE ALSO
-
-L<req(1)>, L<ca(1)>, L<x509(1)>,
-L<ASN1_generate_nconf(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64,
-ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN, - ASN.1 INTEGER and ENUMERATED utilities
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
- int ASN1_INTEGER_get(const ASN1_INTEGER *a, long v);
-
- int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
- long ASN1_INTEGER_set(const ASN1_INTEGER *a);
-
- int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);
- int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);
-
- ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
- BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
-
- int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
- long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
-
- int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
- int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
-
- ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
- BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn);
-
-=head1 DESCRIPTION
-
-These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED>
-structures.
-
-ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type
-If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails
-(due to invalid type or the value being too big to fit into an B<int64_t> type)
-it returns 0.
-
-ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it
-converts to a B<uint64_t> type and an error is returned if the passed integer
-is negative.
-
-ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is
-NULL and -1 on error (which is ambiguous because -1 is a legitimate value for
-an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64()
-instead.
-
-ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the
-B<int64_t> value B<r>.
-
-ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the
-B<uint64_t> value B<r>.
-
-ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
-B<v>.
-
-BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai>
-is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then
-the existing structure will be used instead.
-
-ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is
-NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the
-existing structure will be used instead.
-
-ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
-ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN()
-behave in an identical way to their ASN1_INTEGER counterparts except they
-operate on an B<ASN1_ENUMERATED> value.
-
-ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to
-ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not
-fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
-instead.
-
-=head1 NOTES
-
-In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an
-integer of almost arbitrary size and so cannot always be represented by a C
-B<int64_t> type. However in many cases (for example version numbers) they
-represent small integers which can be more easily manipulated if converted to
-an appropriate C integer type.
-
-=head1 BUGS
-
-The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get()
-mean these functions should be avoided if possible. They are retained for
-compatibility. Normally the ambiguous return values are not legitimate
-values for the fields they represent.
-
-=head1 RETURN VALUES
-
-ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and
-ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only
-fail if a memory allocation error occurs.
-
-ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success
-and 0 for failure. They will fail if the passed type is incorrect (this will
-only happen if there is a programming error) or if the value exceeds the range
-of an B<int64_t> type.
-
-BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or
-B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will
-only fail due to a memory allocation error.
-
-ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure
-of NULL if an error occurs. They can fail if the passed type is incorrect
-(due to programming error) or due to a memory allocation failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-
-=head1 HISTORY
-
-ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(),
-ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64()
-were added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- const ASN1_ITEM *ASN1_ITEM_lookup(const char *name);
- const ASN1_ITEM *ASN1_ITEM_get(size_t i);
-
-=head1 DESCRIPTION
-
-ASN1_ITEM_lookup() returns the B<ASN1_ITEM name>.
-
-ASN1_ITEM_get() returns the B<ASN1_ITEM> with index B<i>. This function
-returns B<NULL> if the index B<i> is out of range.
-
-=head1 RETURN VALUES
-
-ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid B<ASN1_ITEM> structure
-or B<NULL> if an error occurred.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- ASN1_OBJECT *ASN1_OBJECT_new(void);
- void ASN1_OBJECT_free(ASN1_OBJECT *a);
-
-=head1 DESCRIPTION
-
-The ASN1_OBJECT allocation routines, allocate and free an
-ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
-
-ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.
-
-ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
-If B<a> is NULL, nothing is done.
-
-=head1 NOTES
-
-Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
-is almost never used in applications. The ASN1 object utility functions
-such as OBJ_nid2obj() are used instead.
-
-=head1 RETURN VALUES
-
-If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
-code that can be obtained by L<ERR_get_error(3)>.
-Otherwise it returns a pointer to the newly allocated structure.
-
-ASN1_OBJECT_free() returns no value.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
-ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
-ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- int ASN1_STRING_length(ASN1_STRING *x);
- const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
- unsigned char * ASN1_STRING_data(ASN1_STRING *x);
-
- ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
-
- int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
-
- int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
-
- int ASN1_STRING_type(const ASN1_STRING *x);
-
- int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
-
-=head1 DESCRIPTION
-
-These functions allow an B<ASN1_STRING> structure to be manipulated.
-
-ASN1_STRING_length() returns the length of the content of B<x>.
-
-ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
-Since this is an internal pointer it should B<not> be freed or
-modified in any way.
-
-ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the
-returned value is not constant. This function is deprecated:
-applications should use ASN1_STRING_get0_data() instead.
-
-ASN1_STRING_dup() returns a copy of the structure B<a>.
-
-ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
-are identical. The string types and content are compared.
-
-ASN1_STRING_set() sets the data of string B<str> to the buffer
-B<data> or length B<len>. The supplied data is copied. If B<len>
-is -1 then the length is determined by strlen(data).
-
-ASN1_STRING_type() returns the type of B<x>, using standard constants
-such as B<V_ASN1_OCTET_STRING>.
-
-ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
-converted data is allocated in a buffer in B<*out>. The length of
-B<out> is returned or a negative error code. The buffer B<*out>
-should be freed using OPENSSL_free().
-
-=head1 NOTES
-
-Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
-structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed
-to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.
-B<ASN1_STRING> is also used for some B<CHOICE> types which consist
-entirely of primitive string types such as B<DirectoryString> and
-B<Time>.
-
-These functions should B<not> be used to examine or modify B<ASN1_INTEGER>
-or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED>
-utility functions should be used instead.
-
-In general it cannot be assumed that the data returned by ASN1_STRING_data()
-is null terminated or does not contain embedded nulls. The actual format
-of the data will depend on the actual string type itself: for example
-for 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 SEE ALSO
-
-L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -
-ASN1_STRING allocation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- ASN1_STRING * ASN1_STRING_new(void);
- ASN1_STRING * ASN1_STRING_type_new(int type);
- void ASN1_STRING_free(ASN1_STRING *a);
-
-=head1 DESCRIPTION
-
-ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type
-is undefined.
-
-ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
-type B<type>.
-
-ASN1_STRING_free() frees up B<a>.
-If B<a> is NULL nothing is done.
-
-=head1 NOTES
-
-Other string types call the B<ASN1_STRING> functions. For example
-ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
-
-=head1 RETURN VALUES
-
-ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
-ASN1_STRING structure or B<NULL> if an error occurred.
-
-ASN1_STRING_free() does not return a value.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
- int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
- int ASN1_STRING_print(BIO *out, const ASN1_STRING *str);
-
-
-=head1 DESCRIPTION
-
-These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
-represent all the ASN1 string types.
-
-ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
-the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
-to B<fp> instead.
-
-ASN1_STRING_print() prints B<str> to B<out> but using a different format to
-ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
-with '.'.
-
-=head1 NOTES
-
-ASN1_STRING_print() is a legacy function which should be avoided in new applications.
-
-Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
-suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
-
-The complete set of supported options for B<flags> is listed below.
-
-Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
-determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
-characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the
-MSB set are escaped: this option should B<not> be used if the terminal correctly
-interprets UTF8 sequences.
-
-Escaping takes several forms.
-
-If the character being escaped is a 16 bit character then the form "\UXXXX" is used
-using exactly four characters for the hex representation. If it is 32 bits then
-"\WXXXXXXXX" is used using eight characters of its hex representation. These forms
-will only be used if UTF8 conversion is not set (see below).
-
-Printable characters are normally escaped using the backslash '\' character. If
-B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by
-double quote characters: this is arguably more readable than the backslash
-notation. Other characters use the "\XX" using exactly two characters of the hex
-representation.
-
-If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8
-format first. If the terminal supports the display of UTF8 sequences then this
-option will correctly display multi byte characters.
-
-If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at
-all: everything is assumed to be one byte per character. This is primarily for
-debugging purposes and can result in confusing output in multi character strings.
-
-If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out
-before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str().
-
-The content of a string instead of being interpreted can be "dumped": this just
-outputs the value of the string using the form #XXXX using hex format for each
-octet.
-
-If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped.
-
-Normally non character string types (such as OCTET STRING) are assumed to be
-one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will
-be dumped instead.
-
-When a type is dumped normally just the content octets are printed, if
-B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
-instead (including tag and length octets).
-
-B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is
-equivalent to:
- ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
- ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
-
-=head1 SEE ALSO
-
-L<X509_NAME_print_ex(3)>,
-L<ASN1_tag2str(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string,
-ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions
-
-=head1 SYNOPSIS
-
- ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
- ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t,
- int offset_day, long offset_sec);
- int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
- int ASN1_TIME_check(const ASN1_TIME *t);
- int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
-
- int ASN1_TIME_diff(int *pday, int *psec,
- const ASN1_TIME *from, const ASN1_TIME *to);
-
-=head1 DESCRIPTION
-
-The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the
-time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME
-structure is allocated and returned.
-
-ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented
-by the time B<offset_day> and B<offset_sec> after the time_t value B<t>.
-The values of B<offset_day> or B<offset_sec> can be negative to set a
-time before B<t>. The B<offset_sec> value can also exceed the number of
-seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated
-and returned.
-
-ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time
-represented by string B<str> which must be in appropriate ASN.1 time
-format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
-
-ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>.
-
-ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable
-format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
-"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time
-structure has invalid format it prints out "Bad time value" and returns
-an error.
-
-ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
-B<from> and B<to>. If B<to> represents a time later than B<from> then
-one or both (depending on the time difference) of B<*pday> and B<*psec>
-will be positive. If B<to> represents a time earlier than B<from> then
-one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
-represent the same time then B<*pday> and B<*psec> will both be zero.
-If both B<*pday> and B<*psec> are non-zero they will always have the same
-sign. The value of B<*psec> will always be less than the number of seconds
-in a day. If B<from> or B<to> is NULL the current time is used.
-
-=head1 NOTES
-
-The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
-defined in RFC5280 et al. The time setting functions obey the rules outlined
-in RFC5280: if the date can be represented by UTCTime it is used, else
-GeneralizedTime is used.
-
-The ASN1_TIME structure is represented as an ASN1_STRING internally and can
-be freed up using ASN1_STRING_free().
-
-The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
-is made to correct ancient calendar changes (for example from Julian to
-Gregorian calendars).
-
-Some applications add offset times directly to a time_t value and pass the
-results to ASN1_TIME_set() (or equivalent). This can cause problems as the
-time_t value can overflow on some systems resulting in unexpected results.
-New applications should use ASN1_TIME_adj() instead and pass the offset value
-in the B<offset_sec> and B<offset_day> parameters instead of directly
-manipulating a time_t value.
-
-=head1 BUGS
-
-ASN1_TIME_print() currently does not print out the time zone: it either prints
-out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT
-anyway.
-
-=head1 EXAMPLES
-
-Set a time structure to one hour after the current time and print it out:
-
- #include <time.h>
- #include <openssl/asn1.h>
- ASN1_TIME *tm;
- time_t t;
- BIO *b;
- t = time(NULL);
- tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
- b = BIO_new_fp(stdout, BIO_NOCLOSE);
- ASN1_TIME_print(b, tm);
- ASN1_STRING_free(tm);
- BIO_free(b);
-
-Determine if one time is later or sooner than the current time:
-
- int day, sec;
-
- if (!ASN1_TIME_diff(&day, &sec, NULL, to))
- /* Invalid time format */
-
- if (day > 0 || sec > 0)
- printf("Later\n");
- else if (day < 0 || sec < 0)
- printf("Sooner\n");
- else
- printf("Same\n");
-
-=head1 RETURN VALUES
-
-ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure
-or NULL if an error occurred.
-
-ASN1_TIME_set_string() returns 1 if the time value is successfully set and
-0 otherwise.
-
-ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0
-otherwise.
-
-ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if
-an error occurred (I/O error or invalid time format).
-
-ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
-pass ASN1_TIME structure has invalid syntax for example.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility
-functions
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- int ASN1_TYPE_get(const ASN1_TYPE *a);
- void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);
- int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);
- int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);
-
- void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);
- ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s,
- ASN1_TYPE **t);
-
-=head1 DESCRIPTION
-
-These functions allow an ASN1_TYPE structure to be manipulated. The
-ASN1_TYPE structure can contain any ASN.1 type or constructed type
-such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.
-
-ASN1_TYPE_get() returns the type of B<a>.
-
-ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This
-function uses the pointer B<value> internally so it must B<not> be freed
-up after the call.
-
-ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>.
-
-ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if
-they are identical and non-zero otherwise.
-
-ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in
-B<t> using the ASN.1 structure B<it>. If successful it returns a pointer
-to the ASN.1 structure corresponding to B<it> which must be freed by the
-caller. If it fails it return NULL.
-
-ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s>
-corresponding to B<it> into an ASN1_TYPE. If successful the encoded
-ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type
-is written to B<t> overwriting any existing data. If B<t> is not NULL
-but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>.
-
-=head1 NOTES
-
-The type and meaning of the B<value> parameter for ASN1_TYPE_set() and
-ASN1_TYPE_set1() is determined by the B<type> parameter.
-If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN
-then the boolean is set to TRUE if B<value> is not NULL. If B<type> is
-V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type>
-is and ASN1_STRING structure. If B<type> corresponds to a primitive type
-(or a string type) then the contents of the ASN1_STRING contain the content
-octets of the type. If B<type> corresponds to a constructed type or
-a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the
-ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and
-length octets).
-
-ASN1_TYPE_cmp() may not return zero if two types are equivalent but have
-different encodings. For example the single content octet of the boolean TRUE
-value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will
-only return zero if the values are the same.
-
-If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
-return value is non-zero. Technically if both parameters are NULL the two
-types could be absent OPTIONAL fields and so should match, however passing
-NULL values could also indicate a programming error (for example an
-unparseable type which returns NULL) for types which do B<not> match. So
-applications should handle the case of two absent values separately.
-
-=head1 RETURN VALUES
-
-ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.
-
-ASN1_TYPE_set() does not return a value.
-
-ASN1_TYPE_set1() returns 1 for success and 0 for failure.
-
-ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise.
-
-ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or
-NULL on failure.
-
-ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or
-NULL on failure.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1.h>
-
- ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
- ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
-
-=head1 DESCRIPTION
-
-These functions generate the ASN1 encoding of a string
-in an B<ASN1_TYPE> structure.
-
-B<str> contains the string to encode B<nconf> or B<cnf> contains
-the optional configuration information where additional strings
-will be read from. B<nconf> will typically come from a config
-file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
-which will typically be used by X509 v3 certificate extension
-functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
-configuration will be used.
-
-=head1 GENERATION STRING FORMAT
-
-The actual data encoded is determined by the string B<str> and
-the configuration information. The general format of the string
-is:
-
-=over 2
-
-=item B<[modifier,]type[:value]>
-
-=back
-
-That is zero or more comma separated modifiers followed by a type
-followed by an optional colon and a value. The formats of B<type>,
-B<value> and B<modifier> are explained below.
-
-=head2 Supported Types
-
-The supported types are listed below. Unless otherwise specified
-only the B<ASCII> format is permissible.
-
-=over 2
-
-=item B<BOOLEAN>, B<BOOL>
-
-This encodes a boolean type. The B<value> string is mandatory and
-should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
-B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
-are acceptable.
-
-=item B<NULL>
-
-Encode the B<NULL> type, the B<value> string must not be present.
-
-=item B<INTEGER>, B<INT>
-
-Encodes an ASN1 B<INTEGER> type. The B<value> string represents
-the value of the integer, it can be prefaced by a minus sign and
-is normally interpreted as a decimal value unless the prefix B<0x>
-is included.
-
-=item B<ENUMERATED>, B<ENUM>
-
-Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
-B<INTEGER>.
-
-=item B<OBJECT>, B<OID>
-
-Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
-a short name, a long name or numerical format.
-
-=item B<UTCTIME>, B<UTC>
-
-Encodes an ASN1 B<UTCTime> structure, the value should be in
-the format B<YYMMDDHHMMSSZ>.
-
-=item B<GENERALIZEDTIME>, B<GENTIME>
-
-Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
-the format B<YYYYMMDDHHMMSSZ>.
-
-=item B<OCTETSTRING>, B<OCT>
-
-Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
-of this structure, the format strings B<ASCII> and B<HEX> can be
-used to specify the format of B<value>.
-
-=item B<BITSTRING>, B<BITSTR>
-
-Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
-of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
-can be used to specify the format of B<value>.
-
-If the format is anything other than B<BITLIST> the number of unused
-bits is set to zero.
-
-=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
-B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
-B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
-B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
-B<NUMERIC>
-
-These encode the corresponding string types. B<value> represents the
-contents of this structure. The format can be B<ASCII> or B<UTF8>.
-
-=item B<SEQUENCE>, B<SEQ>, B<SET>
-
-Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
-should be a section name which will contain the contents. The
-field names in the section are ignored and the values are in the
-generated string format. If B<value> is absent then an empty SEQUENCE
-will be encoded.
-
-=back
-
-=head2 Modifiers
-
-Modifiers affect the following structure, they can be used to
-add EXPLICIT or IMPLICIT tagging, add wrappers or to change
-the string format of the final type and value. The supported
-formats are documented below.
-
-=over 2
-
-=item B<EXPLICIT>, B<EXP>
-
-Add an explicit tag to the following structure. This string
-should be followed by a colon and the tag value to use as a
-decimal value.
-
-By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
-APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
-the default is CONTEXT SPECIFIC.
-
-=item B<IMPLICIT>, B<IMP>
-
-This is the same as B<EXPLICIT> except IMPLICIT tagging is used
-instead.
-
-=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
-
-The following structure is surrounded by an OCTET STRING, a SEQUENCE,
-a SET or a BIT STRING respectively. For a BIT STRING the number of unused
-bits is set to zero.
-
-=item B<FORMAT>
-
-This specifies the format of the ultimate value. It should be followed
-by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
-
-If no format specifier is included then B<ASCII> is used. If B<UTF8> is
-specified then the value string must be a valid B<UTF8> string. For B<HEX> the
-output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT
-STRING) is a comma separated list of the indices of the set bits, all other
-bits are zero.
-
-=back
-
-=head1 EXAMPLES
-
-A simple IA5String:
-
- IA5STRING:Hello World
-
-An IA5String explicitly tagged:
-
- EXPLICIT:0,IA5STRING:Hello World
-
-An IA5String explicitly tagged using APPLICATION tagging:
-
- EXPLICIT:0A,IA5STRING:Hello World
-
-A BITSTRING with bits 1 and 5 set and all others zero:
-
- FORMAT:BITLIST,BITSTRING:1,5
-
-A more complex example using a config file to produce a
-SEQUENCE consisting of a BOOL an OID and a UTF8String:
-
- asn1 = SEQUENCE:seq_section
-
- [seq_section]
-
- field1 = BOOLEAN:TRUE
- field2 = OID:commonName
- field3 = UTF8:Third field
-
-This example produces an RSAPrivateKey structure, this is the
-key contained in the file client.pem in all OpenSSL distributions
-(note: the field names such as 'coeff' are ignored and are present just
-for clarity):
-
- asn1=SEQUENCE:private_key
- [private_key]
- version=INTEGER:0
-
- n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
- D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
-
- e=INTEGER:0x010001
-
- d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
- F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
-
- p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
- D4BD57
-
- q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
- 46EC4F
-
- exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
- 9C0A39B9
-
- exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
- E7B2458F
-
- coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
- 628657053A
-
-This example is the corresponding public key in a SubjectPublicKeyInfo
-structure:
-
- # Start with a SEQUENCE
- asn1=SEQUENCE:pubkeyinfo
-
- # pubkeyinfo contains an algorithm identifier and the public key wrapped
- # in a BIT STRING
- [pubkeyinfo]
- algorithm=SEQUENCE:rsa_alg
- pubkey=BITWRAP,SEQUENCE:rsapubkey
-
- # algorithm ID for RSA is just an OID and a NULL
- [rsa_alg]
- algorithm=OID:rsaEncryption
- parameter=NULL
-
- # Actual public key: modulus and exponent
- [rsapubkey]
- n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
- D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
-
- e=INTEGER:0x010001
-
-=head1 RETURN VALUES
-
-ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
-data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
-
-The error codes that can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
-ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
-ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage
-waiting for asynchronous jobs to complete
-
-=head1 SYNOPSIS
-
- #include <openssl/async.h>
-
- ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
- void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
- int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
- OSSL_ASYNC_FD fd,
- void *custom_data,
- void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
- OSSL_ASYNC_FD, void *));
- int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
- OSSL_ASYNC_FD *fd, void **custom_data);
- int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
- size_t *numfds);
- int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
- size_t *numaddfds, OSSL_ASYNC_FD *delfd,
- size_t *numdelfds);
- int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
-
-
-=head1 DESCRIPTION
-
-For an overview of how asynchronous operations are implemented in OpenSSL see
-L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous
-"session", i.e. a related set of crypto operations. For example in SSL terms
-this would have a one-to-one correspondence with an SSL connection.
-
-Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new()
-function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
-the job is started it is associated with the ASYNC_WAIT_CTX for the duration of
-that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one
-time, but can be reused after an ASYNC_JOB has finished for a subsequent
-ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed),
-application code cleans up with ASYNC_WAIT_CTX_free().
-
-ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling
-ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in
-the B<ctx> parameter will return the wait file descriptors associated with that
-job in B<*fd>. The number of file descriptors returned will be stored in
-B<*numfds>. It is the caller's responsibility to ensure that sufficient memory
-has been allocated in B<*fd> to receive all the file descriptors. Calling
-ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file
-descriptors but will still populate B<*numfds>. Therefore application code is
-typically expected to call this function twice: once to get the number of fds,
-and then again when sufficient memory has been allocated. If only one
-asynchronous engine is being used then normally this call will only ever return
-one fd. If multiple asynchronous engines are being used then more could be
-returned.
-
-The function ASYNC_WAIT_CTX_fds_have_changed() can be used to detect if any fds
-have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE
-result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has
-been received). The B<numaddfds> and B<numdelfds> parameters will be populated
-with the number of fds added or deleted respectively. B<*addfd> and B<*delfd>
-will be populated with the list of added and deleted fds respectively. Similarly
-to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
-NULL then the caller is responsible for ensuring sufficient memory is allocated.
-
-Implementors of async aware code (e.g. engines) are encouraged to return a
-stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn"
-of regularly changing fds - although no guarantees of this are provided to
-applications.
-
-Applications can wait for the file descriptor to be ready for "read" using a
-system function call such as select or poll (being ready for "read" indicates
-that the job should be resumed). If no file descriptor is made available then an
-application will have to periodically "poll" the job by attempting to restart it
-to see if it is ready to continue.
-
-Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job
-via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting
-on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an
-engine immediately prior to calling ASYNC_pause_job() and not by end user code.
-An existing association with a file descriptor can be obtained using
-ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
-these functions requires a B<key> value which is unique to the async aware
-code. This could be any unique value but a good candidate might be the
-B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and
-will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
-ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
-routine. This can be NULL but if provided will automatically get called when
-the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the
-fd or any other resources. Note: The "cleanup" routine does not get called if
-the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
-
-An example of typical usage might be an async capable engine. User code would
-initiate cryptographic operations. The engine would initiate those operations
-asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
-ASYNC_pause_job() to return control to the user code. The user code can then
-perform other tasks or wait for the job to be ready by calling "select" or other
-similar function on the wait file descriptor. The engine can signal to the user
-code that the job should be resumed by making the wait file descriptor
-"readable". Once resumed the engine should clear the wake signal on the wait
-file descriptor.
-
-=head1 RETURN VALUES
-
-ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
-NULL on error.
-
-ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
-ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
-success or 0 on error.
-
-=head1 NOTES
-
-On Windows platforms the openssl/async.h header is dependent on some
-of the types customarily made available by including windows.h. The
-application developer is likely to require control over when the latter
-is included, commonly as one of the first included headers. Therefore
-it is defined as an application developer's responsibility to include
-windows.h prior to async.h.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ASYNC_start_job(3)>
-
-=head1 HISTORY
-
-ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
-ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
-ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to
-OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASYNC_get_wait_ctx,
-ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job,
-ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
-- asynchronous job management functions
-
-=head1 SYNOPSIS
-
- #include <openssl/async.h>
-
- int ASYNC_init_thread(size_t max_size, size_t init_size);
- void ASYNC_cleanup_thread(void);
-
- int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,
- int (*func)(void *), void *args, size_t size);
- int ASYNC_pause_job(void);
-
- ASYNC_JOB *ASYNC_get_current_job(void);
- ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);
- void ASYNC_block_pause(void);
- void ASYNC_unblock_pause(void);
-
- int ASYNC_is_capable(void);
-
-=head1 DESCRIPTION
-
-OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This
-represents code that can be started and executes until some event occurs. At
-that point the code can be paused and control returns to user code until some
-subsequent event indicates that the job can be resumed.
-
-The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for
-efficiency reasons, jobs can be created up front and reused many times. They are
-held in a pool until they are needed, at which point they are removed from the
-pool, used, and then returned to the pool when the job completes. If the user
-application is multi-threaded, then ASYNC_init_thread() may be called for each
-thread that will initiate asynchronous jobs. Before
-user code exits per-thread resources need to be cleaned up. This will normally
-occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly
-initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be
-outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to
-ensure this will result in memory leaks.
-
-The B<max_size> argument limits the number of ASYNC_JOBs that will be held in
-the pool. If B<max_size> is set to 0 then no upper limit is set. When an
-ASYNC_JOB is needed but there are none available in the pool already then one
-will be automatically created, as long as the total of ASYNC_JOBs managed by the
-pool does not exceed B<max_size>. When the pool is first initialised
-B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is
-not called before the pool is first used then it will be called automatically
-with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs
-created up front).
-
-An asynchronous job is started by calling the ASYNC_start_job() function.
-Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX
-object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should
-point to a location where the return value of the asynchronous function should
-be stored on completion of the job. B<func> represents the function that should
-be started asynchronously. The data pointed to by B<args> and of size B<size>
-will be copied and then passed as an argument to B<func> when the job starts.
-ASYNC_start_job will return one of the following values:
-
-=over 4
-
-=item B<ASYNC_ERR>
-
-An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
-see L<ERR_print_errors(3)>) for more details.
-
-=item B<ASYNC_NO_JOBS>
-
-There are no jobs currently available in the pool. This call can be retried
-again at a later time.
-
-=item B<ASYNC_PAUSE>
-
-The job was successfully started but was "paused" before it completed (see
-ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work
-can be performed (if desired) and the job restarted at a later time. To restart
-a job call ASYNC_start_job() again passing the job handle in B<*job>. The
-B<func>, B<args> and B<size> parameters will be ignored when restarting a job.
-When restarting a job ASYNC_start_job() B<must> be called from the same thread
-that the job was originally started from.
-
-=item B<ASYNC_FINISH>
-
-The job completed. B<*job> will be NULL and the return value from B<func> will
-be placed in B<*ret>.
-
-=back
-
-At any one time there can be a maximum of one job actively running per thread
-(you can have many that are paused). ASYNC_get_current_job() can be used to get
-a pointer to the currently executing ASYNC_JOB. If no job is currently executing
-then this will return NULL.
-
-If executing within the context of a job (i.e. having been called directly or
-indirectly by the function "func" passed as an argument to ASYNC_start_job())
-then ASYNC_pause_job() will immediately return control to the calling
-application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A
-subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the
-B<*job> parameter will resume execution from the ASYNC_pause_job() call. If
-ASYNC_pause_job() is called whilst not within the context of a job then no
-action is taken and ASYNC_pause_job() returns immediately.
-
-ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX
-for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated
-with them. Applications can wait for the file descriptor to be ready for "read"
-using a system function call such as select or poll (being ready for "read"
-indicates that the job should be resumed). If no file descriptor is made
-available then an application will have to periodically "poll" the job by
-attempting to restart it to see if it is ready to continue.
-
-An example of typical usage might be an async capable engine. User code would
-initiate cryptographic operations. The engine would initiate those operations
-asynchronously and then call L<ASYNC_WAIT_CTX_set_wait_fd(3)> followed by
-ASYNC_pause_job() to return control to the user code. The user code can then
-perform other tasks or wait for the job to be ready by calling "select" or other
-similar function on the wait file descriptor. The engine can signal to the user
-code that the job should be resumed by making the wait file descriptor
-"readable". Once resumed the engine should clear the wake signal on the wait
-file descriptor.
-
-The ASYNC_block_pause() function will prevent the currently active job from
-pausing. The block will remain in place until a subsequent call to
-ASYNC_unblock_pause(). These functions can be nested, e.g. if you call
-ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in
-order to re-enable pausing. If these functions are called while there is no
-currently active job then they have no effect. This functionality can be useful
-to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an
-application acquires a lock. It then calls some cryptographic function which
-invokes ASYNC_pause_job(). This returns control back to the code that created
-the ASYNC_JOB. If that code then attempts to acquire the same lock before
-resuming the original job then a deadlock can occur. By calling
-ASYNC_block_pause() immediately after acquiring the lock and
-ASYNC_unblock_pause() immediately before releasing it then this situation cannot
-occur.
-
-Some platforms cannot support async operations. The ASYNC_is_capable() function
-can be used to detect whether the current platform is async capable or not.
-
-=head1 RETURN VALUES
-
-ASYNC_init_thread returns 1 on success or 0 otherwise.
-
-ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or
-ASYNC_FINISH as described above.
-
-ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
-not within the context of an ASYNC_JOB then this is counted as success so 1 is
-returned.
-
-ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or
-NULL if not within the context of a job.
-
-ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.
-
-ASYNC_is_capable() returns 1 if the current platform is async capable or 0
-otherwise.
-
-=head1 NOTES
-
-On Windows platforms the openssl/async.h header is dependent on some
-of the types customarily made available by including windows.h. The
-application developer is likely to require control over when the latter
-is included, commonly as one of the first included headers. Therefore
-it is defined as an application developer's responsibility to include
-windows.h prior to async.h.
-
-=head1 EXAMPLE
-
-The following example demonstrates how to use most of the core async APIs:
-
- #ifdef _WIN32
- # include <windows.h>
- #endif
- #include <stdio.h>
- #include <unistd.h>
- #include <openssl/async.h>
- #include <openssl/crypto.h>
-
- int unique = 0;
-
- void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
- {
- OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;
- close(r);
- close(*w);
- OPENSSL_free(w);
- }
-
- int jobfunc(void *arg)
- {
- ASYNC_JOB *currjob;
- unsigned char *msg;
- int pipefds[2] = {0, 0};
- OSSL_ASYNC_FD *wptr;
- char buf = 'X';
-
- currjob = ASYNC_get_current_job();
- if (currjob != NULL) {
- printf("Executing within a job\n");
- } else {
- printf("Not executing within a job - should not happen\n");
- return 0;
- }
-
- msg = (unsigned char *)arg;
- printf("Passed in message is: %s\n", msg);
-
- if (pipe(pipefds) != 0) {
- printf("Failed to create pipe\n");
- return 0;
- }
- wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
- if (wptr == NULL) {
- printf("Failed to malloc\n");
- return 0;
- }
- *wptr = pipefds[1];
- ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,
- pipefds[0], wptr, cleanup);
-
- /*
- * Normally some external event would cause this to happen at some
- * later point - but we do it here for demo purposes, i.e.
- * immediately signalling that the job is ready to be woken up after
- * we return to main via ASYNC_pause_job().
- */
- write(pipefds[1], &buf, 1);
-
- /* Return control back to main */
- ASYNC_pause_job();
-
- /* Clear the wake signal */
- read(pipefds[0], &buf, 1);
-
- printf ("Resumed the job after a pause\n");
-
- return 1;
- }
-
- int main(void)
- {
- ASYNC_JOB *job = NULL;
- ASYNC_WAIT_CTX *ctx = NULL;
- int ret;
- OSSL_ASYNC_FD waitfd;
- fd_set waitfdset;
- size_t numfds;
- unsigned char msg[13] = "Hello world!";
-
- printf("Starting...\n");
-
- ctx = ASYNC_WAIT_CTX_new();
- if (ctx == NULL) {
- printf("Failed to create ASYNC_WAIT_CTX\n");
- abort();
- }
-
- for (;;) {
- switch(ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
- case ASYNC_ERR:
- case ASYNC_NO_JOBS:
- printf("An error occurred\n");
- goto end;
- case ASYNC_PAUSE:
- printf("Job was paused\n");
- break;
- case ASYNC_FINISH:
- printf("Job finished with return value %d\n", ret);
- goto end;
- }
-
- /* Wait for the job to be woken */
- printf("Waiting for the job to be woken up\n");
-
- if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
- || numfds > 1) {
- printf("Unexpected number of fds\n");
- abort();
- }
- ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);
- FD_ZERO(&waitfdset);
- FD_SET(waitfd, &waitfdset);
- select(waitfd + 1, &waitfdset, NULL, NULL, NULL);
- }
-
- end:
- ASYNC_WAIT_CTX_free(ctx);
- printf("Finishing\n");
-
- return 0;
- }
-
-The expected output from executing the above example program is:
-
- Starting...
- Executing within a job
- Passed in message is: Hello world!
- Job was paused
- Waiting for the job to be woken up
- Resumed the job after a pause
- Job finished with return value 1
- Finishing
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ERR_print_errors(3)>
-
-=head1 HISTORY
-
-ASYNC_init_thread, ASYNC_cleanup_thread,
-ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(),
-ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first
-added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
-BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
-
-=head1 SYNOPSIS
-
- #include <openssl/blowfish.h>
-
- void BF_set_key(BF_KEY *key, int len, const unsigned char *data);
-
- void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
- BF_KEY *key, int enc);
- void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
- long length, BF_KEY *schedule, unsigned char *ivec, int enc);
- void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
- long length, BF_KEY *schedule, unsigned char *ivec, int *num,
- int enc);
- void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
- long length, BF_KEY *schedule, unsigned char *ivec, int *num);
- const char *BF_options(void);
-
- void BF_encrypt(BF_LONG *data, const BF_KEY *key);
- void BF_decrypt(BF_LONG *data, const BF_KEY *key);
-
-=head1 DESCRIPTION
-
-This library implements the Blowfish cipher, which was invented and described
-by Counterpane (see http://www.counterpane.com/blowfish.html ).
-
-Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
-It uses a variable size key, but typically, 128 bit (16 byte) keys are
-considered good for strong encryption. Blowfish can be used in the same
-modes as DES (see L<des_modes(7)>). Blowfish is currently one
-of the faster block ciphers. It is quite a bit faster than DES, and much
-faster than IDEA or RC2.
-
-Blowfish consists of a key setup phase and the actual encryption or decryption
-phase.
-
-BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key
-at B<data>.
-
-BF_ecb_encrypt() is the basic Blowfish encryption and decryption function.
-It encrypts or decrypts the first 64 bits of B<in> using the key B<key>,
-putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
-or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by
-B<in> and B<out> must be 64 bits in length, no less. If they are larger,
-everything after the first 64 bits is ignored.
-
-The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
-all operate on variable length data. They all take an initialization vector
-B<ivec> which needs to be passed along into the next call of the same function
-for the same message. B<ivec> may be initialized with anything, but the
-recipient needs to know what it was initialized with, or it won't be able
-to decrypt. Some programs and protocols simplify this, like SSH, where
-B<ivec> is simply initialized to zero.
-BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while
-BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable
-number of bytes (the amount does not have to be an exact multiple of 8). The
-purpose of the latter two is to simulate stream ciphers, and therefore, they
-need the parameter B<num>, which is a pointer to an integer where the current
-offset in B<ivec> is stored between calls. This integer must be initialized
-to zero when B<ivec> is initialized.
-
-BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It
-encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>,
-putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or
-decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte
-long initialization vector.
-
-BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback.
-It encrypts or decrypts the bytes in B<in> using the key B<schedule>,
-putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
-or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an
-8 byte long initialization vector. B<num> must point at an integer which must
-be initially zero.
-
-BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback.
-It uses the same parameters as BF_cfb64_encrypt(), which must be initialized
-the same way.
-
-BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish
-encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
-B<data>, using the key B<key>. These functions should not be used unless you
-implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt().
-If you still want to use these functions, you should be aware that they take
-each 32-bit chunk in host-byte order, which is little-endian on little-endian
-platforms and big-endian on big-endian ones.
-
-=head1 RETURN VALUES
-
-None of the functions presented here return any value.
-
-=head1 NOTE
-
-Applications should use the higher level functions
-L<EVP_EncryptInit(3)> etc. instead of calling these
-functions directly.
-
-=head1 SEE ALSO
-
-L<EVP_EncryptInit(3)>,
-L<des_modes(7)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake,
-BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
-BIO_ADDR_hostname_string, BIO_ADDR_service_string,
-BIO_ADDR_path_string - BIO_ADDR routines
-
-=head1 SYNOPSIS
-
- #include <sys/types.h>
- #include <openssl/bio.h>
-
- typedef union bio_addr_st BIO_ADDR;
-
- BIO_ADDR *BIO_ADDR_new(void);
- void BIO_ADDR_free(BIO_ADDR *);
- void BIO_ADDR_clear(BIO_ADDR *ap);
- int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
- const void *where, size_t wherelen, unsigned short port);
- int BIO_ADDR_family(const BIO_ADDR *ap);
- int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
- unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
- char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
- char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
- char *BIO_ADDR_path_string(const BIO_ADDR *ap);
-
-=head1 DESCRIPTION
-
-The B<BIO_ADDR> type is a wrapper around all types of socket
-addresses that OpenSSL deals with, currently transparently
-supporting AF_INET, AF_INET6 and AF_UNIX according to what's
-available on the platform at hand.
-
-BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
-with routines that will fill it with information, such as
-BIO_accept_ex().
-
-BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new().
-
-BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
-it back to an uninitialised state.
-
-BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of
-size B<wherelen> with an address in network byte order pointed at
-by B<where> and a port number in network byte order in B<port> (except
-for the B<AF_UNIX> protocol family, where B<port> is meaningless and
-therefore ignored) and populates the given B<BIO_ADDR> with them.
-In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected
-to be the length of the path string (not including the terminating
-NUL, such as the result of a call to strlen()).
-I<Read on about the addresses in L</RAW ADDRESSES> below>.
-
-BIO_ADDR_family() returns the protocol family of the given
-B<BIO_ADDR>. The possible non-error results are one of the
-constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the
-BIO_ADDR has not been initialised.
-
-BIO_ADDR_rawaddress() will write the raw address of the given
-B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL,
-and will set B<*l> to be the amount of bytes the raw address
-takes up if B<l> is non-NULL.
-A technique to only find out the size of the address is a call
-with B<p> set to B<NULL>. The raw address will be in network byte
-order, most significant byte first.
-In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the
-path string (not including the terminating NUL, such as the result of
-a call to strlen()).
-I<Read on about the addresses in L</RAW ADDRESSES> below>.
-
-BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>.
-The raw port will be in network byte order.
-
-BIO_ADDR_hostname_string() returns a character string with the
-hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string
-will contain the numerical form of the address. This only works for
-B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
-returned string has been allocated on the heap and must be freed
-with OPENSSL_free().
-
-BIO_ADDR_service_string() returns a character string with the
-service name of the port of the given B<BIO_ADDR>. If B<numeric>
-is 1, the string will contain the port number. This only works
-for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
-returned string has been allocated on the heap and must be freed
-with OPENSSL_free().
-
-BIO_ADDR_path_string() returns a character string with the path
-of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the
-protocol family AF_UNIX. The returned string has been allocated
-on the heap and must be freed with OPENSSL_free().
-
-=head1 RAW ADDRESSES
-
-Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a
-network byte order address of a specific site. Internally, those are
-treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct
-in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all
-depending on the protocol family the address is for.
-
-=head1 RETURN VALUES
-
-The string producing functions BIO_ADDR_hostname_string(),
-BIO_ADDR_service_string() and BIO_ADDR_path_string() will
-return B<NULL> on error and leave an error indication on the
-OpenSSL error stack.
-
-All other functions described here return 0 or B<NULL> when the
-information they should return isn't available.
-
-=head1 SEE ALSO
-
-L<BIO_connect(3)>, L<BIO_s_connect(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
-BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
-BIO_ADDRINFO_address,
-BIO_lookup
-- BIO_ADDRINFO type and routines
-
-=head1 SYNOPSIS
-
- #include <sys/types.h>
- #include <openssl/bio.h>
-
- typedef union bio_addrinfo_st BIO_ADDRINFO;
-
- enum BIO_lookup_type {
- BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
- };
- int BIO_lookup(const char *node, const char *service,
- enum BIO_lookup_type lookup_type,
- int family, int socktype, BIO_ADDRINFO **res);
-
- const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
- int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
- int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
- int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
- const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
- void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
-
-=head1 DESCRIPTION
-
-The B<BIO_ADDRINFO> type is a wrapper for address information
-types provided on your platform.
-
-B<BIO_ADDRINFO> normally forms a chain of several that can be
-picked at one by one.
-
-BIO_lookup() looks up a specified B<host> and B<service>, and
-uses B<lookup_type> to determine what the default address should
-be if B<host> is B<NULL>. B<family>, B<socktype> are used to
-determine what protocol family and protocol should be used for
-the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
-AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM.
-B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
-chain.
-For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service>
-parameter and expects the B<node> parameter to hold the path to the
-socket file.
-
-BIO_ADDRINFO_family() returns the family of the given
-B<BIO_ADDRINFO>. The result will be one of the constants
-AF_INET, AF_INET6 and AF_UNIX.
-
-BIO_ADDRINFO_socktype() returns the socket type of the given
-B<BIO_ADDRINFO>. The result will be one of the constants
-SOCK_STREAM and SOCK_DGRAM.
-
-BIO_ADDRINFO_protocol() returns the protocol id of the given
-B<BIO_ADDRINFO>. The result will be one of the constants
-IPPROTO_TCP and IPPROTO_UDP.
-
-BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR>
-of the given B<BIO_ADDRINFO>.
-
-BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain
-from the given one.
-
-BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
-with the given one.
-
-=head1 RETURN VALUES
-
-BIO_lookup() returns 1 on success and 0 when an error occurred, and
-will leave an error indication on the OpenSSL error stack in that case.
-
-All other functions described here return 0 or B<NULL> when the
-information they should return isn't available.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
-socket communication setup routines
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- int BIO_socket(int domain, int socktype, int protocol, int options);
- int BIO_connect(int sock, const BIO_ADDR *addr, int options);
- int BIO_listen(int sock, const BIO_ADDR *addr, int options);
- int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);
- int BIO_closesocket(int sock);
-
-=head1 DESCRIPTION
-
-BIO_socket() creates a socket in the domain B<domain>, of type
-B<socktype> and B<protocol>. Socket B<options> are currently unused,
-but is present for future use.
-
-BIO_connect() connects B<sock> to the address and service given by
-B<addr>. Connection B<options> may be zero or any combination of
-B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>.
-The flags are described in L</FLAGS> below.
-
-BIO_listen() has B<sock> start listening on the address and service
-given by B<addr>. Connection B<options> may be zero or any
-combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>,
-B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>.
-The flags are described in L</FLAGS> below.
-
-BIO_accept_ex() waits for an incoming connections on the given
-socket B<accept_sock>. When it gets a connection, the address and
-port of the peer gets stored in B<peer> if that one is non-NULL.
-Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied
-on the accepted socket. The flags are described in L</FLAGS> below.
-
-BIO_closesocket() closes B<sock>.
-
-=head1 FLAGS
-
-=over 4
-
-=item BIO_SOCK_KEEPALIVE
-
-Enables regular sending of keep-alive messages.
-
-=item BIO_SOCK_NONBLOCK
-
-Sets the socket to non-blocking mode.
-
-=item BIO_SOCK_NODELAY
-
-Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With
-this set, any data will be sent as soon as possible instead of being
-buffered until there's enough for the socket to send out in one go.
-
-=item BIO_SOCK_REUSEADDR
-
-Try to reuse the address and port combination for a recently closed
-port.
-
-=item BIO_SOCK_V6_ONLY
-
-When creating an IPv6 socket, make it only listen for IPv6 addresses
-and not IPv4 addresses mapped to IPv6.
-
-=back
-
-These flags are bit flags, so they are to be combined with the
-C<|> operator, for example:
-
- BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);
-
-=head1 RETURN VALUES
-
-BIO_socket() returns the socket number on success or B<INVALID_SOCKET>
-(-1) on error. When an error has occurred, the OpenSSL error stack
-will hold the error data and errno has the system error.
-
-BIO_connect() and BIO_listen() return 1 on success or 0 on error.
-When an error has occurred, the OpenSSL error stack will hold the error
-data and errno has the system error.
-
-BIO_accept_ex() returns the accepted socket on success or
-B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
-OpenSSL error stack will hold the error data and errno has the system
-error.
-
-=head1 HISTORY
-
-BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
-BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL
-1.1. Use the functions described above instead.
-
-=head1 SEE ALSO
-
-L<BIO_ADDR(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
-BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
-BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
-BIO_get_info_callback, BIO_set_info_callback - BIO control operations
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
-
- long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
- long BIO_callback_ctrl(BIO *b, int cmd, bio_info_cb cb);
- char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
- long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
-
- int BIO_reset(BIO *b);
- int BIO_seek(BIO *b, int ofs);
- int BIO_tell(BIO *b);
- int BIO_flush(BIO *b);
- int BIO_eof(BIO *b);
- int BIO_set_close(BIO *b, long flag);
- int BIO_get_close(BIO *b);
- int BIO_pending(BIO *b);
- int BIO_wpending(BIO *b);
- size_t BIO_ctrl_pending(BIO *b);
- size_t BIO_ctrl_wpending(BIO *b);
-
- int BIO_get_info_callback(BIO *b, bio_info_cb **cbp);
- int BIO_set_info_callback(BIO *b, bio_info_cb *cb);
-
-=head1 DESCRIPTION
-
-BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
-are BIO "control" operations taking arguments of various types.
-These functions are not normally called directly, various macros
-are used instead. The standard macros are described below, macros
-specific to a particular type of BIO are described in the specific
-BIOs manual page as well as any special features of the standard
-calls.
-
-BIO_reset() typically resets a BIO to some initial state, in the case
-of file related BIOs for example it rewinds the file pointer to the
-start of the file.
-
-BIO_seek() resets a file related BIO's (that is file descriptor and
-FILE BIOs) file position pointer to B<ofs> bytes from start of file.
-
-BIO_tell() returns the current file position of a file related BIO.
-
-BIO_flush() normally writes out any internally buffered data, in some
-cases it is used to signal EOF and that no more data will be written.
-
-BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of
-"EOF" varies according to the BIO type.
-
-BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can
-take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
-in a source/sink BIO to indicate that the underlying I/O stream should
-be closed when the BIO is freed.
-
-BIO_get_close() returns the BIOs close flag.
-
-BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
-return the number of pending characters in the BIOs read and write buffers.
-Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending()
-return a size_t type and are functions, BIO_pending() and BIO_wpending() are
-macros which call BIO_ctrl().
-
-=head1 RETURN VALUES
-
-BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
-BIOs are an exception, they return 0 for success and -1 for failure.
-
-BIO_seek() and BIO_tell() both return the current file position on success
-and -1 for failure, except file BIOs which for BIO_seek() always return 0
-for success and -1 for failure.
-
-BIO_flush() returns 1 for success and 0 or -1 for failure.
-
-BIO_eof() returns 1 if EOF has been reached 0 otherwise.
-
-BIO_set_close() always returns 1.
-
-BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
-
-BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
-return the amount of pending data.
-
-=head1 NOTES
-
-BIO_flush(), because it can write data may return 0 or -1 indicating
-that the call should be retried later in a similar manner to BIO_write().
-The BIO_should_retry() call should be used and appropriate action taken
-is the call fails.
-
-The return values of BIO_pending() and BIO_wpending() may not reliably
-determine the amount of pending data in all cases. For example in the
-case of a file BIO some data may be available in the FILE structures
-internal buffers but it is not possible to determine this in a
-portably way. For other types of BIO they may not be supported.
-
-Filter BIOs if they do not internally handle a particular BIO_ctrl()
-operation usually pass the operation to the next BIO in the chain.
-This often means there is no need to locate the required BIO for
-a particular operation, it can be called on a chain and it will
-be automatically passed to the relevant BIO. However this can cause
-unexpected results: for example no current filter BIOs implement
-BIO_seek(), but this may still succeed if the chain ends in a FILE
-or file descriptor BIO.
-
-Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl()
-operation.
-
-=head1 BUGS
-
-Some of the return values are ambiguous and care should be taken. In
-particular a return value of 0 can be returned if an operation is not
-supported, if an error occurred, if EOF has not been reached and in
-the case of BIO_seek() on a file BIO for a successful operation.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_f_base64 - base64 BIO filter
-
-=for comment multiple includes
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
- #include <openssl/evp.h>
-
- const BIO_METHOD *BIO_f_base64(void);
-
-=head1 DESCRIPTION
-
-BIO_f_base64() returns the base64 BIO method. This is a filter
-BIO that base64 encodes any data written through it and decodes
-any data read through it.
-
-Base64 BIOs do not support BIO_gets() or BIO_puts().
-
-BIO_flush() on a base64 BIO that is being written through is
-used to signal that no more data is to be encoded: this is used
-to flush the final block through the BIO.
-
-The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
-to encode the data all on one line or expect the data to be all
-on one line.
-
-=head1 NOTES
-
-Because of the format of base64 encoding the end of the encoded
-block cannot always be reliably determined.
-
-=head1 RETURN VALUES
-
-BIO_f_base64() returns the base64 BIO method.
-
-=head1 EXAMPLES
-
-Base64 encode the string "Hello World\n" and write the result
-to standard output:
-
- BIO *bio, *b64;
- char message[] = "Hello World \n";
-
- b64 = BIO_new(BIO_f_base64());
- bio = BIO_new_fp(stdout, BIO_NOCLOSE);
- BIO_push(b64, bio);
- BIO_write(b64, message, strlen(message));
- BIO_flush(b64);
-
- BIO_free_all(b64);
-
-Read Base64 encoded data from standard input and write the decoded
-data to standard output:
-
- BIO *bio, *b64, *bio_out;
- char inbuf[512];
- int inlen;
-
- b64 = BIO_new(BIO_f_base64());
- bio = BIO_new_fp(stdin, BIO_NOCLOSE);
- bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
- BIO_push(b64, bio);
- while((inlen = BIO_read(b64, inbuf, 512)) > 0)
- BIO_write(bio_out, inbuf, inlen);
-
- BIO_flush(bio_out);
- BIO_free_all(b64);
-
-=head1 BUGS
-
-The ambiguity of EOF in base64 encoded data can cause additional
-data following the base64 encoded block to be misinterpreted.
-
-There should be some way of specifying a test that the BIO can perform
-to reliably determine EOF (for example a MIME boundary).
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_get_buffer_num_lines,
-BIO_set_read_buffer_size,
-BIO_set_write_buffer_size,
-BIO_set_buffer_size,
-BIO_set_buffer_read_data,
-BIO_f_buffer
-- buffering BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD *BIO_f_buffer(void);
-
- long BIO_get_buffer_num_lines(BIO *b);
- long BIO_set_read_buffer_size(BIO *b, long size);
- long BIO_set_write_buffer_size(BIO *b, long size);
- long BIO_set_buffer_size(BIO *b, long size);
- long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
-
-=head1 DESCRIPTION
-
-BIO_f_buffer() returns the buffering BIO method.
-
-Data written to a buffering BIO is buffered and periodically written
-to the next BIO in the chain. Data read from a buffering BIO comes from
-an internal buffer which is filled from the next BIO in the chain.
-Both BIO_gets() and BIO_puts() are supported.
-
-Calling BIO_reset() on a buffering BIO clears any buffered data.
-
-BIO_get_buffer_num_lines() returns the number of lines currently buffered.
-
-BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
-set the read, write or both read and write buffer sizes to B<size>. The initial
-buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the
-buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared
-when the buffer is resized.
-
-BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>
-bytes of B<buf>. If B<num> is larger than the current buffer size the buffer
-is expanded.
-
-=head1 NOTES
-
-These functions, other than BIO_f_buffer(), are implemented as macros.
-
-Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
-next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
-possible to provide BIO_gets() functionality if the following BIOs do not
-support it (for example SSL BIOs).
-
-Data is only written to the next BIO in the chain when the write buffer fills
-or when BIO_flush() is called. It is therefore important to call BIO_flush()
-whenever any pending data should be written such as when removing a buffering
-BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
-source/sink BIO is non blocking.
-
-=head1 RETURN VALUES
-
-BIO_f_buffer() returns the buffering BIO method.
-
-BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
-
-BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
-return 1 if the buffer was successfully resized or 0 for failure.
-
-BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if
-there was an error.
-
-=head1 SEE ALSO
-
-L<BIO(3)>,
-L<BIO_reset(3)>,
-L<BIO_flush(3)>,
-L<BIO_pop(3)>,
-L<BIO_ctrl(3)>.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
-
-=for comment multiple includes
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
- #include <openssl/evp.h>
-
- const BIO_METHOD *BIO_f_cipher(void);
- void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
- unsigned char *key, unsigned char *iv, int enc);
- int BIO_get_cipher_status(BIO *b)
- int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
-
-=head1 DESCRIPTION
-
-BIO_f_cipher() returns the cipher BIO method. This is a filter
-BIO that encrypts any data written through it, and decrypts any data
-read from it. It is a BIO wrapper for the cipher routines
-EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
-
-Cipher BIOs do not support BIO_gets() or BIO_puts().
-
-BIO_flush() on an encryption BIO that is being written through is
-used to signal that no more data is to be encrypted: this is used
-to flush and possibly pad the final block through the BIO.
-
-BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key>
-and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
-decryption.
-
-When reading from an encryption BIO the final block is automatically
-decrypted and checked when EOF is detected. BIO_get_cipher_status()
-is a BIO_ctrl() macro which can be called to determine whether the
-decryption operation was successful.
-
-BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
-BIO cipher context. The retrieved context can be used in conjunction
-with the standard cipher routines to set it up. This is useful when
-BIO_set_cipher() is not flexible enough for the applications needs.
-
-=head1 NOTES
-
-When encrypting BIO_flush() B<must> be called to flush the final block
-through the BIO. If it is not then the final block will fail a subsequent
-decrypt.
-
-When decrypting an error on the final block is signaled by a zero
-return value from the read operation. A successful decrypt followed
-by EOF will also return zero for the final read. BIO_get_cipher_status()
-should be called to determine if the decrypt was successful.
-
-As always, if BIO_gets() or BIO_puts() support is needed then it can
-be achieved by preceding the cipher BIO with a buffering BIO.
-
-=head1 RETURN VALUES
-
-BIO_f_cipher() returns the cipher BIO method.
-
-BIO_set_cipher() does not return a value.
-
-BIO_get_cipher_status() returns 1 for a successful decrypt and 0
-for failure.
-
-BIO_get_cipher_ctx() currently always returns 1.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
-
-=for comment multiple includes
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
- #include <openssl/evp.h>
-
- const BIO_METHOD *BIO_f_md(void);
- int BIO_set_md(BIO *b, EVP_MD *md);
- int BIO_get_md(BIO *b, EVP_MD **mdp);
- int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
-
-=head1 DESCRIPTION
-
-BIO_f_md() returns the message digest BIO method. This is a filter
-BIO that digests any data passed through it, it is a BIO wrapper
-for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
-and EVP_DigestFinal().
-
-Any data written or read through a digest BIO using BIO_read() and
-BIO_write() is digested.
-
-BIO_gets(), if its B<size> parameter is large enough finishes the
-digest calculation and returns the digest value. BIO_puts() is
-not supported.
-
-BIO_reset() reinitialises a digest BIO.
-
-BIO_set_md() sets the message digest of BIO B<b> to B<md>: this
-must be called to initialize a digest BIO before any data is
-passed through it. It is a BIO_ctrl() macro.
-
-BIO_get_md() places the a pointer to the digest BIOs digest method
-in B<mdp>, it is a BIO_ctrl() macro.
-
-BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.
-
-=head1 NOTES
-
-The context returned by BIO_get_md_ctx() can be used in calls
-to EVP_DigestFinal() and also the signature routines EVP_SignFinal()
-and EVP_VerifyFinal().
-
-The context returned by BIO_get_md_ctx() is an internal context
-structure. Changes made to this context will affect the digest
-BIO itself and the context pointer will become invalid when the digest
-BIO is freed.
-
-After the digest has been retrieved from a digest BIO it must be
-reinitialized by calling BIO_reset(), or BIO_set_md() before any more
-data is passed through it.
-
-If an application needs to call BIO_gets() or BIO_puts() through
-a chain containing digest BIOs then this can be done by prepending
-a buffering BIO.
-
-Calling BIO_get_md_ctx() will return the context and initialize the BIO
-state. This allows applications to initialize the context externally
-if the standard calls such as BIO_set_md() are not sufficiently flexible.
-
-=head1 RETURN VALUES
-
-BIO_f_md() returns the digest BIO method.
-
-BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and
-0 for failure.
-
-=head1 EXAMPLES
-
-The following example creates a BIO chain containing an SHA1 and MD5
-digest BIO and passes the string "Hello World" through it. Error
-checking has been omitted for clarity.
-
- BIO *bio, *mdtmp;
- char message[] = "Hello World";
- bio = BIO_new(BIO_s_null());
- mdtmp = BIO_new(BIO_f_md());
- BIO_set_md(mdtmp, EVP_sha1());
- /* For BIO_push() we want to append the sink BIO and keep a note of
- * the start of the chain.
- */
- bio = BIO_push(mdtmp, bio);
- mdtmp = BIO_new(BIO_f_md());
- BIO_set_md(mdtmp, EVP_md5());
- bio = BIO_push(mdtmp, bio);
- /* Note: mdtmp can now be discarded */
- BIO_write(bio, message, strlen(message));
-
-The next example digests data by reading through a chain instead:
-
- BIO *bio, *mdtmp;
- char buf[1024];
- int rdlen;
- bio = BIO_new_file(file, "rb");
- mdtmp = BIO_new(BIO_f_md());
- BIO_set_md(mdtmp, EVP_sha1());
- bio = BIO_push(mdtmp, bio);
- mdtmp = BIO_new(BIO_f_md());
- BIO_set_md(mdtmp, EVP_md5());
- bio = BIO_push(mdtmp, bio);
- do {
- rdlen = BIO_read(bio, buf, sizeof(buf));
- /* Might want to do something with the data here */
- } while (rdlen > 0);
-
-This next example retrieves the message digests from a BIO chain and
-outputs them. This could be used with the examples above.
-
- BIO *mdtmp;
- unsigned char mdbuf[EVP_MAX_MD_SIZE];
- int mdlen;
- int i;
- mdtmp = bio; /* Assume bio has previously been set up */
- do {
- EVP_MD *md;
- mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
- if (!mdtmp) break;
- BIO_get_md(mdtmp, &md);
- printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
- mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
- for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
- printf("\n");
- mdtmp = BIO_next(mdtmp);
- } while (mdtmp);
-
- BIO_free_all(bio);
-
-=head1 BUGS
-
-The lack of support for BIO_puts() and the non standard behaviour of
-BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()
-and BIO_puts() should be passed to the next BIO in the chain and digest
-the data passed through and that digests should be retrieved using a
-separate BIO_ctrl() call.
-
-=head1 HISTORY
-
-Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the
-BIO was initialized first.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_f_null - null filter
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD * BIO_f_null(void);
-
-=head1 DESCRIPTION
-
-BIO_f_null() returns the null filter BIO method. This is a filter BIO
-that does nothing.
-
-All requests to a null filter BIO are passed through to the next BIO in
-the chain: this means that a BIO chain containing a null filter BIO
-behaves just as though the BIO was not there.
-
-=head1 NOTES
-
-As may be apparent a null filter BIO is not particularly useful.
-
-=head1 RETURN VALUES
-
-BIO_f_null() returns the null filter BIO method.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_do_handshake,
-BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
-BIO_set_ssl_renegotiate_bytes,
-BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
-BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
-BIO_ssl_shutdown - SSL BIO
-
-=for comment multiple includes
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
- #include <openssl/ssl.h>
-
- const BIO_METHOD *BIO_f_ssl(void);
-
- long BIO_set_ssl(BIO *b, SSL *ssl, long c);
- long BIO_get_ssl(BIO *b, SSL **sslp);
- long BIO_set_ssl_mode(BIO *b, long client);
- long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
- long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
- long BIO_get_num_renegotiates(BIO *b);
-
- BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
- BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
- BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
- int BIO_ssl_copy_session_id(BIO *to, BIO *from);
- void BIO_ssl_shutdown(BIO *bio);
-
- long BIO_do_handshake(BIO *b);
-
-=head1 DESCRIPTION
-
-BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
-is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
-SSL I/O.
-
-I/O performed on an SSL BIO communicates using the SSL protocol with
-the SSLs read and write BIOs. If an SSL connection is not established
-then an attempt is made to establish one on the first I/O call.
-
-If a BIO is appended to an SSL BIO using BIO_push() it is automatically
-used as the SSL BIOs read and write BIOs.
-
-Calling BIO_reset() on an SSL BIO closes down any current SSL connection
-by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
-the chain: this will typically disconnect the underlying transport.
-The SSL BIO is then reset to the initial accept or connect state.
-
-If the close flag is set when an SSL BIO is freed then the internal
-SSL structure is also freed using SSL_free().
-
-BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
-the close flag B<c>.
-
-BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
-manipulated using the standard SSL library functions.
-
-BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
-is 1 client mode is set. If B<client> is 0 server mode is set.
-
-BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
-to B<num>. When set after every B<num> bytes of I/O (read and write)
-the SSL session is automatically renegotiated. B<num> must be at
-least 512 bytes.
-
-BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
-B<seconds>. When the renegotiate timeout elapses the session is
-automatically renegotiated.
-
-BIO_get_num_renegotiates() returns the total number of session
-renegotiations due to I/O or timeout.
-
-BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
-client mode if B<client> is non zero.
-
-BIO_new_ssl_connect() creates a new BIO chain consisting of an
-SSL BIO (using B<ctx>) followed by a connect BIO.
-
-BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
-of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
-BIO.
-
-BIO_ssl_copy_session_id() copies an SSL session id between
-BIO chains B<from> and B<to>. It does this by locating the
-SSL BIOs in each chain and calling SSL_copy_session_id() on
-the internal SSL pointer.
-
-BIO_ssl_shutdown() closes down an SSL connection on BIO
-chain B<bio>. It does this by locating the SSL BIO in the
-chain and calling SSL_shutdown() on its internal SSL
-pointer.
-
-BIO_do_handshake() attempts to complete an SSL handshake on the
-supplied BIO and establish the SSL connection. It returns 1
-if the connection was established successfully. A zero or negative
-value is returned if the connection could not be established, the
-call BIO_should_retry() should be used for non blocking connect BIOs
-to determine if the call should be retried. If an SSL connection has
-already been established this call has no effect.
-
-=head1 NOTES
-
-SSL BIOs are exceptional in that if the underlying transport
-is non blocking they can still request a retry in exceptional
-circumstances. Specifically this will happen if a session
-renegotiation takes place during a BIO_read() operation, one
-case where this happens is when step up occurs.
-
-The SSL flag SSL_AUTO_RETRY can be
-set to disable this behaviour. That is when this flag is set
-an SSL BIO using a blocking transport will never request a
-retry.
-
-Since unknown BIO_ctrl() operations are sent through filter
-BIOs the servers name and port can be set using BIO_set_host()
-on the BIO returned by BIO_new_ssl_connect() without having
-to locate the connect BIO first.
-
-Applications do not have to call BIO_do_handshake() but may wish
-to do so to separate the handshake process from other I/O
-processing.
-
-BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
-BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
-BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
-
-=head1 EXAMPLE
-
-This SSL/TLS client example, attempts to retrieve a page from an
-SSL/TLS web server. The I/O routines are identical to those of the
-unencrypted example in L<BIO_s_connect(3)>.
-
- BIO *sbio, *out;
- int len;
- char tmpbuf[1024];
- SSL_CTX *ctx;
- SSL *ssl;
-
- /* XXX Seed the PRNG if needed. */
-
- ctx = SSL_CTX_new(TLS_client_method());
-
- /* XXX Set verify paths and mode here. */
-
- sbio = BIO_new_ssl_connect(ctx);
- BIO_get_ssl(sbio, &ssl);
- if (ssl == NULL) {
- fprintf(stderr, "Can't locate SSL pointer\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- /* Don't want any retries */
- SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
-
- /* XXX We might want to do other things with ssl here */
-
- /* An empty host part means the loopback address */
- BIO_set_conn_hostname(sbio, ":https");
-
- out = BIO_new_fp(stdout, BIO_NOCLOSE);
- if (BIO_do_connect(sbio) <= 0) {
- fprintf(stderr, "Error connecting to server\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
- if (BIO_do_handshake(sbio) <= 0) {
- fprintf(stderr, "Error establishing SSL connection\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- /* XXX Could examine ssl here to get connection info */
-
- BIO_puts(sbio, "GET / HTTP/1.0\n\n");
- for ( ; ; ) {
- len = BIO_read(sbio, tmpbuf, 1024);
- if (len <= 0)
- break;
- BIO_write(out, tmpbuf, len);
- }
- BIO_free_all(sbio);
- BIO_free(out);
-
-Here is a simple server example. It makes use of a buffering
-BIO to allow lines to be read from the SSL BIO using BIO_gets.
-It creates a pseudo web page containing the actual request from
-a client and also echoes the request to standard output.
-
- BIO *sbio, *bbio, *acpt, *out;
- int len;
- char tmpbuf[1024];
- SSL_CTX *ctx;
- SSL *ssl;
-
- /* XXX Seed the PRNG if needed. */
-
- ctx = SSL_CTX_new(TLS_server_method());
- if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
- || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
- || !SSL_CTX_check_private_key(ctx)) {
- fprintf(stderr, "Error setting up SSL_CTX\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- /* XXX Other things like set verify locations, EDH temp callbacks. */
-
- /* New SSL BIO setup as server */
- sbio = BIO_new_ssl(ctx, 0);
- BIO_get_ssl(sbio, &ssl);
- if (ssl == NULL) {
- fprintf(stderr, "Can't locate SSL pointer\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
- bbio = BIO_new(BIO_f_buffer());
- sbio = BIO_push(bbio, sbio);
- acpt = BIO_new_accept("4433");
-
- /*
- * By doing this when a new connection is established
- * we automatically have sbio inserted into it. The
- * BIO chain is now 'swallowed' by the accept BIO and
- * will be freed when the accept BIO is freed.
- */
- BIO_set_accept_bios(acpt, sbio);
- out = BIO_new_fp(stdout, BIO_NOCLOSE);
-
- /* Setup accept BIO */
- if (BIO_do_accept(acpt) <= 0) {
- fprintf(stderr, "Error setting up accept BIO\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- if (BIO_do_accept(acpt) <= 0) {
- fprintf(stderr, "Error in connection\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- /* We only want one connection so remove and free accept BIO */
- sbio = BIO_pop(acpt);
- BIO_free_all(acpt);
-
- if (BIO_do_handshake(sbio) <= 0) {
- fprintf(stderr, "Error in SSL handshake\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
- BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
- BIO_puts(sbio, "--------------------------------------------------\r\n");
-
- for ( ; ; ) {
- len = BIO_gets(sbio, tmpbuf, 1024);
- if (len <= 0)
- break;
- BIO_write(sbio, tmpbuf, len);
- BIO_write(out, tmpbuf, len);
- /* Look for blank line signifying end of headers*/
- if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
- break;
- }
-
- BIO_puts(sbio, "--------------------------------------------------\r\n");
- BIO_puts(sbio, "\r\n");
- BIO_flush(sbio);
- BIO_free_all(sbio);
-
-=head1 BUGS
-
-In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly,
-the I/O BIO reference count was incorrectly incremented (instead of
-decremented) and dissociated with the SSL BIO even if the SSL BIO was not
-explicitly being popped (e.g. a pop higher up the chain). Applications which
-included workarounds for this bug (e.g. freeing BIOs more than once) should
-be modified to handle this fix or they may free up an already freed BIO.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- BIO *BIO_find_type(BIO *b, int bio_type);
- BIO *BIO_next(BIO *b);
- int BIO_method_type(const BIO *b);
-
-=head1 DESCRIPTION
-
-The BIO_find_type() searches for a BIO of a given type in a chain, starting
-at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search
-is made for a BIO of that type. If B<type> is a general type (such as
-B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
-searched for. BIO_find_type() returns the next matching BIO or NULL if none is
-found.
-
-The following general types are defined:
-B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
-
-For a list of the specific types, see the B<openssl/bio.h> header file.
-
-BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
-in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
-certain type.
-
-BIO_method_type() returns the type of a BIO.
-
-=head1 RETURN VALUES
-
-BIO_find_type() returns a matching BIO or NULL for no match.
-
-BIO_next() returns the next BIO in a chain.
-
-BIO_method_type() returns the type of the BIO B<b>.
-
-=head1 EXAMPLE
-
-Traverse a chain looking for digest BIOs:
-
- BIO *btmp;
- btmp = in_bio; /* in_bio is chain to search through */
-
- do {
- btmp = BIO_find_type(btmp, BIO_TYPE_MD);
- if (btmp == NULL) break; /* Not found */
- /* btmp is a digest BIO, do something with it ...*/
- ...
-
- btmp = BIO_next(btmp);
- } while (btmp);
-
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown,
-BIO_get_shutdown - functions for managing BIO state information
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- void BIO_set_data(BIO *a, void *ptr);
- void *BIO_get_data(BIO *a);
- void BIO_set_init(BIO *a, int init);
- int BIO_get_init(BIO *a);
- void BIO_set_shutdown(BIO *a, int shut);
- int BIO_get_shutdown(BIO *a);
-
-=head1 DESCRIPTION
-
-These functions are mainly useful when implementing a custom BIO.
-
-The BIO_set_data() function associates the custom data pointed to by B<ptr> with
-the BIO. This data can subsequently be retrieved via a call to BIO_get_data().
-This can be used by custom BIOs for storing implementation specific information.
-
-The BIO_set_init() function sets the value of the BIO's "init" flag to indicate
-whether initialisation has been completed for this BIO or not. A non-zero value
-indicates that initialisation is complete, whilst zero indicates that it is not.
-Often initialisation will complete during initial construction of the BIO. For
-some BIOs however, initialisation may not complete until after additional steps
-have occurred (for example through calling custom ctrls). The BIO_get_init()
-function returns the value of the "init" flag.
-
-The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of
-this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource
-is also closed when the BIO is freed.
-
-=head1 RETURN VALUES
-
-BIO_get_data() returns a pointer to the implementation specific custom data
-associated with this BIO, or NULL if none has been set.
-
-BIO_get_init() returns the state of the BIO's init flag.
-
-BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.
-
-=head1 SEE ALSO
-
-L<bio>, L<BIO_meth_new>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data,
-ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
-UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data,
-X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data,
-X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data,
-X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data,
-DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
-DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
-ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data,
-ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_get_ex_data,
-RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
-- application-specific data
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int TYPE_get_ex_new_index(long argl, void *argp,
- CRYPTO_EX_new *new_func,
- CRYPTO_EX_dup *dup_func,
- CRYPTO_EX_free *free_func);
-
- int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
-
- void *TYPE_get_ex_data(TYPE *d, int idx);
-
-=head1 DESCRIPTION
-
-In the description here, I<TYPE> is used a placeholder
-for any of the OpenSSL datatypes listed in
-L<CRYPTO_get_ex_new_index(3)>.
-
-These functions handle application-specific data for OpenSSL data
-structures.
-
-TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
-with the correct B<index> value.
-
-TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
-an offset into the opaque exdata part of the TYPE object.
-
-TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an
-an offset into the opaque exdata part of the TYPE object.
-
-=head1 SEE ALSO
-
-L<CRYPTO_get_ex_new_index(3)>.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_get_new_index,
-BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,
-BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,
-BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,
-BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,
-BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
-BIO_meth_set_callback_ctrl - Routines to build up BIO methods
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- int BIO_get_new_index(void);
- BIO_METHOD *BIO_meth_new(int type, const char *name);
- void BIO_meth_free(BIO_METHOD *biom);
- int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);
- int BIO_meth_set_write(BIO_METHOD *biom,
- int (*write) (BIO *, const char *, int));
- int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);
- int BIO_meth_set_read(BIO_METHOD *biom,
- int (*read) (BIO *, char *, int));
- int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);
- int BIO_meth_set_puts(BIO_METHOD *biom,
- int (*puts) (BIO *, const char *));
- int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int);
- int BIO_meth_set_gets(BIO_METHOD *biom,
- int (*gets) (BIO *, char *, int));
- long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *);
- int BIO_meth_set_ctrl(BIO_METHOD *biom,
- long (*ctrl) (BIO *, int, long, void *));
- int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *);
- int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *));
- int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *);
- int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *));
- long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom))
- (BIO *, int, bio_info_cb *);
- int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
- long (*callback_ctrl) (BIO *, int,
- bio_info_cb *));
-
-=head1 DESCRIPTION
-
-The B<BIO_METHOD> type is a structure used for the implementation of new BIO
-types. It provides a set of of functions used by OpenSSL for the implementation
-of the various BIO capabilities. See the L<bio> page for more information.
-
-BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
-unique integer B<type> and a string that represents its B<name>.
-Use BIO_get_new_index() to get the value for B<type>.
-
-The set of
-standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
-include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
-type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
-should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
-based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
-"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
-more information.
-
-BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
-associated with it.
-
-BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for
-writing arbitrary length data to the BIO respectively. This function will be
-called in response to the application calling BIO_write(). The parameters for
-the function have the same meaning as for BIO_write().
-
-BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for
-reading arbitrary length data from the BIO respectively. This function will be
-called in response to the application calling BIO_read(). The parameters for the
-function have the same meaning as for BIO_read().
-
-BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
-writing a NULL terminated string to the BIO respectively. This function will be
-called in response to the application calling BIO_puts(). The parameters for
-the function have the same meaning as for BIO_puts().
-
-BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
-used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
-page for more information). This function will be called in response to the
-application calling BIO_gets(). The parameters for the function have the same
-meaning as for BIO_gets().
-
-BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
-processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
-more information. This function will be called in response to the application
-calling BIO_ctrl(). The parameters for the function have the same meaning as for
-BIO_ctrl().
-
-BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
-for creating a new instance of the BIO respectively. This function will be
-called in response to the application calling BIO_new() and passing
-in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
-memory for the new BIO, and a pointer to this newly allocated structure will
-be passed as a parameter to the function.
-
-BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
-for destroying an instance of a BIO respectively. This function will be
-called in response to the application calling BIO_free(). A pointer to the BIO
-to be destroyed is passed as a parameter. The destroy function should be used
-for BIO specific clean up. The memory for the BIO itself should not be freed by
-this function.
-
-BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
-function used for processing callback ctrl messages in the BIO respectively. See
-the L<BIO_callback_ctrl(3)> page for more information. This function will be called
-in response to the application calling BIO_callback_ctrl(). The parameters for
-the function have the same meaning as for BIO_callback_ctrl().
-
-=head1 SEE ALSO
-
-L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all,
-BIO_set - BIO allocation and freeing functions
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- BIO * BIO_new(const BIO_METHOD *type);
- int BIO_set(BIO *a, const BIO_METHOD *type);
- int BIO_up_ref(BIO *a);
- int BIO_free(BIO *a);
- void BIO_vfree(BIO *a);
- void BIO_free_all(BIO *a);
-
-=head1 DESCRIPTION
-
-The BIO_new() function returns a new BIO using method B<type>.
-
-BIO_up_ref() increments the reference count associated with the BIO object.
-
-BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
-but it does not return a value.
-If B<a> is NULL nothing is done.
-Calling BIO_free() may also have some effect
-on the underlying I/O structure, for example it may close the file being
-referred to under certain circumstances. For more details see the individual
-BIO_METHOD descriptions.
-
-BIO_free_all() frees up an entire BIO chain, it does not halt if an error
-occurs freeing up an individual BIO in the chain.
-If B<a> is NULL nothing is done.
-
-=head1 RETURN VALUES
-
-BIO_new() returns a newly created BIO or NULL if the call fails.
-
-BIO_set(), BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.
-
-BIO_free_all() and BIO_vfree() do not return values.
-
-=head1 NOTES
-
-If BIO_free() is called on a BIO chain it will only free one BIO resulting
-in a memory leak.
-
-Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free()
-on it other than the discarded return value.
-
-=head1 HISTORY
-
-BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
-
-=head1 EXAMPLE
-
-Create a memory BIO:
-
- BIO *mem = BIO_new(BIO_s_mem());
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_new_CMS - CMS streaming filter BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);
-
-=head1 DESCRIPTION
-
-BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output
-of the filter is written to B<out>. Any data written to the chain is
-automatically translated to a BER format CMS structure of the appropriate type.
-
-=head1 NOTES
-
-The chain returned by this function behaves like a standard filter BIO. It
-supports non blocking I/O. Content is processed and streamed on the fly and not
-all held in memory at once: so it is possible to encode very large structures.
-After all content has been written through the chain BIO_flush() must be called
-to finalise the structure.
-
-The B<CMS_STREAM> flag must be included in the corresponding B<flags>
-parameter of the B<cms> creation function.
-
-If an application wishes to write additional data to B<out> BIOs should be
-removed from the chain using BIO_pop() and freed with BIO_free() until B<out>
-is reached. If no additional data needs to be written BIO_free_all() can be
-called to free up the whole chain.
-
-Any content written through the filter is used verbatim: no canonical
-translation is performed.
-
-It is possible to chain multiple BIOs to, for example, create a triple wrapped
-signed, enveloped, signed structure. In this case it is the applications
-responsibility to set the inner content type of any outer CMS_ContentInfo
-structures.
-
-Large numbers of small writes through the chain should be avoided as this will
-produce an output consisting of lots of OCTET STRING structures. Prepending
-a BIO_f_buffer() buffering BIO will prevent this.
-
-=head1 BUGS
-
-There is currently no corresponding inverse BIO: i.e. one which can decode
-a CMS structure on the fly.
-
-=head1 RETURN VALUES
-
-BIO_new_CMS() returns a BIO chain when successful or NULL if an error
-occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>,
-L<CMS_encrypt(3)>
-
-=head1 HISTORY
-
-BIO_new_CMS() was added to OpenSSL 1.0.0
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_parse_hostserv - utility routines to parse a standard host and service
-string
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- enum BIO_hostserv_priorities {
- BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
- };
- int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
- enum BIO_hostserv_priorities hostserv_prio);
-
-=head1 DESCRIPTION
-
-BIO_parse_hostserv() will parse the information given in B<hostserv>,
-create strings with the host name and service name and give those
-back via B<host> and B<service>. Those will need to be freed after
-they are used. B<hostserv_prio> helps determine if B<hostserv> shall
-be interpreted primarily as a host name or a service name in ambiguous
-cases.
-
-The syntax the BIO_parse_hostserv() recognises is:
-
- host + ':' + service
- host + ':' + '*'
- host + ':'
- ':' + service
- '*' + ':' + service
- host
- service
-
-The host part can be a name or an IP address. If it's a IPv6
-address, it MUST be enclosed in brackets, such as '[::1]'.
-
-The service part can be a service name or its port number.
-
-The returned values will depend on the given B<hostserv> string
-and B<hostserv_prio>, as follows:
-
- host + ':' + service => *host = "host", *service = "service"
- host + ':' + '*' => *host = "host", *service = NULL
- host + ':' => *host = "host", *service = NULL
- ':' + service => *host = NULL, *service = "service"
- '*' + ':' + service => *host = NULL, *service = "service"
-
- in case no ':' is present in the string, the result depends on
- hostserv_prio, as follows:
-
- when hostserv_prio == BIO_PARSE_PRIO_HOST
- host => *host = "host", *service untouched
-
- when hostserv_prio == BIO_PARSE_PRIO_SERV
- service => *host untouched, *service = "service"
-
-=head1 SEE ALSO
-
-L<BIO_ADDRINFO(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- BIO *BIO_push(BIO *b, BIO *append);
- BIO *BIO_pop(BIO *b);
- void BIO_set_next(BIO *b, BIO *next);
-
-=head1 DESCRIPTION
-
-The BIO_push() function appends the BIO B<append> to B<b>, it returns
-B<b>.
-
-BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
-in the chain, or NULL if there is no next BIO. The removed BIO then
-becomes a single BIO with no association with the original chain,
-it can thus be freed or attached to a different chain.
-
-BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
-by B<next>. The new chain may include some of the same BIOs from the old chain
-or it may be completely different.
-
-=head1 NOTES
-
-The names of these functions are perhaps a little misleading. BIO_push()
-joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
-the deleted BIO does not need to be at the end of a chain.
-
-The process of calling BIO_push() and BIO_pop() on a BIO may have additional
-consequences (a control call is made to the affected BIOs) any effects will
-be noted in the descriptions of individual BIOs.
-
-=head1 EXAMPLES
-
-For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
-a base64 BIO and B<f> is a file BIO.
-
-If the call:
-
- BIO_push(b64, f);
-
-is made then the new chain will be B<b64-f>. After making the calls
-
- BIO_push(md2, b64);
- BIO_push(md1, md2);
-
-the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
-by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
-
-It should be noted that reading causes data to pass in the reverse
-direction, that is data is read from B<f>, base64 B<decoded> and digested
-by B<md1> and B<md2>. If the call:
-
- BIO_pop(md2);
-
-The call will return B<b64> and the new chain will be B<md1-b64-f> data can
-be written to B<md1> as before.
-
-=head1 RETURN VALUES
-
-BIO_push() returns the end of the chain, B<b>.
-
-BIO_pop() returns the next BIO in the chain, or NULL if there is no next
-BIO.
-
-=head1 SEE ALSO
-
-L<bio>
-
-=head1 HISTORY
-
-The BIO_set_next() function was added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- int BIO_read(BIO *b, void *buf, int len);
- int BIO_gets(BIO *b, char *buf, int size);
- int BIO_write(BIO *b, const void *buf, int len);
- int BIO_puts(BIO *b, const char *buf);
-
-=head1 DESCRIPTION
-
-BIO_read() attempts to read B<len> bytes from BIO B<b> and places
-the data in B<buf>.
-
-BIO_gets() performs the BIOs "gets" operation and places the data
-in B<buf>. Usually this operation will attempt to read a line of data
-from the BIO of maximum length B<len-1>. There are exceptions to this,
-however; for example, BIO_gets() on a digest BIO will calculate and
-return the digest and other BIOs may not support BIO_gets() at all.
-The returned string is always NUL-terminated.
-
-BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
-
-BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
-
-=head1 RETURN VALUES
-
-All these functions return either the amount of data successfully read or
-written (if the return value is positive) or that no data was successfully
-read or written if the result is 0 or -1. If the return value is -2 then
-the operation is not implemented in the specific BIO type. The trailing
-NUL is not included in the length returned by BIO_gets().
-
-=head1 NOTES
-
-A 0 or -1 return is not necessarily an indication of an error. In
-particular when the source/sink is non-blocking or of a certain type
-it may merely be an indication that no data is currently available and that
-the application should retry the operation later.
-
-One technique sometimes used with blocking sockets is to use a system call
-(such as select(), poll() or equivalent) to determine when data is available
-and then call read() to read the data. The equivalent with BIOs (that is call
-select() on the underlying I/O structure and then call BIO_read() to
-read the data) should B<not> be used because a single call to BIO_read()
-can cause several reads (and writes in the case of SSL BIOs) on the underlying
-I/O structure and may block as a result. Instead select() (or equivalent)
-should be combined with non blocking I/O so successive reads will request
-a retry instead of blocking.
-
-See L<BIO_should_retry(3)> for details of how to
-determine the cause of a retry and other I/O issues.
-
-If the BIO_gets() function is not supported by a BIO then it possible to
-work around this by adding a buffering BIO L<BIO_f_buffer(3)>
-to the chain.
-
-=head1 SEE ALSO
-
-L<BIO_should_retry(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
-BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios,
-BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD *BIO_s_accept(void);
-
- long BIO_set_accept_name(BIO *b, char *name);
- char *BIO_get_accept_name(BIO *b);
-
- long BIO_set_accept_port(BIO *b, char *port);
- char *BIO_get_accept_port(BIO *b);
-
- BIO *BIO_new_accept(char *host_port);
-
- long BIO_set_nbio_accept(BIO *b, int n);
- long BIO_set_accept_bios(BIO *b, char *bio);
-
- long BIO_set_bind_mode(BIO *b, long mode);
- long BIO_get_bind_mode(BIO *b);
-
- int BIO_do_accept(BIO *b);
-
-=head1 DESCRIPTION
-
-BIO_s_accept() returns the accept BIO method. This is a wrapper
-round the platform's TCP/IP socket accept routines.
-
-Using accept BIOs, TCP/IP connections can be accepted and data
-transferred using only BIO routines. In this way any platform
-specific operations are hidden by the BIO abstraction.
-
-Read and write operations on an accept BIO will perform I/O
-on the underlying connection. If no connection is established
-and the port (see below) is set up properly then the BIO
-waits for an incoming connection.
-
-Accept BIOs support BIO_puts() but not BIO_gets().
-
-If the close flag is set on an accept BIO then any active
-connection on that chain is shutdown and the socket closed when
-the BIO is freed.
-
-Calling BIO_reset() on an accept BIO will close any active
-connection and reset the BIO into a state where it awaits another
-incoming connection.
-
-BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
-the accept socket. See L<BIO_s_fd(3)>
-
-BIO_set_accept_name() uses the string B<name> to set the accept
-name. The name is represented as a string of the form "host:port",
-where "host" is the interface to use and "port" is the port.
-The host can be "*" or empty which is interpreted as meaning
-any interface. If the host is an IPv6 address, it has to be
-enclosed in brackets, for example "[::1]:https". "port" has the
-same syntax as the port specified in BIO_set_conn_port() for
-connect BIOs, that is it can be a numerical port string or a
-string to lookup using getservbyname() and a string table.
-
-BIO_set_accept_port() uses the string B<port> to set the accept
-port. "port" has the same syntax as the port specified in
-BIO_set_conn_port() for connect BIOs, that is it can be a numerical
-port string or a string to lookup using getservbyname() and a string
-table.
-
-BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into
-a single call: that is it creates a new accept BIO with port
-B<host_port>.
-
-BIO_set_nbio_accept() sets the accept socket to blocking mode
-(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
-
-BIO_set_accept_bios() can be used to set a chain of BIOs which
-will be duplicated and prepended to the chain when an incoming
-connection is received. This is useful if, for example, a
-buffering or SSL BIO is required for each connection. The
-chain of BIOs must not be freed after this call, they will
-be automatically freed when the accept BIO is freed.
-
-BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
-the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set
-then another socket cannot be bound to the same port. If
-B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
-same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
-attempt is first made to use BIO_BIN_NORMAL, if this fails
-and the port is not in use then a second attempt is made
-using B<BIO_BIND_REUSEADDR>.
-
-BIO_do_accept() serves two functions. When it is first
-called, after the accept BIO has been setup, it will attempt
-to create the accept socket and bind an address to it. Second
-and subsequent calls to BIO_do_accept() will await an incoming
-connection, or request a retry in non blocking mode.
-
-=head1 NOTES
-
-When an accept BIO is at the end of a chain it will await an
-incoming connection before processing I/O calls. When an accept
-BIO is not at then end of a chain it passes I/O calls to the next
-BIO in the chain.
-
-When a connection is established a new socket BIO is created for
-the connection and appended to the chain. That is the chain is now
-accept->socket. This effectively means that attempting I/O on
-an initial accept socket will await an incoming connection then
-perform I/O on it.
-
-If any additional BIOs have been set using BIO_set_accept_bios()
-then they are placed between the socket and the accept BIO,
-that is the chain will be accept->otherbios->socket.
-
-If a server wishes to process multiple connections (as is normally
-the case) then the accept BIO must be made available for further
-incoming connections. This can be done by waiting for a connection and
-then calling:
-
- connection = BIO_pop(accept);
-
-After this call B<connection> will contain a BIO for the recently
-established connection and B<accept> will now be a single BIO
-again which can be used to await further incoming connections.
-If no further connections will be accepted the B<accept> can
-be freed using BIO_free().
-
-If only a single connection will be processed it is possible to
-perform I/O using the accept BIO itself. This is often undesirable
-however because the accept BIO will still accept additional incoming
-connections. This can be resolved by using BIO_pop() (see above)
-and freeing up the accept BIO after the initial connection.
-
-If the underlying accept socket is non-blocking and BIO_do_accept() is
-called to await an incoming connection it is possible for
-BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
-then it is an indication that an accept attempt would block: the application
-should take appropriate action to wait until the underlying socket has
-accepted a connection and retry the call.
-
-BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(),
-BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
-BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
-
-=head1 RETURN VALUES
-
-BIO_do_accept(),
-BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
-BIO_set_accept_bios(), and BIO_set_bind_mode(), return 1 for success and 0 or
--1 for failure.
-
-BIO_get_accept_name() returns the accept name or NULL on error.
-
-BIO_get_accept_port() returns the port as a string or NULL on error.
-
-BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
-
-BIO_new_accept() returns a BIO or NULL on error.
-
-=head1 EXAMPLE
-
-This example accepts two connections on port 4444, sends messages
-down each and finally closes both down.
-
- BIO *abio, *cbio, *cbio2;
-
- /* First call to BIO_accept() sets up accept BIO */
- abio = BIO_new_accept("4444");
- if (BIO_do_accept(abio) <= 0) {
- fprintf(stderr, "Error setting up accept\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
- /* Wait for incoming connection */
- if (BIO_do_accept(abio) <= 0) {
- fprintf(stderr, "Error accepting connection\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
- fprintf(stderr, "Connection 1 established\n");
-
- /* Retrieve BIO for connection */
- cbio = BIO_pop(abio);
- BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
- fprintf(stderr, "Sent out data on connection 1\n");
-
- /* Wait for another connection */
- if (BIO_do_accept(abio) <= 0) {
- fprintf(stderr, "Error accepting connection\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
- fprintf(stderr, "Connection 2 established\n");
-
- /* Close accept BIO to refuse further connections */
- cbio2 = BIO_pop(abio);
- BIO_free(abio);
- BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
- fprintf(stderr, "Sent out data on connection 2\n");
-
- BIO_puts(cbio, "Connection 1: Second connection established\n");
-
- /* Close the two established connections */
- BIO_free(cbio);
- BIO_free(cbio2);
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
-BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
-BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
-BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD *BIO_s_bio(void);
-
- int BIO_make_bio_pair(BIO *b1, BIO *b2);
- int BIO_destroy_bio_pair(BIO *b);
- int BIO_shutdown_wr(BIO *b);
-
-
- int BIO_set_write_buf_size(BIO *b, long size);
- size_t BIO_get_write_buf_size(BIO *b, long size);
-
- int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
-
- int BIO_get_write_guarantee(BIO *b);
- size_t BIO_ctrl_get_write_guarantee(BIO *b);
- int BIO_get_read_request(BIO *b);
- size_t BIO_ctrl_get_read_request(BIO *b);
- int BIO_ctrl_reset_read_request(BIO *b);
-
-=head1 DESCRIPTION
-
-BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink
-BIOs where data written to either half of the pair is buffered and can be read from
-the other half. Both halves must usually by handled by the same application thread
-since no locking is done on the internal data structures.
-
-Since BIO chains typically end in a source/sink BIO it is possible to make this
-one half of a BIO pair and have all the data processed by the chain under application
-control.
-
-One typical use of BIO pairs is to place TLS/SSL I/O under application control, this
-can be used when the application wishes to use a non standard transport for
-TLS/SSL or the normal socket routines are inappropriate.
-
-Calls to BIO_read() will read data from the buffer or request a retry if no
-data is available.
-
-Calls to BIO_write() will place data in the buffer or request a retry if the
-buffer is full.
-
-The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
-determine the amount of pending data in the read or write buffer.
-
-BIO_reset() clears any data in the write buffer.
-
-BIO_make_bio_pair() joins two separate BIOs into a connected pair.
-
-BIO_destroy_pair() destroys the association between two connected BIOs. Freeing
-up any half of the pair will automatically destroy the association.
-
-BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
-writes on BIO B<b> are allowed (they will return an error). Reads on the other
-half of the pair will return any pending data or EOF when all pending data has
-been read.
-
-BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
-If the size is not initialized a default value is used. This is currently
-17K, sufficient for a maximum size TLS record.
-
-BIO_get_write_buf_size() returns the size of the write buffer.
-
-BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
-BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
-with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
-zero then the default size is used. BIO_new_bio_pair() does not check whether
-B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
-BIO_free() is not called.
-
-BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
-length of data that can be currently written to the BIO. Writes larger than this
-value will return a value from BIO_write() less than the amount requested or if the
-buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function
-whereas BIO_get_write_guarantee() is a macro.
-
-BIO_get_read_request() and BIO_ctrl_get_read_request() return the
-amount of data requested, or the buffer size if it is less, if the
-last read attempt at the other half of the BIO pair failed due to an
-empty buffer. This can be used to determine how much data should be
-written to the BIO so the next read will succeed: this is most useful
-in TLS/SSL applications where the amount of data read is usually
-meaningful rather than just a buffer size. After a successful read
-this call will return zero. It also will return zero once new data
-has been written satisfying the read request or part of it.
-Note that BIO_get_read_request() never returns an amount larger
-than that returned by BIO_get_write_guarantee().
-
-BIO_ctrl_reset_read_request() can also be used to reset the value returned by
-BIO_get_read_request() to zero.
-
-=head1 NOTES
-
-Both halves of a BIO pair should be freed. That is even if one half is implicit
-freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.
-
-When used in bidirectional applications (such as TLS/SSL) care should be taken to
-flush any data in the write buffer. This can be done by calling BIO_pending()
-on the other half of the pair and, if any data is pending, reading it and sending
-it to the underlying transport. This must be done before any normal processing
-(such as calling select() ) due to a request and BIO_should_read() being true.
-
-To see why this is important consider a case where a request is sent using
-BIO_write() and a response read with BIO_read(), this can occur during an
-TLS/SSL handshake for example. BIO_write() will succeed and place data in the write
-buffer. BIO_read() will initially fail and BIO_should_read() will be true. If
-the application then waits for data to be available on the underlying transport
-before flushing the write buffer it will never succeed because the request was
-never sent!
-
-BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
-shutdown.
-
-BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(),
-BIO_set_write_buf_size(), BIO_get_write_buf_size(),
-BIO_get_write_guarantee(), and BIO_get_read_request() are implemented
-as macros.
-
-=head1 RETURN VALUES
-
-BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
-B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
-locations for B<bio1> and B<bio2>. Check the error stack for more information.
-
-[XXXXX: More return values need to be added here]
-
-=head1 EXAMPLE
-
-The BIO pair can be used to have full control over the network access of an
-application. The application can call select() on the socket as required
-without having to go through the SSL-interface.
-
- BIO *internal_bio, *network_bio;
- ...
- BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
- SSL_set_bio(ssl, internal_bio, internal_bio);
- SSL_operations(); //e.g SSL_read and SSL_write
- ...
-
- application | TLS-engine
- | |
- +----------> SSL_operations()
- | /\ ||
- | || \/
- | BIO-pair (internal_bio)
- | BIO-pair (network_bio)
- | || /\
- | \/ ||
- +-----------< BIO_operations()
- | |
- | |
- socket
-
- ...
- SSL_free(ssl); /* implicitly frees internal_bio */
- BIO_free(network_bio);
- ...
-
-As the BIO pair will only buffer the data and never directly access the
-connection, it behaves non-blocking and will return as soon as the write
-buffer is full or the read buffer is drained. Then the application has to
-flush the write buffer and/or fill the read buffer.
-
-Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
-and must be transferred to the network. Use BIO_ctrl_get_read_request() to
-find out, how many bytes must be written into the buffer before the
-SSL_operation() can successfully be continued.
-
-=head1 WARNING
-
-As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
-condition, but there is still data in the write buffer. An application must
-not rely on the error value of SSL_operation() but must assure that the
-write buffer is always flushed first. Otherwise a deadlock may occur as
-the peer might be waiting for the data before being able to continue.
-
-=head1 SEE ALSO
-
-L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
-L<BIO_should_retry(3)>, L<BIO_read(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_set_conn_address, BIO_get_conn_address,
-BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
-BIO_get_conn_hostname,
-BIO_get_conn_port,
-BIO_set_nbio, BIO_do_connect - connect BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD * BIO_s_connect(void);
-
- BIO *BIO_new_connect(char *name);
-
- long BIO_set_conn_hostname(BIO *b, char *name);
- long BIO_set_conn_port(BIO *b, char *port);
- long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
- const char *BIO_get_conn_hostname(BIO *b);
- const char *BIO_get_conn_port(BIO *b);
- const BIO_ADDR *BIO_get_conn_address(BIO *b);
-
- long BIO_set_nbio(BIO *b, long n);
-
- int BIO_do_connect(BIO *b);
-
-=head1 DESCRIPTION
-
-BIO_s_connect() returns the connect BIO method. This is a wrapper
-round the platform's TCP/IP socket connection routines.
-
-Using connect BIOs, TCP/IP connections can be made and data
-transferred using only BIO routines. In this way any platform
-specific operations are hidden by the BIO abstraction.
-
-Read and write operations on a connect BIO will perform I/O
-on the underlying connection. If no connection is established
-and the port and hostname (see below) is set up properly then
-a connection is established first.
-
-Connect BIOs support BIO_puts() but not BIO_gets().
-
-If the close flag is set on a connect BIO then any active
-connection is shutdown and the socket closed when the BIO
-is freed.
-
-Calling BIO_reset() on a connect BIO will close any active
-connection and reset the BIO into a state where it can connect
-to the same host again.
-
-BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
-it also returns the socket . If B<c> is not NULL it should be of
-type (int *).
-
-BIO_set_conn_hostname() uses the string B<name> to set the hostname.
-The hostname can be an IP address; if the address is an IPv6 one, it
-must be enclosed with brackets. The hostname can also include the
-port in the form hostname:port.
-
-BIO_set_conn_port() sets the port to B<port>. B<port> can be the
-numerical form or a string such as "http". A string will be looked
-up first using getservbyname() on the host platform but if that
-fails a standard table of port names will be used. This internal
-list is http, telnet, socks, https, ssl, ftp, and gopher.
-
-BIO_set_conn_address() sets the address and port information using
-a BIO_ADDR(3ssl).
-
-BIO_get_conn_hostname() returns the hostname of the connect BIO or
-NULL if the BIO is initialized but no hostname is set.
-This return value is an internal pointer which should not be modified.
-
-BIO_get_conn_port() returns the port as a string.
-This return value is an internal pointer which should not be modified.
-
-BIO_get_conn_address() returns the address information as a BIO_ADDR.
-This return value is an internal pointer which should not be modified.
-
-BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
-zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
-is set. Blocking I/O is the default. The call to BIO_set_nbio()
-should be made before the connection is established because
-non blocking I/O is set during the connect process.
-
-BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
-a single call: that is it creates a new connect BIO with B<name>.
-
-BIO_do_connect() attempts to connect the supplied BIO. It returns 1
-if the connection was established successfully. A zero or negative
-value is returned if the connection could not be established, the
-call BIO_should_retry() should be used for non blocking connect BIOs
-to determine if the call should be retried.
-
-=head1 NOTES
-
-If blocking I/O is set then a non positive return value from any
-I/O call is caused by an error condition, although a zero return
-will normally mean that the connection was closed.
-
-If the port name is supplied as part of the host name then this will
-override any value set with BIO_set_conn_port(). This may be undesirable
-if the application does not wish to allow connection to arbitrary
-ports. This can be avoided by checking for the presence of the ':'
-character in the passed hostname and either indicating an error or
-truncating the string at that point.
-
-The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
-BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
-connection attempt is made. Before any connection attempt the values
-returned are those set by the application itself.
-
-Applications do not have to call BIO_do_connect() but may wish to do
-so to separate the connection process from other I/O processing.
-
-If non blocking I/O is set then retries will be requested as appropriate.
-
-It addition to BIO_should_read() and BIO_should_write() it is also
-possible for BIO_should_io_special() to be true during the initial
-connection process with the reason BIO_RR_CONNECT. If this is returned
-then this is an indication that a connection attempt would block,
-the application should then take appropriate action to wait until
-the underlying socket has connected and retry the call.
-
-BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(),
-BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(),
-BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and
-BIO_do_connect() are macros.
-
-=head1 RETURN VALUES
-
-BIO_s_connect() returns the connect BIO method.
-
-BIO_get_fd() returns the socket or -1 if the BIO has not
-been initialized.
-
-BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
-BIO_set_conn_int_port() always return 1.
-
-BIO_get_conn_hostname() returns the connected hostname or NULL is
-none was set.
-
-BIO_get_conn_port() returns a string representing the connected
-port or NULL if not set.
-
-BIO_get_conn_ip() returns a pointer to the connected IP address in
-binary form or all zeros if not set.
-
-BIO_get_conn_int_port() returns the connected port or 0 if none was
-set.
-
-BIO_set_nbio() always returns 1.
-
-BIO_do_connect() returns 1 if the connection was successfully
-established and 0 or -1 if the connection failed.
-
-=head1 EXAMPLE
-
-This is example connects to a webserver on the local host and attempts
-to retrieve a page and copy the result to standard output.
-
-
- BIO *cbio, *out;
- int len;
- char tmpbuf[1024];
-
- cbio = BIO_new_connect("localhost:http");
- out = BIO_new_fp(stdout, BIO_NOCLOSE);
- if (BIO_do_connect(cbio) <= 0) {
- fprintf(stderr, "Error connecting to server\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
- BIO_puts(cbio, "GET / HTTP/1.0\n\n");
- for ( ; ; ) {
- len = BIO_read(cbio, tmpbuf, 1024);
- if (len <= 0)
- break;
- BIO_write(out, tmpbuf, len);
- }
- BIO_free(cbio);
- BIO_free(out);
-
-
-=head1 SEE ALSO
-
-L<BIO_ADDR(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD *BIO_s_fd(void);
-
- int BIO_set_fd(BIO *b, int fd, int c);
- int BIO_get_fd(BIO *b, int *c);
-
- BIO *BIO_new_fd(int fd, int close_flag);
-
-=head1 DESCRIPTION
-
-BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
-round the platforms file descriptor routines such as read() and write().
-
-BIO_read() and BIO_write() read or write the underlying descriptor.
-BIO_puts() is supported but BIO_gets() is not.
-
-If the close flag is set then close() is called on the underlying
-file descriptor when the BIO is freed.
-
-BIO_reset() attempts to change the file pointer to the start of file
-such as by using B<lseek(fd, 0, 0)>.
-
-BIO_seek() sets the file pointer to position B<ofs> from start of file
-such as by using B<lseek(fd, ofs, 0)>.
-
-BIO_tell() returns the current file position such as by calling
-B<lseek(fd, 0, 1)>.
-
-BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
-flag to B<c>.
-
-BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
-returns the file descriptor.
-
-BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
-
-=head1 NOTES
-
-The behaviour of BIO_read() and BIO_write() depends on the behavior of the
-platforms read() and write() calls on the descriptor. If the underlying
-file descriptor is in a non blocking mode then the BIO will behave in the
-manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)>
-manual pages.
-
-File descriptor BIOs should not be used for socket I/O. Use socket BIOs
-instead.
-
-BIO_set_fd() and BIO_get_fd() are implemented as macros.
-
-=head1 RETURN VALUES
-
-BIO_s_fd() returns the file descriptor BIO method.
-
-BIO_set_fd() always returns 1.
-
-BIO_get_fd() returns the file descriptor or -1 if the BIO has not
-been initialized.
-
-BIO_new_fd() returns the newly allocated BIO or NULL is an error
-occurred.
-
-=head1 EXAMPLE
-
-This is a file descriptor BIO version of "Hello World":
-
- BIO *out;
-
- out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
- BIO_printf(out, "Hello World\n");
- BIO_free(out);
-
-=head1 SEE ALSO
-
-L<BIO_seek(3)>, L<BIO_tell(3)>,
-L<BIO_reset(3)>, L<BIO_read(3)>,
-L<BIO_write(3)>, L<BIO_puts(3)>,
-L<BIO_gets(3)>, L<BIO_printf(3)>,
-L<BIO_set_close(3)>, L<BIO_get_close(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
-BIO_read_filename, BIO_write_filename, BIO_append_filename,
-BIO_rw_filename - FILE bio
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD * BIO_s_file(void);
- BIO *BIO_new_file(const char *filename, const char *mode);
- BIO *BIO_new_fp(FILE *stream, int flags);
-
- BIO_set_fp(BIO *b, FILE *fp, int flags);
- BIO_get_fp(BIO *b, FILE **fpp);
-
- int BIO_read_filename(BIO *b, char *name)
- int BIO_write_filename(BIO *b, char *name)
- int BIO_append_filename(BIO *b, char *name)
- int BIO_rw_filename(BIO *b, char *name)
-
-=head1 DESCRIPTION
-
-BIO_s_file() returns the BIO file method. As its name implies it
-is a wrapper round the stdio FILE structure and it is a
-source/sink BIO.
-
-Calls to BIO_read() and BIO_write() read and write data to the
-underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
-
-BIO_flush() on a file BIO calls the fflush() function on the wrapped
-stream.
-
-BIO_reset() attempts to change the file pointer to the start of file
-using fseek(stream, 0, 0).
-
-BIO_seek() sets the file pointer to position B<ofs> from start of file
-using fseek(stream, ofs, 0).
-
-BIO_eof() calls feof().
-
-Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
-is freed.
-
-BIO_new_file() creates a new file BIO with mode B<mode> the meaning
-of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
-flag is set on the returned BIO.
-
-BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
-BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
-stream to text mode, default is binary: this only has any effect under
-Win32).
-
-BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same
-meaning as in BIO_new_fp(), it is a macro.
-
-BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
-
-BIO_seek() is a macro that sets the position pointer to B<offset> bytes
-from the start of file.
-
-BIO_tell() returns the value of the position pointer.
-
-BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
-BIO_rw_filename() set the file BIO B<b> to use file B<name> for
-reading, writing, append or read write respectively.
-
-=head1 NOTES
-
-When wrapping stdout, stdin or stderr the underlying stream should not
-normally be closed so the BIO_NOCLOSE flag should be set.
-
-Because the file BIO calls the underlying stdio functions any quirks
-in stdio behaviour will be mirrored by the corresponding BIO.
-
-On Windows BIO_new_files reserves for the filename argument to be
-UTF-8 encoded. In other words if you have to make it work in multi-
-lingual environment, encode file names in UTF-8.
-
-=head1 EXAMPLES
-
-File BIO "hello world":
-
- BIO *bio_out;
- bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
- BIO_printf(bio_out, "Hello World\n");
-
-Alternative technique:
-
- BIO *bio_out;
- bio_out = BIO_new(BIO_s_file());
- if (bio_out == NULL) /* Error ... */
- if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
- BIO_printf(bio_out, "Hello World\n");
-
-Write to a file:
-
- BIO *out;
- out = BIO_new_file("filename.txt", "w");
- if (!out) /* Error occurred */
- BIO_printf(out, "Hello World\n");
- BIO_free(out);
-
-Alternative technique:
-
- BIO *out;
- out = BIO_new(BIO_s_file());
- if (out == NULL) /* Error ... */
- if (!BIO_write_filename(out, "filename.txt")) /* Error ... */
- BIO_printf(out, "Hello World\n");
- BIO_free(out);
-
-=head1 RETURN VALUES
-
-BIO_s_file() returns the file BIO method.
-
-BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
-occurred.
-
-BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
-(although the current implementation never return 0).
-
-BIO_seek() returns the same value as the underlying fseek() function:
-0 for success or -1 for failure.
-
-BIO_tell() returns the current file position.
-
-BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
-BIO_rw_filename() return 1 for success or 0 for failure.
-
-=head1 BUGS
-
-BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
-stream. The return value for fseek() is 0 for success or -1 if an error
-occurred this differs from other types of BIO which will typically return
-1 for success and a non positive value if an error occurred.
-
-=head1 SEE ALSO
-
-L<BIO_seek(3)>, L<BIO_tell(3)>,
-L<BIO_reset(3)>, L<BIO_flush(3)>,
-L<BIO_read(3)>,
-L<BIO_write(3)>, L<BIO_puts(3)>,
-L<BIO_gets(3)>, L<BIO_printf(3)>,
-L<BIO_set_close(3)>, L<BIO_get_close(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_s_secmem,
-BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
-BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD * BIO_s_mem(void);
- const BIO_METHOD * BIO_s_secmem(void);
-
- BIO_set_mem_eof_return(BIO *b, int v)
- long BIO_get_mem_data(BIO *b, char **pp)
- BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c)
- BIO_get_mem_ptr(BIO *b, BUF_MEM **pp)
-
- BIO *BIO_new_mem_buf(const void *buf, int len);
-
-=head1 DESCRIPTION
-
-BIO_s_mem() return the memory BIO method function.
-
-A memory BIO is a source/sink BIO which uses memory for its I/O. Data
-written to a memory BIO is stored in a BUF_MEM structure which is extended
-as appropriate to accommodate the stored data.
-
-BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used
-for buffer storage.
-
-Any data written to a memory BIO can be recalled by reading from it.
-Unless the memory BIO is read only any data read from it is deleted from
-the BIO.
-
-Memory BIOs support BIO_gets() and BIO_puts().
-
-If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
-BUF_MEM structure is also freed.
-
-Calling BIO_reset() on a read write memory BIO clears any data in it if the
-flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag
-BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and
-the data can be read again.
-
-BIO_eof() is true if no data is in the BIO.
-
-BIO_ctrl_pending() returns the number of bytes currently stored.
-
-BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
-empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
-it will return zero and BIO_should_retry(b) will be false. If B<v> is non
-zero then it will return B<v> when it is empty and it will set the read retry
-flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
-positive return value B<v> should be set to a negative value, typically -1.
-
-BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data
-and returns the total amount of data available. It is implemented as a macro.
-
-BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
-close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
-It is a macro.
-
-BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is
-a macro.
-
-BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
-if B<len> is -1 then the B<buf> is assumed to be nul terminated and its
-length is determined by B<strlen>. The BIO is set to a read only state and
-as a result cannot be written to. This is useful when some data needs to be
-made available from a static area of memory in the form of a BIO. The
-supplied data is read directly from the supplied buffer: it is B<not> copied
-first, so the supplied area of memory must be unchanged until the BIO is freed.
-
-=head1 NOTES
-
-Writes to memory BIOs will always succeed if memory is available: that is
-their size can grow indefinitely.
-
-Every read from a read write memory BIO will remove the data just read with
-an internal copy operation, if a BIO contains a lot of data and it is
-read in small chunks the operation can be very slow. The use of a read only
-memory BIO avoids this problem. If the BIO must be read write then adding
-a buffering BIO to the chain will speed up the process.
-
-Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
-give undefined results, including perhaps a program crash.
-
-=head1 BUGS
-
-There should be an option to set the maximum size of a memory BIO.
-
-=head1 EXAMPLE
-
-Create a memory BIO and write some data to it:
-
- BIO *mem = BIO_new(BIO_s_mem());
- BIO_puts(mem, "Hello World\n");
-
-Create a read only memory BIO:
-
- char data[] = "Hello World";
- BIO *mem;
- mem = BIO_new_mem_buf(data, -1);
-
-Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
-
- BUF_MEM *bptr;
- BIO_get_mem_ptr(mem, &bptr);
- BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
- BIO_free(mem);
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_s_null - null data sink
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD * BIO_s_null(void);
-
-=head1 DESCRIPTION
-
-BIO_s_null() returns the null sink BIO method. Data written to
-the null sink is discarded, reads return EOF.
-
-=head1 NOTES
-
-A null sink BIO behaves in a similar manner to the Unix /dev/null
-device.
-
-A null bio can be placed on the end of a chain to discard any data
-passed through it.
-
-A null sink is useful if, for example, an application wishes to digest some
-data by writing through a digest bio but not send the digested data anywhere.
-Since a BIO chain must normally include a source/sink BIO this can be achieved
-by adding a null sink BIO to the end of the chain
-
-=head1 RETURN VALUES
-
-BIO_s_null() returns the null sink BIO method.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_s_socket, BIO_new_socket - socket BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- const BIO_METHOD *BIO_s_socket(void);
-
- BIO *BIO_new_socket(int sock, int close_flag);
-
-=head1 DESCRIPTION
-
-BIO_s_socket() returns the socket BIO method. This is a wrapper
-round the platform's socket routines.
-
-BIO_read() and BIO_write() read or write the underlying socket.
-BIO_puts() is supported but BIO_gets() is not.
-
-If the close flag is set then the socket is shut down and closed
-when the BIO is freed.
-
-BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
-
-=head1 NOTES
-
-Socket BIOs also support any relevant functionality of file descriptor
-BIOs.
-
-The reason for having separate file descriptor and socket BIOs is that on some
-platforms sockets are not file descriptors and use distinct I/O routines,
-Windows is one such platform. Any code mixing the two will not work on
-all platforms.
-
-=head1 RETURN VALUES
-
-BIO_s_socket() returns the socket BIO method.
-
-BIO_new_socket() returns the newly allocated BIO or NULL is an error
-occurred.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
-BIO_debug_callback - BIO callback functions
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
-
- typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
- long argl, long ret);
-
- void BIO_set_callback(BIO *b, BIO_callack_fn cb);
- BIO_callack_fn BIO_get_callback(BIO *b);
- void BIO_set_callback_arg(BIO *b, char *arg);
- char *BIO_get_callback_arg(const BIO *b);
-
- long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
- long argl, long ret);
-
-=head1 DESCRIPTION
-
-BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
-they are both macros. The callback is called during most high level BIO
-operations. It can be used for debugging purposes to trace operations on
-a BIO or to modify its operation.
-
-BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
-used to set and retrieve an argument for use in the callback.
-
-BIO_debug_callback() is a standard debugging callback which prints
-out information relating to each BIO operation. If the callback
-argument is set it is interpreted as a BIO to send the information
-to, otherwise stderr is used.
-
-BIO_callback_fn() is the type of the callback function. The meaning of each
-argument is described below:
-
-=over
-
-=item B<b>
-
-The BIO the callback is attached to is passed in B<b>.
-
-=item B<oper>
-
-B<oper> is set to the operation being performed. For some operations
-the callback is called twice, once before and once after the actual
-operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
-
-=item B<argp> B<argi> B<argl>
-
-The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
-the value of B<oper>, that is the operation being performed.
-
-=item B<ret>
-
-B<ret> is the return value that would be returned to the
-application if no callback were present. The actual value returned
-is the return value of the callback itself. In the case of callbacks
-called before the actual BIO operation 1 is placed in B<ret>, if
-the return value is not positive it will be immediately returned to
-the application and the BIO operation will not be performed.
-
-=back
-
-The callback should normally simply return B<ret> when it has
-finished processing, unless it specifically wishes to modify the
-value returned to the application.
-
-=head1 CALLBACK OPERATIONS
-
-In the notes below, B<callback> defers to the actual callback
-function that is called.
-
-=over 4
-
-=item B<BIO_free(b)>
-
-callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
-free operation.
-
-=item B<BIO_read(b, out, outl)>
-
-callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
-the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
-after.
-
-=item B<BIO_write(b, in, inl)>
-
-callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
-the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
-after.
-
-=item B<BIO_gets(b, out, outl)>
-
-callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
-the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
-after.
-
-=item B<BIO_puts(b, in)>
-
-callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
-the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
-after.
-
-=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
-
-callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L) is called before the call and
-callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) after.
-
-=back
-
-=head1 EXAMPLE
-
-The BIO_debug_callback() function is a good example, its source is
-in crypto/bio/bio_cb.c
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BIO_should_read, BIO_should_write,
-BIO_should_io_special, BIO_retry_type, BIO_should_retry,
-BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
-functions
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- int BIO_should_read(BIO *b);
- int BIO_should_write(BIO *b);
- int BIO_should_io_special(iBIO *b);
- int BIO_retry_type(BIO *b);
- int BIO_should_retry(BIO *b);
-
- BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
- int BIO_get_retry_reason(BIO *bio);
- void BIO_set_retry_reason(BIO *bio, int reason);
-
-=head1 DESCRIPTION
-
-These functions determine why a BIO is not able to read or write data.
-They will typically be called after a failed BIO_read() or BIO_write()
-call.
-
-BIO_should_retry() is true if the call that produced this condition
-should then be retried at a later time.
-
-If BIO_should_retry() is false then the cause is an error condition.
-
-BIO_should_read() is true if the cause of the condition is that a BIO
-needs to read data.
-
-BIO_should_write() is true if the cause of the condition is that a BIO
-needs to read data.
-
-BIO_should_io_special() is true if some "special" condition, that is a
-reason other than reading or writing is the cause of the condition.
-
-BIO_retry_type() returns a mask of the cause of a retry condition
-consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
-B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
-these.
-
-BIO_get_retry_BIO() determines the precise reason for the special
-condition, it returns the BIO that caused this condition and if
-B<reason> is not NULL it contains the reason code. The meaning of
-the reason code and the action that should be taken depends on
-the type of BIO that resulted in this condition.
-
-BIO_get_retry_reason() returns the reason for a special condition if
-passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
-
-BIO_set_retry_reason() sets the retry reason for a special condition for a given
-BIO. This would usually only be called by BIO implementations.
-
-=head1 NOTES
-
-BIO_should_read(), BIO_should_write(), BIO_should_io_special(),
-BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
-
-If BIO_should_retry() returns false then the precise "error condition"
-depends on the BIO type that caused it and the return code of the BIO
-operation. For example if a call to BIO_read() on a socket BIO returns
-0 and BIO_should_retry() is false then the cause will be that the
-connection closed. A similar condition on a file BIO will mean that it
-has reached EOF. Some BIO types may place additional information on
-the error queue. For more details see the individual BIO type manual
-pages.
-
-If the underlying I/O structure is in a blocking mode almost all current
-BIO types will not request a retry, because the underlying I/O
-calls will not. If the application knows that the BIO type will never
-signal a retry then it need not call BIO_should_retry() after a failed
-BIO I/O call. This is typically done with file BIOs.
-
-SSL BIOs are the only current exception to this rule: they can request a
-retry even if the underlying I/O structure is blocking, if a handshake
-occurs during a call to BIO_read(). An application can retry the failed
-call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
-on the underlying SSL structure.
-
-While an application may retry a failed non blocking call immediately
-this is likely to be very inefficient because the call will fail
-repeatedly until data can be processed or is available. An application
-will normally wait until the necessary condition is satisfied. How
-this is done depends on the underlying I/O structure.
-
-For example if the cause is ultimately a socket and BIO_should_read()
-is true then a call to select() may be made to wait until data is
-available and then retry the BIO operation. By combining the retry
-conditions of several non blocking BIOs in a single select() call
-it is possible to service several BIOs in a single thread, though
-the performance may be poor if SSL BIOs are present because long delays
-can occur during the initial handshake process.
-
-It is possible for a BIO to block indefinitely if the underlying I/O
-structure cannot process or return any data. This depends on the behaviour of
-the platforms I/O functions. This is often not desirable: one solution
-is to use non blocking I/O and use a timeout on the select() (or
-equivalent) call.
-
-=head1 BUGS
-
-The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
-that is they cannot retry after a partial read or write. This is usually
-worked around by only passing the relevant data to ASN1 functions when
-the entire structure can be read or written.
-
-=head1 SEE ALSO
-
-L<bio>
-
-=head1 HISTORY
-
-The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
-OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
-BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
-BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread,
-BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags,
-BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
- BIGNUM *mod);
- void BN_BLINDING_free(BN_BLINDING *b);
- int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
- int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
- int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
- int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
- BN_CTX *ctx);
- int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
- BN_CTX *ctx);
- int BN_BLINDING_is_current_thread(BN_BLINDING *b);
- void BN_BLINDING_set_current_thread(BN_BLINDING *b);
- int BN_BLINDING_lock(BN_BLINDING *b);
- int BN_BLINDING_unlock(BN_BLINDING *b);
- unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
- void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
- BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
- const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
- int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
- const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
- BN_MONT_CTX *m_ctx);
-
-=head1 DESCRIPTION
-
-BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
-the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
-
-BN_BLINDING_free() frees the B<BN_BLINDING> structure.
-If B<b> is NULL, nothing is done.
-
-BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
-the B<A> and B<Ai> or, after specific number of uses and if the
-necessary parameters are set, by re-creating the blinding parameters.
-
-BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
-If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
-returned in B<r> (this is useful if a B<RSA> object is shared among
-several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
-inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
-the inverse blinding.
-
-BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
-functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
-with B<r> set to NULL.
-
-BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING>
-structure is owned by the current thread. This is to help users
-provide proper locking if needed for multi-threaded use.
-
-BN_BLINDING_set_current_thread() sets the current thread as the
-owner of the B<BN_BLINDING> structure.
-
-BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
-
-BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
-
-BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
-there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
-B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
-automatic update of the B<BN_BLINDING> parameters after each use
-and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
-of the B<BN_BLINDING> parameters after a fixed number of uses (currently
-32). In newly allocated B<BN_BLINDING> objects no flags are set.
-BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
-
-BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
-using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
-B<m_ctx> can be used to pass special functions for exponentiation
-(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
-
-=head1 RETURN VALUES
-
-BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
-or NULL in case of an error.
-
-BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
-BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
-success and 0 if an error occurred.
-
-BN_BLINDING_is_current_thread() returns 1 if the current thread owns
-the B<BN_BLINDING> object, 0 otherwise.
-
-BN_BLINDING_set_current_thread() doesn't return anything.
-
-BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
-succeeded or 0 on error.
-
-BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
-(a B<unsigned long> value).
-
-BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
-parameters or NULL on error.
-
-=head1 SEE ALSO
-
-L<bn(3)>
-
-=head1 HISTORY
-
-BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it
-deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().
-
-=head1 COPYRIGHT
-
-Copyright 2005-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- BN_CTX *BN_CTX_new(void);
-
- BN_CTX *BN_CTX_secure_new(void);
-
- void BN_CTX_free(BN_CTX *c);
-
-=head1 DESCRIPTION
-
-A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
-library functions. Since dynamic memory allocation to create B<BIGNUM>s
-is rather expensive when used in conjunction with repeated subroutine
-calls, the B<BN_CTX> structure is used.
-
-BN_CTX_new() allocates and initializes a B<BN_CTX> structure.
-BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure
-but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the
-B<BIGNUM>s.
-
-BN_CTX_free() frees the components of the B<BN_CTX>, and if it was
-created by BN_CTX_new(), also the structure itself.
-If L<BN_CTX_start(3)> has been used on the B<BN_CTX>,
-L<BN_CTX_end(3)> must be called before the B<BN_CTX>
-may be freed by BN_CTX_free().
-If B<c> is NULL, nothing is done.
-
-=head1 RETURN VALUES
-
-BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>.
-If the allocation fails,
-they return B<NULL> and sets an error code that can be obtained by
-L<ERR_get_error(3)>.
-
-BN_CTX_free() has no return values.
-
-=head1 REMOVED FUNCTIONALITY
-
- void BN_CTX_init(BN_CTX *c);
-
-BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should
-replace use of BN_CTX_init with BN_CTX_new instead:
-
- BN_CTX *ctx;
- ctx = BN_CTX_new();
- if(!ctx) /* Handle error */
- ...
- BN_CTX_free(ctx);
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
-L<BN_CTX_start(3)>
-
-=head1 HISTORY
-
-BN_CTX_init() was removed in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- void BN_CTX_start(BN_CTX *ctx);
-
- BIGNUM *BN_CTX_get(BN_CTX *ctx);
-
- void BN_CTX_end(BN_CTX *ctx);
-
-=head1 DESCRIPTION
-
-These functions are used to obtain temporary B<BIGNUM> variables from
-a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)>)
-in order to save the overhead of repeatedly creating and
-freeing B<BIGNUM>s in functions that are called from inside a loop.
-
-A function must call BN_CTX_start() first. Then, BN_CTX_get() may be
-called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get()
-calls must be made before calling any other functions that use the
-B<ctx> as an argument.
-
-Finally, BN_CTX_end() must be called before returning from the function.
-When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from
-BN_CTX_get() become invalid.
-
-=head1 RETURN VALUES
-
-BN_CTX_start() and BN_CTX_end() return no values.
-
-BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error.
-Once BN_CTX_get() has failed, the subsequent calls will return B<NULL>
-as well, so it is sufficient to check the return value of the last
-BN_CTX_get() call. In case of an error, an error code is set, which
-can be obtained by L<ERR_get_error(3)>.
-
-
-=head1 SEE ALSO
-
-L<BN_CTX_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
-BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd -
-arithmetic operations on BIGNUMs
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
-
- int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
-
- int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
-
- int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
-
- int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
- BN_CTX *ctx);
-
- int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
-
- int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
-
- int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
- BN_CTX *ctx);
-
- int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
- BN_CTX *ctx);
-
- int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
- BN_CTX *ctx);
-
- int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
-
- int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
-
- int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
- const BIGNUM *m, BN_CTX *ctx);
-
- int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
-
-=head1 DESCRIPTION
-
-BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
-I<r> may be the same B<BIGNUM> as I<a> or I<b>.
-
-BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
-I<r> may be the same B<BIGNUM> as I<a> or I<b>.
-
-BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
-I<r> may be the same B<BIGNUM> as I<a> or I<b>.
-For multiplication by powers of 2, use L<BN_lshift(3)>.
-
-BN_sqr() takes the square of I<a> and places the result in I<r>
-(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
-This function is faster than BN_mul(r,a,a).
-
-BN_div() divides I<a> by I<d> and places the result in I<dv> and the
-remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may
-be B<NULL>, in which case the respective value is not returned.
-The result is rounded towards zero; thus if I<a> is negative, the
-remainder will be zero or negative.
-For division by powers of 2, use BN_rshift(3).
-
-BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>.
-
-BN_nnmod() reduces I<a> modulo I<m> and places the non-negative
-remainder in I<r>.
-
-BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative
-result in I<r>.
-
-BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the
-non-negative result in I<r>.
-
-BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
-remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
-the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
-repeated computations using the same modulus, see
-L<BN_mod_mul_montgomery(3)> and
-L<BN_mod_mul_reciprocal(3)>.
-
-BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
-result in I<r>.
-
-BN_exp() raises I<a> to the I<p>-th power and places the result in I<r>
-(C<r=a^p>). This function is faster than repeated applications of
-BN_mul().
-
-BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p %
-m>). This function uses less time and space than BN_exp().
-
-BN_gcd() computes the greatest common divisor of I<a> and I<b> and
-places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
-I<b>.
-
-For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
-temporary variables; see L<BN_CTX_new(3)>.
-
-Unless noted otherwise, the result B<BIGNUM> must be different from
-the arguments.
-
-=head1 RETURN VALUES
-
-For all functions, 1 is returned for success, 0 on error. The return
-value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<BN_CTX_new(3)>,
-L<BN_add_word(3)>, L<BN_set_bit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic
-functions on BIGNUMs with integers
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_add_word(BIGNUM *a, BN_ULONG w);
-
- int BN_sub_word(BIGNUM *a, BN_ULONG w);
-
- int BN_mul_word(BIGNUM *a, BN_ULONG w);
-
- BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
-
- BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
-
-=head1 DESCRIPTION
-
-These functions perform arithmetic operations on BIGNUMs with unsigned
-integers. They are much more efficient than the normal BIGNUM
-arithmetic operations.
-
-BN_add_word() adds B<w> to B<a> (C<a+=w>).
-
-BN_sub_word() subtracts B<w> from B<a> (C<a-=w>).
-
-BN_mul_word() multiplies B<a> and B<w> (C<a*=w>).
-
-BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder.
-
-BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%w>).
-
-For BN_div_word() and BN_mod_word(), B<w> must not be 0.
-
-=head1 RETURN VALUES
-
-BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0
-on error. The error codes can be obtained by L<ERR_get_error(3)>.
-
-BN_mod_word() and BN_div_word() return B<a>%B<w> on success and
-B<(BN_ULONG)-1> if an error occurred.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_bn2binpad,
-BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec,
-BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi,
-BN_mpi2bn - format conversions
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_bn2bin(const BIGNUM *a, unsigned char *to);
- int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);
- BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
-
- int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
- BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
-
- char *BN_bn2hex(const BIGNUM *a);
- char *BN_bn2dec(const BIGNUM *a);
- int BN_hex2bn(BIGNUM **a, const char *str);
- int BN_dec2bn(BIGNUM **a, const char *str);
-
- int BN_print(BIO *fp, const BIGNUM *a);
- int BN_print_fp(FILE *fp, const BIGNUM *a);
-
- int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
- BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
-
-=head1 DESCRIPTION
-
-BN_bn2bin() converts the absolute value of B<a> into big-endian form
-and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
-memory.
-
-BN_bn2binpad() also converts the absolute value of B<a> into big-endian form
-and stores it at B<to>. B<tolen> indicates the length of the output buffer
-B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than
-BN_num_bytes(B<a>) an error is returned.
-
-BN_bin2bn() converts the positive integer in big-endian form of length
-B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
-NULL, a new B<BIGNUM> is created.
-
-BN_bn2lebinpad() and BN_bin2lbn() are identical to BN_bn2binpad() and
-BN_bin2bn() except the buffer is in little-endian format.
-
-BN_bn2hex() and BN_bn2dec() return printable strings containing the
-hexadecimal and decimal encoding of B<a> respectively. For negative
-numbers, the string is prefaced with a leading '-'. The string must be
-freed later using OPENSSL_free().
-
-BN_hex2bn() takes as many characters as possible from the string B<str>,
-including the leading character '-' which means negative, to form a valid
-hexadecimal number representation and converts them to a B<BIGNUM> and
-stores it in **B<bn>. If *B<bn> is NULL, a new B<BIGNUM> is created. If
-B<bn> is NULL, it only computes the length of valid representation.
-A "negative zero" is converted to zero.
-BN_dec2bn() is the same using the decimal system.
-
-BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>,
-with a leading '-' for negative numbers, to the B<BIO> or B<FILE>
-B<fp>.
-
-BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format
-that consists of the number's length in bytes represented as a 4-byte
-big-endian number, and the number itself in big-endian format, where
-the most significant bit signals a negative number (the representation
-of numbers with the MSB set is prefixed with null byte).
-
-BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to>
-must be large enough to hold the result. The size can be determined by
-calling BN_bn2mpi(B<a>, NULL).
-
-BN_mpi2bn() converts the B<len> bytes long representation at B<s> to
-a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM>
-if B<ret> is NULL.
-
-=head1 RETURN VALUES
-
-BN_bn2bin() returns the length of the big-endian number placed at B<to>.
-BN_bin2bn() returns the B<BIGNUM>, NULL on error.
-
-BN_bn2binpad() returns the number of bytes written or -1 if the supplied
-buffer is too small.
-
-BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL
-on error. BN_hex2bn() and BN_dec2bn() return the the length of valid
-representation in hexadecimal or decimal digits, and 0 on error, in which
-case no new B<BIGNUM> will be created.
-
-BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
-
-BN_bn2mpi() returns the length of the representation. BN_mpi2bn()
-returns the B<BIGNUM>, and NULL on error.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<BN_zero(3)>,
-L<ASN1_INTEGER_to_BN(3)>,
-L<BN_num_bytes(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_cmp(BIGNUM *a, BIGNUM *b);
- int BN_ucmp(BIGNUM *a, BIGNUM *b);
-
- int BN_is_zero(BIGNUM *a);
- int BN_is_one(BIGNUM *a);
- int BN_is_word(BIGNUM *a, BN_ULONG w);
- int BN_is_odd(BIGNUM *a);
-
-=head1 DESCRIPTION
-
-BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their
-absolute values.
-
-BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1,
-or B<w> respectively. BN_is_odd() tests if a is odd.
-
-BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros.
-
-=head1 RETURN VALUES
-
-BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if
-B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values
-of B<a> and B<b>.
-
-BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if
-the condition is true, 0 otherwise.
-
-=head1 SEE ALSO
-
-L<bn(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_copy, BN_dup, BN_with_flags - copy BIGNUMs
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);
-
- BIGNUM *BN_dup(const BIGNUM *from);
-
- void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);
-
-=head1 DESCRIPTION
-
-BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM>
-containing the value B<from>.
-
-BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places
-significant restrictions on the copied data. Applications that do no adhere to
-these restrictions may encounter unexpected side effects or crashes. For that
-reason use of this function is discouraged. Any flags provided in B<flags> will
-be set in B<dest> in addition to any flags already set in B<b>. For example this
-might commonly be used to create a temporary copy of a BIGNUM with the
-B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in
-B<dest> will share some internal state with B<b>. For this reason the following
-restrictions apply to the use of B<dest>:
-
-=over 4
-
-=item *
-
-B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It
-should not have been used for other purposes or initialised in any way.
-
-=item *
-
-B<dest> must only be used in "read-only" operations, i.e. typically those
-functions where the relevant parameter is declared "const".
-
-=item *
-
-B<dest> must be used and freed before any further subsequent use of B<b>
-
-=back
-
-=head1 RETURN VALUES
-
-BN_copy() returns B<to> on success, NULL on error. BN_dup() returns
-the new B<BIGNUM>, and NULL on error. The error codes can be obtained
-by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
-BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg,
-BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test
-for primality
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
- const BIGNUM *rem, BN_GENCB *cb);
-
- int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
-
- int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
- int do_trial_division, BN_GENCB *cb);
-
- int BN_GENCB_call(BN_GENCB *cb, int a, int b);
-
- BN_GENCB *BN_GENCB_new(void);
-
- void BN_GENCB_free(BN_GENCB *cb);
-
- void BN_GENCB_set_old(BN_GENCB *gencb,
- void (*callback)(int, int, void *), void *cb_arg);
-
- void BN_GENCB_set(BN_GENCB *gencb,
- int (*callback)(int, int, BN_GENCB *), void *cb_arg);
-
- void *BN_GENCB_get_arg(BN_GENCB *cb);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x00908000L
- BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
- BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
-
- int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,
- void *), BN_CTX *ctx, void *cb_arg);
-
- int BN_is_prime_fasttest(const BIGNUM *a, int checks,
- void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
- int do_trial_division);
- #endif
-
-=head1 DESCRIPTION
-
-BN_generate_prime_ex() generates a pseudo-random prime number of
-at least bit length B<bits>.
-If B<ret> is not B<NULL>, it will be used to store the number.
-
-If B<cb> is not B<NULL>, it is used as follows:
-
-=over 4
-
-=item *
-
-B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th
-potential prime number.
-
-=item *
-
-While the number is being tested for primality,
-B<BN_GENCB_call(cb, 1, j)> is called as described below.
-
-=item *
-
-When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called.
-
-=back
-
-The prime may have to fulfill additional requirements for use in
-Diffie-Hellman key exchange:
-
-If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add>
-== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given
-generator.
-
-If B<safe> is true, it will be a safe prime (i.e. a prime p so
-that (p-1)/2 is also prime).
-
-The PRNG must be seeded prior to calling BN_generate_prime_ex().
-The prime number generation has a negligible error probability.
-
-BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
-prime. The following tests are performed until one of them shows that
-B<p> is composite; if B<p> passes all these tests, it is considered
-prime.
-
-BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>,
-first attempts trial division by a number of small primes;
-if no divisors are found by this test and B<cb> is not B<NULL>,
-B<BN_GENCB_call(cb, 1, -1)> is called.
-If B<do_trial_division == 0>, this test is skipped.
-
-Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin
-probabilistic primality test with B<nchecks> iterations. If
-B<nchecks == BN_prime_checks>, a number of iterations is used that
-yields a false positive rate of at most 2^-80 for random input.
-
-If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called
-after the j-th iteration (j = 0, 1, ...). B<ctx> is a
-pre-allocated B<BN_CTX> (to save the overhead of allocating and
-freeing the structure in a loop), or B<NULL>.
-
-BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure
-and passes the ints B<a> and B<b> as arguments. There are two types of
-B<BN_GENCB> structure that are supported: "new" style and "old" style. New
-programs should prefer the "new" style, whilst the "old" style is provided
-for backwards compatibility purposes.
-
-A BN_GENCB structure should be created through a call to BN_GENCB_new(),
-and freed through a call to BN_GENCB_free().
-
-For "new" style callbacks a BN_GENCB structure should be initialised with a
-call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of
-type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>.
-"Old" style callbacks are the same except they are initialised with a call
-to BN_GENCB_set_old() and B<callback> is of type
-B<void (*callback)(int, int, void *)>.
-
-A callback is invoked through a call to B<BN_GENCB_call>. This will check
-the type of the callback and will invoke B<callback(a, b, gencb)> for new
-style callbacks or B<callback(a, b, cb_arg)> for old style.
-
-It is possible to obtained the argument associated with a BN_GENCB structure
-(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
-
-BN_generate_prime (deprecated) works in the same way as
-BN_generate_prime_ex but expects an old style callback function
-directly in the B<callback> parameter, and an argument to pass to it in
-the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are
-deprecated and can be compared to BN_is_prime_ex and
-BN_is_prime_fasttest_ex respectively.
-
-=head1 RETURN VALUES
-
-BN_generate_prime_ex() return 1 on success or 0 on error.
-
-BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and
-BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is
-prime with an error probability of less than 0.25^B<nchecks>, and
--1 on error.
-
-BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
-
-BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL>
-otherwise.
-
-BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB
-structure.
-
-Callback functions should return 1 on success or 0 on error.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 REMOVED FUNCTIONALITY
-
-As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure
-directly, as in:
-
- BN_GENCB callback;
-
-Instead applications should create a BN_GENCB structure using BN_GENCB_new:
-
- BN_GENCB *callback;
- callback = BN_GENCB_new();
- if(!callback) /* handle error */
- ...
- BN_GENCB_free(callback);
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>
-
-=head1 HISTORY
-
-BN_GENCB_new(), BN_GENCB_free(),
-and BN_GENCB_get_arg() were added in OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_mod_inverse - compute inverse modulo n
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
- BN_CTX *ctx);
-
-=head1 DESCRIPTION
-
-BN_mod_inverse() computes the inverse of B<a> modulo B<n>
-places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL,
-a new B<BIGNUM> is created.
-
-B<ctx> is a previously allocated B<BN_CTX> used for temporary
-variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>.
-
-=head1 RETURN VALUES
-
-BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and
-NULL on error. The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_mod_mul_montgomery, BN_MONT_CTX_new,
-BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
-BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- BN_MONT_CTX *BN_MONT_CTX_new(void);
- void BN_MONT_CTX_free(BN_MONT_CTX *mont);
-
- int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
- BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
-
- int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
- BN_MONT_CTX *mont, BN_CTX *ctx);
-
- int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
- BN_CTX *ctx);
-
- int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
- BN_CTX *ctx);
-
-=head1 DESCRIPTION
-
-These functions implement Montgomery multiplication. They are used
-automatically when L<BN_mod_exp(3)> is called with suitable input,
-but they may be useful when several operations are to be performed
-using the same modulus.
-
-BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure.
-
-BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m>
-by precomputing its inverse and a value R.
-
-BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>.
-
-BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if
-it was created by BN_MONT_CTX_new(), also the structure itself.
-If B<mont> is NULL, nothing is done.
-
-BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places
-the result in I<r>.
-
-BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1.
-
-BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R.
-Note that I<a> must be non-negative and smaller than the modulus.
-
-For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
-temporary variables.
-
-=head1 RETURN VALUES
-
-BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL
-on error.
-
-BN_MONT_CTX_free() has no return value.
-
-For the other functions, 1 is returned for success, 0 on error.
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 WARNING
-
-The inputs must be reduced modulo B<m>, otherwise the result will be
-outside the expected range.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
-L<BN_CTX_new(3)>
-
-=head1 HISTORY
-
-BN_MONT_CTX_init() was removed in OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new,
-BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
-reciprocal
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- BN_RECP_CTX *BN_RECP_CTX_new(void);
- void BN_RECP_CTX_free(BN_RECP_CTX *recp);
-
- int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
-
- int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp,
- BN_CTX *ctx);
-
- int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
- BN_RECP_CTX *recp, BN_CTX *ctx);
-
-=head1 DESCRIPTION
-
-BN_mod_mul_reciprocal() can be used to perform an efficient
-L<BN_mod_mul(3)> operation when the operation will be performed
-repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m>
-using B<recp>=1/B<m>, which is set as described below. B<ctx> is a
-previously allocated B<BN_CTX> used for temporary variables.
-
-BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure.
-
-BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it
-was created by BN_RECP_CTX_new(), also the structure itself.
-If B<recp> is NULL, nothing is done.
-
-BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing
-1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an
-integer. The result and the number of bits it was shifted left will
-later be stored in B<recp>.
-
-BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient
-in B<dv> and the remainder in B<rem>.
-
-The B<BN_RECP_CTX> structure cannot be shared between threads.
-
-=head1 RETURN VALUES
-
-BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL
-on error.
-
-BN_RECP_CTX_free() has no return value.
-
-For the other functions, 1 is returned for success, 0 on error.
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
-L<BN_CTX_new(3)>
-
-=head1 HISTORY
-
-BN_RECP_CTX_init() was removed in OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- BIGNUM *BN_new(void);
-
- BIGNUM *BN_secure_new(void);
-
- void BN_clear(BIGNUM *a);
-
- void BN_free(BIGNUM *a);
-
- void BN_clear_free(BIGNUM *a);
-
-=head1 DESCRIPTION
-
-BN_new() allocates and initializes a B<BIGNUM> structure.
-BN_secure_new() does the same except that the secure heap
-OPENSSL_secure_malloc(3) is used to store the value.
-
-BN_clear() is used to destroy sensitive data such as keys when they
-are no longer needed. It erases the memory used by B<a> and sets it
-to the value 0.
-
-BN_free() frees the components of the B<BIGNUM>, and if it was created
-by BN_new(), also the structure itself. BN_clear_free() additionally
-overwrites the data before the memory is returned to the system.
-If B<a> is NULL, nothing is done.
-
-=head1 RETURN VALUES
-
-BN_new() and BN_secure_new()
-return a pointer to the B<BIGNUM>. If the allocation fails,
-they return B<NULL> and set an error code that can be obtained
-by L<ERR_get_error(3)>.
-
-BN_clear(), BN_free() and BN_clear_free() have no return values.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>
-
-=head1 HISTORY
-
-BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_num_bytes(const BIGNUM *a);
-
- int BN_num_bits(const BIGNUM *a);
-
- int BN_num_bits_word(BN_ULONG w);
-
-=head1 DESCRIPTION
-
-BN_num_bytes() returns the size of a B<BIGNUM> in bytes.
-
-BN_num_bits_word() returns the number of significant bits in a word.
-If we take 0x00000432 as an example, it returns 11, not 16, not 32.
-Basically, except for a zero, it returns I<floor(log2(w))+1>.
-
-BN_num_bits() returns the number of significant bits in a B<BIGNUM>,
-following the same principle as BN_num_bits_word().
-
-BN_num_bytes() is a macro.
-
-=head1 RETURN VALUES
-
-The size.
-
-=head1 NOTES
-
-Some have tried using BN_num_bits() on individual numbers in RSA keys,
-DH keys and DSA keys, and found that they don't always come up with
-the number of bits they expected (something like 512, 1024, 2048,
-...). This is because generating a number with some specific number
-of bits doesn't always set the highest bits, thereby making the number
-of I<significant> bits a little lower. If you want to know the "key
-size" of such a key, either use functions like RSA_size(), DH_size()
-and DSA_size(), or use BN_num_bytes() and multiply with 8 (although
-there's no real guarantee that will match the "key size", just a lot
-more probability).
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<DH_size(3)>, L<DSA_size(3)>,
-L<RSA_size(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
-
- int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
-
- int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
-
- int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
-
-=head1 DESCRIPTION
-
-BN_rand() generates a cryptographically strong pseudo-random number of
-B<bits> in length and stores it in B<rnd>.
-If B<bits> is less than zero, or too small to
-accomodate the requirements specified by the B<top> and B<bottom>
-parameters, an error is returned.
-The B<top> parameters specifies
-requirements on the most significant bit of the generated number.
-If it is B<BN_RAND_TOP_ANY>, there is no constraint.
-If it is B<BN_RAND_TOP_ONE>, the top bit must be one.
-If it is B<BN_RAND_TOP_TWO>, the two most significant bits of
-the number will be set to 1, so that the product of two such random
-numbers will always have 2*B<bits> length.
-If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
-is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
-If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
-
-BN_pseudo_rand() does the same, but pseudo-random numbers generated by
-this function are not necessarily unpredictable. They can be used for
-non-cryptographic purposes and for certain purposes in cryptographic
-protocols, but usually not for key generation etc.
-
-BN_rand_range() generates a cryptographically strong pseudo-random
-number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
-BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(),
-and hence numbers generated by it are not necessarily unpredictable.
-
-The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
-
-=head1 RETURN VALUES
-
-The functions return 1 on success, 0 on error.
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>,
-L<RAND_add(3)>, L<RAND_bytes(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift,
-BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- int BN_set_bit(BIGNUM *a, int n);
- int BN_clear_bit(BIGNUM *a, int n);
-
- int BN_is_bit_set(const BIGNUM *a, int n);
-
- int BN_mask_bits(BIGNUM *a, int n);
-
- int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
- int BN_lshift1(BIGNUM *r, BIGNUM *a);
-
- int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
- int BN_rshift1(BIGNUM *r, BIGNUM *a);
-
-=head1 DESCRIPTION
-
-BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The
-number is expanded if necessary.
-
-BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An
-error occurs if B<a> is shorter than B<n> bits.
-
-BN_is_bit_set() tests if bit B<n> in B<a> is set.
-
-BN_mask_bits() truncates B<a> to an B<n> bit number
-(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is
-shorter than B<n> bits.
-
-BN_lshift() shifts B<a> left by B<n> bits and places the result in
-B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts
-B<a> left by one and places the result in B<r> (C<r=2*a>).
-
-BN_rshift() shifts B<a> right by B<n> bits and places the result in
-B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts
-B<a> right by one and places the result in B<r> (C<r=a/2>).
-
-For the shift functions, B<r> and B<a> may be the same variable.
-
-=head1 RETURN VALUES
-
-BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.
-
-All other functions return 1 for success, 0 on error. The error codes
-can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<BN_num_bytes(3)>, L<BN_add(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=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)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment
-operations
-
-=head1 SYNOPSIS
-
- #include <openssl/bn.h>
-
- void BN_zero(BIGNUM *a);
- int BN_one(BIGNUM *a);
-
- const BIGNUM *BN_value_one(void);
-
- int BN_set_word(BIGNUM *a, unsigned long w);
- unsigned long BN_get_word(BIGNUM *a);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x00908000L
- int BN_zero(BIGNUM *a);
- #endif
-
-=head1 DESCRIPTION
-
-BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
-B<w> respectively. BN_zero() and BN_one() are macros.
-
-BN_value_one() returns a B<BIGNUM> constant of value 1. This constant
-is useful for use in comparisons and assignment.
-
-BN_get_word() returns B<a>, if it can be represented as an unsigned
-long.
-
-=head1 RETURN VALUES
-
-BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot
-be represented as an unsigned long.
-
-BN_one(), BN_set_word() and the deprecated version of BN_zero()
-return 1 on success, 0 otherwise.
-BN_value_one() returns the constant.
-The preferred version of BN_zero() never fails and returns no value.
-
-=head1 BUGS
-
-Someone might change the constant.
-
-If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an
-unsigned long but this value is also returned on error.
-
-=head1 SEE ALSO
-
-L<bn(3)>, L<BN_bn2bin(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow
-BUF_MEM_grow_clean, BUF_reverse
-- simple character array structure
-
-standard C library equivalents
-
-=head1 SYNOPSIS
-
- #include <openssl/buffer.h>
-
- BUF_MEM *BUF_MEM_new(void);
-
- BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
-
- void BUF_MEM_free(BUF_MEM *a);
-
- int BUF_MEM_grow(BUF_MEM *str, int len);
- size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len);
-
- void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size);
-
-=head1 DESCRIPTION
-
-The buffer library handles simple character arrays. Buffers are used for
-various purposes in the library, most notably memory BIOs.
-
-BUF_MEM_new() allocates a new buffer of zero size.
-
-BUF_MEM_new_ex() allocates a buffer with the specified flags.
-The flag B<BUF_MEM_FLAG_SECURE> specifies that the B<data> pointer
-should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>.
-
-BUF_MEM_free() frees up an already existing buffer. The data is zeroed
-before freeing up in case the buffer contains sensitive data.
-
-BUF_MEM_grow() changes the size of an already existing buffer to
-B<len>. Any data already in the buffer is preserved if it increases in
-size.
-
-BUF_MEM_grow_clean() is similar to BUF_MEM_grow() but it sets any free'd
-or additionally-allocated memory to zero.
-
-BUF_reverse() reverses B<size> bytes at B<in> into B<out>. If B<out>
-is NULL, the array is reversed in-place.
-
-=head1 RETURN VALUES
-
-BUF_MEM_new() returns the buffer or NULL on error.
-
-BUF_MEM_free() has no return value.
-
-BUF_MEM_grow() and BUF_MEM_grow_clean() return
-zero on error or the new size (i.e., B<len>).
-
-=head1 SEE ALSO
-
-L<bio(3)>,
-L<CRYPTO_secure_malloc(3)>.
-
-=head1 HISTORY
-
-BUF_MEM_new_ex() was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);
- int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);
- STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);
-
- int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);
- int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl);
- STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);
-
-
-=head1 DESCRIPTION
-
-CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>.
-must be of type signed data or enveloped data.
-
-CMS_get1_certs() returns all certificates in B<cms>.
-
-CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls()
-returns any CRLs in B<cms>.
-
-=head1 NOTES
-
-The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped
-data or an error will be returned.
-
-For signed data certificates and CRLs are added to the B<certificates> and
-B<crls> fields of SignedData structure. For enveloped data they are added to
-B<OriginatorInfo>.
-
-As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it
-must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
-must be freed up.
-
-The same certificate or CRL must not be added to the same cms structure more
-than once.
-
-=head1 RETURN VALUES
-
-CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return
-1 for success and 0 for failure.
-
-CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
-or NULL if there are none or an error occurs. The only error which will occur
-in practice is if the B<cms> type is invalid.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<CMS_sign(3)>,
-L<CMS_encrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags);
-
- CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType);
-
-=head1 DESCRIPTION
-
-CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
-data structure B<cms> as a KeyTransRecipientInfo structure.
-
-CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
-wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional
-values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped
-data structure B<cms> as a KEKRecipientInfo structure.
-
-The CMS_ContentInfo structure should be obtained from an initial call to
-CMS_encrypt() with the flag B<CMS_PARTIAL> set.
-
-=head1 NOTES
-
-The main purpose of this function is to provide finer control over a CMS
-enveloped data structure where the simpler CMS_encrypt() function defaults are
-not appropriate. For example if one or more KEKRecipientInfo structures
-need to be added. New attributes can also be added using the returned
-CMS_RecipientInfo structure and the CMS attribute utility functions.
-
-OpenSSL will by default identify recipient certificates using issuer name
-and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
-identifier value instead. An error occurs if all recipient certificates do not
-have a subject key identifier extension.
-
-Currently only AES based key wrapping algorithms are supported for B<nid>,
-specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
-If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
-consistent with B<keylen>.
-
-=head1 RETURN VALUES
-
-CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
-pointer to the CMS_RecipientInfo structure just added or NULL if an error
-occurs.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
-L<CMS_final(3)>,
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
-
- int CMS_SignerInfo_sign(CMS_SignerInfo *si);
-
-
-=head1 DESCRIPTION
-
-CMS_add1_signer() adds a signer with certificate B<signcert> and private
-key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
-structure B<cms>.
-
-The CMS_ContentInfo structure should be obtained from an initial call to
-CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a
-valid CMS_ContentInfo SignedData structure.
-
-If the B<md> parameter is B<NULL> then the default digest for the public
-key algorithm will be used.
-
-Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo
-structure is not complete and must be finalized either by streaming (if
-applicable) or a call to CMS_final().
-
-The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo
-structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags
-are both set.
-
-=head1 NOTES
-
-The main purpose of CMS_add1_signer() is to provide finer control
-over a CMS signed data structure where the simpler CMS_sign() function defaults
-are not appropriate. For example if multiple signers or non default digest
-algorithms are needed. New attributes can also be added using the returned
-CMS_SignerInfo structure and the CMS attribute utility functions or the
-CMS signed receipt request functions.
-
-Any of the following flags (ored together) can be passed in the B<flags>
-parameter.
-
-If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content
-digest value from the CMS_ContentInfo structure: to add a signer to an existing
-structure. An error occurs if a matching digest value cannot be found to copy.
-The returned CMS_ContentInfo structure will be valid and finalized when this
-flag is set.
-
-If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the
-CMS_SignerInfo structure will not be finalized so additional attributes
-can be added. In this case an explicit call to CMS_SignerInfo_sign() is
-needed to finalize it.
-
-If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
-CMS_ContentInfo structure, the signer's certificate must still be supplied in
-the B<signcert> parameter though. This can reduce the size of the signature if
-the signers certificate can be obtained by other means: for example a
-previously signed message.
-
-The SignedData structure includes several CMS signedAttributes including the
-signing time, the CMS content type and the supported list of ciphers in an
-SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
-will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
-omitted.
-
-OpenSSL will by default identify signing certificates using issuer name
-and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
-identifier value instead. An error occurs if the signing certificate does not
-have a subject key identifier extension.
-
-If present the SMIMECapabilities attribute indicates support for the following
-algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
-bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
-If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
-not loaded.
-
-CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
-structure just added, this can be used to set additional attributes
-before it is finalized.
-
-=head1 RETURN VALUES
-
-CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
-structure just added or NULL if an error occurs.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>,
-L<CMS_final(3)>,
-
-=head1 COPYRIGHT
-
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_compress - create a CMS CompressedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid>
-is the compression algorithm to use or B<NID_undef> to use the default
-algorithm (zlib compression). B<in> is the content to be compressed.
-B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-The only currently supported compression algorithm is zlib using the NID
-NID_zlib_compression.
-
-If zlib support is not compiled into OpenSSL then CMS_compress() will return
-an error.
-
-If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
-prepended to the data.
-
-Normally the supplied content is translated into MIME canonical format (as
-required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
-occurs. This option should be used if the supplied data is in binary format
-otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
-B<CMS_TEXT> is ignored.
-
-If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
-returned suitable for streaming I/O: no data is read from the BIO B<in>.
-
-The compressed data is included in the CMS_ContentInfo structure, unless
-B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
-practice and is not supported by SMIME_write_CMS().
-
-=head1 NOTES
-
-If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
-B<not> complete and outputting its contents via a function that does not
-properly finalize the B<CMS_ContentInfo> structure will give unpredictable
-results.
-
-Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
-PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
-can be performed by obtaining the streaming ASN1 B<BIO> directly using
-BIO_new_CMS().
-
-Additional compression parameters such as the zlib compression level cannot
-currently be set.
-
-=head1 RETURN VALUES
-
-CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error
-occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_uncompress(3)>
-
-=head1 HISTORY
-
-The B<CMS_STREAM> flag was added in OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_decrypt - decrypt content from a CMS envelopedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData
-structure. B<pkey> is the private key of the recipient, B<cert> is the
-recipient's certificate, B<out> is a BIO to write the content to and
-B<flags> is an optional set of flags.
-
-The B<dcont> parameter is used in the rare case where the encrypted content
-is detached. It will normally be set to NULL.
-
-=head1 NOTES
-
-Although the recipients certificate is not needed to decrypt the data it is
-needed to locate the appropriate (of possible several) recipients in the CMS
-structure.
-
-If B<cert> is set to NULL all possible recipients are tried. This case however
-is problematic. To thwart the MMA attack (Bleichenbacher's attack on
-PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
-not. If no recipient succeeds then a random symmetric key is used to decrypt
-the content: this will typically output garbage and may (but is not guaranteed
-to) ultimately return a padding error only. If CMS_decrypt() just returned an
-error when all recipient encrypted keys failed to decrypt an attacker could
-use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set
-then the above behaviour is modified and an error B<is> returned if no
-recipient encrypted key can be decrypted B<without> generating a random
-content encryption key. Applications should use this flag with
-B<extreme caution> especially in automated gateways as it can leave them
-open to attack.
-
-It is possible to determine the correct recipient key by other means (for
-example looking them up in a database) and setting them in the CMS structure
-in advance using the CMS utility functions such as CMS_set1_pkey(). In this
-case both B<cert> and B<pkey> should be set to NULL.
-
-To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
-and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and
-B<cert> and B<pkey> set to NULL.
-
-The following flags can be passed in the B<flags> parameter.
-
-If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
-from the content. If the content is not of type B<text/plain> then an error is
-returned.
-
-=head1 RETURN VALUES
-
-CMS_decrypt() returns either 1 for success or 0 for failure.
-The error can be obtained from ERR_get_error(3)
-
-=head1 BUGS
-
-The lack of single pass processing and the need to hold all data in memory as
-mentioned in CMS_verify() also applies to CMS_decrypt().
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_encrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_encrypt - create a CMS envelopedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs>
-is a list of recipient certificates. B<in> is the content to be encrypted.
-B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-Only certificates carrying RSA keys are supported so the recipient certificates
-supplied to this function must all contain RSA public keys, though they do not
-have to be signed using the RSA algorithm.
-
-EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
-because most clients will support it.
-
-The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
-its parameters.
-
-Many browsers implement a "sign and encrypt" option which is simply an S/MIME
-envelopedData containing an S/MIME signed message. This can be readily produced
-by storing the S/MIME signed message in a memory BIO and passing it to
-CMS_encrypt().
-
-The following flags can be passed in the B<flags> parameter.
-
-If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
-prepended to the data.
-
-Normally the supplied content is translated into MIME canonical format (as
-required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
-occurs. This option should be used if the supplied data is in binary format
-otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
-B<CMS_TEXT> is ignored.
-
-OpenSSL will by default identify recipient certificates using issuer name
-and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
-identifier value instead. An error occurs if all recipient certificates do not
-have a subject key identifier extension.
-
-If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
-returned suitable for streaming I/O: no data is read from the BIO B<in>.
-
-If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
-returned to which additional recipients and attributes can be added before
-finalization.
-
-The data being encrypted is included in the CMS_ContentInfo structure, unless
-B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
-practice and is not supported by SMIME_write_CMS().
-
-=head1 NOTES
-
-If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
-B<not> complete and outputting its contents via a function that does not
-properly finalize the B<CMS_ContentInfo> structure will give unpredictable
-results.
-
-Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
-PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
-can be performed by obtaining the streaming ASN1 B<BIO> directly using
-BIO_new_CMS().
-
-The recipients specified in B<certs> use a CMS KeyTransRecipientInfo info
-structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL>
-and CMS_add0_recipient_key().
-
-The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients
-added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().
-
-=head1 RETURN VALUES
-
-CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error
-occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_decrypt(3)>
-
-=head1 HISTORY
-
-The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_final - finalise a CMS_ContentInfo structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_final() finalises the structure B<cms>. It's purpose is to perform any
-operations necessary on B<cms> (digest computation for example) and set the
-appropriate fields. The parameter B<data> contains the content to be
-processed. The B<dcont> parameter contains a BIO to write content to after
-processing: this is only used with detached data and will usually be set to
-NULL.
-
-=head1 NOTES
-
-This function will normally be called when the B<CMS_PARTIAL> flag is used. It
-should only be used when streaming is not performed because the streaming
-I/O functions perform finalisation operations internally.
-
-=head1 RETURN VALUES
-
-CMS_final() returns 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>,
-L<CMS_encrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
-CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
-CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
-CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key,
-CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt
-- CMS envelopedData RecipientInfo routines
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
- int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
-
- int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
- int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
- int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
-
- int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype);
- int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen);
- int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
-
- int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
- int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
-
-=head1 DESCRIPTION
-
-The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
-structures associated with a CMS EnvelopedData structure.
-
-CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
-It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
-CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
-
-CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
-identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
-must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
-B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
-
-CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
-CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
-It returns zero if the comparison is successful and non zero if not.
-
-CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
-the CMS_RecipientInfo structure B<ri>, which must be of type
-CMS_RECIPINFO_TRANS.
-
-CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
-CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any
-of the remaining parameters can be NULL if the application is not interested in
-the value of a field. Where a field is optional and absent NULL will be written
-to the corresponding parameter. The keyEncryptionAlgorithm field is written to
-B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
-present is written to B<pdate>, if the B<other> field is present the components
-B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
-B<pothertype>.
-
-CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
-parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
-which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is
-successful and non zero if not.
-
-CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
-B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
-CMS_RECIPINFO_KEK.
-
-CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
-B<ri> in structure B<cms>. A key must have been associated with the structure
-first.
-
-CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
-B<ri> in structure B<cms>. A key must have been associated with the structure
-first and the content encryption key must be available: for example by a
-previous call to CMS_RecipientInfo_decrypt().
-
-=head1 NOTES
-
-The main purpose of these functions is to enable an application to lookup
-recipient keys using any appropriate technique when the simpler method
-of CMS_decrypt() is not appropriate.
-
-In typical usage and application will retrieve all CMS_RecipientInfo structures
-using CMS_get0_RecipientInfos() and check the type of each using
-CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
-can be ignored or its key identifier data retrieved using an appropriate
-function. Then if the corresponding secret or private key can be obtained by
-any appropriate means it can then associated with the structure and
-CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
-with a NULL key to decrypt the enveloped content.
-
-The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
-existing enveloped data structure. Typically an application will first decrypt
-an appropriate CMS_RecipientInfo structure to make the content encrypt key
-available, it will then add a new recipient using a function such as
-CMS_add1_recipient_cert() and finally encrypt the content encryption key
-using CMS_RecipientInfo_encrypt().
-
-=head1 RETURN VALUES
-
-CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
-an error occurs.
-
-CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
-CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
-CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
-CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
-
-CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
-for a successful comparison and non zero otherwise.
-
-Any error can be obtained from L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_decrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_SignerInfo_set1_signer_cert,
-CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id,
-CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp,
-- CMS signedData signer functions
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
-
- int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
- ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);
- int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
- void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
-
-=head1 DESCRIPTION
-
-The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures
-associated with a CMS signedData structure.
-
-CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier
-associated with a specific CMS_SignerInfo structure B<si>. Either the
-keyidentifier will be set in B<keyid> or B<both> issuer name and serial number
-in B<issuer> and B<sno>.
-
-CMS_SignerInfo_get0_signature() retrieves the signature associated with
-B<si> in a pointer to an ASN1_OCTET_STRING structure. This pointer returned
-corresponds to the internal signature value if B<si> so it may be read or
-modified.
-
-CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer
-identifier B<si>. It returns zero if the comparison is successful and non zero
-if not.
-
-CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to
-B<signer>.
-
-=head1 NOTES
-
-The main purpose of these functions is to enable an application to lookup
-signers certificates using any appropriate technique when the simpler method
-of CMS_verify() is not appropriate.
-
-In typical usage and application will retrieve all CMS_SignerInfo structures
-using CMS_get0_SignerInfo() and retrieve the identifier information using
-CMS. It will then obtain the signer certificate by some unspecified means
-(or return and error if it cannot be found) and set it using
-CMS_SignerInfo_set1_signer_cert().
-
-Once all signer certificates have been set CMS_verify() can be used.
-
-Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if
-there are no signers this is not a problem in practice because the only
-error which can occur is if the B<cms> structure is not of type signedData
-due to application error.
-
-=head1 RETURN VALUES
-
-CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there
-are no signers or an error occurs.
-
-CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.
-
-CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non
-zero otherwise.
-
-CMS_SignerInfo_set1_signer_cert() does not return a value.
-
-Any error can be obtained from L<ERR_get_error(3)>
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms);
- int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
- const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
- ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
-
-=head1 DESCRIPTION
-
-CMS_get0_type() returns the content type of a CMS_ContentInfo structure as
-and ASN1_OBJECT pointer. An application can then decide how to process the
-CMS_ContentInfo structure based on this value.
-
-CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo
-structure. It should be called with CMS functions with the B<CMS_PARTIAL>
-flag and B<before> the structure is finalised, otherwise the results are
-undefined.
-
-ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
-content type.
-
-CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer
-containing the embedded content.
-
-=head1 NOTES
-
-As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and
-CMS_get0_content() return internal pointers which should B<not> be freed up.
-CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up
-after use.
-
-The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
-using OBJ_obj2nid(). For the currently supported content types the following
-values are returned:
-
- NID_pkcs7_data
- NID_pkcs7_signed
- NID_pkcs7_digest
- NID_id_smime_ct_compressedData:
- NID_pkcs7_encrypted
- NID_pkcs7_enveloped
-
-The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING>
-content pointer. That means that for example:
-
- ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
-
-B<*pconf> could be NULL if there is no embedded content. Applications can
-access, modify or create the embedded content in a B<CMS_ContentInfo> structure
-using this function. Applications usually will not need to modify the
-embedded content as it is normally set by higher level functions.
-
-=head1 RETURN VALUES
-
-CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure.
-
-CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The
-error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);
- int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);
- int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);
- void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto);
-
-=head1 DESCRIPTION
-
-CMS_ReceiptRequest_create0() creates a signed receipt request structure. The
-B<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set
-to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL
-the allOrFirstTier option in B<receiptsFrom> is used and set to the value of
-the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList>
-option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the
-B<receiptsTo> field value.
-
-The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr>
-to SignerInfo structure B<si>.
-
-int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if
-any is found it is decoded and written to B<prr>.
-
-CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request.
-The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier>
-option of B<receiptsFrom> is used its value is copied to B<pallorfirst>
-otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo>
-parameter is copied to B<prto>.
-
-=head1 NOTES
-
-For more details of the meaning of the fields see RFC2634.
-
-The contents of a signed receipt should only be considered meaningful if the
-corresponding CMS_ContentInfo structure can be successfully verified using
-CMS_verify().
-
-=head1 RETURN VALUES
-
-CMS_ReceiptRequest_create0() returns a signed receipt request structure or
-NULL if an error occurred.
-
-CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred.
-
-CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and
-decoded. It returns 0 if a signed receipt request is not present and -1 if
-it is present but malformed.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>,
-L<CMS_sign_receipt(3)>, L<CMS_verify(3)>
-L<CMS_verify_receipt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_sign - create a CMS SignedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is
-the certificate to sign with, B<pkey> is the corresponding private key.
-B<certs> is an optional additional set of certificates to include in the CMS
-structure (for example any intermediate CAs in the chain). Any or all of
-these parameters can be B<NULL>, see B<NOTES> below.
-
-The data to be signed is read from BIO B<data>.
-
-B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-Any of the following flags (ored together) can be passed in the B<flags>
-parameter.
-
-Many S/MIME clients expect the signed content to include valid MIME headers. If
-the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended
-to the data.
-
-If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
-CMS_ContentInfo structure, the signer's certificate must still be supplied in
-the B<signcert> parameter though. This can reduce the size of the signature if
-the signers certificate can be obtained by other means: for example a
-previously signed message.
-
-The data being signed is included in the CMS_ContentInfo structure, unless
-B<CMS_DETACHED> is set in which case it is omitted. This is used for
-CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
-messages for example.
-
-Normally the supplied content is translated into MIME canonical format (as
-required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
-occurs. This option should be used if the supplied data is in binary format
-otherwise the translation will corrupt it.
-
-The SignedData structure includes several CMS signedAttributes including the
-signing time, the CMS content type and the supported list of ciphers in an
-SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
-will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
-omitted.
-
-If present the SMIMECapabilities attribute indicates support for the following
-algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
-bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
-If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
-not loaded.
-
-OpenSSL will by default identify signing certificates using issuer name
-and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
-identifier value instead. An error occurs if the signing certificate does not
-have a subject key identifier extension.
-
-If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo>
-structure is just initialized ready to perform the signing operation. The
-signing is however B<not> performed and the data to be signed is not read from
-the B<data> parameter. Signing is deferred until after the data has been
-written. In this way data can be signed in a single pass.
-
-If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
-output to which additional signers and capabilities can be added before
-finalization.
-
-If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
-B<not> complete and outputting its contents via a function that does not
-properly finalize the B<CMS_ContentInfo> structure will give unpredictable
-results.
-
-Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
-PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
-can be performed by obtaining the streaming ASN1 B<BIO> directly using
-BIO_new_CMS().
-
-If a signer is specified it will use the default digest for the signing
-algorithm. This is B<SHA1> for both RSA and DSA keys.
-
-If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is
-output.
-
-The function CMS_sign() is a basic CMS signing function whose output will be
-suitable for many purposes. For finer control of the output format the
-B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the
-B<CMS_PARTIAL> flag set. Then one or more signers can be added using the
-function CMS_sign_add1_signer(), non default digests can be used and custom
-attributes added. CMS_final() must then be called to finalize the
-structure if streaming is not enabled.
-
-=head1 BUGS
-
-Some attributes such as counter signatures are not supported.
-
-=head1 RETURN VALUES
-
-CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error
-occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_verify(3)>
-
-=head1 HISTORY
-
-The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8,
-it is supported for embedded data in OpenSSL 1.0.0 and later.
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_sign_receipt - create a CMS signed receipt
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_sign_receipt() creates and returns a CMS signed receipt structure. B<si> is
-the B<CMS_SignerInfo> structure containing the signed receipt request.
-B<signcert> is the certificate to sign with, B<pkey> is the corresponding
-private key. B<certs> is an optional additional set of certificates to include
-in the CMS structure (for example any intermediate CAs in the chain).
-
-B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-This functions behaves in a similar way to CMS_sign() except the flag values
-B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM>
-are not supported since they do not make sense in the context of signed
-receipts.
-
-=head1 RETURN VALUES
-
-CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if
-an error occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<CMS_verify_receipt(3)>,
-L<CMS_sign(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_uncompress - uncompress a CMS CompressedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_uncompress() extracts and uncompresses the content from a CMS
-CompressedData structure B<cms>. B<data> is a BIO to write the content to and
-B<flags> is an optional set of flags.
-
-The B<dcont> parameter is used in the rare case where the compressed content
-is detached. It will normally be set to NULL.
-
-=head1 NOTES
-
-The only currently supported compression algorithm is zlib: if the structure
-indicates the use of any other algorithm an error is returned.
-
-If zlib support is not compiled into OpenSSL then CMS_uncompress() will always
-return an error.
-
-The following flags can be passed in the B<flags> parameter.
-
-If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
-from the content. If the content is not of type B<text/plain> then an error is
-returned.
-
-=head1 RETURN VALUES
-
-CMS_uncompress() returns either 1 for success or 0 for failure. The error can
-be obtained from ERR_get_error(3)
-
-=head1 BUGS
-
-The lack of single pass processing and the need to hold all data in memory as
-mentioned in CMS_verify() also applies to CMS_decompress().
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_compress(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_verify, CMS_get0_signers - verify a CMS SignedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags);
-
- STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
-
-=head1 DESCRIPTION
-
-CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
-structure to verify. B<certs> is a set of certificates in which to search for
-the signing certificate(s). B<store> is a trusted certificate store used for
-chain verification. B<indata> is the detached content if the content is not
-present in B<cms>. The content is written to B<out> if it is not NULL.
-
-B<flags> is an optional set of flags, which can be used to modify the verify
-operation.
-
-CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must
-be called after a successful CMS_verify() operation.
-
-=head1 VERIFY PROCESS
-
-Normally the verify process proceeds as follows.
-
-Initially some sanity checks are performed on B<cms>. The type of B<cms> must
-be SignedData. There must be at least one signature on the data and if
-the content is detached B<indata> cannot be B<NULL>.
-
-An attempt is made to locate all the signing certificate(s), first looking in
-the B<certs> parameter (if it is not NULL) and then looking in any
-certificates contained in the B<cms> structure itself. If any signing
-certificate cannot be located the operation fails.
-
-Each signing certificate is chain verified using the B<smimesign> purpose and
-the supplied trusted certificate store. Any internal certificates in the message
-are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
-CRLs are used in addition to attempting to look them up in B<store>. If any
-chain verify fails an error code is returned.
-
-Finally the signed content is read (and written to B<out> is it is not NULL)
-and the signature's checked.
-
-If all signature's verify correctly then the function is successful.
-
-Any of the following flags (ored together) can be passed in the B<flags>
-parameter to change the default verify behaviour.
-
-If B<CMS_NOINTERN> is set the certificates in the message itself are not
-searched when locating the signing certificate(s). This means that all the
-signing certificates must be in the B<certs> parameter.
-
-If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
-CRLs in the message itself are ignored.
-
-If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
-from the content. If the content is not of type B<text/plain> then an error is
-returned.
-
-If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
-verified.
-
-If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
-verified.
-
-If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
-
-=head1 NOTES
-
-One application of B<CMS_NOINTERN> is to only accept messages signed by
-a small number of certificates. The acceptable certificates would be passed
-in the B<certs> parameter. In this case if the signer is not one of the
-certificates supplied in B<certs> then the verify will fail because the
-signer cannot be found.
-
-In some cases the standard techniques for looking up and validating
-certificates are not appropriate: for example an application may wish to
-lookup certificates in a database or perform customised verification. This
-can be achieved by setting and verifying the signers certificates manually
-using the signed data utility functions.
-
-Care should be taken when modifying the default verify behaviour, for example
-setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification
-and any modified content will be considered valid. This combination is however
-useful if one merely wishes to write the content to B<out> and its validity
-is not considered important.
-
-Chain verification should arguably be performed using the signing time rather
-than the current time. However since the signing time is supplied by the
-signer it cannot be trusted without additional evidence (such as a trusted
-timestamp).
-
-=head1 RETURN VALUES
-
-CMS_verify() returns 1 for a successful verification and zero if an error
-occurred.
-
-CMS_get0_signers() returns all signers or NULL if an error occurred.
-
-The error can be obtained from L<ERR_get_error(3)>
-
-=head1 BUGS
-
-The trusted certificate store is not searched for the signing certificate,
-this is primarily due to the inadequacies of the current B<X509_STORE>
-functionality.
-
-The lack of single pass processing means that the signed content must all
-be held in memory if it is not detached.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CMS_verify_receipt - verify a CMS signed receipt
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags);
-
-=head1 DESCRIPTION
-
-CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed
-receipt to verify. B<ocms> is the original SignedData structure containing the
-receipt request. B<certs> is a set of certificates in which to search for the
-signing certificate. B<store> is a trusted certificate store (used for chain
-verification).
-
-B<flags> is an optional set of flags, which can be used to modify the verify
-operation.
-
-=head1 NOTES
-
-This functions behaves in a similar way to CMS_verify() except the flag values
-B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> are not
-supported since they do not make sense in the context of signed receipts.
-
-=head1 RETURN VALUES
-
-CMS_verify_receipt() returns 1 for a successful verification and zero if an
-error occurred.
-
-The error can be obtained from L<ERR_get_error(3)>
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<CMS_sign_receipt(3)>,
-L<CMS_verify(3)>,
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CONF_modules_free, CONF_modules_finish, CONF_modules_unload -
-OpenSSL configuration cleanup functions
-
-=head1 SYNOPSIS
-
- #include <openssl/conf.h>
-
- void CONF_modules_finish(void);
- void CONF_modules_unload(int all);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void CONF_modules_free(void)
- #endif
-
-=head1 DESCRIPTION
-
-CONF_modules_free() closes down and frees up all memory allocated by all
-configuration modules.
-
-CONF_modules_finish() calls each configuration modules B<finish> handler
-to free up any configuration that module may have performed.
-
-CONF_modules_unload() finishes and unloads configuration modules. If
-B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
-B<all> is B<1> all modules, including builtin modules will be unloaded.
-
-=head1 NOTES
-
-Normally in versions of OpenSSL prior to 1.1.0 applications will only call
-CONF_modules_free() at application exit to tidy up any configuration performed.
-From 1.1.0 CONF_modules_free() is deprecated and no explicit CONF cleanup is
-required at all. For more information see L<OPENSSL_init_crypto(3)>.
-
-=head1 RETURN VALUE
-
-None of the functions return a value.
-
-=head1 SEE ALSO
-
-L<conf(5)>, L<OPENSSL_config(3)>,
-L<CONF_modules_load_file(3)>
-
-=head1 HISTORY
-
-CONF_modules_free() was deprecated in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
-
-=head1 SYNOPSIS
-
- #include <openssl/conf.h>
-
- int CONF_modules_load_file(const char *filename, const char *appname,
- unsigned long flags);
- int CONF_modules_load(const CONF *cnf, const char *appname,
- unsigned long flags);
-
-=head1 DESCRIPTION
-
-The function CONF_modules_load_file() configures OpenSSL using file
-B<filename> and application name B<appname>. If B<filename> is NULL
-the standard OpenSSL configuration file is used. If B<appname> is
-NULL the standard OpenSSL application name B<openssl_conf> is used.
-The behaviour can be customized using B<flags>.
-
-CONF_modules_load() is identical to CONF_modules_load_file() except it
-reads configuration information from B<cnf>.
-
-=head1 NOTES
-
-The following B<flags> are currently recognized:
-
-B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
-configuration modules are ignored. If not set the first module error is
-considered fatal and no further modules are loaded.
-
-Normally any modules errors will add error information to the error queue. If
-B<CONF_MFLAGS_SILENT> is set no error information is added.
-
-If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
-disabled.
-
-B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
-ignore missing configuration files. Normally a missing configuration file
-return an error.
-
-B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
-default section pointed to by B<openssl_conf> if B<appname> does not exist.
-
-By using CONF_modules_load_file() with appropriate flags an application can
-customise application configuration to best suit its needs. In some cases the
-use of a configuration file is optional and its absence is not an error: in
-this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
-
-Errors during configuration may also be handled differently by different
-applications. For example in some cases an error may simply print out a warning
-message and the application continue. In other cases an application might
-consider a configuration file error as fatal and exit immediately.
-
-Applications can use the CONF_modules_load() function if they wish to load a
-configuration file themselves and have finer control over how errors are
-treated.
-
-=head1 EXAMPLES
-
-Load a configuration file and print out any errors and exit (missing file
-considered fatal):
-
- if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
- fprintf(stderr, "FATAL: error loading configuration file\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
-Load default configuration file using the section indicated by "myapp",
-tolerate missing files, but exit on other errors:
-
- if (CONF_modules_load_file(NULL, "myapp",
- CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
- fprintf(stderr, "FATAL: error loading configuration file\n");
- ERR_print_errors_fp(stderr);
- exit(1);
- }
-
-Load custom configuration file and section, only print warnings on error,
-missing configuration file ignored:
-
- if (CONF_modules_load_file("/something/app.cnf", "myapp",
- CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
- fprintf(stderr, "WARNING: error loading configuration file\n");
- ERR_print_errors_fp(stderr);
- }
-
-Load and parse configuration file manually, custom error handling:
-
- FILE *fp;
- CONF *cnf = NULL;
- long eline;
- fp = fopen("/somepath/app.cnf", "r");
- if (fp == NULL) {
- fprintf(stderr, "Error opening configuration file\n");
- /* Other missing configuration file behaviour */
- } else {
- cnf = NCONF_new(NULL);
- if (NCONF_load_fp(cnf, fp, &eline) == 0) {
- fprintf(stderr, "Error on line %ld of configuration file\n", eline);
- ERR_print_errors_fp(stderr);
- /* Other malformed configuration file behaviour */
- } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
- fprintf(stderr, "Error configuring application\n");
- ERR_print_errors_fp(stderr);
- /* Other configuration error behaviour */
- }
- fclose(fp);
- NCONF_free(cnf);
- }
-
-=head1 RETURN VALUES
-
-These functions return 1 for success and a zero or negative value for
-failure. If module errors are not ignored the return code will reflect the
-return value of the failing module (this will always be zero or negative).
-
-=head1 SEE ALSO
-
-L<conf(5)>, L<OPENSSL_config(3)>,
-L<CONF_free(3)>, L<err(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CRYPTO_THREAD_run_once,
-CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
-CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support
-
-=head1 SYNOPSIS
-
- #include <openssl/crypto.h>
-
- CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
- int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
-
- CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
- int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
- int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
- int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);
- void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
-
- int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
-
-=head1 DESCRIPTION
-
-OpenSSL can be safely used in multi-threaded applications provided that
-support for the underlying OS threading API is built-in. Currently, OpenSSL
-supports the pthread and Windows APIs. OpenSSL can also be built without
-any multi-threading support, for example on platforms that don't provide
-any threading support or that provide a threading API that is not yet
-supported by OpenSSL.
-
-The following multi-threading function are provided:
-
-=over 4
-
-=item *
-CRYPTO_THREAD_run_once() can be used to perform one-time initialization.
-The B<once> argument must be a pointer to a static object of type
-B<CRYPTO_ONCE> that was statically initialized to the value
-B<CRYPTO_ONCE_STATIC_INIT>.
-The B<init> argument is a pointer to a function that performs the desired
-exactly once initialization.
-In particular, this can be used to allocate locks in a thread-safe manner,
-which can then be used with the locking functions below.
-
-=item *
-CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
-lock.
-
-=item *
-CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading.
-
-=item *
-CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
-
-=item *
-CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
-
-=item *
-CRYPTO_THREAD_lock_frees() frees the provided B<lock>.
-
-=item *
-CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the
-result of the operation in B<ret>. B<lock> will be locked, unless atomic
-operations are supported on the specific platform. Because of this, if a
-variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must
-be the only way that the variable is modified.
-
-=back
-
-=head1 RETURN VALUES
-
-CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.
-
-CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
-
-CRYPTO_THREAD_lock_frees() returns no value.
-
-The other functions return 1 on success or 0 on error.
-
-=head1 NOTES
-
-On Windows platforms the CRYPTO_THREAD_* types and functions in the
-openssl/crypto.h header are dependent on some of the types customarily
-made available by including windows.h. The application developer is
-likely to require control over when the latter is included, commonly as
-one of the first included headers. Therefore it is defined as an
-application developer's responsibility to include windows.h prior to
-crypto.h where use of CRYPTO_THREAD_* types and functions is required.
-
-=head1 EXAMPLE
-
-This example safely initializes and uses a lock.
-
- #ifdef _WIN32
- # include <windows.h>
- #endif
- #include <openssl/crypto.h>
-
- static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
- static CRYPTO_RWLOCK *lock;
-
- static void myinit(void)
- {
- lock = CRYPTO_THREAD_lock_new();
- }
-
- static int mylock(void)
- {
- if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)
- return 0;
- return CRYPTO_THREAD_write_lock(lock);
- }
-
- static int myunlock(void)
- {
- return CRYPTO_THREAD_unlock(lock);
- }
-
- int serialized(void)
- {
- int ret = 0;
-
- if (mylock()) {
- /* Your code here, do not return without releasing the lock! */
- ret = ... ;
- }
- myunlock();
- return ret;
- }
-
-Finalization of locks is an advanced topic, not covered in this example.
-This can only be done at process exit or when a dynamically loaded library is
-no longer in use and is unloaded.
-The simplest solution is to just "leak" the lock in applications and not
-repeatedly load/unload shared libraries that allocate locks.
-
-=head1 NOTES
-
-You can find out if OpenSSL was configured with thread support:
-
- #include <openssl/opensslconf.h>
- #if defined(OPENSSL_THREADS)
- // thread support enabled
- #else
- // no thread support
- #endif
-
-=head1 SEE ALSO
-
-L<crypto(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,
-CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data,
-CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
-- functions supporting application-specific data
-
-=head1 SYNOPSIS
-
- #include <openssl/crypto.h>
-
- int CRYPTO_get_ex_new_index(int class_index,
- long argl, void *argp,
- CRYPTO_EX_new *new_func,
- CRYPTO_EX_dup *dup_func,
- CRYPTO_EX_free *free_func);
-
- typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
- int idx, long argl, void *argp);
- typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
- int idx, long argl, void *argp);
- typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
- void *from_d, int idx, long argl, void *argp);
-
- int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
-
- int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
-
- void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
-
- void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);
-
- int CRYPTO_free_ex_index(int class_index, int idx);
-
-=head1 DESCRIPTION
-
-Several OpenSSL structures can have application-specific data attached to them,
-known as "exdata."
-The specific structures are:
-
- SSL
- SSL_CTX
- SSL_SESSION
- X509
- X509_STORE
- X509_STORE_CTX
- DH
- DSA
- EC_KEY
- RSA
- ENGINE
- UI
- BIO
-
-Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
-header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for
-applications to use this facility for their own structures.
-
-The API described here is used by OpenSSL to manipulate exdata for specific
-structures. Since the application data can be anything at all it is passed
-and retrieved as a B<void *> type.
-
-The B<CRYPTO_EX_DATA> type is opaque. To initialize the exdata part of
-a structure, call CRYPTO_new_ex_data(). This is only necessary for
-B<CRYPTO_EX_INDEX_APP> objects.
-
-Exdata types are identified by an B<index>, an integer guaranteed to be
-unique within structures for the lifetime of the program. Applications
-using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and
-store the result in a global variable, or write a wrapper function to
-provide lazy evaluation. The B<class_index> should be one of the
-B<CRYPTO_EX_INDEX_xxx> values. The B<argl> and B<argp> parameters are saved
-to be passed to the callbacks but are otherwise not used. In order to
-transparently manipulate exdata, three callbacks must be provided. The
-semantics of those callbacks are described below.
-
-When copying or releasing objects with exdata, the callback functions
-are called in increasing order of their B<index> value.
-
-If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index()
-when this is done.
-This will replace the callbacks with no-ops
-so that applications don't crash. Any existing exdata will be leaked.
-
-To set or get the exdata on an object, the appropriate type-specific
-routine must be used. This is because the containing structure is opaque
-and the B<CRYPTO_EX_DATA> field is not accessible. In both API's, the
-B<idx> parameter should be an already-created index value.
-
-When setting exdata, the pointer specified with a particular index is saved,
-and returned on a subsequent "get" call. If the application is going to
-release the data, it must make sure to set a B<NULL> value at the index,
-to avoid likely double-free crashes.
-
-The function B<CRYPTO_free_ex_data> is used to free all exdata attached
-to a structure. The appropriate type-specific routine must be used.
-The B<class_index> identifies the structure type, the B<obj> is
-be the pointer to the actual structure, and B<r> is a pointer to the
-structure's exdata field.
-
-=head2 Callback Functions
-
-This section describes how the callback functions are used. Applications
-that are defining their own exdata using B<CYPRTO_EX_INDEX_APP> must
-call them as described here.
-
-When a structure is initially allocated (such as RSA_new()) then the
-new_func() is called for every defined index. There is no requirement
-that the entire parent, or containing, structure has been set up.
-The new_func() is typically used only to allocate memory to store the
-exdata, and perhaps an "initialized" flag within that memory.
-The exdata value should be set by calling CRYPTO_set_ex_data().
-
-When a structure is free'd (such as SSL_CTX_free()) then the
-free_func() is called for every defined index. Again, the state of the
-parent structure is not guaranteed. The free_func() may be called with a
-NULL pointer.
-
-Both new_func() and free_func() take the same parameters.
-The B<parent> is the pointer to the structure that contains the exdata.
-The B<ptr> is the current exdata item; for new_func() this will typically
-be NULL. The B<r> parameter is a pointer to the exdata field of the object.
-The B<idx> is the index and is the value returned when the callbacks were
-initially registered via CRYPTO_get_ex_new_index() and can be used if
-the same callback handles different types of exdata.
-
-dup_func() is called when a structure is being copied. This is only done
-for B<SSL> and B<SSL_SESSION> objects. The B<to> and B<from> parameters
-are pointers to the destination and source B<CRYPTO_EX_DATA> structures,
-respectively. The B<srcp> parameter is a pointer to the source exdata.
-When the dup_func() returns, the value in B<srcp> is copied to the
-destination ex_data. If the pointer contained in B<srcp> is not modified
-by the dup_func(), then both B<to> and B<from> will point to the same data.
-The B<idx>, B<argl> and B<argp> parameters are as described for the other
-two callbacks.
-
-=head1 RETURN VALUES
-
-CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the
-value B<0> is reserved for the legacy "app_data" API's.
-
-CRYPTO_free_ex_index() and
-CRYPTO_set_ex_data() return 1 on success or 0 on failure.
-
-CRYPTO_get_ex_data() returns the application data or NULL on failure;
-note that NULL may be a valid value.
-
-dup_func() should return 0 for failure and 1 for success.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CTLOG_STORE_get0_log_by_id -
-Get a Certificate Transparency log from a CTLOG_STORE
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store,
- const uint8_t *log_id,
- size_t log_id_len);
-
-=head1 DESCRIPTION
-
-A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency
-(CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2).
-Therefore, it is useful to be able to look up more information about a log
-(e.g. its public key) using this LogID.
-
-CTLOG_STORE_get0_log_by_id() provides a way to do this. It will find a CTLOG
-in a CTLOG_STORE that has a given LogID.
-
-=head1 RETURN VALUES
-
-B<CTLOG_STORE_get0_log_by_id> returns a CTLOG with the given LogID, if it
-exists in the given CTLOG_STORE, otherwise it returns NULL.
-
-=head1 SEE ALSO
-
-L<ct(3)>,
-L<CTLOG_STORE_new(3)>
-
-=head1 HISTORY
-
-This function was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CTLOG_STORE_new, CTLOG_STORE_free,
-CTLOG_STORE_load_default_file, CTLOG_STORE_load_file -
-Create and populate a Certificate Transparency log list
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- CTLOG_STORE *CTLOG_STORE_new(void);
- void CTLOG_STORE_free(CTLOG_STORE *store);
-
- int CTLOG_STORE_load_default_file(CTLOG_STORE *store);
- int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file);
-
-=head1 DESCRIPTION
-
-A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency
-logs). The list can be loaded from one or more files and then searched by LogID
-(see RFC 6962, Section 3.2, for the definition of a LogID).
-
-CTLOG_STORE_new() creates an empty list of CT logs. This is then populated
-by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file().
-CTLOG_STORE_load_default_file() loads from the default file, which is named
-"ct_log_list.cnf" in OPENSSLDIR (see the output of L<version>). This can be
-overridden using an environment variable named "CTLOG_FILE".
-CTLOG_STORE_load_file() loads from a caller-specified file path instead.
-Both of these functions append any loaded CT logs to the CTLOG_STORE.
-
-The expected format of the file is:
-
- enabled_logs=foo,bar
-
- [foo]
- description = Log 1
- key = <base64-encoded DER SubjectPublicKeyInfo here>
-
- [bar]
- description = Log 2
- key = <base64-encoded DER SubjectPublicKeyInfo here>
-
-Once a CTLOG_STORE is no longer required, it should be passed to
-CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along
-with the CTLOG_STORE itself.
-
-=head1 NOTES
-
-If there are any invalid CT logs in a file, they are skipped and the remaining
-valid logs will still be added to the CTLOG_STORE. A CT log will be considered
-invalid if it is missing a "key" or "description" field.
-
-=head1 RETURN VALUES
-
-Both B<CTLOG_STORE_load_default_file> and B<CTLOG_STORE_load_file> return 1 if
-all CT logs in the file are successfully parsed and loaded, 0 otherwise.
-
-=head1 SEE ALSO
-
-L<ct(3)>,
-L<CTLOG_STORE_get0_log_by_id(3)>,
-L<SSL_CTX_set_ctlog_list_file(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CTLOG_new, CTLOG_new_from_base64, CTLOG_free,
-CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key -
-encapsulates information about a Certificate Transparency log
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);
- int CTLOG_new_from_base64(CTLOG ** ct_log,
- const char *pkey_base64, const char *name);
- void CTLOG_free(CTLOG *log);
- const char *CTLOG_get0_name(const CTLOG *log);
- void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id,
- size_t *log_id_len);
- EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log);
-
-=head1 DESCRIPTION
-
-CTLOG_new() returns a new CTLOG that represents the Certificate Transparency
-(CT) log with the given public key. A name must also be provided that can be
-used to help users identify this log. Ownership of the public key is
-transferred.
-
-CTLOG_new_from_base64() also creates a new CTLOG, but takes the public key in
-base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG.
-The base64 will be decoded and the public key parsed.
-
-Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the
-caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer
-needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that
-was passed to it.
-
-CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was
-created. Ownership of the string remains with the CTLOG.
-
-CTLOG_get0_log_id() sets *log_id to point to a string containing that log's
-LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a
-v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of
-the string remains with the CTLOG.
-
-CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the
-EVP_PKEY remains with the CTLOG.
-
-=head1 RETURN VALUES
-
-CTLOG_new() will return NULL if an error occurs.
-
-CTLOG_new_from_base64() will return 1 on success, 0 otherwise.
-
-=head1 SEE ALSO
-
-L<ct(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free,
-CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert,
-CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer,
-CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE -
-Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);
- void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);
- X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);
- int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert);
- X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);
- int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);
- const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);
- void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store);
-
-=head1 DESCRIPTION
-
-A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed
-Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy.
-This policy may be, for example, that at least one valid SCT is available. To
-determine this, an SCT's signature must be verified. This requires:
-
-=over
-
-=item * the public key of the log that issued the SCT
-
-=item * the certificate that the SCT was issued for
-
-=item * the issuer certificate (if the SCT was issued for a pre-certificate)
-
-=back
-
-The above requirements are met using the setters described below.
-
-CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This
-should then be populated using:
-
-=over
-
-=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for
-
-Increments the reference count of the certificate.
-
-=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate
-
-Increments the reference count of the certificate.
-
-=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs
-
-Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the
-CT_POLICY_EVAL_CTX.
-
-=back
-
-Each setter has a matching getter for accessing the current value.
-
-When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to
-CT_POLICY_EVAL_CTX_free() to delete it.
-
-=head1 NOTES
-
-The issuer certificate only needs to be provided if at least one of the SCTs
-was issued for a pre-certificate. This will be the case for SCTs embedded in a
-certificate (i.e. those in an X.509 extension), but may not be the case for SCTs
-found in the TLS SCT extension or OCSP response.
-
-=head1 RETURN VALUES
-
-CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails.
-
-=head1 SEE ALSO
-
-L<ct(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,
-DEFINE_SPECIAL_STACK_OF_CONST,
-OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
-OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free,
-OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null,
-OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push,
-OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort,
-OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero,
-sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_free,
-sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push,
-sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free,
-sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort,
-sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func -
-stack container
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- #include <openssl/safestack.h>
-
- STACK_OF(TYPE)
- DEFINE_STACK_OF(TYPE)
- DEFINE_STACK_OF_CONST(TYPE)
- DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)
- DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)
-
- typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);
- typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);
- typedef void (*sk_TYPE_freefunc)(TYPE *a);
-
- int sk_TYPE_num(const STACK_OF(TYPE) *sk);
- TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);
- STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);
- STACK_OF(TYPE) *sk_TYPE_new_null(void);
- void sk_TYPE_free(const STACK_OF(TYPE) *sk);
- void sk_TYPE_zero(const STACK_OF(TYPE) *sk);
- TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);
- TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);
- int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);
- int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);
- TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);
- TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);
- void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);
- int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);
- TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);
- int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);
- int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);
- void sk_TYPE_sort(const STACK_OF(TYPE) *sk);
- int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);
- STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);
- STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,
- sk_TYPE_copyfunc copyfunc,
- sk_TYPE_freefunc freefunc);
- sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, sk_TYPE_compfunc compare);
-
-=head1 DESCRIPTION
-
-Applications can create and use their own stacks by placing any of the macros
-described below in a header file. These macros define typesafe inline
-functions that wrap around the utility B<OPENSSL_sk_> API.
-In the description here, I<TYPE> is used
-as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
-
-STACK_OF() returns the name for a stack of the specified B<TYPE>.
-DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This
-will mean that type B<TYPE> is stored in each stack, the type is referenced by
-STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example:
-
- TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
-
-DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except
-each element is constant. For example:
-
- const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
-
-DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but
-each function uses B<FUNCNAME> in the function name. For example:
-
- TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
-
-DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is
-constant:
-
- const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
-
-sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is
-B<NULL>.
-
-sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at
-zero. If B<idx> is out of range then B<NULL> is returned.
-
-sk_TYPE_new() allocates a new empty stack using comparison function B<compar>.
-If B<compar> is B<NULL> then no comparison function is used.
-
-sk_TYPE_new_null() allocates a new empty stack with no comparison function.
-
-sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compar>.
-The previous comparison function is returned or B<NULL> if there was
-no previous comparison function.
-
-sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any
-elements of B<sk>. After this call B<sk> is no longer valid.
-
-sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free
-B<sk> so after this call B<sk> is still valid.
-
-sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The
-free function freefunc() is called on each element to free it.
-
-sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted
-element or B<NULL> if B<i> is out of range.
-
-sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns
-the deleted element or B<NULL> if no element matching B<ptr> was found.
-
-sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing
-elements at or after B<idx> are moved downwards. If B<idx> is out of range
-the new element is appended to B<sk>. sk_TYPE_insert() either returns the
-number of elements in B<sk> after the new element is inserted or zero if
-an error (such as memory allocation failure) occurred.
-
-sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to:
-
- sk_TYPE_insert(sk, ptr, -1);
-
-sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to:
-
- sk_TYPE_insert(sk, ptr, 0);
-
-sk_TYPE_pop() returns and removes the last element from B<sk>.
-
-sk_TYPE_shift() returns and removes the first element from B<sk>.
-
-sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current
-element. The new element value is returned or B<NULL> if an error occurred:
-this will only happen if B<sk> is B<NULL> or B<idx> is out of range.
-
-sk_TYPE_find() and sk_TYPE_find_ex() search B<sk> using the supplied
-comparison function for an element matching B<ptr>. sk_TYPE_find() returns
-the index of the first matching element or B<-1> if there is no match.
-sk_TYPE_find_ex() returns a matching element or the nearest element that
-does not match B<ptr>. Note: if a comparison function is set then B<sk> is
-sorted before the search which may change its order. If no comparison
-function is set then a linear search is made for a pointer matching B<ptr>
-and the stack is not reordered.
-
-sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
-
-sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
-
-sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy
-are identical to the original.
-
-sk_TYPE_deep_copy() returns a new stack where each element has been copied.
-Copying is performed by the supplied copyfunc() and freeing by freefunc(). The
-function freefunc() is only called if an error occurs.
-
-=head1 NOTES
-
-Care should be taken when accessing stacks in multi-threaded environments.
-Any operation which increases the size of a stack such as sk_TYPE_insert() or
-sk_push() can "grow" the size of an internal array and cause race conditions
-if the same stack is accessed in a different thread. Operations such as
-sk_find() and sk_sort() can also reorder the stack.
-
-Any comparison function supplied should use a metric suitable
-for use in a binary search operation. That is it should return zero, a
-positive or negative value if B<a> is equal to, greater than
-or less than B<b> respectively.
-
-Care should be taken when checking the return values of the functions
-sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the
-matching element. In particular B<0> indicates a matching first element.
-A failed search is indicated by a B<-1> return value.
-
-STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and
-DEFINE_SPECIAL_STACK_OF() are implemented as macros.
-
-=head1 RETURN VALUES
-
-sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
-passed stack is B<NULL>.
-
-sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
-index is out of range.
-
-sk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B<NULL> if
-an error occurs.
-
-sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if
-there was no old comparison function.
-
-sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do
-not return values.
-
-sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr()
-return a pointer to the deleted element or B<NULL> on error.
-
-sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total
-number of elements in the stack and 0 if an error occurred.
-
-sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on
-error.
-
-sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element
-or B<-1> on error.
-
-sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is
-not.
-
-sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the
-stack.
-
-=head1 HISTORY
-
-Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
-and was not a public API.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked,
-DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key,
-DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt,
-DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
-DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt,
-DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt,
-DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
-DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
-DES_fcrypt, DES_crypt - DES encryption
-
-=head1 SYNOPSIS
-
- #include <openssl/des.h>
-
- void DES_random_key(DES_cblock *ret);
-
- int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);
- int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);
- int DES_set_key_checked(const_DES_cblock *key,
- DES_key_schedule *schedule);
- void DES_set_key_unchecked(const_DES_cblock *key,
- DES_key_schedule *schedule);
-
- void DES_set_odd_parity(DES_cblock *key);
- int DES_is_weak_key(const_DES_cblock *key);
-
- void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,
- DES_key_schedule *ks, int enc);
- void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
- DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
- void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
- DES_key_schedule *ks1, DES_key_schedule *ks2,
- DES_key_schedule *ks3, int enc);
-
- void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,
- long length, DES_key_schedule *schedule, DES_cblock *ivec,
- int enc);
- void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
- int numbits, long length, DES_key_schedule *schedule,
- DES_cblock *ivec, int enc);
- void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
- int numbits, long length, DES_key_schedule *schedule,
- DES_cblock *ivec);
- void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
- long length, DES_key_schedule *schedule, DES_cblock *ivec,
- int enc);
- void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
- long length, DES_key_schedule *schedule, DES_cblock *ivec,
- int *num, int enc);
- void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,
- long length, DES_key_schedule *schedule, DES_cblock *ivec,
- int *num);
-
- void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,
- long length, DES_key_schedule *schedule, DES_cblock *ivec,
- const_DES_cblock *inw, const_DES_cblock *outw, int enc);
-
- void DES_ede2_cbc_encrypt(const unsigned char *input,
- unsigned char *output, long length, DES_key_schedule *ks1,
- DES_key_schedule *ks2, DES_cblock *ivec, int enc);
- void DES_ede2_cfb64_encrypt(const unsigned char *in,
- unsigned char *out, long length, DES_key_schedule *ks1,
- DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc);
- void DES_ede2_ofb64_encrypt(const unsigned char *in,
- unsigned char *out, long length, DES_key_schedule *ks1,
- DES_key_schedule *ks2, DES_cblock *ivec, int *num);
-
- void DES_ede3_cbc_encrypt(const unsigned char *input,
- unsigned char *output, long length, DES_key_schedule *ks1,
- DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec,
- int enc);
- void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
- long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
- DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc);
- void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
- long length, DES_key_schedule *ks1,
- DES_key_schedule *ks2, DES_key_schedule *ks3,
- DES_cblock *ivec, int *num);
-
- DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,
- long length, DES_key_schedule *schedule,
- const_DES_cblock *ivec);
- DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
- long length, int out_count, DES_cblock *seed);
- void DES_string_to_key(const char *str, DES_cblock *key);
- void DES_string_to_2keys(const char *str, DES_cblock *key1,
- DES_cblock *key2);
-
- char *DES_fcrypt(const char *buf, const char *salt, char *ret);
- char *DES_crypt(const char *buf, const char *salt);
-
-=head1 DESCRIPTION
-
-This library contains a fast implementation of the DES encryption
-algorithm.
-
-There are two phases to the use of DES encryption. The first is the
-generation of a I<DES_key_schedule> from a key, the second is the
-actual encryption. A DES key is of type I<DES_cblock>. This type is
-consists of 8 bytes with odd parity. The least significant bit in
-each byte is the parity bit. The key schedule is an expanded form of
-the key; it is used to speed the encryption process.
-
-DES_random_key() generates a random key. The PRNG must be seeded
-prior to using this function (see L<rand(3)>). If the PRNG
-could not generate a secure key, 0 is returned.
-
-Before a DES key can be used, it must be converted into the
-architecture dependent I<DES_key_schedule> via the
-DES_set_key_checked() or DES_set_key_unchecked() function.
-
-DES_set_key_checked() will check that the key passed is of odd parity
-and is not a week or semi-weak key. If the parity is wrong, then -1
-is returned. If the key is a weak key, then -2 is returned. If an
-error is returned, the key schedule is not generated.
-
-DES_set_key() works like
-DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
-otherwise like DES_set_key_unchecked(). These functions are available
-for compatibility; it is recommended to use a function that does not
-depend on a global variable.
-
-DES_set_odd_parity() sets the parity of the passed I<key> to odd.
-
-DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it
-is ok.
-
-The following routines mostly operate on an input and output stream of
-I<DES_cblock>s.
-
-DES_ecb_encrypt() is the basic DES encryption routine that encrypts or
-decrypts a single 8-byte I<DES_cblock> in I<electronic code book>
-(ECB) mode. It always transforms the input data, pointed to by
-I<input>, into the output data, pointed to by the I<output> argument.
-If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input>
-(cleartext) is encrypted in to the I<output> (ciphertext) using the
-key_schedule specified by the I<schedule> argument, previously set via
-I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now
-ciphertext) is decrypted into the I<output> (now cleartext). Input
-and output may overlap. DES_ecb_encrypt() does not return a value.
-
-DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using
-three-key Triple-DES encryption in ECB mode. This involves encrypting
-the input with I<ks1>, decrypting with the key schedule I<ks2>, and
-then encrypting with I<ks3>. This routine greatly reduces the chances
-of brute force breaking of DES and has the advantage of if I<ks1>,
-I<ks2> and I<ks3> are the same, it is equivalent to just encryption
-using ECB mode and I<ks1> as the key.
-
-The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES
-encryption by using I<ks1> for the final encryption.
-
-DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining>
-(CBC) mode of DES. If the I<encrypt> argument is non-zero, the
-routine cipher-block-chain encrypts the cleartext data pointed to by
-the I<input> argument into the ciphertext pointed to by the I<output>
-argument, using the key schedule provided by the I<schedule> argument,
-and initialization vector provided by the I<ivec> argument. If the
-I<length> argument is not an integral multiple of eight bytes, the
-last block is copied to a temporary area and zero filled. The output
-is always an integral multiple of eight bytes.
-
-DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and
-I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret
-(unlike the iv) and are as such, part of the key. So the key is sort
-of 24 bytes. This is much better than CBC DES.
-
-DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with
-three keys. This means that each DES operation inside the CBC mode is
-an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
-
-The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by
-reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>.
-This form of Triple-DES is used by the RSAREF library.
-
-DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block
-chaining mode used by Kerberos v4. Its parameters are the same as
-DES_ncbc_encrypt().
-
-DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This
-method takes an array of characters as input and outputs and array of
-characters. It does not require any padding to 8 character groups.
-Note: the I<ivec> variable is changed and the new changed value needs to
-be passed to the next call to this function. Since this function runs
-a complete DES ECB encryption per I<numbits>, this function is only
-suggested for use when sending small numbers of characters.
-
-DES_cfb64_encrypt()
-implements CFB mode of DES with 64bit feedback. Why is this
-useful you ask? Because this routine will allow you to encrypt an
-arbitrary number of bytes, no 8 byte padding. Each call to this
-routine will encrypt the input bytes to output and then update ivec
-and num. num contains 'how far' we are though ivec. If this does
-not make much sense, read more about cfb mode of DES :-).
-
-DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as
-DES_cfb64_encrypt() except that Triple-DES is used.
-
-DES_ofb_encrypt() encrypts using output feedback mode. This method
-takes an array of characters as input and outputs and array of
-characters. It does not require any padding to 8 character groups.
-Note: the I<ivec> variable is changed and the new changed value needs to
-be passed to the next call to this function. Since this function runs
-a complete DES ECB encryption per numbits, this function is only
-suggested for use when sending small numbers of characters.
-
-DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output
-Feed Back mode.
-
-DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as
-DES_ofb64_encrypt(), using Triple-DES.
-
-The following functions are included in the DES library for
-compatibility with the MIT Kerberos library.
-
-DES_cbc_cksum() produces an 8 byte checksum based on the input stream
-(via CBC encryption). The last 4 bytes of the checksum are returned
-and the complete 8 bytes are placed in I<output>. This function is
-used by Kerberos v4. Other applications should use
-L<EVP_DigestInit(3)> etc. instead.
-
-DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte
-checksum from the input bytes. The algorithm can be iterated over the
-input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is
-non-NULL, the 8 bytes generated by each pass are written into
-I<output>.
-
-The following are DES-based transformations:
-
-DES_fcrypt() is a fast version of the Unix crypt(3) function. This
-version takes only a small amount of space relative to other fast
-crypt() implementations. This is different to the normal crypt in
-that the third parameter is the buffer that the return value is
-written into. It needs to be at least 14 bytes long. This function
-is thread safe, unlike the normal crypt.
-
-DES_crypt() is a faster replacement for the normal system crypt().
-This function calls DES_fcrypt() with a static array passed as the
-third parameter. This mostly emulates the normal non-thread-safe semantics
-of crypt(3).
-The B<salt> must be two ASCII characters.
-
-DES_enc_write() writes I<len> bytes to file descriptor I<fd> from
-buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default)
-using I<sched> for the key and I<iv> as a starting vector. The actual
-data send down I<fd> consists of 4 bytes (in network byte order)
-containing the length of the following encrypted data. The encrypted
-data then follows, padded with random data out to a multiple of 8
-bytes.
-
-=head1 BUGS
-
-DES_3cbc_encrypt() is flawed and must not be used in applications.
-
-DES_cbc_encrypt() does not modify B<ivec>; use DES_ncbc_encrypt()
-instead.
-
-DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits.
-What this means is that if you set numbits to 12, and length to 2, the
-first 12 bits will come from the 1st input byte and the low half of
-the second input byte. The second 12 bits will have the low 8 bits
-taken from the 3rd input byte and the top 4 bits taken from the 4th
-input byte. The same holds for output. This function has been
-implemented this way because most people will be using a multiple of 8
-and because once you get into pulling bytes input bytes apart things
-get ugly!
-
-DES_string_to_key() is available for backward compatibility with the
-MIT library. New applications should use a cryptographic hash function.
-The same applies for DES_string_to_2key().
-
-=head1 NOTES
-
-The B<des> library was written to be source code compatible with
-the MIT Kerberos library.
-
-Applications should use the higher level functions
-L<EVP_EncryptInit(3)> etc. instead of calling these
-functions directly.
-
-Single-key DES is insecure due to its short key size. ECB mode is
-not suitable for most applications; see L<des_modes(7)>.
-
-=head1 HISTORY
-
-The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
-be two ASCII characters was first enforced in
-OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A>
-if both character were not present, and could crash when given non-ASCII
-on some platforms.
-
-=head1 SEE ALSO
-
-L<des_modes(7)>,
-L<EVP_EncryptInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
-
- int DH_generate_key(DH *dh);
-
- int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
-
-=head1 DESCRIPTION
-
-DH_generate_key() performs the first step of a Diffie-Hellman key
-exchange by generating private and public DH values. By calling
-DH_compute_key(), these are combined with the other party's public
-value to compute the shared key.
-
-DH_generate_key() expects B<dh> to contain the shared parameters
-B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value
-unless B<dh-E<gt>priv_key> is already set, and computes the
-corresponding public value B<dh-E<gt>pub_key>, which can then be
-published.
-
-DH_compute_key() computes the shared secret from the private DH value
-in B<dh> and the other party's public value in B<pub_key> and stores
-it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory.
-
-=head1 RETURN VALUES
-
-DH_generate_key() returns 1 on success, 0 otherwise.
-
-DH_compute_key() returns the size of the shared secret on success, -1
-on error.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>, L<DH_size(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_generate_parameters_ex, DH_generate_parameters,
-DH_check - generate and check Diffie-Hellman parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
-
- int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);
-
- int DH_check(DH *dh, int *codes);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x00908000L
- DH *DH_generate_parameters(int prime_len, int generator,
- void (*callback)(int, int, void *), void *cb_arg);
- #endif
-
-=head1 DESCRIPTION
-
-DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
-be shared among a group of users, and stores them in the provided B<DH>
-structure. The pseudo-random number generator must be
-seeded prior to calling DH_generate_parameters().
-
-B<prime_len> is the length in bits of the safe prime to be generated.
-B<generator> is a small number E<gt> 1, typically 2 or 5.
-
-A callback function may be used to provide feedback about the progress
-of the key generation. If B<cb> is not B<NULL>, it will be
-called as described in L<BN_generate_prime(3)> while a random prime
-number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)>
-is called. See L<BN_generate_prime(3)> for information on
-the BN_GENCB_call() function.
-
-DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The
-value of B<*codes> is updated with any problems found. If B<*codes> is zero then
-no problems were found, otherwise the following bits may be set:
-
-=over 4
-
-=item DH_CHECK_P_NOT_PRIME
-
-The parameter B<p> is not prime.
-
-=item DH_CHECK_P_NOT_SAFE_PRIME
-
-The parameter B<p> is not a safe prime and no B<q> value is present.
-
-=item DH_UNABLE_TO_CHECK_GENERATOR
-
-The generator B<g> cannot be checked for suitability.
-
-=item DH_NOT_SUITABLE_GENERATOR
-
-The generator B<g> is not suitable.
-
-=item DH_CHECK_Q_NOT_PRIME
-
-The parameter B<q> is not prime.
-
-=item DH_CHECK_INVALID_Q_VALUE
-
-The parameter B<q> is invalid.
-
-=item DH_CHECK_INVALID_J_VALUE
-
-The parameter B<j> is invalid.
-
-=back
-
-=head1 RETURN VALUES
-
-DH_generate_parameters_ex() and DH_check() return 1 if the check could be
-performed, 0 otherwise.
-
-DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or
-NULL if the parameter generation fails.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 NOTES
-
-DH_generate_parameters_ex() and DH_generate_parameters() may run for several
-hours before finding a suitable prime.
-
-The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters()
-are not to be used in signature schemes.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>,
-L<DH_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_clear_flags,
-DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length,
-DH_set_length - Routines for getting and setting data in a DH object
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
-
- void DH_get0_pqg(const DH *dh,
- const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);
- int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);
- void DH_get0_key(const DH *dh,
- const BIGNUM **pub_key, const BIGNUM **priv_key);
- int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key);
- void DH_clear_flags(DH *dh, int flags);
- int DH_test_flags(const DH *dh, int flags);
- void DH_set_flags(DH *dh, int flags);
- ENGINE *DH_get0_engine(DH *d);
- long DH_get_length(const DH *dh);
- int DH_set_length(DH *dh, long length);
-
-=head1 DESCRIPTION
-
-A DH object contains the parameters B<p>, B<q> and B<g>. Note that the B<q>
-parameter is optional. It also contains a public key (B<pub_key>) and
-(optionally) a private key (B<priv_key>).
-
-The B<p>, B<q> and B<g> parameters can be obtained by calling DH_get0_pqg().
-If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set
-to NULL. Otherwise they are set to pointers to their respective values. These
-point directly to the internal representations of the values and therefore
-should not be freed directly.
-
-The B<p>, B<q> and B<g> values can be set by calling DH_set0_pqg() and passing
-the new values for B<p>, B<q> and B<g> as parameters to the function. Calling
-this function transfers the memory management of the values to the DH object,
-and therefore the values that have been passed in should not be freed directly
-after this function has been called. The B<q> parameter may be NULL.
-
-To get the public and private key values use the DH_get0_key() function. A
-pointer to the public key will be stored in B<*pub_key>, and a pointer to the
-private key will be stored in B<*priv_key>. Either may be NULL if they have not
-been set yet, although if the private key has been set then the public key must
-be. The values point to the internal representation of the public key and
-private key values. This memory should not be freed directly.
-
-The public and private key values can be set using DH_set0_key(). The public
-key must be non-NULL the first time this function is called on a given DH
-object. The private key may be NULL. On subsequent calls, either may be NULL,
-which means the corresponding DH field is left untouched. As for DH_set0_pqg()
-this function transfers the memory management of the key values to the DH
-object, and therefore they should not be freed directly after this function has
-been called.
-
-DH_set_flags() sets the flags in the B<flags> parameter on the DH object.
-Multiple flags can be passed in one go (bitwise ORed together). Any flags that
-are already set are left set. DH_test_flags() tests to see whether the flags
-passed in the B<flags> parameter are currently set in the DH object. Multiple
-flags can be tested in one go. All flags that are currently set are returned, or
-zero if none of the flags are set. DH_clear_flags() clears the specified flags
-within the DH object.
-
-DH_get0_engine() returns a handle to the ENGINE that has been set for this DH
-object, or NULL if no such ENGINE has been set.
-
-The DH_get_length() and DH_set_length() functions get and set the optional
-length parameter associated with this DH object. If the length is non-zero then
-it is used, otherwise it is ignored. The B<length> parameter indicates the
-length of the secret exponent (private key) in bits.
-
-=head1 NOTES
-
-Values retrieved with DH_get0_key() are owned by the DH object used
-in the call and may therefore I<not> be passed to DH_set0_key(). If
-needed, duplicate the received value using BN_dup() and pass the
-duplicate. The same applies to DH_get0_pqg() and DH_set0_pqg().
-
-=head1 RETURN VALUES
-
-DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure.
-
-DH_test_flags() returns the current state of the flags in the DH object.
-
-DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE
-has been set.
-
-DH_get_length() returns the length of the secret exponent (private key) in bits,
-or zero if no such length has been explicitly set.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
-L<DH_set_method(3)>, L<DH_size(3)>, L<DH_meth_new(3)>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_get_1024_160,
-DH_get_2048_224,
-DH_get_2048_256,
-BN_get0_nist_prime_192,
-BN_get0_nist_prime_224,
-BN_get0_nist_prime_256,
-BN_get0_nist_prime_384,
-BN_get0_nist_prime_521,
-BN_get_rfc2409_prime_768,
-BN_get_rfc2409_prime_1024,
-BN_get_rfc3526_prime_1536,
-BN_get_rfc3526_prime_2048,
-BN_get_rfc3526_prime_3072,
-BN_get_rfc3526_prime_4096,
-BN_get_rfc3526_prime_6144,
-BN_get_rfc3526_prime_8192
-- Create standardized public primes or DH pairs
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
- DH *DH_get_1024_160(void)
- DH *DH_get_2048_224(void)
- DH *DH_get_2048_256(void)
-
- const BIGNUM *BN_get0_nist_prime_192(void)
- const BIGNUM *BN_get0_nist_prime_224(void)
- const BIGNUM *BN_get0_nist_prime_256(void)
- const BIGNUM *BN_get0_nist_prime_384(void)
- const BIGNUM *BN_get0_nist_prime_521(void)
-
- BIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn)
- BIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn)
- BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn)
- BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn)
- BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn)
- BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn)
- BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn)
- BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn)
-
-=head1 DESCRIPTION
-
-DH_get_1024_160(), DH_get_2048_224(), and DH_get_2048_256() each return
-a DH object for the IETF RFC 5114 value.
-
-BN_get0_nist_prime_192(), BN_get0_nist_prime_224(), BN_get0_nist_prime_256(),
-BN_get0_nist_prime_384(), and BN_get0_nist_prime_521() functions return
-a BIGNUM for the specific NIST prime curve (e.g., P-256).
-
-BN_get_rfc2409_prime_768(), BN_get_rfc2409_prime_1024(),
-BN_get_rfc3526_prime_1536(), BN_get_rfc3526_prime_2048(),
-BN_get_rfc3526_prime_3072(), BN_get_rfc3526_prime_4096(),
-BN_get_rfc3526_prime_6144(), and BN_get_rfc3526_prime_8192() functions
-return a BIGNUM for the specified size from IETF RFC 2409. If B<bn>
-is not NULL, the BIGNUM will be set into that location as well.
-
-=head1 RETURN VALUES
-
-Defined above.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name,
-DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data,
-DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key,
-DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp,
-DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish,
-DH_meth_set_finish, DH_meth_get_generate_params,
-DH_meth_set_generate_params - Routines to build up DH methods
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
-
- DH_METHOD *DH_meth_new(const char *name, int flags);
- void DH_meth_free(DH_METHOD *dhm);
- DH_METHOD *DH_meth_dup(const DH_METHOD *dhm);
- const char *DH_meth_get0_name(const DH_METHOD *dhm);
- int DH_meth_set1_name(DH_METHOD *dhm, const char *name);
- int DH_meth_get_flags(DH_METHOD *dhm);
- int DH_meth_set_flags(DH_METHOD *dhm, int flags);
- void *DH_meth_get0_app_data(const DH_METHOD *dhm);
- int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data);
- int (*DH_meth_get_generate_key(const DH_METHOD *dhm)) (DH *);
- int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key) (DH *));
- int (*DH_meth_get_compute_key(const DH_METHOD *dhm))
- (unsigned char *key, const BIGNUM *pub_key, DH *dh);
- int DH_meth_set_compute_key(DH_METHOD *dhm,
- int (*compute_key) (unsigned char *key, const BIGNUM *pub_key, DH *dh));
- int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm))
- (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
- const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
- int DH_meth_set_bn_mod_exp(DH_METHOD *dhm,
- int (*bn_mod_exp) (const DH *dh, BIGNUM *r, const BIGNUM *a,
- const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,
- BN_MONT_CTX *m_ctx));
- int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *);
- int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *));
- int (*DH_meth_get_finish(const DH_METHOD *dhm)) (DH *);
- int DH_meth_set_finish(DH_METHOD *dhm, int (*finish) (DH *));
- int (*DH_meth_get_generate_params(const DH_METHOD *dhm))
- (DH *, int, int, BN_GENCB *);
- int DH_meth_set_generate_params(DH_METHOD *dhm,
- int (*generate_params) (DH *, int, int, BN_GENCB *));
-
-=head1 DESCRIPTION
-
-The B<DH_METHOD> type is a structure used for the provision of custom DH
-implementations. It provides a set of of functions used by OpenSSL for the
-implementation of the various DH capabilities.
-
-DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a
-unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated
-string, which will be duplicated and stored in the B<DH_METHOD> object. It is
-the callers responsibility to free the original string. The flags will be used
-during the construction of a new B<DH> object based on this B<DH_METHOD>. Any
-new B<DH> object will have those flags set by default.
-
-DH_meth_dup() creates a duplicate copy of the B<DH_METHOD> object passed as a
-parameter. This might be useful for creating a new B<DH_METHOD> based on an
-existing one, but with some differences.
-
-DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory
-associated with it.
-
-DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This
-is a pointer to the internal name string and so should not be freed by the
-caller. DH_meth_set1_name() sets the name of the DH_METHOD to B<name>. The
-string is duplicated and the copy is stored in the DH_METHOD structure, so the
-caller remains responsible for freeing the memory associated with the name.
-
-DH_meth_get_flags() returns the current value of the flags associated with this
-DH_METHOD. DH_meth_set_flags() provides the ability to set these flags.
-
-The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the
-ability to associate implementation specific data with the DH_METHOD. It is
-the application's responsibility to free this data before the DH_METHOD is
-freed via a call to DH_meth_free().
-
-DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the
-function used for generating a new DH key pair respectively. This function will
-be called in response to the application calling DH_generate_key(). The
-parameter for the function has the same meaning as for DH_generate_key().
-
-DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the
-function used for computing a new DH shared secret respectively. This function
-will be called in response to the application calling DH_compute_key(). The
-parameters for the function have the same meaning as for DH_compute_key().
-
-DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function
-used for computing the following value:
-
- r = a ^ p mod m
-
-This function will be called by the default OpenSSL function for
-DH_generate_key(). The result is stored in the B<r> parameter. This function
-may be NULL unless using the default generate key function, in which case it
-must be present.
-
-DH_meth_get_init() and DH_meth_set_init() get and set the function used
-for creating a new DH instance respectively. This function will be
-called in response to the application calling DH_new() (if the current default
-DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method()
-functions will allocate the memory for the new DH object, and a pointer to this
-newly allocated structure will be passed as a parameter to the function. This
-function may be NULL.
-
-DH_meth_get_finish() and DH_meth_set_finish() get and set the function used
-for destroying an instance of a DH object respectively. This function will be
-called in response to the application calling DH_free(). A pointer to the DH
-to be destroyed is passed as a parameter. The destroy function should be used
-for DH implementation specific clean up. The memory for the DH itself should
-not be freed by this function. This function may be NULL.
-
-DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the
-function used for generating DH parameters respectively. This function will be
-called in response to the application calling DH_generate_parameters_ex() (or
-DH_generate_parameters()). The parameters for the function have the same
-meaning as for DH_generate_parameters_ex(). This function may be NULL.
-
-=head1 RETURN VALUES
-
-DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object
-or NULL on failure.
-
-DH_meth_get0_name() and DH_meth_get_flags() return the name and flags
-associated with the DH_METHOD respectively.
-
-All other DH_meth_get_*() functions return the appropriate function pointer
-that has been set in the DH_METHOD, or NULL if no such pointer has yet been
-set.
-
-DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or
-0 on failure.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
-L<DH_set_method(3)>, L<DH_size(3)>, L<DH_get0_pqg(3)>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_new, DH_free - allocate and free DH objects
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
-
- DH* DH_new(void);
-
- void DH_free(DH *dh);
-
-=head1 DESCRIPTION
-
-DH_new() allocates and initializes a B<DH> structure.
-
-DH_free() frees the B<DH> structure and its components. The values are
-erased before the memory is returned to the system.
-If B<dh> is NULL nothing is done.
-
-=head1 RETURN VALUES
-
-If the allocation fails, DH_new() returns B<NULL> and sets an error
-code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns
-a pointer to the newly allocated structure.
-
-DH_free() returns no value.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<ERR_get_error(3)>,
-L<DH_generate_parameters(3)>,
-L<DH_generate_key(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_set_default_method, DH_get_default_method,
-DH_set_method, DH_new_method, DH_OpenSSL - select DH method
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
-
- void DH_set_default_method(const DH_METHOD *meth);
-
- const DH_METHOD *DH_get_default_method(void);
-
- int DH_set_method(DH *dh, const DH_METHOD *meth);
-
- DH *DH_new_method(ENGINE *engine);
-
- const DH_METHOD *DH_OpenSSL(void);
-
-=head1 DESCRIPTION
-
-A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
-operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
-important information about how these DH API functions are affected by the use
-of B<ENGINE> API calls.
-
-Initially, the default DH_METHOD is the OpenSSL internal implementation, as
-returned by DH_OpenSSL().
-
-DH_set_default_method() makes B<meth> the default method for all DH
-structures created later. B<NB>: This is true only whilst no ENGINE has been set
-as a default for DH, so this function is no longer recommended.
-
-DH_get_default_method() returns a pointer to the current default DH_METHOD.
-However, the meaningfulness of this result is dependent on whether the ENGINE
-API is being used, so this function is no longer recommended.
-
-DH_set_method() selects B<meth> to perform all operations using the key B<dh>.
-This will replace the DH_METHOD used by the DH key and if the previous method
-was supplied by an ENGINE, the handle to that ENGINE will be released during the
-change. It is possible to have DH keys that only work with certain DH_METHOD
-implementations (eg. from an ENGINE module that supports embedded
-hardware-protected keys), and in such cases attempting to change the DH_METHOD
-for the key can have unexpected results.
-
-DH_new_method() allocates and initializes a DH structure so that B<engine> will
-be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
-operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
-DH_set_default_method() is used.
-
-A new DH_METHOD object may be constructed using DH_meth_new() (see
-L<DH_meth_new(3)>).
-
-=head1 RETURN VALUES
-
-DH_OpenSSL() and DH_get_default_method() return pointers to the respective
-B<DH_METHOD>s.
-
-DH_set_default_method() returns no value.
-
-DH_set_method() returns non-zero if the provided B<meth> was successfully set as
-the method for B<dh> (including unloading the ENGINE handle if the previous
-method was supplied by an ENGINE).
-
-DH_new_method() returns NULL and sets an error code that can be obtained by
-L<ERR_get_error(3)> if the allocation fails. Otherwise it
-returns a pointer to the newly allocated structure.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<DH_new(3)>, L<DH_meth_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DH_size, DH_bits - get Diffie-Hellman prime size
-
-=head1 SYNOPSIS
-
-#include <openssl/dh.h>
-
-int DH_size(const DH *dh);
-
-int DH_bits(const DH *dh);
-
-=head1 DESCRIPTION
-
-DH_size() returns the Diffie-Hellman prime size in bytes. It can be used
-to determine how much memory must be allocated for the shared secret
-computed by DH_compute_key().
-
-DH_bits() returns the number of significant bits.
-
-B<dh> and B<dh-E<gt>p> must not be B<NULL>.
-
-=head1 RETURN VALUE
-
-The size.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<DH_generate_key(3)>,
-L<BN_num_bits(3)>
-
-=head1 HISTORY
-
-DH_bits() was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_SIG_get0, DSA_SIG_set0,
-DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- DSA_SIG *DSA_SIG_new(void);
- void DSA_SIG_free(DSA_SIG *a);
- void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
- int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s);
-
-=head1 DESCRIPTION
-
-DSA_SIG_new() allocates an empty B<DSA_SIG> structure.
-
-DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
-values are erased before the memory is returned to the system.
-
-DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained
-in B<sig>.
-
-The B<r> and B<s> values can be set by calling DSA_SIG_set0() and passing the
-new values for B<r> and B<s> as parameters to the function. Calling this
-function transfers the memory management of the values to the DSA_SIG object,
-and therefore the values that have been passed in should not be freed directly
-after this function has been called.
-
-=head1 RETURN VALUES
-
-If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an
-error code that can be obtained by
-L<ERR_get_error(3)>. Otherwise it returns a pointer
-to the newly allocated structure.
-
-DSA_SIG_free() returns no value.
-
-DSA_SIG_set0() returns 1 on success or 0 on failure.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<ERR_get_error(3)>,
-L<DSA_do_sign(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_do_sign, DSA_do_verify - raw DSA signature operations
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
-
- int DSA_do_verify(const unsigned char *dgst, int dgst_len,
- DSA_SIG *sig, DSA *dsa);
-
-=head1 DESCRIPTION
-
-DSA_do_sign() computes a digital signature on the B<len> byte message
-digest B<dgst> using the private key B<dsa> and returns it in a
-newly allocated B<DSA_SIG> structure.
-
-L<DSA_sign_setup(3)> may be used to precompute part
-of the signing operation in case signature generation is
-time-critical.
-
-DSA_do_verify() verifies that the signature B<sig> matches a given
-message digest B<dgst> of size B<len>. B<dsa> is the signer's public
-key.
-
-=head1 RETURN VALUES
-
-DSA_do_sign() returns the signature, NULL on error. DSA_do_verify()
-returns 1 for a valid signature, 0 for an incorrect signature and -1
-on error. The error codes can be obtained by
-L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
-L<DSA_SIG_new(3)>,
-L<DSA_sign(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_dup_DH - create a DH structure out of DSA structure
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- DH * DSA_dup_DH(const DSA *r);
-
-=head1 DESCRIPTION
-
-DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
-is lost during that conversion, but the resulting DH parameters
-contain its length.
-
-=head1 RETURN VALUE
-
-DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The
-error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 NOTE
-
-Be careful to avoid small subgroup attacks when using this.
-
-=head1 SEE ALSO
-
-L<dh(3)>, L<dsa(3)>, L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_generate_key - generate DSA key pair
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- int DSA_generate_key(DSA *a);
-
-=head1 DESCRIPTION
-
-DSA_generate_key() expects B<a> to contain DSA parameters. It generates
-a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
-
-The PRNG must be seeded prior to calling DSA_generate_key().
-
-=head1 RETURN VALUE
-
-DSA_generate_key() returns 1 on success, 0 otherwise.
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
-L<DSA_generate_parameters(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- int DSA_generate_parameters_ex(DSA *dsa, int bits,
- const unsigned char *seed, int seed_len,
- int *counter_ret, unsigned long *h_ret, BN_GENCB *cb);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x00908000L
- DSA *DSA_generate_parameters(int bits, unsigned char *seed,
- int seed_len, int *counter_ret, unsigned long *h_ret,
- void (*callback)(int, int, void *), void *cb_arg);
- #endif
-
-=head1 DESCRIPTION
-
-DSA_generate_parameters_ex() generates primes p and q and a generator g
-for use in the DSA and stores the result in B<dsa>.
-
-B<bits> is the length of the prime p to be generated.
-For lengths under 2048 bits, the length of q is 160 bits; for lengths
-greater than or equal to 2048 bits, the length of q is set to 256 bits.
-
-If B<seed> is NULL, the primes will be generated at random.
-If B<seed_len> is less than the length of q, an error is returned.
-
-DSA_generate_parameters_ex() places the iteration count in
-*B<counter_ret> and a counter used for finding a generator in
-*B<h_ret>, unless these are B<NULL>.
-
-A callback function may be used to provide feedback about the progress
-of the key generation. If B<cb> is not B<NULL>, it will be
-called as shown below. For information on the BN_GENCB structure and the
-BN_GENCB_call function discussed below, refer to
-L<BN_generate_prime(3)>.
-
-=over 4
-
-=item *
-
-When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called
-(m is 0 for the first candidate).
-
-=item *
-
-When a candidate for q has passed a test by trial division,
-B<BN_GENCB_call(cb, 1, -1)> is called.
-While a candidate for q is tested by Miller-Rabin primality tests,
-B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
-(once for each witness that confirms that the candidate may be prime);
-i is the loop counter (starting at 0).
-
-=item *
-
-When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and
-B<BN_GENCB_call(cb, 3, 0)> are called.
-
-=item *
-
-Before a candidate for p (other than the first) is generated and tested,
-B<BN_GENCB_call(cb, 0, counter)> is called.
-
-=item *
-
-When a candidate for p has passed the test by trial division,
-B<BN_GENCB_call(cb, 1, -1)> is called.
-While it is tested by the Miller-Rabin primality test,
-B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
-(once for each witness that confirms that the candidate may be prime).
-i is the loop counter (starting at 0).
-
-=item *
-
-When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called.
-
-=item *
-
-When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called.
-
-=back
-
-DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and
-instead a newly allocated B<DSA> structure is returned. Additionally "old
-style" callbacks are used instead of the newer BN_GENCB based approach.
-Refer to L<BN_generate_prime(3)> for further information.
-
-=head1 RETURN VALUE
-
-DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise.
-
-DSA_generate_parameters() returns a pointer to the DSA structure, or
-B<NULL> if the parameter generation fails.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 BUGS
-
-Seed lengths E<gt> 20 are not supported.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
-L<DSA_free(3)>, L<BN_generate_prime(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, DSA_clear_flags,
-DSA_test_flags, DSA_set_flags, DSA_get0_engine - Routines for getting and
-setting data in a DSA object
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- void DSA_get0_pqg(const DSA *d,
- const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);
- int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g);
- void DSA_get0_key(const DSA *d,
- const BIGNUM **pub_key, const BIGNUM **priv_key);
- int DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key);
- void DSA_clear_flags(DSA *d, int flags);
- int DSA_test_flags(const DSA *d, int flags);
- void DSA_set_flags(DSA *d, int flags);
- ENGINE *DSA_get0_engine(DSA *d);
-
-=head1 DESCRIPTION
-
-A DSA object contains the parameters B<p>, B<q> and B<g>. It also contains a
-public key (B<pub_key>) and (optionally) a private key (B<priv_key>).
-
-The B<p>, B<q> and B<g> parameters can be obtained by calling DSA_get0_pqg().
-If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set
-to NULL. Otherwise they are set to pointers to their respective values. These
-point directly to the internal representations of the values and therefore
-should not be freed directly.
-
-The B<p>, B<q> and B<g> values can be set by calling DSA_set0_pqg() and passing
-the new values for B<p>, B<q> and B<g> as parameters to the function. Calling
-this function transfers the memory management of the values to the DSA object,
-and therefore the values that have been passed in should not be freed directly
-after this function has been called.
-
-To get the public and private key values use the DSA_get0_key() function. A
-pointer to the public key will be stored in B<*pub_key>, and a pointer to the
-private key will be stored in B<*priv_key>. Either may be NULL if they have not
-been set yet, although if the private key has been set then the public key must
-be. The values point to the internal representation of the public key and
-private key values. This memory should not be freed directly.
-
-The public and private key values can be set using DSA_set0_key(). The public
-key must be non-NULL the first time this function is called on a given DSA
-object. The private key may be NULL. On subsequent calls, either may be NULL,
-which means the corresponding DSA field is left untouched. As for DSA_set0_pqg()
-this function transfers the memory management of the key values to the DSA
-object, and therefore they should not be freed directly after this function has
-been called.
-
-DSA_set_flags() sets the flags in the B<flags> parameter on the DSA object.
-Multiple flags can be passed in one go (bitwise ORed together). Any flags that
-are already set are left set. DSA_test_flags() tests to see whether the flags
-passed in the B<flags> parameter are currently set in the DSA object. Multiple
-flags can be tested in one go. All flags that are currently set are returned, or
-zero if none of the flags are set. DSA_clear_flags() clears the specified flags
-within the DSA object.
-
-DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA
-object, or NULL if no such ENGINE has been set.
-
-=head1 NOTES
-
-Values retrieved with DSA_get0_key() are owned by the DSA object used
-in the call and may therefore I<not> be passed to DSA_set0_key(). If
-needed, duplicate the received value using BN_dup() and pass the
-duplicate. The same applies to DSA_get0_pqg() and DSA_set0_pqg().
-
-=head1 RETURN VALUES
-
-DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure.
-
-DSA_test_flags() returns the current state of the flags in the DSA object.
-
-DSA_get0_engine() returns the ENGINE set for the DSA object or NULL if no ENGINE
-has been set.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>,
-L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>,
-L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_meth_new(3)>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name,
-DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags,
-DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign,
-DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup,
-DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp,
-DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp,
-DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish,
-DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen,
-DSA_meth_set_keygen - Routines to build up DSA methods
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- DSA_METHOD *DSA_meth_new(const char *name, int flags);
- void DSA_meth_free(DSA_METHOD *dsam);
- DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth);
- const char *DSA_meth_get0_name(const DSA_METHOD *dsam);
- int DSA_meth_set1_name(DSA_METHOD *dsam, const char *name);
- int DSA_meth_get_flags(DSA_METHOD *dsam);
- int DSA_meth_set_flags(DSA_METHOD *dsam, int flags);
- void *DSA_meth_get0_app_data(const DSA_METHOD *dsam);
- int DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data);
- DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))
- (const unsigned char *, int, DSA *);
- int DSA_meth_set_sign(DSA_METHOD *dsam,
- DSA_SIG *(*sign) (const unsigned char *, int, DSA *));
- int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))
- (DSA *, BN_CTX *, BIGNUM **, BIGNUM **);
- int DSA_meth_set_sign_setup(DSA_METHOD *dsam,
- int (*sign_setup) (DSA *, BN_CTX *, BIGNUM **, BIGNUM **));
- int (*DSA_meth_get_verify(const DSA_METHOD *dsam))
- (const unsigned char *, int , DSA_SIG *, DSA *);
- int DSA_meth_set_verify(DSA_METHOD *dsam,
- int (*verify) (const unsigned char *, int, DSA_SIG *, DSA *));
- int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))
- (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2, BIGNUM *p2,
- BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont);
- int DSA_meth_set_mod_exp(DSA_METHOD *dsam,
- int (*mod_exp) (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2,
- BIGNUM *p2, BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont));
- int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))
- (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m,
- BN_CTX *ctx, BN_MONT_CTX *mont);
- int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam,
- int (*bn_mod_exp) (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
- const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont));
- int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *);
- int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *));
- int (*DSA_meth_get_finish(const DSA_METHOD *dsam)) (DSA *);
- int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish) (DSA *));
- int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))
- (DSA *, int, const unsigned char *, int, int *, unsigned long *,
- BN_GENCB *);
- int DSA_meth_set_paramgen(DSA_METHOD *dsam,
- int (*paramgen) (DSA *, int, const unsigned char *, int, int *,
- unsigned long *, BN_GENCB *));
- int (*DSA_meth_get_keygen(const DSA_METHOD *dsam)) (DSA *);
- int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen) (DSA *));
-
-=head1 DESCRIPTION
-
-The B<DSA_METHOD> type is a structure used for the provision of custom DSA
-implementations. It provides a set of of functions used by OpenSSL for the
-implementation of the various DSA capabilities. See the L<dsa> page for more
-information.
-
-DSA_meth_new() creates a new B<DSA_METHOD> structure. It should be given a
-unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated
-string, which will be duplicated and stored in the B<DSA_METHOD> object. It is
-the callers responsibility to free the original string. The flags will be used
-during the construction of a new B<DSA> object based on this B<DSA_METHOD>. Any
-new B<DSA> object will have those flags set by default.
-
-DSA_meth_dup() creates a duplicate copy of the B<DSA_METHOD> object passed as a
-parameter. This might be useful for creating a new B<DSA_METHOD> based on an
-existing one, but with some differences.
-
-DSA_meth_free() destroys a B<DSA_METHOD> structure and frees up any memory
-associated with it.
-
-DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This
-is a pointer to the internal name string and so should not be freed by the
-caller. DSA_meth_set1_name() sets the name of the DSA_METHOD to B<name>. The
-string is duplicated and the copy is stored in the DSA_METHOD structure, so the
-caller remains responsible for freeing the memory associated with the name.
-
-DSA_meth_get_flags() returns the current value of the flags associated with this
-DSA_METHOD. DSA_meth_set_flags() provides the ability to set these flags.
-
-The functions DSA_meth_get0_app_data() and DSA_meth_set0_app_data() provide the
-ability to associate implementation specific data with the DSA_METHOD. It is
-the application's responsibility to free this data before the DSA_METHOD is
-freed via a call to DSA_meth_free().
-
-DSA_meth_get_sign() and DSA_meth_set_sign() get and set the function used for
-creating a DSA signature respectively. This function will be
-called in response to the application calling DSA_do_sign() (or DSA_sign()). The
-parameters for the function have the same meaning as for DSA_do_sign().
-
-DSA_meth_get_sign_setup() and DSA_meth_set_sign_setup() get and set the function
-used for precalculating the DSA signature values B<k^-1> and B<r>. This function
-will be called in response to the application calling DSA_sign_setup(). The
-parameters for the function have the same meaning as for DSA_sign_setup().
-
-DSA_meth_get_verify() and DSA_meth_set_verify() get and set the function used
-for verifying a DSA signature respectively. This function will be called in
-response to the application calling DSA_do_verify() (or DSA_verify()). The
-parameters for the function have the same meaning as for DSA_do_verify().
-
-DSA_meth_get_mod_exp() and DSA_meth_set_mod_exp() get and set the function used
-for computing the following value:
-
- rr = a1^p1 * a2^p2 mod m
-
-This function will be called by the default OpenSSL method during verification
-of a DSA signature. The result is stored in the B<rr> parameter. This function
-may be NULL.
-
-DSA_meth_get_bn_mod_exp() and DSA_meth_set_bn_mod_exp() get and set the function
-used for computing the following value:
-
- r = a ^ p mod m
-
-This function will be called by the default OpenSSL function for
-DSA_sign_setup(). The result is stored in the B<r> parameter. This function
-may be NULL.
-
-DSA_meth_get_init() and DSA_meth_set_init() get and set the function used
-for creating a new DSA instance respectively. This function will be
-called in response to the application calling DSA_new() (if the current default
-DSA_METHOD is this one) or DSA_new_method(). The DSA_new() and DSA_new_method()
-functions will allocate the memory for the new DSA object, and a pointer to this
-newly allocated structure will be passed as a parameter to the function. This
-function may be NULL.
-
-DSA_meth_get_finish() and DSA_meth_set_finish() get and set the function used
-for destroying an instance of a DSA object respectively. This function will be
-called in response to the application calling DSA_free(). A pointer to the DSA
-to be destroyed is passed as a parameter. The destroy function should be used
-for DSA implementation specific clean up. The memory for the DSA itself should
-not be freed by this function. This function may be NULL.
-
-DSA_meth_get_paramgen() and DSA_meth_set_paramgen() get and set the function
-used for generating DSA parameters respectively. This function will be called in
-response to the application calling DSA_generate_parameters_ex() (or
-DSA_generate_parameters()). The parameters for the function have the same
-meaning as for DSA_generate_parameters_ex().
-
-DSA_meth_get_keygen() and DSA_meth_set_keygen() get and set the function
-used for generating a new DSA key pair respectively. This function will be
-called in response to the application calling DSA_generate_key(). The parameter
-for the function has the same meaning as for DSA_generate_key().
-
-=head1 RETURN VALUES
-
-DSA_meth_new() and DSA_meth_dup() return the newly allocated DSA_METHOD object
-or NULL on failure.
-
-DSA_meth_get0_name() and DSA_meth_get_flags() return the name and flags
-associated with the DSA_METHOD respectively.
-
-All other DSA_meth_get_*() functions return the appropriate function pointer
-that has been set in the DSA_METHOD, or NULL if no such pointer has yet been
-set.
-
-DSA_meth_set1_name() and all DSA_meth_set_*() functions return 1 on success or
-0 on failure.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>,
-L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>,
-L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_get0_pqg(3)>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_new, DSA_free - allocate and free DSA objects
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- DSA* DSA_new(void);
-
- void DSA_free(DSA *dsa);
-
-=head1 DESCRIPTION
-
-DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to
-calling DSA_new_method(NULL).
-
-DSA_free() frees the B<DSA> structure and its components. The values are
-erased before the memory is returned to the system.
-If B<dsa> is NULL nothing is done.
-
-=head1 RETURN VALUES
-
-If the allocation fails, DSA_new() returns B<NULL> and sets an error
-code that can be obtained by
-L<ERR_get_error(3)>. Otherwise it returns a pointer
-to the newly allocated structure.
-
-DSA_free() returns no value.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<ERR_get_error(3)>,
-L<DSA_generate_parameters(3)>,
-L<DSA_generate_key(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_set_default_method, DSA_get_default_method,
-DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- void DSA_set_default_method(const DSA_METHOD *meth);
-
- const DSA_METHOD *DSA_get_default_method(void);
-
- int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
-
- DSA *DSA_new_method(ENGINE *engine);
-
- DSA_METHOD *DSA_OpenSSL(void);
-
-=head1 DESCRIPTION
-
-A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
-operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
-important information about how these DSA API functions are affected by the use
-of B<ENGINE> API calls.
-
-Initially, the default DSA_METHOD is the OpenSSL internal implementation,
-as returned by DSA_OpenSSL().
-
-DSA_set_default_method() makes B<meth> the default method for all DSA
-structures created later. B<NB>: This is true only whilst no ENGINE has
-been set as a default for DSA, so this function is no longer recommended.
-
-DSA_get_default_method() returns a pointer to the current default
-DSA_METHOD. However, the meaningfulness of this result is dependent on
-whether the ENGINE API is being used, so this function is no longer
-recommended.
-
-DSA_set_method() selects B<meth> to perform all operations using the key
-B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
-previous method was supplied by an ENGINE, the handle to that ENGINE will
-be released during the change. It is possible to have DSA keys that only
-work with certain DSA_METHOD implementations (eg. from an ENGINE module
-that supports embedded hardware-protected keys), and in such cases
-attempting to change the DSA_METHOD for the key can have unexpected
-results. See L<DSA_meth_new> for information on constructing custom DSA_METHOD
-objects;
-
-DSA_new_method() allocates and initializes a DSA structure so that B<engine>
-will be used for the DSA operations. If B<engine> is NULL, the default engine
-for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
-controlled by DSA_set_default_method() is used.
-
-=head1 RETURN VALUES
-
-DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective
-B<DSA_METHOD>s.
-
-DSA_set_default_method() returns no value.
-
-DSA_set_method() returns non-zero if the provided B<meth> was successfully set as
-the method for B<dsa> (including unloading the ENGINE handle if the previous
-method was supplied by an ENGINE).
-
-DSA_new_method() returns NULL and sets an error code that can be
-obtained by L<ERR_get_error(3)> if the allocation
-fails. Otherwise it returns a pointer to the newly allocated structure.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<DSA_new(3)>, L<DSA_meth_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- int DSA_sign(int type, const unsigned char *dgst, int len,
- unsigned char *sigret, unsigned int *siglen, DSA *dsa);
-
- int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
- BIGNUM **rp);
-
- int DSA_verify(int type, const unsigned char *dgst, int len,
- unsigned char *sigbuf, int siglen, DSA *dsa);
-
-=head1 DESCRIPTION
-
-DSA_sign() computes a digital signature on the B<len> byte message
-digest B<dgst> using the private key B<dsa> and places its ASN.1 DER
-encoding at B<sigret>. The length of the signature is places in
-*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory.
-
-DSA_sign_setup() may be used to precompute part of the signing
-operation in case signature generation is time-critical. It expects
-B<dsa> to contain DSA parameters. It places the precomputed values
-in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing
-the old ones unless *B<kinvp> and *B<rp> are NULL. These values may
-be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>.
-B<ctx> is a pre-allocated B<BN_CTX> or NULL.
-
-DSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
-matches a given message digest B<dgst> of size B<len>.
-B<dsa> is the signer's public key.
-
-The B<type> parameter is ignored.
-
-The PRNG must be seeded before DSA_sign() (or DSA_sign_setup())
-is called.
-
-=head1 RETURN VALUES
-
-DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error.
-DSA_verify() returns 1 for a valid signature, 0 for an incorrect
-signature and -1 on error. The error codes can be obtained by
-L<ERR_get_error(3)>.
-
-=head1 CONFORMING TO
-
-US Federal Information Processing Standard FIPS 186 (Digital Signature
-Standard, DSS), ANSI X9.30
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
-L<DSA_do_sign(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DSA_size, DSA_bits - get DSA signature size or key bits
-
-=head1 SYNOPSIS
-
- #include <openssl/dsa.h>
-
- int DSA_size(const DSA *dsa);
- int DSA_bits(const DSA *dsa);
-
-=head1 DESCRIPTION
-
-DSA_size() returns the maximum size of an ASN.1 encoded DSA signature
-for key B<dsa> in bytes. It can be used to determine how much memory must
-be allocated for a DSA signature.
-
-B<dsa-E<gt>q> must not be B<NULL>.
-
-DSA_bits() returns the number of bits in key B<dsa>: this is the number
-of bits in the B<p> parameter.
-
-=head1 RETURN VALUE
-
-DSA_size() returns the size in bytes.
-
-DSA_bits() returns the number of bits in the key.
-
-=head1 SEE ALSO
-
-L<dsa(3)>, L<DSA_sign(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ECDSA_SIG_get0, ECDSA_SIG_set0,
-ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size,
-ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup,
-ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic curve digital signature
-algorithm (ECDSA) functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ecdsa.h>
-
- ECDSA_SIG *ECDSA_SIG_new(void);
- void ECDSA_SIG_free(ECDSA_SIG *sig);
- void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
- int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
- int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
- ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len);
- int ECDSA_size(const EC_KEY *eckey);
-
- int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
- unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
- ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
- EC_KEY *eckey);
-
- int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
- const unsigned char *sig, int siglen, EC_KEY *eckey);
- int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
- const ECDSA_SIG *sig, EC_KEY* eckey);
-
- ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
- const BIGNUM *kinv, const BIGNUM *rp,
- EC_KEY *eckey);
- int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
- int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
- unsigned char *sig, unsigned int *siglen,
- const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
-
-=head1 DESCRIPTION
-
-Note: these functions provide a low level interface to ECDSA. Most
-applications should use the higher level B<EVP> interface such as
-L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)> instead.
-
-B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the
-B<r> and B<s> value of an ECDSA signature (see X9.62 or FIPS 186-2).
-
-ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure. Note: before
-OpenSSL 1.1.0 the: the B<r> and B<s> components were initialised.
-
-ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
-
-ECDSA_SIG_get0() returns internal pointers the B<r> and B<s> values contained
-in B<sig>.
-
-The B<r> and B<s> values can be set by calling ECDSA_SIG_set0() and passing the
-new values for B<r> and B<s> as parameters to the function. Calling this
-function transfers the memory management of the values to the ECDSA_SIG object,
-and therefore the values that have been passed in should not be freed directly
-after this function has been called.
-
-i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B<sig> and
-writes the encoded signature to B<*pp> (note: if B<pp> is NULL i2d_ECDSA_SIG()
-returns the expected length in bytes of the DER encoded signature).
-i2d_ECDSA_SIG() returns the length of the DER encoded signature (or 0 on
-error).
-
-d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the decoded
-signature in a newly allocated B<ECDSA_SIG> structure. B<*sig> points to the
-buffer containing the DER encoded signature of size B<len>.
-
-ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
-created with the private EC key B<eckey>.
-
-ECDSA_sign() computes a digital signature of the B<dgstlen> bytes hash value
-B<dgst> using the private EC key B<eckey>. The DER encoded signatures is
-stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> must
-point to ECDSA_size(eckey) bytes of memory. The parameter B<type> is currently
-ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B<kinv>
-and B<rp> set to NULL.
-
-ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned
-as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign()
-is a wrapper function for ECDSA_do_sign_ex() with B<kinv> and B<rp> set to
-NULL.
-
-ECDSA_verify() verifies that the signature in B<sig> of size B<siglen> is a
-valid ECDSA signature of the hash value B<dgst> of size B<dgstlen> using the
-public key B<eckey>. The parameter B<type> is ignored.
-
-ECDSA_do_verify() is similar to ECDSA_verify() except the signature is
-presented in the form of a pointer to an B<ECDSA_SIG> structure.
-
-The remaining functions utilise the internal B<kinv> and B<r> values used
-during signature computation. Most applications will never need to call these
-and some external ECDSA ENGINE implementations may not support them at all if
-either B<kinv> or B<r> is not B<NULL>.
-
-ECDSA_sign_setup() may be used to precompute parts of the signing operation.
-B<eckey> is the private EC key and B<ctx> is a pointer to B<BN_CTX> structure
-(or NULL). The precomputed values or returned in B<kinv> and B<rp> and can be
-used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().
-
-ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes hash value
-B<dgst> using the private EC key B<eckey> and the optional pre-computed values
-B<kinv> and B<rp>. The DER encoded signatures is stored in B<sig> and it's
-length is returned in B<sig_len>. Note: B<sig> must point to ECDSA_size(eckey)
-bytes of memory. The parameter B<type> is ignored.
-
-ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is
-returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error).
-
-=head1 RETURN VALUES
-
-ECDSA_SIG_set0() returns 1 on success or 0 on failure.
-
-ECDSA_size() returns the maximum length signature or 0 on error.
-
-ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful
-or 0 on error.
-
-ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated
-B<ECDSA_SIG> structure or NULL on error.
-
-ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
-signature, 0 for an invalid signature and -1 on error.
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 EXAMPLES
-
-Creating an ECDSA signature of a given SHA-256 hash value using the
-named curve prime256v1 (aka P-256).
-
-First step: create an EC_KEY object (note: this part is B<not> ECDSA
-specific)
-
- int ret;
- ECDSA_SIG *sig;
- EC_KEY *eckey;
- eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
- if (eckey == NULL) {
- /* error */
- }
- if (EC_KEY_generate_key(eckey) == 0) {
- /* error */
- }
-
-Second step: compute the ECDSA signature of a SHA-256 hash value
-using ECDSA_do_sign():
-
- sig = ECDSA_do_sign(digest, 32, eckey);
- if (sig == NULL) {
- /* error */
- }
-
-or using ECDSA_sign():
-
- unsigned char *buffer, *pp;
- int buf_len;
- buf_len = ECDSA_size(eckey);
- buffer = OPENSSL_malloc(buf_len);
- pp = buffer;
- if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) {
- /* error */
- }
-
-Third step: verify the created ECDSA signature using ECDSA_do_verify():
-
- ret = ECDSA_do_verify(digest, 32, sig, eckey);
-
-or using ECDSA_verify():
-
- ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);
-
-and finally evaluate the return value:
-
- if (ret == 1) {
- /* signature ok */
- } else if (ret == 0) {
- /* incorrect signature */
- } else {
- /* error */
- }
-
-=head1 CONFORMING TO
-
-ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
-(Digital Signature Standard, DSS)
-
-=head1 SEE ALSO
-
-L<dsa(3)>,
-L<EVP_DigestSignInit(3)>,
-L<EVP_DigestVerifyInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and
-encoding ASN1 representations of elliptic curve entities
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off);
- int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off);
-
-=head1 DESCRIPTION
-
-The ECPKParameters represent the public parameters for an
-B<EC_GROUP> structure, which represents a curve.
-
-The ECPKParameters_print() and ECPKParameters_print_fp() functions print
-a human-readable output of the public parameters of the EC_GROUP to B<bp>
-or B<fp>. The output lines are indented by B<off> spaces.
-
-=head1 RETURN VALUES
-
-ECPKParameters_print() and ECPKParameters_print_fp()
-return 1 for success and 0 if an error occurs.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
-L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)>,
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining EC_METHOD objects
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- const EC_METHOD *EC_GFp_simple_method(void);
- const EC_METHOD *EC_GFp_mont_method(void);
- const EC_METHOD *EC_GFp_nist_method(void);
- const EC_METHOD *EC_GFp_nistp224_method(void);
- const EC_METHOD *EC_GFp_nistp256_method(void);
- const EC_METHOD *EC_GFp_nistp521_method(void);
-
- const EC_METHOD *EC_GF2m_simple_method(void);
-
- int EC_METHOD_get_field_type(const EC_METHOD *meth);
-
-=head1 DESCRIPTION
-
-The Elliptic Curve library provides a number of different implementations through a single common interface.
-When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)>) an
-implementation method must be provided. The functions described here all return a const pointer to an
-B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation
-type for the form of curve selected is used.
-
-For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method.
-
-For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All
-other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the
-use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)>). EC_GFp_nist_method
-offers an implementation optimised for use with NIST recommended curves (NIST curves are available through
-EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)>).
-
-The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit
-optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these
-implementations are not available on all platforms.
-
-EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either
-F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is
-F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the
-obj_mac.h header file.
-
-=head1 RETURN VALUES
-
-All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure.
-
-EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
-L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
-L<d2i_ECPKParameters(3)>,
-L<BN_mod_mul_montgomery(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor,
-EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator,
-EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor,
-EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag,
-EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form,
-EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed,
-EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree,
-EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp,
-EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis,
-EC_GROUP_get_pentanomial_basis
-- Functions for manipulating EC_GROUP objects
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
- EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
-
- const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
-
- int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor);
- const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
-
- int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);
- const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);
- int EC_GROUP_order_bits(const EC_GROUP *group);
- int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);
- const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group);
-
- void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
- int EC_GROUP_get_curve_name(const EC_GROUP *group);
-
- void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);
- int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
-
- void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
- point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *);
-
- unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x);
- size_t EC_GROUP_get_seed_len(const EC_GROUP *);
- size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len);
-
- int EC_GROUP_get_degree(const EC_GROUP *group);
-
- int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
-
- int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
-
- int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);
-
- int EC_GROUP_get_basis_type(const EC_GROUP *);
- int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k);
- int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
- unsigned int *k2, unsigned int *k3);
-
-=head1 DESCRIPTION
-
-EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
-
-EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created
-EC_GROUP object.
-
-EC_GROUP_method_of obtains the EC_METHOD of B<group>.
-
-EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These
-parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
-curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
-n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve.
-
-EC_GROUP_get0_generator returns the generator for the identified B<group>.
-
-The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters
-with the respective order and cofactors for the B<group>.
-
-The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
-(see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
-will return 0.
-
-The asn1_flag value is used to determine whether the curve encoding uses
-explicit parameters or a named curve using an ASN1 OID: many applications only
-support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the
-named curve form is used and the parameters must have a corresponding
-named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the
-parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and
-EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve.
-Note: B<OPENSSL_EC_EXPLICIT_CURVE> was first added to OpenSSL 1.1.0, for
-previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL
-1.1.0 the default form was to use explicit parameters (meaning that
-applications would have to explicitly set the named curve form) in OpenSSL
-1.1.0 and later the named curve form is the default.
-
-The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA).
-point_conversion_form_t is an enum defined as follows:
-
- typedef enum {
- /** the point is encoded as z||x, where the octet z specifies
- * which solution of the quadratic equation y is */
- POINT_CONVERSION_COMPRESSED = 2,
- /** the point is encoded as z||x||y, where z is the octet 0x04 */
- POINT_CONVERSION_UNCOMPRESSED = 4,
- /** the point is encoded as z||x||y, where the octet z specifies
- * which solution of the quadratic equation y is */
- POINT_CONVERSION_HYBRID = 6
- } point_conversion_form_t;
-
-For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by
-the octets for x, followed by the octets for y.
-
-For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For
-POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of
-the two possible solutions for y has been used, followed by the octets for x.
-
-For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
-possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
-
-The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form
-for the curve respectively.
-
-ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages
-in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it.
-If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library
-does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block
-containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the
-builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
-EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
-this seed value, although it will be preserved in any ASN1 based communications.
-
-EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
-the value m.
-
-The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid.
-For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
-simply b. In either case for the curve to be valid the discriminant must be non zero.
-
-The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include
-verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
-the correct order.
-
-EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
-
-The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
-defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial
-function f(x). This function is either a trinomial of the form:
-
-f(x) = x^m + x^k + 1 with m > k >= 1
-
-or a pentanomial of the form:
-
-f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
-
-The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
-function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
-the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
-B<k2> and B<k3> respectively.
-
-=head1 RETURN VALUES
-
-The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check,
-EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis.
-
-EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error.
-
-EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error.
-
-EC_GROUP_get0_generator returns the generator for the given curve or NULL on error.
-
-EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form
-and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
-specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
-
-EC_GROUP_get0_order() returns an internal pointer to the group order.
-EC_GROUP_get_order_bits() returns the number of bits in the group order.
-EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor.
-
-EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
-specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
-
-EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
-0, the return value will be 1. On error 0 is returned.
-
-EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
-
-EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
-trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>,
-L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters,
-EC_GROUP_new, EC_GROUP_new_from_ecparameters,
-EC_GROUP_new_from_ecpkparameters,
-EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp,
-EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp,
-EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m,
-EC_get_builtin_curves - Functions for creating and destroying EC_GROUP
-objects
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
- EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
- EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
- void EC_GROUP_free(EC_GROUP *group);
- void EC_GROUP_clear_free(EC_GROUP *group);
-
- EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
- EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
- EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
-
- int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
- int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
- int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
- int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
-
- ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params)
- ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params)
-
- size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
-
-=head1 DESCRIPTION
-
-Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
-prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised
-elliptic curve equation as follows:
-
-y^2 mod p = x^3 +ax + b mod p
-
-The second form is those defined over a binary field F2^m where the elements of the field are integers of length at
-most m bits. For this form the elliptic curve equation is modified to:
-
-y^2 + xy = x^3 + ax^2 + b (where b != 0)
-
-Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
-use a trinomial or a pentanomial for this parameter.
-
-A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
-L<EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or
-EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively.
-EC_GROUP_new_from_ecparameters() will create a group from the
-specified B<params> and
-EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>.
-
-EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>.
-EC_group_get_curve_GFp obtains the previously set curve parameters.
-
-EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents
-the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three
-or five bits set dependent on whether the polynomial is a trinomial or a pentanomial.
-EC_group_get_curve_GF2m obtains the previously set curve parameters.
-
-The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the
-appropriate EC_group_set_curve function. An appropriate default implementation method will be used.
-
-Whilst the library can be used to create any curve using the functions described above, there are also a number of
-predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
-EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
-will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
-curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
-provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
-not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
-The EC_builtin_curve structure is defined as follows:
-
- typedef struct {
- int nid;
- const char *comment;
- } EC_builtin_curve;
-
-Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
-
-In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to
-be constructed.
-
-EC_GROUP_free frees the memory associated with the EC_GROUP.
-If B<group> is NULL nothing is done.
-
-EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
-If B<group> is NULL nothing is done.
-
-=head1 RETURN VALUES
-
-All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
-
-EC_get_builtin_curves returns the number of builtin curves that are available.
-
-EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_copy(3)>,
-L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EC_KEY_get_enc_flags, EC_KEY_set_enc_flags
-- Get and set flags for encoding EC_KEY structures
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- unsigned int EC_KEY_get_enc_flags(const EC_KEY *key);
- void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
-
-=head1 DESCRIPTION
-
-The format of the external representation of the public key written by
-i2d_ECPrivateKey() (such as whether it is stored in a compressed form or not) is
-described by the point_conversion_form. See L<EC_GROUP_copy(3)>
-for a description of point_conversion_form.
-
-When reading a private key encoded without an associated public key (e.g. if
-EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey() generates
-the missing public key automatically. Private keys encoded without parameters
-(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using
-d2i_ECPrivateKey().
-
-The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the
-value of the encoding flags for the B<key>. There are two encoding flags
-currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags
-define the behaviour of how the B<key> is converted into ASN1 in a call to
-i2d_ECPrivateKey(). If EC_PKEY_NO_PARAMETERS is set then the public parameters for
-the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is
-set then the public key is not encoded along with the private key.
-
-=head1 RETURN VALUES
-
-EC_KEY_get_enc_flags() returns the value of the current encoding flags for the
-EC_KEY.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>,
-L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>,
-L<EC_POINT_add(3)>,
-L<EC_GFp_simple_method(3)>,
-L<d2i_ECPKParameters(3)>,
-L<d2i_ECPrivateKey(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EC_KEY_get_method, EC_KEY_set_method,
-EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags,
-EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref,
-EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key,
-EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key,
-EC_KEY_get_conv_form,
-EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult,
-EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates,
-EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct,
-EC_KEY_priv2buf - Functions for creating, destroying and manipulating
-EC_KEY objects
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- EC_KEY *EC_KEY_new(void);
- int EC_KEY_get_flags(const EC_KEY *key);
- void EC_KEY_set_flags(EC_KEY *key, int flags);
- void EC_KEY_clear_flags(EC_KEY *key, int flags);
- EC_KEY *EC_KEY_new_by_curve_name(int nid);
- void EC_KEY_free(EC_KEY *key);
- EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
- EC_KEY *EC_KEY_dup(const EC_KEY *src);
- int EC_KEY_up_ref(EC_KEY *key);
- const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
- int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
- const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);
- int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv);
- const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);
- int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);
- point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
- void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);
- void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);
- int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
- int EC_KEY_generate_key(EC_KEY *key);
- int EC_KEY_check_key(const EC_KEY *key);
- int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key,
- BIGNUM *x, BIGNUM *y);
- const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key);
- int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth);
-
- int EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len,
- BN_CTX *ctx);
- size_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form,
- unsigned char **pbuf, BN_CTX *ctx);
-
- int EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len);
- size_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len);
-
- size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf);
-
-=head1 DESCRIPTION
-
-An EC_KEY represents a public key and, optionally, the associated private
-key. A new EC_KEY with no associated curve can be constructed by calling
-EC_KEY_new(). The reference count for the newly created EC_KEY is initially
-set to 1. A curve can be associated with the EC_KEY by calling
-EC_KEY_set_group().
-
-Alternatively a new EC_KEY can be constructed by calling
-EC_KEY_new_by_curve_name() and supplying the nid of the associated curve. See
-L<EC_GROUP_new(3)> for a description of curve names. This function simply
-wraps calls to EC_KEY_new() and EC_GROUP_new_by_curve_name().
-
-Calling EC_KEY_free() decrements the reference count for the EC_KEY object,
-and if it has dropped to zero then frees the memory associated with it. If
-B<key> is NULL nothing is done.
-
-EC_KEY_copy() copies the contents of the EC_KEY in B<src> into B<dest>.
-
-EC_KEY_dup() creates a new EC_KEY object and copies B<ec_key> into it.
-
-EC_KEY_up_ref() increments the reference count associated with the EC_KEY
-object.
-
-EC_KEY_generate_key() generates a new public and private key for the supplied
-B<eckey> object. B<eckey> must have an EC_GROUP object associated with it
-before calling this function. The private key is a random integer (0 < priv_key
-< order, where I<order> is the order of the EC_GROUP object). The public key is
-an EC_POINT on the curve calculated by multiplying the generator for the
-curve by the private key.
-
-EC_KEY_check_key() performs various sanity checks on the EC_KEY object to
-confirm that it is valid.
-
-EC_KEY_set_public_key_affine_coordinates() sets the public key for B<key> based
-on its affine co-ordinates; i.e., it constructs an EC_POINT object based on
-the supplied B<x> and B<y> values and sets the public key to be this
-EC_POINT. It also performs certain sanity checks on the key to confirm
-that it is valid.
-
-The functions EC_KEY_get0_group(), EC_KEY_set_group(),
-EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(),
-and EC_KEY_set_public_key() get and set the EC_GROUP object, the private key,
-and the EC_POINT public key for the B<key> respectively.
-
-The functions EC_KEY_get_conv_form() and EC_KEY_set_conv_form() get and set the
-point_conversion_form for the B<key>. For a description of
-point_conversion_forms please see L<EC_POINT_new(3)>.
-
-EC_KEY_set_flags() sets the flags in the B<flags> parameter on the EC_KEY
-object. Any flags that are already set are left set. The flags currently
-defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In
-addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH.
-EC_KEY_get_flags() returns the current flags that are set for this EC_KEY.
-EC_KEY_clear_flags() clears the flags indicated by the B<flags> parameter; all
-other flags are left in their existing state.
-
-EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object
-(if set). Refer to L<EC_GROUP_copy(3)> for further information on the
-asn1_flag.
-
-EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator
-for faster point multiplication. See also L<EC_POINT_add(3)>.
-
-EC_KEY_oct2key() and EC_KEY_key2buf() are identical to the functions
-EC_POINT_oct2point() and EC_KEY_point2buf() except they use the public key
-EC_POINT in B<eckey>.
-
-EC_KEY_oct2priv() and EC_KEY_priv2oct() convert between the private key
-component of B<eckey> and octet form. The octet form consists of the content
-octets of the B<privateKey> OCTET STRING in an B<ECPrivateKey> ASN.1 structure.
-
-The function EC_KEY_priv2oct() must be supplied with a buffer long enough to
-store the octet form. The return value provides the number of octets stored.
-Calling the function with a NULL buffer will not perform the conversion but
-will just return the required buffer length.
-
-The function EC_KEY_priv2buf() allocates a buffer of suitable length and writes
-an EC_KEY to it in octet format. The allocated buffer is written to B<*pbuf>
-and its length is returned. The caller must free up the allocated buffer with a
-call to OPENSSL_free(). Since the allocated buffer value is written to B<*pbuf>
-the B<pbuf> parameter B<MUST NOT> be B<NULL>.
-
-EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer.
-
-=head1 RETURN VALUES
-
-EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to
-the newly created EC_KEY object, or NULL on error.
-
-EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an
-integer.
-
-EC_KEY_copy() returns a pointer to the destination key, or NULL on error.
-
-EC_KEY_up_ref(), EC_KEY_set_group(), EC_KEY_set_private_key(),
-EC_KEY_set_public_key(), EC_KEY_precompute_mult(), EC_KEY_generate_key(),
-EC_KEY_check_key(), EC_KEY_set_public_key_affine_coordinates(),
-EC_KEY_oct2key() and EC_KEY_oct2priv() return 1 on success or 0 on error.
-
-EC_KEY_get0_group() returns the EC_GROUP associated with the EC_KEY.
-
-EC_KEY_get0_private_key() returns the private key associated with the EC_KEY.
-
-EC_KEY_get_conv_form() return the point_conversion_form for the EC_KEY.
-
-EC_KEY_key2buf(), EC_KEY_priv2oct() and EC_KEY_priv2buf() return the length
-of the buffer or 0 on error.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>,
-L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>,
-L<EC_POINT_add(3)>,
-L<EC_GFp_simple_method(3)>,
-L<d2i_ECPKParameters(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on EC_POINT objects
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
- int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);
- int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);
- int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
- int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
- int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
- int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
- int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx);
- int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
- int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
- int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
- int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
-
-
-=head1 DESCRIPTION
-
-EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the
-result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>.
-
-EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>.
-
-The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.
-
-EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.
-
-EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.
-
-The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
-co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
-forced.
-
-EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>.
-
-EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value
-B<n> may be NULL.
-
-The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
-EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information
-about the generator.
-
-
-=head1 RETURN VALUES
-
-The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine,
-EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.
-
-EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.
-
-EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.
-
-EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.
-
-EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
-L<EC_POINT_new(3)>, L<EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf,
-EC_POINT_new, EC_POINT_free, EC_POINT_clear_free,
-EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of,
-EC_POINT_set_to_infinity,
-EC_POINT_get_Jprojective_coordinates_GFp,
-EC_POINT_set_affine_coordinates_GFp,
-EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp,
-EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m,
-EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct,
-EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex,
-EC_POINT_hex2point
-- Functions for creating, destroying and manipulating EC_POINT objects
-
-=head1 SYNOPSIS
-
- #include <openssl/ec.h>
-
- EC_POINT *EC_POINT_new(const EC_GROUP *group);
- void EC_POINT_free(EC_POINT *point);
- void EC_POINT_clear_free(EC_POINT *point);
- int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
- EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
- const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
- int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
- int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,
- EC_POINT *p,
- const BIGNUM *x, const BIGNUM *y,
- const BIGNUM *z, BN_CTX *ctx);
- int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
- const EC_POINT *p,
- BIGNUM *x, BIGNUM *y, BIGNUM *z,
- BN_CTX *ctx);
- int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
- const BIGNUM *x, const BIGNUM *y,
- BN_CTX *ctx);
- int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
- const EC_POINT *p,
- BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
- int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group,
- EC_POINT *p,
- const BIGNUM *x, int y_bit,
- BN_CTX *ctx);
- int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
- const BIGNUM *x, const BIGNUM *y,
- BN_CTX *ctx);
- int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
- const EC_POINT *p,
- BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
- int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group,
- EC_POINT *p,
- const BIGNUM *x, int y_bit,
- BN_CTX *ctx);
- size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
- point_conversion_form_t form,
- unsigned char *buf, size_t len, BN_CTX *ctx);
- size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point,
- point_conversion_form_t form,
- unsigned char **pbuf, BN_CTX *ctx);
- int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
- const unsigned char *buf, size_t len, BN_CTX *ctx);
- BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p,
- point_conversion_form_t form, BIGNUM *bn,
- BN_CTX *ctx);
- EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn,
- EC_POINT *p, BN_CTX *ctx);
- char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p,
- point_conversion_form_t form, BN_CTX *ctx);
- EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex,
- EC_POINT *p, BN_CTX *ctx);
-
-
-=head1 DESCRIPTION
-
-An B<EC_POINT> structure represents a point on a curve. A new point is
-constructed by calling the function EC_POINT_new() and providing the
-B<group> object that the point relates to.
-
-EC_POINT_free() frees the memory associated with the B<EC_POINT>.
-if B<point> is NULL nothing is done.
-
-EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and
-then frees its memory. If B<point> is NULL nothing is done.
-
-EC_POINT_copy() copies the point B<src> into B<dst>. Both B<src> and B<dst>
-must use the same B<EC_METHOD>.
-
-EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from
-B<src> to the newly created B<EC_POINT> object.
-
-EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>.
-
-A valid point on a curve is the special point at infinity. A point is set to
-be at infinity by calling EC_POINT_set_to_infinity().
-
-The affine co-ordinates for a point describe a point in terms of its x and y
-position. The functions EC_POINT_set_affine_coordinates_GFp() and
-EC_POINT_set_affine_coordinates_GF2m() set the B<x> and B<y> co-ordinates for
-the point B<p> defined over the curve given in B<group>.
-
-As well as the affine co-ordinates, a point can alternatively be described in
-terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian
-projective co-ordinates are expressed as three values x, y and z. Working in
-this co-ordinate system provides more efficient point multiplication
-operations. A mapping exists between Jacobian projective co-ordinates and
-affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written
-as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian
-projective from affine co-ordinates is simple. The co-ordinate (x, y) is mapped
-to (x, y, 1). To set or get the projective co-ordinates use
-EC_POINT_set_Jprojective_coordinates_GFp() and
-EC_POINT_get_Jprojective_coordinates_GFp() respectively.
-
-Points can also be described in terms of their compressed co-ordinates. For a
-point (x, y), for any given value for x such that the point is on the curve
-there will only ever be two possible values for y. Therefore a point can be set
-using the EC_POINT_set_compressed_coordinates_GFp() and
-EC_POINT_set_compressed_coordinates_GF2m() functions where B<x> is the x
-co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two
-possible values for y should be used.
-
-In addition B<EC_POINT> can be converted to and from various external
-representations. The octet form is the binary encoding of the B<ECPoint>
-structure (as defined in RFC5480 and used in certificates and TLS records):
-only the content octets are present, the B<OCTET STRING> tag and length are
-not included. B<BIGNUM> form is the octet form interpreted as a big endian
-integer converted to a B<BIGNUM> structure. Hexadecimal form is the octet
-form converted to a NULL terminated character string where each character
-is one of the printable values 0-9 or A-F (or a-f).
-
-The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(),
-EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from
-and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively.
-
-The function EC_POINT_point2oct() must be supplied with a buffer long enough to
-store the octet form. The return value provides the number of octets stored.
-Calling the function with a NULL buffer will not perform the conversion but
-will still return the required buffer length.
-
-The function EC_POINT_point2buf() allocates a buffer of suitable length and
-writes an EC_POINT to it in octet format. The allocated buffer is written to
-B<*pbuf> and its length is returned. The caller must free up the allocated
-buffer with a call to OPENSSL_free(). Since the allocated buffer value is
-written to B<*pbuf> the B<pbuf> parameter B<MUST NOT> be B<NULL>.
-
-The function EC_POINT_point2hex() will allocate sufficient memory to store the
-hexadecimal string. It is the caller's responsibility to free this memory with
-a subsequent call to OPENSSL_free().
-
-=head1 RETURN VALUES
-
-EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL
-on error.
-
-The following functions return 1 on success or 0 on error: EC_POINT_copy(),
-EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(),
-EC_POINT_get_Jprojective_coordinates_GFp(),
-EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(),
-EC_POINT_set_compressed_coordinates_GFp(),
-EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(),
-EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point().
-
-EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.
-
-EC_POINT_point2oct() and EC_point2buf() return the length of the required
-buffer or 0 on error.
-
-EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on
-error.
-
-EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on
-error.
-
-EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error.
-
-EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on
-error.
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
-L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
-L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ENGINE_get_DH, ENGINE_get_DSA, ENGINE_get_ECDH, ENGINE_get_ECDSA,
-ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH,
-ENGINE_get_default_DSA, ENGINE_get_default_ECDH,
-ENGINE_get_default_ECDSA, ENGINE_get_default_RAND,
-ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first,
-ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new,
-ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests,
-ENGINE_get_destroy_function, ENGINE_get_finish_function,
-ENGINE_get_init_function, ENGINE_get_load_privkey_function,
-ENGINE_get_load_pubkey_function, ENGINE_load_private_key,
-ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id,
-ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher,
-ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable,
-ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string,
-ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init,
-ENGINE_register_DH, ENGINE_register_DSA, ENGINE_register_ECDH,
-ENGINE_register_ECDSA, ENGINE_register_RAND, ENGINE_register_RSA,
-ENGINE_register_all_complete, ENGINE_register_ciphers,
-ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove,
-ENGINE_set_DH, ENGINE_set_DSA, ENGINE_set_ECDH, ENGINE_set_ECDSA,
-ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers,
-ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default,
-ENGINE_set_default_DH, ENGINE_set_default_DSA, ENGINE_set_default_ECDH,
-ENGINE_set_default_ECDSA, ENGINE_set_default_RAND, ENGINE_set_default_RSA,
-ENGINE_set_default_ciphers, ENGINE_set_default_digests,
-ENGINE_set_default_string, ENGINE_set_destroy_function,
-ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags,
-ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function,
-ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref,
-ENGINE_get_table_flags, ENGINE_cleanup,
-ENGINE_load_builtin_engines, ENGINE_register_all_DH,
-ENGINE_register_all_DSA, ENGINE_register_all_ECDH,
-ENGINE_register_all_ECDSA, ENGINE_register_all_RAND,
-ENGINE_register_all_RSA, ENGINE_register_all_ciphers,
-ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH,
-ENGINE_unregister_DSA, ENGINE_unregister_ECDH, ENGINE_unregister_ECDSA,
-ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers,
-ENGINE_unregister_digests
-- ENGINE cryptographic module support
-
-=head1 SYNOPSIS
-
- #include <openssl/engine.h>
-
- ENGINE *ENGINE_get_first(void);
- ENGINE *ENGINE_get_last(void);
- ENGINE *ENGINE_get_next(ENGINE *e);
- ENGINE *ENGINE_get_prev(ENGINE *e);
-
- int ENGINE_add(ENGINE *e);
- int ENGINE_remove(ENGINE *e);
-
- ENGINE *ENGINE_by_id(const char *id);
-
- int ENGINE_init(ENGINE *e);
- int ENGINE_finish(ENGINE *e);
-
- void ENGINE_load_builtin_engines(void);
-
- ENGINE *ENGINE_get_default_RSA(void);
- ENGINE *ENGINE_get_default_DSA(void);
- ENGINE *ENGINE_get_default_ECDH(void);
- ENGINE *ENGINE_get_default_ECDSA(void);
- ENGINE *ENGINE_get_default_DH(void);
- ENGINE *ENGINE_get_default_RAND(void);
- ENGINE *ENGINE_get_cipher_engine(int nid);
- ENGINE *ENGINE_get_digest_engine(int nid);
-
- int ENGINE_set_default_RSA(ENGINE *e);
- int ENGINE_set_default_DSA(ENGINE *e);
- int ENGINE_set_default_ECDH(ENGINE *e);
- int ENGINE_set_default_ECDSA(ENGINE *e);
- int ENGINE_set_default_DH(ENGINE *e);
- int ENGINE_set_default_RAND(ENGINE *e);
- int ENGINE_set_default_ciphers(ENGINE *e);
- int ENGINE_set_default_digests(ENGINE *e);
- int ENGINE_set_default_string(ENGINE *e, const char *list);
-
- int ENGINE_set_default(ENGINE *e, unsigned int flags);
-
- unsigned int ENGINE_get_table_flags(void);
- void ENGINE_set_table_flags(unsigned int flags);
-
- int ENGINE_register_RSA(ENGINE *e);
- void ENGINE_unregister_RSA(ENGINE *e);
- void ENGINE_register_all_RSA(void);
- int ENGINE_register_DSA(ENGINE *e);
- void ENGINE_unregister_DSA(ENGINE *e);
- void ENGINE_register_all_DSA(void);
- int ENGINE_register_ECDH(ENGINE *e);
- void ENGINE_unregister_ECDH(ENGINE *e);
- void ENGINE_register_all_ECDH(void);
- int ENGINE_register_ECDSA(ENGINE *e);
- void ENGINE_unregister_ECDSA(ENGINE *e);
- void ENGINE_register_all_ECDSA(void);
- int ENGINE_register_DH(ENGINE *e);
- void ENGINE_unregister_DH(ENGINE *e);
- void ENGINE_register_all_DH(void);
- int ENGINE_register_RAND(ENGINE *e);
- void ENGINE_unregister_RAND(ENGINE *e);
- void ENGINE_register_all_RAND(void);
- int ENGINE_register_ciphers(ENGINE *e);
- void ENGINE_unregister_ciphers(ENGINE *e);
- void ENGINE_register_all_ciphers(void);
- int ENGINE_register_digests(ENGINE *e);
- void ENGINE_unregister_digests(ENGINE *e);
- void ENGINE_register_all_digests(void);
- int ENGINE_register_complete(ENGINE *e);
- int ENGINE_register_all_complete(void);
-
- int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
- int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
- int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
- long i, void *p, void (*f)(void), int cmd_optional);
- int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
- int cmd_optional);
-
- ENGINE *ENGINE_new(void);
- int ENGINE_free(ENGINE *e);
- int ENGINE_up_ref(ENGINE *e);
-
- int ENGINE_set_id(ENGINE *e, const char *id);
- int ENGINE_set_name(ENGINE *e, const char *name);
- int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
- int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
- int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth);
- int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth);
- int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
- int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
- int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
- int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
- int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
- int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
- int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
- int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
- int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
- int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
- int ENGINE_set_flags(ENGINE *e, int flags);
- int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
-
- const char *ENGINE_get_id(const ENGINE *e);
- const char *ENGINE_get_name(const ENGINE *e);
- const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
- const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
- const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e);
- const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e);
- const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
- const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
- ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
- ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
- ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
- ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
- ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
- ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
- ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
- ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
- const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
- const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
- int ENGINE_get_flags(const ENGINE *e);
- const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
-
- EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
- UI_METHOD *ui_method, void *callback_data);
- EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
- UI_METHOD *ui_method, void *callback_data);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void ENGINE_cleanup(void)
- #endif
-
-=head1 DESCRIPTION
-
-These functions create, manipulate, and use cryptographic modules in the
-form of B<ENGINE> objects. These objects act as containers for
-implementations of cryptographic algorithms, and support a
-reference-counted mechanism to allow them to be dynamically loaded in and
-out of the running application.
-
-The cryptographic functionality that can be provided by an B<ENGINE>
-implementation includes the following abstractions;
-
- RSA_METHOD - for providing alternative RSA implementations
- DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD,
- - similarly for other OpenSSL APIs
- EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid')
- EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid')
- key-loading - loading public and/or private EVP_PKEY keys
-
-=head2 Reference counting and handles
-
-Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be
-treated as handles - ie. not only as pointers, but also as references to
-the underlying ENGINE object. Ie. one should obtain a new reference when
-making copies of an ENGINE pointer if the copies will be used (and
-released) independently.
-
-ENGINE objects have two levels of reference-counting to match the way in
-which the objects are used. At the most basic level, each ENGINE pointer is
-inherently a B<structural> reference - a structural reference is required
-to use the pointer value at all, as this kind of reference is a guarantee
-that the structure can not be deallocated until the reference is released.
-
-However, a structural reference provides no guarantee that the ENGINE is
-initialised and able to use any of its cryptographic
-implementations. Indeed it's quite possible that most ENGINEs will not
-initialise at all in typical environments, as ENGINEs are typically used to
-support specialised hardware. To use an ENGINE's functionality, you need a
-B<functional> reference. This kind of reference can be considered a
-specialised form of structural reference, because each functional reference
-implicitly contains a structural reference as well - however to avoid
-difficult-to-find programming bugs, it is recommended to treat the two
-kinds of reference independently. If you have a functional reference to an
-ENGINE, you have a guarantee that the ENGINE has been initialised and
-is ready to perform cryptographic operations, and will remain initialised
-until after you have released your reference.
-
-I<Structural references>
-
-This basic type of reference is used for instantiating new ENGINEs,
-iterating across OpenSSL's internal linked-list of loaded
-ENGINEs, reading information about an ENGINE, etc. Essentially a structural
-reference is sufficient if you only need to query or manipulate the data of
-an ENGINE implementation rather than use its functionality.
-
-The ENGINE_new() function returns a structural reference to a new (empty)
-ENGINE object. There are other ENGINE API functions that return structural
-references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(),
-ENGINE_get_next(), ENGINE_get_prev(). All structural references should be
-released by a corresponding to call to the ENGINE_free() function - the
-ENGINE object itself will only actually be cleaned up and deallocated when
-the last structural reference is released.
-
-It should also be noted that many ENGINE API function calls that accept a
-structural reference will internally obtain another reference - typically
-this happens whenever the supplied ENGINE will be needed by OpenSSL after
-the function has returned. Eg. the function to add a new ENGINE to
-OpenSSL's internal list is ENGINE_add() - if this function returns success,
-then OpenSSL will have stored a new structural reference internally so the
-caller is still responsible for freeing their own reference with
-ENGINE_free() when they are finished with it. In a similar way, some
-functions will automatically release the structural reference passed to it
-if part of the function's job is to do so. Eg. the ENGINE_get_next() and
-ENGINE_get_prev() functions are used for iterating across the internal
-ENGINE list - they will return a new structural reference to the next (or
-previous) ENGINE in the list or NULL if at the end (or beginning) of the
-list, but in either case the structural reference passed to the function is
-released on behalf of the caller.
-
-To clarify a particular function's handling of references, one should
-always consult that function's documentation "man" page, or failing that
-the openssl/engine.h header file includes some hints.
-
-I<Functional references>
-
-As mentioned, functional references exist when the cryptographic
-functionality of an ENGINE is required to be available. A functional
-reference can be obtained in one of two ways; from an existing structural
-reference to the required ENGINE, or by asking OpenSSL for the default
-operational ENGINE for a given cryptographic purpose.
-
-To obtain a functional reference from an existing structural reference,
-call the ENGINE_init() function. This returns zero if the ENGINE was not
-already operational and couldn't be successfully initialised (eg. lack of
-system drivers, no special hardware attached, etc), otherwise it will
-return non-zero to indicate that the ENGINE is now operational and will
-have allocated a new B<functional> reference to the ENGINE. All functional
-references are released by calling ENGINE_finish() (which removes the
-implicit structural reference as well).
-
-The second way to get a functional reference is by asking OpenSSL for a
-default implementation for a given task, eg. by ENGINE_get_default_RSA(),
-ENGINE_get_default_cipher_engine(), etc. These are discussed in the next
-section, though they are not usually required by application programmers as
-they are used automatically when creating and using the relevant
-algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc.
-
-=head2 Default implementations
-
-For each supported abstraction, the ENGINE code maintains an internal table
-of state to control which implementations are available for a given
-abstraction and which should be used by default. These implementations are
-registered in the tables and indexed by an 'nid' value, because
-abstractions like EVP_CIPHER and EVP_DIGEST support many distinct
-algorithms and modes, and ENGINEs can support arbitrarily many of them.
-In the case of other abstractions like RSA, DSA, etc, there is only one
-"algorithm" so all implementations implicitly register using the same 'nid'
-index.
-
-When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg.
-when calling RSA_new_method(NULL)), a "get_default" call will be made to the
-ENGINE subsystem to process the corresponding state table and return a
-functional reference to an initialised ENGINE whose implementation should be
-used. If no ENGINE should (or can) be used, it will return NULL and the caller
-will operate with a NULL ENGINE handle - this usually equates to using the
-conventional software implementation. In the latter case, OpenSSL will from
-then on behave the way it used to before the ENGINE API existed.
-
-Each state table has a flag to note whether it has processed this
-"get_default" query since the table was last modified, because to process
-this question it must iterate across all the registered ENGINEs in the
-table trying to initialise each of them in turn, in case one of them is
-operational. If it returns a functional reference to an ENGINE, it will
-also cache another reference to speed up processing future queries (without
-needing to iterate across the table). Likewise, it will cache a NULL
-response if no ENGINE was available so that future queries won't repeat the
-same iteration unless the state table changes. This behaviour can also be
-changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using
-ENGINE_set_table_flags()), no attempted initialisations will take place,
-instead the only way for the state table to return a non-NULL ENGINE to the
-"get_default" query will be if one is expressly set in the table. Eg.
-ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except
-that it also sets the state table's cached response for the "get_default"
-query. In the case of abstractions like EVP_CIPHER, where implementations are
-indexed by 'nid', these flags and cached-responses are distinct for each 'nid'
-value.
-
-=head2 Application requirements
-
-This section will explain the basic things an application programmer should
-support to make the most useful elements of the ENGINE functionality
-available to the user. The first thing to consider is whether the
-programmer wishes to make alternative ENGINE modules available to the
-application and user. OpenSSL maintains an internal linked list of
-"visible" ENGINEs from which it has to operate - at start-up, this list is
-empty and in fact if an application does not call any ENGINE API calls and
-it uses static linking against openssl, then the resulting application
-binary will not contain any alternative ENGINE code at all. So the first
-consideration is whether any/all available ENGINE implementations should be
-made visible to OpenSSL - this is controlled by calling the various "load"
-functions.
-
-Having called any of these functions, ENGINE objects would have been
-dynamically allocated and populated with these implementations and linked
-into OpenSSL's internal linked list. At this point it is important to
-mention an important API function;
-
- void ENGINE_cleanup(void)
-
-If no ENGINE API functions are called at all in an application, then there
-are no inherent memory leaks to worry about from the ENGINE functionality.
-However, prior to OpenSSL 1.1.0 if any ENGINEs are loaded, even if they are
-never registered or used, it was necessary to use the ENGINE_cleanup() function
-to correspondingly cleanup before program exit, if the caller wishes to avoid
-memory leaks. This mechanism used an internal callback registration table
-so that any ENGINE API functionality that knows it requires cleanup can
-register its cleanup details to be called during ENGINE_cleanup(). This
-approach allowed ENGINE_cleanup() to clean up after any ENGINE functionality
-at all that your program uses, yet doesn't automatically create linker
-dependencies to all possible ENGINE functionality - only the cleanup
-callbacks required by the functionality you do use will be required by the
-linker. From OpenSSL 1.1.0 it is no longer necessary to explicitly call
-ENGINE_cleanup and this function is deprecated. Cleanup automatically takes
-place at program exit.
-
-The fact that ENGINEs are made visible to OpenSSL (and thus are linked into
-the program and loaded into memory at run-time) does not mean they are
-"registered" or called into use by OpenSSL automatically - that behaviour
-is something for the application to control. Some applications
-will want to allow the user to specify exactly which ENGINE they want used
-if any is to be used at all. Others may prefer to load all support and have
-OpenSSL automatically use at run-time any ENGINE that is able to
-successfully initialise - ie. to assume that this corresponds to
-acceleration hardware attached to the machine or some such thing. There are
-probably numerous other ways in which applications may prefer to handle
-things, so we will simply illustrate the consequences as they apply to a
-couple of simple cases and leave developers to consider these and the
-source code to openssl's builtin utilities as guides.
-
-I<Using a specific ENGINE implementation>
-
-Here we'll assume an application has been configured by its user or admin
-to want to use the "ACME" ENGINE if it is available in the version of
-OpenSSL the application was compiled with. If it is available, it should be
-used by default for all RSA, DSA, and symmetric cipher operations, otherwise
-OpenSSL should use its builtin software as per usual. The following code
-illustrates how to approach this;
-
- ENGINE *e;
- const char *engine_id = "ACME";
- ENGINE_load_builtin_engines();
- e = ENGINE_by_id(engine_id);
- if(!e)
- /* the engine isn't available */
- return;
- if(!ENGINE_init(e)) {
- /* the engine couldn't initialise, release 'e' */
- ENGINE_free(e);
- return;
- }
- if(!ENGINE_set_default_RSA(e))
- /* This should only happen when 'e' can't initialise, but the previous
- * statement suggests it did. */
- abort();
- ENGINE_set_default_DSA(e);
- ENGINE_set_default_ciphers(e);
- /* Release the functional reference from ENGINE_init() */
- ENGINE_finish(e);
- /* Release the structural reference from ENGINE_by_id() */
- ENGINE_free(e);
-
-I<Automatically using builtin ENGINE implementations>
-
-Here we'll assume we want to load and register all ENGINE implementations
-bundled with OpenSSL, such that for any cryptographic algorithm required by
-OpenSSL - if there is an ENGINE that implements it and can be initialised,
-it should be used. The following code illustrates how this can work;
-
- /* Load all bundled ENGINEs into memory and make them visible */
- ENGINE_load_builtin_engines();
- /* Register all of them for every algorithm they collectively implement */
- ENGINE_register_all_complete();
-
-That's all that's required. Eg. the next time OpenSSL tries to set up an
-RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to
-ENGINE_init() and if any of those succeed, that ENGINE will be set as the
-default for RSA use from then on.
-
-=head2 Advanced configuration support
-
-There is a mechanism supported by the ENGINE framework that allows each
-ENGINE implementation to define an arbitrary set of configuration
-"commands" and expose them to OpenSSL and any applications based on
-OpenSSL. This mechanism is entirely based on the use of name-value pairs
-and assumes ASCII input (no unicode or UTF for now!), so it is ideal if
-applications want to provide a transparent way for users to provide
-arbitrary configuration "directives" directly to such ENGINEs. It is also
-possible for the application to dynamically interrogate the loaded ENGINE
-implementations for the names, descriptions, and input flags of their
-available "control commands", providing a more flexible configuration
-scheme. However, if the user is expected to know which ENGINE device he/she
-is using (in the case of specialised hardware, this goes without saying)
-then applications may not need to concern themselves with discovering the
-supported control commands and simply prefer to pass settings into ENGINEs
-exactly as they are provided by the user.
-
-Before illustrating how control commands work, it is worth mentioning what
-they are typically used for. Broadly speaking there are two uses for
-control commands; the first is to provide the necessary details to the
-implementation (which may know nothing at all specific to the host system)
-so that it can be initialised for use. This could include the path to any
-driver or config files it needs to load, required network addresses,
-smart-card identifiers, passwords to initialise protected devices,
-logging information, etc etc. This class of commands typically needs to be
-passed to an ENGINE B<before> attempting to initialise it, ie. before
-calling ENGINE_init(). The other class of commands consist of settings or
-operations that tweak certain behaviour or cause certain operations to take
-place, and these commands may work either before or after ENGINE_init(), or
-in some cases both. ENGINE implementations should provide indications of
-this in the descriptions attached to builtin control commands and/or in
-external product documentation.
-
-I<Issuing control commands to an ENGINE>
-
-Let's illustrate by example; a function for which the caller supplies the
-name of the ENGINE it wishes to use, a table of string-pairs for use before
-initialisation, and another table for use after initialisation. Note that
-the string-pairs used for control commands consist of a command "name"
-followed by the command "parameter" - the parameter could be NULL in some
-cases but the name can not. This function should initialise the ENGINE
-(issuing the "pre" commands beforehand and the "post" commands afterwards)
-and set it as the default for everything except RAND and then return a
-boolean success or failure.
-
- int generic_load_engine_fn(const char *engine_id,
- const char **pre_cmds, int pre_num,
- const char **post_cmds, int post_num)
- {
- ENGINE *e = ENGINE_by_id(engine_id);
- if (!e) return 0;
- while (pre_num--) {
- if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {
- fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
- pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)");
- ENGINE_free(e);
- return 0;
- }
- pre_cmds += 2;
- }
- if (!ENGINE_init(e)) {
- fprintf(stderr, "Failed initialisation\n");
- ENGINE_free(e);
- return 0;
- }
- /* ENGINE_init() returned a functional reference, so free the structural
- * reference from ENGINE_by_id(). */
- ENGINE_free(e);
- while(post_num--) {
- if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {
- fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
- post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)");
- ENGINE_finish(e);
- return 0;
- }
- post_cmds += 2;
- }
- ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
- /* Success */
- return 1;
- }
-
-Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can
-relax the semantics of the function - if set non-zero it will only return
-failure if the ENGINE supported the given command name but failed while
-executing it, if the ENGINE doesn't support the command name it will simply
-return success without doing anything. In this case we assume the user is
-only supplying commands specific to the given ENGINE so we set this to
-FALSE.
-
-I<Discovering supported control commands>
-
-It is possible to discover at run-time the names, numerical-ids, descriptions
-and input parameters of the control commands supported by an ENGINE using a
-structural reference. Note that some control commands are defined by OpenSSL
-itself and it will intercept and handle these control commands on behalf of the
-ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command.
-openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands
-implemented by ENGINEs should be numbered from. Any command value lower than
-this symbol is considered a "generic" command is handled directly by the
-OpenSSL core routines.
-
-It is using these "core" control commands that one can discover the control
-commands implemented by a given ENGINE, specifically the commands:
-
- ENGINE_HAS_CTRL_FUNCTION
- ENGINE_CTRL_GET_FIRST_CMD_TYPE
- ENGINE_CTRL_GET_NEXT_CMD_TYPE
- ENGINE_CTRL_GET_CMD_FROM_NAME
- ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
- ENGINE_CTRL_GET_NAME_FROM_CMD
- ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
- ENGINE_CTRL_GET_DESC_FROM_CMD
- ENGINE_CTRL_GET_CMD_FLAGS
-
-Whilst these commands are automatically processed by the OpenSSL framework code,
-they use various properties exposed by each ENGINE to process these
-queries. An ENGINE has 3 properties it exposes that can affect how this behaves;
-it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in
-the ENGINE's flags, and it can expose an array of control command descriptions.
-If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will
-simply pass all these "core" control commands directly to the ENGINE's ctrl()
-handler (and thus, it must have supplied one), so it is up to the ENGINE to
-reply to these "discovery" commands itself. If that flag is not set, then the
-OpenSSL framework code will work with the following rules;
-
- if no ctrl() handler supplied;
- ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),
- all other commands fail.
- if a ctrl() handler was supplied but no array of control commands;
- ENGINE_HAS_CTRL_FUNCTION returns TRUE,
- all other commands fail.
- if a ctrl() handler and array of control commands was supplied;
- ENGINE_HAS_CTRL_FUNCTION returns TRUE,
- all other commands proceed processing ...
-
-If the ENGINE's array of control commands is empty then all other commands will
-fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of
-the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the
-identifier of a command supported by the ENGINE and returns the next command
-identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string
-name for a command and returns the corresponding identifier or fails if no such
-command name exists, and the remaining commands take a command identifier and
-return properties of the corresponding commands. All except
-ENGINE_CTRL_GET_FLAGS return the string length of a command name or description,
-or populate a supplied character buffer with a copy of the command name or
-description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following
-possible values:
-
- ENGINE_CMD_FLAG_NUMERIC
- ENGINE_CMD_FLAG_STRING
- ENGINE_CMD_FLAG_NO_INPUT
- ENGINE_CMD_FLAG_INTERNAL
-
-If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely
-informational to the caller - this flag will prevent the command being usable
-for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string().
-"INTERNAL" commands are not intended to be exposed to text-based configuration
-by applications, administrations, users, etc. These can support arbitrary
-operations via ENGINE_ctrl(), including passing to and/or from the control
-commands data of any arbitrary type. These commands are supported in the
-discovery mechanisms simply to allow applications to determine if an ENGINE
-supports certain specific commands it might want to use (eg. application "foo"
-might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" -
-and ENGINE could therefore decide whether or not to support this "foo"-specific
-extension).
-
-=head1 SEE ALSO
-
-L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<dsa(3)>, L<dh(3)>, L<rand(3)>
-
-=head1 HISTORY
-
-ENGINE_cleanup(), ENGINE_load_openssl(), ENGINE_load_dynamic(), and
-ENGINE_load_cryptodev() were deprecated in OpenSSL 1.1.0 by
-OPENSSL_init_crypto().
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and
-reason code
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- int ERR_GET_LIB(unsigned long e);
-
- int ERR_GET_FUNC(unsigned long e);
-
- int ERR_GET_REASON(unsigned long e);
-
-=head1 DESCRIPTION
-
-The error code returned by ERR_get_error() consists of a library
-number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC()
-and ERR_GET_REASON() can be used to extract these.
-
-The library number and function code describe where the error
-occurred, the reason code is the information about what went wrong.
-
-Each sub-library of OpenSSL has a unique library number; function and
-reason codes are unique within each sub-library. Note that different
-libraries may use the same value to signal different functions and
-reasons.
-
-B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally
-unique. However, when checking for sub-library specific reason codes,
-be sure to also compare the library number.
-
-ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros.
-
-=head1 RETURN VALUES
-
-The library number, function code and reason code respectively.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_get_error(3)>
-
-=head1 HISTORY
-
-ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in
-all versions of OpenSSL.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_clear_error - clear the error queue
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- void ERR_clear_error(void);
-
-=head1 DESCRIPTION
-
-ERR_clear_error() empties the current thread's error queue.
-
-=head1 RETURN VALUES
-
-ERR_clear_error() has no return value.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
-ERR_func_error_string, ERR_reason_error_string - obtain human-readable
-error message
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- char *ERR_error_string(unsigned long e, char *buf);
- void ERR_error_string_n(unsigned long e, char *buf, size_t len);
-
- const char *ERR_lib_error_string(unsigned long e);
- const char *ERR_func_error_string(unsigned long e);
- const char *ERR_reason_error_string(unsigned long e);
-
-=head1 DESCRIPTION
-
-ERR_error_string() generates a human-readable string representing the
-error code I<e>, and places it at I<buf>. I<buf> must be at least 256
-bytes long. If I<buf> is B<NULL>, the error string is placed in a
-static buffer.
-Note that this function is not thread-safe and does no checks on the size
-of the buffer; use ERR_error_string_n() instead.
-
-ERR_error_string_n() is a variant of ERR_error_string() that writes
-at most I<len> characters (including the terminating 0)
-and truncates the string if necessary.
-For ERR_error_string_n(), I<buf> may not be B<NULL>.
-
-The string will have the following format:
-
- error:[error code]:[library name]:[function name]:[reason string]
-
-I<error code> is an 8 digit hexadecimal number, I<library name>,
-I<function name> and I<reason string> are ASCII text.
-
-ERR_lib_error_string(), ERR_func_error_string() and
-ERR_reason_error_string() return the library name, function
-name and reason string respectively.
-
-If there is no text string registered for the given error code,
-the error string will contain the numeric code.
-
-L<ERR_print_errors(3)> can be used to print
-all error codes currently in the queue.
-
-=head1 RETURN VALUES
-
-ERR_error_string() returns a pointer to a static buffer containing the
-string if I<buf> B<== NULL>, I<buf> otherwise.
-
-ERR_lib_error_string(), ERR_func_error_string() and
-ERR_reason_error_string() return the strings, and B<NULL> if
-none is registered for the error code.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_get_error(3)>,
-L<ERR_print_errors(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_get_error, ERR_peek_error, ERR_peek_last_error,
-ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
-ERR_get_error_line_data, ERR_peek_error_line_data,
-ERR_peek_last_error_line_data - obtain error code and data
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- unsigned long ERR_get_error(void);
- unsigned long ERR_peek_error(void);
- unsigned long ERR_peek_last_error(void);
-
- unsigned long ERR_get_error_line(const char **file, int *line);
- unsigned long ERR_peek_error_line(const char **file, int *line);
- unsigned long ERR_peek_last_error_line(const char **file, int *line);
-
- unsigned long ERR_get_error_line_data(const char **file, int *line,
- const char **data, int *flags);
- unsigned long ERR_peek_error_line_data(const char **file, int *line,
- const char **data, int *flags);
- unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
- const char **data, int *flags);
-
-=head1 DESCRIPTION
-
-ERR_get_error() returns the earliest error code from the thread's error
-queue and removes the entry. This function can be called repeatedly
-until there are no more error codes to return.
-
-ERR_peek_error() returns the earliest error code from the thread's
-error queue without modifying it.
-
-ERR_peek_last_error() returns the latest error code from the thread's
-error queue without modifying it.
-
-See L<ERR_GET_LIB(3)> for obtaining information about
-location and reason of the error, and
-L<ERR_error_string(3)> for human-readable error
-messages.
-
-ERR_get_error_line(), ERR_peek_error_line() and
-ERR_peek_last_error_line() are the same as the above, but they
-additionally store the file name and line number where
-the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
-
-ERR_get_error_line_data(), ERR_peek_error_line_data() and
-ERR_peek_last_error_line_data() store additional data and flags
-associated with the error code in *B<data>
-and *B<flags>, unless these are B<NULL>. *B<data> contains a string
-if *B<flags>&B<ERR_TXT_STRING> is true.
-
-An application B<MUST NOT> free the *B<data> pointer (or any other pointers
-returned by these functions) with OPENSSL_free() as freeing is handled
-automatically by the error library.
-
-=head1 RETURN VALUES
-
-The error code, or 0 if there is no error in the queue.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_error_string(3)>,
-L<ERR_GET_LIB(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings -
-load and free error strings
-
-=head1 SYNOPSIS
-
-Deprecated:
-
- #include <openssl/err.h>
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void ERR_load_crypto_strings(void);
- void ERR_free_strings(void);
- #endif
-
- #include <openssl/ssl.h>
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void SSL_load_error_strings(void);
- #endif
-
-=head1 DESCRIPTION
-
-All of the following functions are deprecated from OpenSSL 1.1.0. No explicit
-initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>
-and L<OPENSSL_init_ssl(3)>.
-
-ERR_load_crypto_strings() registers the error strings for all
-B<libcrypto> functions. SSL_load_error_strings() does the same,
-but also registers the B<libssl> error strings.
-
-In versions of OpenSSL prior to 1.1.0 ERR_free_strings() freed all previously
-loaded error strings. However from OpenSSL 1.1.0 it does nothing.
-
-=head1 RETURN VALUES
-
-ERR_load_crypto_strings(), SSL_load_error_strings() and
-ERR_free_strings() return no values.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_error_string(3)>
-
-=head1 HISTORY
-
-The ERR_load_crypto_strings(), SSL_load_error_strings(), and
-ERR_free_strings() functions were deprecated in OpenSSL 1.1.0 by
-OPENSSL_init_crypto() and OPENSSL_init_ssl().
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load
-arbitrary error strings
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- void ERR_load_strings(int lib, ERR_STRING_DATA str[]);
-
- int ERR_get_next_error_library(void);
-
- unsigned long ERR_PACK(int lib, int func, int reason);
-
-=head1 DESCRIPTION
-
-ERR_load_strings() registers error strings for library number B<lib>.
-
-B<str> is an array of error string data:
-
- typedef struct ERR_string_data_st
- {
- unsigned long error;
- char *string;
- } ERR_STRING_DATA;
-
-The error code is generated from the library number and a function and
-reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>).
-ERR_PACK() is a macro.
-
-The last entry in the array is {0,0}.
-
-ERR_get_next_error_library() can be used to assign library numbers
-to user libraries at runtime.
-
-=head1 RETURN VALUE
-
-ERR_load_strings() returns no value. ERR_PACK() return the error code.
-ERR_get_next_error_library() returns zero on failure, otherwise a new
-library number.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_load_strings(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb
-- print error messages
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- void ERR_print_errors(BIO *bp);
- void ERR_print_errors_fp(FILE *fp);
- void ERR_print_errors_cb(int (*cb)(const char *str, size_t len, void *u),
- void *u)
-
-
-=head1 DESCRIPTION
-
-ERR_print_errors() is a convenience function that prints the error
-strings for all errors that OpenSSL has recorded to B<bp>, thus
-emptying the error queue.
-
-ERR_print_errors_fp() is the same, except that the output goes to a
-B<FILE>.
-
-ERR_print_errors_cb() is the same, except that the callback function,
-B<cb>, is called for each error line with the string, length, and userdata
-B<u> as the callback parameters.
-
-The error strings will have the following format:
-
- [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
-
-I<error code> is an 8 digit hexadecimal number. I<library name>,
-I<function name> and I<reason string> are ASCII text, as is I<optional
-text message> if one was set for the respective error code.
-
-If there is no text string registered for the given error code,
-the error string will contain the numeric code.
-
-=head1 RETURN VALUES
-
-ERR_print_errors() and ERR_print_errors_fp() return no values.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_error_string(3)>,
-L<ERR_get_error(3)>.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_put_error, ERR_add_error_data - record an error
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- void ERR_put_error(int lib, int func, int reason, const char *file,
- int line);
-
- void ERR_add_error_data(int num, ...);
- void ERR_add_error_data(int num, va_list arg);
-
-=head1 DESCRIPTION
-
-ERR_put_error() adds an error code to the thread's error queue. It
-signals that the error of reason code B<reason> occurred in function
-B<func> of library B<lib>, in line number B<line> of B<file>.
-This function is usually called by a macro.
-
-ERR_add_error_data() associates the concatenation of its B<num> string
-arguments with the error code added last.
-ERR_add_error_vdata() is similar except the argument is a B<va_list>.
-
-L<ERR_load_strings(3)> can be used to register
-error strings so that the application can a generate human-readable
-error messages for the error code.
-
-=head2 Reporting errors
-
-Each sub-library has a specific macro XXXerr() that is used to report
-errors. Its first argument is a function code B<XXX_F_...>, the second
-argument is a reason code B<XXX_R_...>. Function codes are derived
-from the function names; reason codes consist of textual error
-descriptions. For example, the function ssl3_read_bytes() reports a
-"handshake failure" as follows:
-
- SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
-
-Function and reason codes should consist of upper case characters,
-numbers and underscores only. The error file generation script translates
-function codes into function names by looking in the header files
-for an appropriate function name, if none is found it just uses
-the capitalized form such as "SSL3_READ_BYTES" in the above example.
-
-The trailing section of a reason code (after the "_R_") is translated
-into lower case and underscores changed to spaces.
-
-Although a library will normally report errors using its own specific
-XXXerr macro, another library's macro can be used. This is normally
-only done when a library wants to include ASN1 code which must use
-the ASN1err() macro.
-
-
-=head1 RETURN VALUES
-
-ERR_put_error() and ERR_add_error_data() return
-no values.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<ERR_load_strings(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_remove_thread_state, ERR_remove_state - DEPRECATED
-
-=head1 SYNOPSIS
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x10000000L
- void ERR_remove_state(unsigned long pid);
- #endif
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void ERR_remove_thread_state(void *);
- #endif
-
-=head1 DESCRIPTION
-
-The functions described here were used to free the error queue
-associated with the current or specified thread.
-
-They are now deprecated and do nothing, as the OpenSSL libraries now
-normally do all thread initialisation and deinitialisation
-automatically (see L<OPENSSL_init_crypto(3)>).
-
-=head1 RETURN VALUE
-
-The functions described here return no value.
-
-=head1 SEE ALSO
-
-L<err(3)>, L<OPENSSL_init_crypto(3)>
-
-=head1 HISTORY
-
-ERR_remove_state() was deprecated in OpenSSL 1.0.0 when
-ERR_remove_thread_state() was introduced.
-
-ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the
-thread handling functionality was entirely rewritten.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark
-
-=head1 SYNOPSIS
-
- #include <openssl/err.h>
-
- int ERR_set_mark(void);
-
- int ERR_pop_to_mark(void);
-
-=head1 DESCRIPTION
-
-ERR_set_mark() sets a mark on the current topmost error record if there
-is one.
-
-ERR_pop_to_mark() will pop the top of the error stack until a mark is found.
-The mark is then removed. If there is no mark, the whole stack is removed.
-
-=head1 RETURN VALUES
-
-ERR_set_mark() returns 0 if the error stack is empty, otherwise 1.
-
-ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which
-implies that the stack became empty, otherwise 1.
-
-=head1 SEE ALSO
-
-L<err(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_BytesToKey - password based encryption routine
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
- const unsigned char *salt,
- const unsigned char *data, int datal, int count,
- unsigned char *key, unsigned char *iv);
-
-=head1 DESCRIPTION
-
-EVP_BytesToKey() derives a key and IV from various parameters. B<type> is
-the cipher to derive the key and IV for. B<md> is the message digest to use.
-The B<salt> parameter is used as a salt in the derivation: it should point to
-an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing
-B<datal> bytes which is used to derive the keying data. B<count> is the
-iteration count to use. The derived key and IV will be written to B<key>
-and B<iv> respectively.
-
-=head1 NOTES
-
-A typical application of this function is to derive keying material for an
-encryption algorithm from a password in the B<data> parameter.
-
-Increasing the B<count> parameter slows down the algorithm which makes it
-harder for an attacker to perform a brute force attack using a large number
-of candidate passwords.
-
-If the total key and IV length is less than the digest length and
-B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5
-otherwise a non standard extension is used to derive the extra data.
-
-Newer applications should use a more modern algorithm such as PBKDF2 as
-defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC.
-
-=head1 KEY DERIVATION ALGORITHM
-
-The key and IV is derived by concatenating D_1, D_2, etc until
-enough data is available for the key and IV. D_i is defined as:
-
- D_i = HASH^count(D_(i-1) || data || salt)
-
-where || denotes concatenation, D_0 is empty, HASH is the digest
-algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data)
-is HASH(HASH(data)) and so on.
-
-The initial bytes are used for the key and the subsequent bytes for
-the IV.
-
-=head1 RETURN VALUES
-
-If B<data> is NULL, then EVP_BytesToKey() returns the number of bytes
-needed to store the derived key.
-Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes,
-or 0 on error.
-
-=head1 SEE ALSO
-
-L<evp(3)>, L<rand(3)>,
-L<PKCS5_PBKDF2_HMAC(3)>,
-L<EVP_EncryptInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_CIPHER_CTX_get_cipher_data, EVP_CIPHER_CTX_set_cipher_data - Routines to
-inspect and modify EVP_CIPHER_CTX objects
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- void *EVP_CIPHER_CTX_get_cipher_data(const EVP_CIPHER_CTX *ctx);
- void *EVP_CIPHER_CTX_set_cipher_data(EVP_CIPHER_CTX *ctx, void *cipher_data);
-
-=head1 DESCRIPTION
-
-The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the cipher
-data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the
-particular implementation of the cipher. For example this data can be used by
-engines to store engine specific information. The data is automatically
-allocated and freed by OpenSSL, so applications and engines should not normally
-free this directly (but see below).
-
-The EVP_CIPHER_CTX_set_cipher_data() function allows an application or engine to
-replace the cipher data with new data. A pointer to any existing cipher data is
-returned from this function. If the old data is no longer required then it
-should be freed through a call to OPENSSL_free().
-
-=head1 RETURN VALUES
-
-The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the current
-cipher data for the EVP_CIPHER_CTX.
-
-The EVP_CIPHER_CTX_set_cipher_data() function returns a pointer to the old
-cipher data for the EVP_CIPHER_CTX.
-
-=head1 HISTORY
-
-The EVP_CIPHER_CTX_get_cipher_data() and EVP_CIPHER_CTX_set_cipher_data()
-functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free,
-EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags,
-EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init,
-EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup,
-EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params,
-EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init,
-EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup,
-EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params,
-EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);
- EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);
- void EVP_CIPHER_meth_free(EVP_CIPHER *cipher);
-
- int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);
- int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);
- int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);
- int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher,
- int (*init) (EVP_CIPHER_CTX *ctx,
- const unsigned char *key,
- const unsigned char *iv,
- int enc));
- int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher,
- int (*do_cipher) (EVP_CIPHER_CTX *ctx,
- unsigned char *out,
- const unsigned char *in,
- size_t inl));
- int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher,
- int (*cleanup) (EVP_CIPHER_CTX *));
- int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher,
- int (*set_asn1_parameters) (EVP_CIPHER_CTX *,
- ASN1_TYPE *));
- int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher,
- int (*get_asn1_parameters) (EVP_CIPHER_CTX *,
- ASN1_TYPE *));
- int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,
- int (*ctrl) (EVP_CIPHER_CTX *, int type,
- int arg, void *ptr));
-
- int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
- const unsigned char *key,
- const unsigned char *iv,
- int enc);
- int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
- unsigned char *out,
- const unsigned char *in,
- size_t inl);
- int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *);
- int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
- ASN1_TYPE *);
- int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
- ASN1_TYPE *);
- int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
- int type, int arg,
- void *ptr);
-
-=head1 DESCRIPTION
-
-The B<EVP_CIPHER> type is a structure for symmetric cipher method
-implementation.
-
-EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure.
-
-EVP_CIPHER_meth_dup() creates a copy of B<cipher>.
-
-EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure.
-
-EVP_CIPHER_meth_iv_length() sets the length of the IV.
-This is only needed when the implemented cipher mode requires it.
-
-EVP_CIPHER_meth_set_flags() sets the flags to describe optional
-behaviours in the particular B<cipher>.
-With the exception of cipher modes, of which only one may be present,
-several flags can be or'd together.
-The available flags are:
-
-=over
-
-=item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE,
-EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE,
-EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE,
-EVP_CIPH_OCB_MODE
-
-The cipher mode.
-
-=item EVP_CIPH_VARIABLE_LENGTH
-
-This cipher is of variable length.
-
-=item EVP_CIPH_CUSTOM_IV
-
-Storing and initialising the IV is left entirely to the
-implementation.
-
-=item EVP_CIPH_ALWAYS_CALL_INIT
-
-Set this if the implementation's init() function should be called even
-if B<key> is B<NULL>.
-
-=item EVP_CIPH_CTRL_INIT
-
-Set this to have the implementation's ctrl() function called with
-command code B<EVP_CTRL_INIT> early in its setup.
-
-=item EVP_CIPH_CUSTOM_KEY_LENGTH
-
-Checking and setting the key length after creating the B<EVP_CIPHER>
-is left to the implementation.
-Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a
-B<EVP_CIPHER> with this flag set, the implementation's ctrl() function
-will be called with the control code B<EVP_CTRL_SET_KEY_LENGTH> and
-the key length in B<arg>.
-
-=item EVP_CIPH_NO_PADDING
-
-Don't use standard block padding.
-
-=item EVP_CIPH_RAND_KEY
-
-Making a key with random content is left to the implementation.
-This is done by calling the implementation's ctrl() function with the
-control code B<EVP_CTRL_RAND_KEY> and the pointer to the key memory
-storage in B<ptr>.
-
-=item EVP_CIPH_CUSTOM_COPY
-
-Set this to have the implementation's ctrl() function called with
-command code B<EVP_CTRL_COPY> at the end of EVP_CIPHER_CTX_copy().
-The intended use is for further things to deal with after the
-implementation specific data block has been copied.
-The destination B<EVP_CIPHER_CTX> is passed to the control with the
-B<ptr> parameter.
-The implementation specific data block is reached with
-EVP_CIPHER_CTX_get_cipher_data().
-
-=item EVP_CIPH_FLAG_DEFAULT_ASN1
-
-Use the default EVP routines to pass IV to and from ASN.1.
-
-=item EVP_CIPH_FLAG_LENGTH_BITS
-
-Signals that the length of the input buffer for encryption /
-decryption is to be understood as the number of bits bits instead of
-bytes for this implementation.
-This is only useful for CFB1 ciphers.
-
-=begin comment
-The FIPS flags seem to be unused, so I'm hiding them until I get an
-explanation or they get removed. /RL
-
-=item EVP_CIPH_FLAG_FIPS
-
-=item EVP_CIPH_FLAG_NON_FIPS_ALLOW
-
-=end comment
-
-=item EVP_CIPH_FLAG_CUSTOM_CIPHER
-
-This indicates that the implementation takes care of everything,
-including padding, buffering and finalization.
-The EVP routines will simply give them control and do nothing more.
-
-=item EVP_CIPH_FLAG_AEAD_CIPHER
-
-This indicates that this is an AEAD cipher implementation.
-
-=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK
-
-Allow interleaving of crypto blocks, a particular optimization only applicable
-to certain TLS ciphers.
-
-=back
-
-EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's
-implementation context so that it can be automatically allocated.
-
-EVP_CIPHER_meth_set_init() sets the cipher init function for
-B<cipher>.
-The cipher init function is called by EVP_CipherInit(),
-EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(),
-EVP_DecryptInit(), EVP_DecryptInit_ex().
-
-EVP_CIPHER_meth_set_do_cipher() sets the cipher function for
-B<cipher>.
-The cipher function is called by EVP_CipherUpdate(),
-EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(),
-EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and
-EVP_DecryptFinal_ex().
-
-EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do
-extra cleanup before the method's private data structure is cleaned
-out and freed.
-Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the
-private data structure is then available with
-EVP_CIPHER_CTX_get_cipher_data().
-This cleanup function is called by EVP_CIPHER_CTX_reset() and
-EVP_CIPHER_CTX_free().
-
-EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>.
-
-=head1 RETURN VALUES
-
-EVP_CIPHER_meth_get_input_blocksize(), EVP_CIPHER_meth_get_result_size(),
-EVP_CIPHER_meth_get_app_datasize(), EVP_CIPHER_meth_get_flags(),
-EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_update(),
-EVP_CIPHER_meth_get_final(), EVP_CIPHER_meth_get_copy(),
-EVP_CIPHER_meth_get_cleanup() and EVP_CIPHER_meth_get_ctrl() are all used
-to retrieve the method data given with the EVP_CIPHER_meth_set_*()
-functions above.
-
-=head1 SEE ALSO
-
-L<EVP_EncryptInit>
-
-=head1 HISTORY
-
-The B<EVP_CIPHER> structure was openly available in OpenSSL before version
-1.1.
-The functions described here were added in OpenSSL version 1.1.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,
-EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex,
-EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type,
-EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
-EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha1,
-EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_mdc2,
-EVP_ripemd160, EVP_blake2b_512, EVP_blake2s_256, EVP_get_digestbyname,
-EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_MD_CTX *EVP_MD_CTX_new(void);
- int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
- void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
-
- int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
- int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
- int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
- unsigned int *s);
-
- int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);
-
- int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
- int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
- unsigned int *s);
-
- int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
-
- int EVP_MD_type(const EVP_MD *md);
- int EVP_MD_pkey_type(const EVP_MD *md);
- int EVP_MD_size(const EVP_MD *md);
- int EVP_MD_block_size(const EVP_MD *md);
-
- const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
- int EVP_MD_CTX_size(const EVP_MD *ctx);
- int EVP_MD_CTX_block_size(const EVP_MD *ctx);
- int EVP_MD_CTX_type(const EVP_MD *ctx);
-
- const EVP_MD *EVP_md_null(void);
- const EVP_MD *EVP_md2(void);
- const EVP_MD *EVP_md5(void);
- const EVP_MD *EVP_sha1(void);
- const EVP_MD *EVP_mdc2(void);
- const EVP_MD *EVP_ripemd160(void);
- const EVP_MD *EVP_blake2b_512(void);
- const EVP_MD *EVP_blake2s_256(void);
-
- const EVP_MD *EVP_sha224(void);
- const EVP_MD *EVP_sha256(void);
- const EVP_MD *EVP_sha384(void);
- const EVP_MD *EVP_sha512(void);
-
- const EVP_MD *EVP_get_digestbyname(const char *name);
- const EVP_MD *EVP_get_digestbynid(int type);
- const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);
-
-=head1 DESCRIPTION
-
-The EVP digest routines are a high level interface to message digests,
-and should be used instead of the cipher-specific functions.
-
-EVP_MD_CTX_new() allocates, initializes and returns a digest context.
-
-EVP_MD_CTX_reset() resets the digest context B<ctx>. This can be used
-to reuse an already existing context.
-
-EVP_MD_CTX_free() cleans up digest context B<ctx> and frees up the
-space allocated to it.
-
-EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest
-B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this
-function. B<type> will typically be supplied by a function such as EVP_sha1().
-If B<impl> is NULL then the default implementation of digest B<type> is used.
-
-EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
-digest context B<ctx>. This function can be called several times on the
-same B<ctx> to hash additional data.
-
-EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places
-it in B<md>. If the B<s> parameter is not NULL then the number of
-bytes of data written (i.e. the length of the digest) will be written
-to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
-After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate()
-can be made, but EVP_DigestInit_ex() can be called to initialize a new
-digest operation.
-
-EVP_MD_CTX_copy_ex() can be used to copy the message digest state from
-B<in> to B<out>. This is useful if large amounts of data are to be
-hashed which only differ in the last few bytes. B<out> must be initialized
-before calling this function.
-
-EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except
-the passed context B<ctx> does not have to be initialized, and it always
-uses the default digest implementation.
-
-EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest
-context B<ctx> is automatically cleaned up.
-
-EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination
-B<out> does not have to be initialized.
-
-EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest
-when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the
-hash.
-
-EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the
-message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure.
-
-EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER
-representing the given message digest when passed an B<EVP_MD> structure.
-For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is
-normally used when setting ASN1 OIDs.
-
-EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed
-B<EVP_MD_CTX>.
-
-EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated
-with this digest. For example EVP_sha1() is associated with RSA so this will
-return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms
-are no longer linked this function is only retained for compatibility
-reasons.
-
-EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(),
-EVP_sha384(), EVP_sha512(), EVP_mdc2(), EVP_ripemd160(), EVP_blake2b_512(), and
-EVP_blake2s_256() return B<EVP_MD> structures for the MD2, MD5, SHA1, SHA224,
-SHA256, SHA384, SHA512, MDC2, RIPEMD160, BLAKE2b-512, and BLAKE2s-256 digest
-algorithms respectively.
-
-EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it
-returns is of zero length.
-
-EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
-return an B<EVP_MD> structure when passed a digest name, a digest NID or
-an ASN1_OBJECT structure respectively.
-
-=head1 RETURN VALUES
-
-EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for
-success and 0 for failure.
-
-EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
-
-EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the
-corresponding OBJECT IDENTIFIER or NID_undef if none exists.
-
-EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and
-EVP_MD_CTX_block_size() return the digest or block size in bytes.
-
-EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(),
-EVP_mdc2(), EVP_ripemd160(), EVP_blake2b_512(), and EVP_blake2s_256() return
-pointers to the corresponding EVP_MD structures.
-
-EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
-return either an B<EVP_MD> structure or NULL if an error occurs.
-
-=head1 NOTES
-
-The B<EVP> interface to message digests should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
-transparent to the digest used and much more flexible.
-
-New applications should use the SHA2 digest algorithms such as SHA256.
-The other digest algorithms are still in common use.
-
-For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
-set to NULL to use the default digest implementation.
-
-The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
-obsolete but are retained to maintain compatibility with existing code. New
-applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
-EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
-instead of initializing and cleaning it up on each call and allow non default
-implementations of digests to be specified.
-
-If digest contexts are not cleaned up after use
-memory leaks will occur.
-
-EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(),
-EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as
-macros.
-
-
-=head1 EXAMPLE
-
-This example digests the data "Test Message\n" and "Hello World\n", using the
-digest name passed on the command line.
-
- #include <stdio.h>
- #include <openssl/evp.h>
-
- main(int argc, char *argv[])
- {
- EVP_MD_CTX *mdctx;
- const EVP_MD *md;
- char mess1[] = "Test Message\n";
- char mess2[] = "Hello World\n";
- unsigned char md_value[EVP_MAX_MD_SIZE];
- int md_len, i;
-
- if(!argv[1]) {
- printf("Usage: mdtest digestname\n");
- exit(1);
- }
-
- md = EVP_get_digestbyname(argv[1]);
-
- if(!md) {
- printf("Unknown message digest %s\n", argv[1]);
- exit(1);
- }
-
- mdctx = EVP_MD_CTX_new();
- EVP_DigestInit_ex(mdctx, md, NULL);
- EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
- EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
- EVP_DigestFinal_ex(mdctx, md_value, &md_len);
- EVP_MD_CTX_free(mdctx);
-
- printf("Digest is: ");
- for (i = 0; i < md_len; i++)
- printf("%02x", md_value[i]);
- printf("\n");
-
- exit(0);
- }
-
-=head1 SEE ALSO
-
-L<dgst(1)>,
-L<evp(3)>
-
-=head1 HISTORY
-
-B<EVP_MD_CTX> became opaque in OpenSSL 1.1. Consequently, stack
-allocated B<EVP_MD_CTX>s are no longer supported.
-
-EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to
-EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.
-
-The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
-later, so now EVP_sha1() can be used with RSA and DSA. The legacy EVP_dss1()
-was removed in OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
- const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
- int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
- int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
-
-=head1 DESCRIPTION
-
-The EVP signature routines are a high level interface to digital signatures.
-
-EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
-ENGINE B<impl> and private key B<pkey>. B<ctx> must be created with
-EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
-EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
-be used to set alternative signing options.
-
-EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
-signature context B<ctx>. This function can be called several times on the
-same B<ctx> to include additional data. This function is currently implemented
-using a macro.
-
-EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
-If B<sig> is B<NULL> then the maximum size of the output buffer is written to
-the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
-B<siglen> parameter should contain the length of the B<sig> buffer, if the
-call is successful the signature is written to B<sig> and the amount of data
-written to B<siglen>.
-
-=head1 RETURN VALUES
-
-EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return
-1 for success and 0 or a negative value for failure. In particular a return
-value of -2 indicates the operation is not supported by the public key
-algorithm.
-
-The error codes can be obtained from L<ERR_get_error(3)>.
-
-=head1 NOTES
-
-The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
-transparent to the algorithm used and much more flexible.
-
-In previous versions of OpenSSL there was a link between message digest types
-and public key algorithms. This meant that "clone" digests such as EVP_dss1()
-needed to be used to sign using SHA1 and DSA. This is no longer necessary and
-the use of clone digest is now discouraged.
-
-For some key types and parameters the random number generator must be seeded
-or the operation will fail.
-
-The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
-context. This means that calls to EVP_DigestSignUpdate() and
-EVP_DigestSignFinal() can be called later to digest and sign additional data.
-
-Since only a copy of the digest context is ever finalized the context must
-be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
-will occur.
-
-The use of EVP_PKEY_size() with these functions is discouraged because some
-signature operations may have a signature length which depends on the
-parameters set. As a result EVP_PKEY_size() would have to return a value
-which indicates the maximum possible signature for any set of parameters.
-
-=head1 SEE ALSO
-
-L<EVP_DigestVerifyInit(3)>,
-L<EVP_DigestInit(3)>, L<err(3)>,
-L<evp(3)>, L<hmac(3)>, L<md2(3)>,
-L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
-L<sha(3)>, L<dgst(1)>
-
-=head1 HISTORY
-
-EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
-were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signature verification functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
- const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
- int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
- int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen);
-
-=head1 DESCRIPTION
-
-The EVP signature routines are a high level interface to digital signatures.
-
-EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest
-B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be created
-with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
-EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this
-can be used to set alternative verification options.
-
-EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
-verification context B<ctx>. This function can be called several times on the
-same B<ctx> to include additional data. This function is currently implemented
-using a macro.
-
-EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in
-B<sig> of length B<siglen>.
-
-=head1 RETURN VALUES
-
-EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0
-for failure.
-
-EVP_DigestVerifyFinal() returns 1 for success; any other value indicates
-failure. A return value of zero indicates that the signature did not verify
-successfully (that is, tbs did not match the original data or the signature had
-an invalid form), while other values indicate a more serious error (and
-sometimes also indicate an invalid signature form).
-
-The error codes can be obtained from L<ERR_get_error(3)>.
-
-=head1 NOTES
-
-The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
-transparent to the algorithm used and much more flexible.
-
-In previous versions of OpenSSL there was a link between message digest types
-and public key algorithms. This meant that "clone" digests such as EVP_dss1()
-needed to be used to sign using SHA1 and DSA. This is no longer necessary and
-the use of clone digest is now discouraged.
-
-For some key types and parameters the random number generator must be seeded
-or the operation will fail.
-
-The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
-context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
-be called later to digest and verify additional data.
-
-Since only a copy of the digest context is ever finalized the context must
-be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
-will occur.
-
-=head1 SEE ALSO
-
-L<EVP_DigestSignInit(3)>,
-L<EVP_DigestInit(3)>, L<err(3)>,
-L<evp(3)>, L<hmac(3)>, L<md2(3)>,
-L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
-L<sha(3)>, L<dgst(1)>
-
-=head1 HISTORY
-
-EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal()
-were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy,
-EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal,
-EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal,
-EVP_DecodeBlock - EVP base 64 encode/decode routines
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void);
- void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx);
- int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx);
- int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx);
- void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
- int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,
- const unsigned char *in, int inl);
- void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl);
- int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n);
-
- void EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
- int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,
- const unsigned char *in, int inl);
- int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
- char *out, int *outl);
- int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n);
-
-=head1 DESCRIPTION
-
-The EVP encode routines provide a high level interface to base 64 encoding and
-decoding. Base 64 encoding converts binary data into a printable form that uses
-the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3
-bytes of binary data provided 4 bytes of base 64 encoded data will be produced
-plus some occasional newlines (see below). If the input data length is not a
-multiple of 3 then the output data will be padded at the end using the "="
-character.
-
-EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for
-the encode/decode functions.
-
-EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the
-space allocated to it.
-
-Encoding of binary data is performed in blocks of 48 input bytes (or less for
-the final block). For each 48 byte input block encoded 64 bytes of base 64 data
-is output plus an additional newline character (i.e. 65 bytes in total). The
-final block (which may be less than 48 bytes) will output 4 bytes for every 3
-bytes of input. If the data length is not divisible by 3 then a full 4 bytes is
-still output for the final 1 or 2 bytes of input. Similarly a newline character
-will also be output.
-
-EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation.
-
-EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by
-B<in>. The output is stored in the buffer B<out> and the number of bytes output
-is stored in B<*outl>. It is the caller's responsibility to ensure that the
-buffer at B<out> is sufficiently large to accommodate the output data. Only full
-blocks of data (48 bytes) will be immediately processed and output by this
-function. Any remainder is held in the B<ctx> object and will be processed by a
-subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the
-required size of the output buffer add together the value of B<inl> with the
-amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore
-any remainder). This gives the number of blocks of data that will be processed.
-Ensure the output buffer contains 65 bytes of storage for each block, plus an
-additional byte for a NUL terminator. EVP_EncodeUpdate() may be called
-repeatedly to process large amounts of input data. In the event of an error
-EVP_EncodeUpdate() will set B<*outl> to 0 and return 0. On success 1 will be
-returned.
-
-EVP_EncodeFinal() must be called at the end of an encoding operation. It will
-process any partial block of data remaining in the B<ctx> object. The output
-data will be stored in B<out> and the length of the data written will be stored
-in B<*outl>. It is the caller's responsibility to ensure that B<out> is
-sufficiently large to accommodate the output data which will never be more than
-65 bytes plus an additional NUL terminator (i.e. 66 bytes in total).
-
-EVP_ENCODE_CTX_copy() can be used to copy a context B<sctx> to a context
-B<dctx>. B<dctx> must be initialized before calling this function.
-
-EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to
-be encoded or decoded that are pending in the B<ctx> object.
-
-EVP_EncodeBlock() encodes a full block of input data in B<f> and of length
-B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of
-output data will be produced. If B<dlen> is not divisible by 3 then the block is
-encoded as a final block of data and the output is padded such that it is always
-divisible by 4. Additionally a NUL terminator character will be added. For
-example if 16 bytes of input data is provided then 24 bytes of encoded data is
-created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of
-the data generated I<without> the NUL terminator is returned from the function.
-
-EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation.
-
-EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed
-to by B<in>. The output is stored in the buffer B<out> and the number of bytes
-output is stored in B<*outl>. It is the caller's responsibility to ensure that
-the buffer at B<out> is sufficiently large to accommodate the output data. This
-function will attempt to decode as much data as possible in 4 byte chunks. Any
-whitespace, newline or carriage return characters are ignored. Any partial chunk
-of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in
-the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If
-any illegal base 64 characters are encountered or if the base 64 padding
-character "=" is encountered in the middle of the data then the function returns
--1 to indicate an error. A return value of 0 or 1 indicates successful
-processing of the data. A return value of 0 additionally indicates that the last
-input data characters processed included the base 64 padding character "=" and
-therefore no more non-padding character data is expected to be processed. For
-every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and
-line feeds), 3 bytes of binary output data will be produced (or less at the end
-of the data where the padding character "=" has been used).
-
-EVP_DecodeFinal() must be called at the end of a decoding operation. If there
-is any unprocessed data still in B<ctx> then the input data must not have been
-a multiple of 4 and therefore an error has occurred. The function will return -1
-in this case. Otherwise the function returns 1 on success.
-
-EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data
-contained in B<f> and store the result in B<t>. Any leading whitespace will be
-trimmed as will any trailing whitespace, newlines, carriage returns or EOF
-characters. After such trimming the length of the data in B<f> must be divisible
-by 4. For every 4 input bytes exactly 3 output bytes will be produced. The
-output will be padded with 0 bits if necessary to ensure that the output is
-always 3 bytes for every 4 input bytes. This function will return the length of
-the data decoded or -1 on error.
-
-=head1 RETURN VALUES
-
-EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX
-object or NULL on error.
-
-EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in
-B<ctx>.
-
-EVP_EncodeUpdate() returns 0 on error or 1 on success.
-
-EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL
-terminator.
-
-EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned
-then no more non-padding base 64 characters are expected.
-
-EVP_DecodeFinal() returns -1 on error or 1 on success.
-
-EVP_DecodeBlock() returns the length of the data decoded or -1 on error.
-
-=head1 SEE ALSO
-
-L<evp(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free,
-EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex,
-EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex,
-EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex,
-EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit,
-EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal,
-EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
-EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid,
-EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length,
-EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher,
-EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
-EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
-EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
-EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
-EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb,
-EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb,
-EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb,
-EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc,
-EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc,
-EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc,
-EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc,
-EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc,
-EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb,
-EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb,
-EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb,
-EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb,
-EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm,
-EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
- int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
- void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
-
- int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
- ENGINE *impl, unsigned char *key, unsigned char *iv);
- int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl, unsigned char *in, int inl);
- int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl);
-
- int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
- ENGINE *impl, unsigned char *key, unsigned char *iv);
- int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl, unsigned char *in, int inl);
- int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
- int *outl);
-
- int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
- ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
- int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl, unsigned char *in, int inl);
- int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
- int *outl);
-
- int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
- unsigned char *key, unsigned char *iv);
- int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl);
-
- int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
- unsigned char *key, unsigned char *iv);
- int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
- int *outl);
-
- int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
- unsigned char *key, unsigned char *iv, int enc);
- int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
- int *outl);
-
- int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
- int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
- int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
-
- const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
- const EVP_CIPHER *EVP_get_cipherbynid(int nid);
- const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);
-
- int EVP_CIPHER_nid(const EVP_CIPHER *e);
- int EVP_CIPHER_block_size(const EVP_CIPHER *e);
- int EVP_CIPHER_key_length(const EVP_CIPHER *e)
- int EVP_CIPHER_key_length(const EVP_CIPHER *e);
- int EVP_CIPHER_iv_length(const EVP_CIPHER *e);
- unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e);
- unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e);
- int EVP_CIPHER_type(const EVP_CIPHER *ctx);
-
- const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
- int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx);
- int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
- int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
- int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
- void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
- void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);
- int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx);
- int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx);
-
- int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
- int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
-
-=head1 DESCRIPTION
-
-The EVP cipher routines are a high level interface to certain
-symmetric ciphers.
-
-EVP_CIPHER_CTX_new() creates a cipher context.
-
-EVP_CIPHER_CTX_free() clears all information from a cipher context
-and free up any allocated memory associate with it, including B<ctx>
-itself. This function should be called after all operations using a
-cipher are complete so sensitive information does not remain in
-memory.
-
-EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
-with cipher B<type> from ENGINE B<impl>. B<ctx> must be created
-before calling this function. B<type> is normally supplied
-by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
-default implementation is used. B<key> is the symmetric key to use
-and B<iv> is the IV to use (if necessary), the actual number of bytes
-used for the key and IV depends on the cipher. It is possible to set
-all parameters to NULL except B<type> in an initial call and supply
-the remaining parameters in subsequent calls, all of which have B<type>
-set to NULL. This is done when the default cipher parameters are not
-appropriate.
-
-EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
-writes the encrypted version to B<out>. This function can be called
-multiple times to encrypt successive blocks of data. The amount
-of data written depends on the block alignment of the encrypted data:
-as a result the amount of data written may be anything from zero bytes
-to (inl + cipher_block_size - 1) so B<out> should contain sufficient
-room. The actual number of bytes written is placed in B<outl>. It also
-checks if B<in> and B<out> are partially overlapping, and if they are
-0 is returned to indicate failure.
-
-If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
-the "final" data, that is any data that remains in a partial block.
-It uses standard block padding (aka PKCS padding) as described in
-the NOTES section, below. The encrypted
-final data is written to B<out> which should have sufficient space for
-one cipher block. The number of bytes written is placed in B<outl>. After
-this function is called the encryption operation is finished and no further
-calls to EVP_EncryptUpdate() should be made.
-
-If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
-data and it will return an error if any data remains in a partial block:
-that is if the total data length is not a multiple of the block size.
-
-EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the
-corresponding decryption operations. EVP_DecryptFinal() will return an
-error code if padding is enabled and the final block is not correctly
-formatted. The parameters and restrictions are identical to the encryption
-operations except that if padding is enabled the decrypted data buffer B<out>
-passed to EVP_DecryptUpdate() should have sufficient room for
-(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in
-which case B<inl> bytes is sufficient.
-
-EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are
-functions that can be used for decryption or encryption. The operation
-performed depends on the value of the B<enc> parameter. It should be set
-to 1 for encryption, 0 for decryption and -1 to leave the value unchanged
-(the actual value of 'enc' being supplied in a previous call).
-
-EVP_CIPHER_CTX_reset() clears all information from a cipher context
-and free up any allocated memory associate with it, except the B<ctx>
-itself. This function should be called anytime B<ctx> is to be reused
-for another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal()
-series of calls.
-
-EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
-similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
-EVP_CipherInit_ex() except the B<ctx> parameter does not need to be
-initialized and they always use the default cipher implementation.
-
-EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are
-identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
-EVP_CipherFinal_ex(). In previous releases they also cleaned up
-the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean()
-must be called to free any context resources.
-
-EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
-return an EVP_CIPHER structure when passed a cipher name, a NID or an
-ASN1_OBJECT structure.
-
-EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when
-passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID
-value is an internal value which may not have a corresponding OBJECT
-IDENTIFIER.
-
-EVP_CIPHER_CTX_set_padding() enables or disables padding. This
-function should be called after the context is set up for encryption
-or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or
-EVP_CipherInit_ex(). By default encryption operations are padded using
-standard block padding and the padding is checked and removed when
-decrypting. If the B<pad> parameter is zero then no padding is
-performed, the total amount of data encrypted or decrypted must then
-be a multiple of the block size or an error will occur.
-
-EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
-length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
-structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
-for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
-given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
-for variable key length ciphers.
-
-EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
-If the cipher is a fixed length cipher then attempting to set the key
-length to any value other than the fixed value is an error.
-
-EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
-length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
-It will return zero if the cipher does not use an IV. The constant
-B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
-
-EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
-size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
-structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the maximum block
-length for all ciphers.
-
-EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
-cipher or context. This "type" is the actual NID of the cipher OBJECT
-IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
-128 bit RC2 have the same NID. If the cipher does not have an object
-identifier or does not have ASN1 support this function will return
-B<NID_undef>.
-
-EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
-an B<EVP_CIPHER_CTX> structure.
-
-EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
-EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
-EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
-EVP_CIPH_STREAM_CIPHER is returned.
-
-EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
-on the passed cipher. This will typically include any parameters and an
-IV. The cipher IV (if any) must be set when this call is made. This call
-should be made before the cipher is actually "used" (before any
-EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function
-may fail if the cipher does not have any ASN1 support.
-
-EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
-AlgorithmIdentifier "parameter". The precise effect depends on the cipher
-In the case of RC2, for example, it will set the IV and effective key length.
-This function should be called after the base cipher type is set but before
-the key is set. For example EVP_CipherInit() will be called with the IV and
-key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
-EVP_CipherInit() again with all parameters except the key set to NULL. It is
-possible for this function to fail if the cipher does not have any ASN1 support
-or the parameters cannot be set (for example the RC2 effective key length
-is not supported.
-
-EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
-and set.
-
-=head1 RETURN VALUES
-
-EVP_CIPHER_CTX_new() returns a pointer to a newly created
-B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
-
-EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
-return 1 for success and 0 for failure.
-
-EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
-EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
-
-EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
-EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
-
-EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
-
-EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
-return an B<EVP_CIPHER> structure or NULL on error.
-
-EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
-
-EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
-size.
-
-EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
-length.
-
-EVP_CIPHER_CTX_set_padding() always returns 1.
-
-EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
-length or zero if the cipher does not use an IV.
-
-EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
-OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
-
-EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
-
-EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater
-than zero for success and zero or a negative number.
-
-=head1 CIPHER LISTING
-
-All algorithms have a fixed key length unless otherwise stated.
-
-=over 4
-
-=item EVP_enc_null()
-
-Null cipher: does nothing.
-
-=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb()
-
-AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb()
-
-AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb()
-
-AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb()
-
-DES in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(), EVP_des_ede_cfb()
-
-Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(), EVP_des_ede3_cfb()
-
-Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_desx_cbc()
-
-DESX algorithm in CBC mode.
-
-=item EVP_rc4()
-
-RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
-
-=item EVP_rc4_40()
-
-RC4 stream cipher with 40 bit key length.
-This is obsolete and new code should use EVP_rc4()
-and the EVP_CIPHER_CTX_set_key_length() function.
-
-=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb()
-
-IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb()
-
-RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
-length cipher with an additional parameter called "effective key bits" or "effective key length".
-By default both are set to 128 bits.
-
-=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc()
-
-RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
-These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
-EVP_CIPHER_CTX_ctrl() to set the key length and effective key length.
-
-=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb()
-
-Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
-length cipher.
-
-=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb()
-
-CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
-length cipher.
-
-=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb()
-
-RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length
-cipher with an additional "number of rounds" parameter. By default the key length is set to 128
-bits and 12 rounds.
-
-=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm()
-
-AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
-These ciphers require additional control operations to function correctly: see
-the L</GCM and OCB Modes> section below for details.
-
-=item EVP_aes_128_ocb(void), EVP_aes_192_ocb(void), EVP_aes_256_ocb(void)
-
-Offset Codebook Mode (OCB) for 128, 192 and 256 bit keys respectively.
-These ciphers require additional control operations to function correctly: see
-the L</GCM and OCB Modes> section below for details.
-
-=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm()
-
-AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively.
-These ciphers require additional control operations to function correctly: see
-CCM mode section below for details.
-
-=back
-
-=head1 GCM and OCB Modes
-
-For GCM and OCB mode ciphers the behaviour of the EVP interface is subtly
-altered and several additional ctrl operations are supported.
-
-To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(),
-EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
-parameter B<out> set to B<NULL>.
-
-When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal()
-indicates if the operation was successful. If it does not indicate success
-the authentication operation has failed and any output data B<MUST NOT>
-be used as it is corrupted.
-
-The following ctrls are supported in both GCM and OCB modes:
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
-
-Sets the IV length: this call can only be made before specifying an IV. If
-not called a default IV length is used. For GCM AES and OCB AES the default is
-12 (i.e. 96 bits). For OCB mode the maximum is 15.
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
-
-Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
-This call can only be made when encrypting data and B<after> all data has been
-processed (e.g. after an EVP_EncryptFinal() call). For OCB mode the taglen must
-either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
-
-Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
-when decrypting data and must be made B<before> any data is processed (e.g.
-before any EVP_DecryptUpdate() call). For OCB mode the taglen must
-either be 16 or the value previously set via EVP_CTRL_AEAD_SET_TAG.
-
-In OCB mode calling this with B<tag> set to NULL sets the tag length. The tag
-length can only be set before specifying an IV. If not called a default tag
-length is used. For OCB AES the default is 16 (i.e. 128 bits). This is also the
-maximum tag length for OCB.
-
-See L</EXAMPLES> below for an example of the use of GCM mode.
-
-=head1 CCM Mode
-
-The behaviour of CCM mode ciphers is similar to GCM mode but with a few
-additional requirements and different ctrl values.
-
-Like GCM and OCB modes any additional authenticated data (AAD) is passed by calling
-EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
-parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext
-length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or
-EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>)
-set to B<NULL> and the length passed in the B<inl> parameter.
-
-The following ctrls are supported in CCM mode:
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
-
-This call is made to set the expected B<CCM> tag value when decrypting or
-the length of the tag (with the B<tag> parameter set to NULL) when encrypting.
-The tag length is often referred to as B<M>. If not set a default value is
-used (12 for AES).
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);
-
-Sets the CCM B<L> value. If not set a default is used (8 for AES).
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
-
-Sets the CCM nonce (IV) length: this call can only be made before specifying
-an nonce value. The nonce length is given by B<15 - L> so it is 7 by default
-for AES.
-
-=head1 NOTES
-
-Where possible the B<EVP> interface to symmetric ciphers should be used in
-preference to the low level interfaces. This is because the code then becomes
-transparent to the cipher used and much more flexible. Additionally, the
-B<EVP> interface will ensure the use of platform specific cryptographic
-acceleration such as AES-NI (the low level interfaces do not provide the
-guarantee).
-
-PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
-length of the encrypted data a multiple of the block size. Padding is always
-added so if the data is already a multiple of the block size B<n> will equal
-the block size. For example if the block size is 8 and 11 bytes are to be
-encrypted then 5 padding bytes of value 5 will be added.
-
-When decrypting the final block is checked to see if it has the correct form.
-
-Although the decryption operation can produce an error if padding is enabled,
-it is not a strong test that the input data or key is correct. A random block
-has better than 1 in 256 chance of being of the correct format and problems with
-the input data earlier on will not produce a final decrypt error.
-
-If padding is disabled then the decryption operation will always succeed if
-the total amount of data decrypted is a multiple of the block size.
-
-The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
-EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
-compatibility with existing code. New code should use EVP_EncryptInit_ex(),
-EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
-EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
-existing context without allocating and freeing it up on each call.
-
-EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.
-
-=head1 BUGS
-
-For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
-a limitation of the current RC5 code rather than the EVP interface.
-
-EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
-default key lengths. If custom ciphers exceed these values the results are
-unpredictable. This is because it has become standard practice to define a
-generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
-
-The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
-for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
-
-=head1 EXAMPLES
-
-Encrypt a string using IDEA:
-
- int do_crypt(char *outfile)
- {
- unsigned char outbuf[1024];
- int outlen, tmplen;
- /* Bogus key and IV: we'd normally set these from
- * another source.
- */
- unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
- unsigned char iv[] = {1,2,3,4,5,6,7,8};
- char intext[] = "Some Crypto Text";
- EVP_CIPHER_CTX ctx;
- FILE *out;
-
- ctx = EVP_CIPHER_CTX_new();
- EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv);
-
- if(!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext)))
- {
- /* Error */
- return 0;
- }
- /* Buffer passed to EVP_EncryptFinal() must be after data just
- * encrypted to avoid overwriting it.
- */
- if(!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen))
- {
- /* Error */
- return 0;
- }
- outlen += tmplen;
- EVP_CIPHER_CTX_free(ctx);
- /* Need binary mode for fopen because encrypted data is
- * binary data. Also cannot use strlen() on it because
- * it won't be null terminated and may contain embedded
- * nulls.
- */
- out = fopen(outfile, "wb");
- fwrite(outbuf, 1, outlen, out);
- fclose(out);
- return 1;
- }
-
-The ciphertext from the above example can be decrypted using the B<openssl>
-utility with the command line (shown on two lines for clarity):
-
- openssl idea -d <filename
- -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
-
-General encryption and decryption function example using FILE I/O and AES128
-with a 128-bit key:
-
- int do_crypt(FILE *in, FILE *out, int do_encrypt)
- {
- /* Allow enough space in output buffer for additional block */
- unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
- int inlen, outlen;
- EVP_CIPHER_CTX *ctx;
- /* Bogus key and IV: we'd normally set these from
- * another source.
- */
- unsigned char key[] = "0123456789abcdeF";
- unsigned char iv[] = "1234567887654321";
-
- /* Don't set key or IV right away; we want to check lengths */
- ctx = EVP_CIPHER_CTX_new();
- EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
- do_encrypt);
- OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
- OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
-
- /* Now we can set key and IV */
- EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt);
-
- for(;;)
- {
- inlen = fread(inbuf, 1, 1024, in);
- if (inlen <= 0) break;
- if(!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen))
- {
- /* Error */
- EVP_CIPHER_CTX_free(ctx);
- return 0;
- }
- fwrite(outbuf, 1, outlen, out);
- }
- if(!EVP_CipherFinal_ex(ctx, outbuf, &outlen))
- {
- /* Error */
- EVP_CIPHER_CTX_free(ctx);
- return 0;
- }
- fwrite(outbuf, 1, outlen, out);
-
- EVP_CIPHER_CTX_free(ctx);
- return 1;
- }
-
-
-=head1 SEE ALSO
-
-L<evp(3)>
-
-=head1 HISTORY
-
-Support for OCB mode was added in OpenSSL 1.1.0
-
-B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result,
-EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
-disappeared. EVP_CIPHER_CTX_init() remains as an alias for
-EVP_CIPHER_CTX_reset().
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_MD_meth_dup,
-EVP_MD_meth_new, EVP_MD_meth_free, EVP_MD_meth_set_input_blocksize,
-EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize,
-EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update,
-EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup,
-EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
-EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
-EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
-EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
-EVP_MD_meth_get_ctrl, EVP_MD_CTX_md_data
-- Routines to build up EVP_MD methods
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type);
- void EVP_MD_meth_free(EVP_MD *md);
- EVP_MD *EVP_MD_meth_dup(const EVP_MD *md);
-
- int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize);
- int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize);
- int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize);
- int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags);
- int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx));
- int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx,
- const void *data,
- size_t count));
- int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx,
- unsigned char *md));
- int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to,
- const EVP_MD_CTX *from));
- void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
- int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx));
- int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd,
- int p1, void *p2));
-
- int EVP_MD_meth_get_input_blocksize(const EVP_MD *md);
- int EVP_MD_meth_get_result_size(const EVP_MD *md);
- int EVP_MD_meth_get_app_datasize(const EVP_MD *md);
- unsigned long EVP_MD_meth_get_flags(const EVP_MD *md);
- int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx);
- int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx,
- const void *data,
- size_t count);
- int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx,
- unsigned char *md);
- int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to,
- const EVP_MD_CTX *from);
- int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx);
- int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
- int p1, void *p2);
-
-=head1 DESCRIPTION
-
-The B<EVP_MD> type is a structure for digest method implementation.
-It can also have associated public/private key signing and verifying
-routines.
-
-EVP_MD_meth_new() creates a new B<EVP_MD> structure.
-
-EVP_MD_meth_dup() creates a copy of B<md>.
-
-EVP_MD_meth_free() destroys a B<EVP_MD> structure.
-
-EVP_MD_meth_set_input_blocksize() sets the internal input block size
-for the method B<md> to B<blocksize> bytes.
-
-EVP_MD_meth_set_result_size() sets the size of the result that the
-digest method in B<md> is expected to produce to B<resultsize> bytes.
-
-The digest method may have its own private data, which OpenSSL will
-allocate for it. EVP_MD_meth_set_app_datasize() should be used to
-set the size for it to B<datasize>.
-
-EVP_MD_meth_set_flags() sets the flags to describe optional
-behaviours in the particular B<md>. Several flags can be or'd
-together. The available flags are:
-
-=over 4
-
-=item EVP_MD_FLAG_ONESHOT
-
-This digest method can only handles one block of input.
-
-=item EVP_MD_FLAG_DIGALGID_NULL
-
-When setting up a DigestAlgorithmIdentifier, this flag will have the
-parameter set to NULL by default. Use this for PKCS#1. I<Note: if
-combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
-
-=item EVP_MD_FLAG_DIGALGID_ABSENT
-
-When setting up a DigestAlgorithmIdentifier, this flag will have the
-parameter be left absent by default. I<Note: if combined with
-EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
-
-=item EVP_MD_FLAG_DIGALGID_CUSTOM
-
-Custom DigestAlgorithmIdentifier handling via ctrl, with
-B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
-EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
-Currently unused.
-
-=back
-
-EVP_MD_meth_set_init() sets the digest init function for B<md>.
-The digest init function is called by EVP_DigestInit(),
-EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
-and EVP_VerifyInit_ex().
-
-EVP_MD_meth_set_update() sets the digest update function for B<md>.
-The digest update function is called by EVP_DigestUpdate(),
-EVP_SignUpdate().
-
-EVP_MD_meth_set_final() sets the digest final function for B<md>.
-The digest final function is called by EVP_DigestFinal(),
-EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
-
-EVP_MD_meth_set_copy() sets the function for B<md> to do extra
-computations after the method's private data structure has been copied
-from one B<EVP_MD_CTX> to another. If all that's needed is to copy
-the data, there is no need for this copy function.
-Note that the copy function is passed two B<EVP_MD_CTX *>, the private
-data structure is then available with EVP_MD_CTX_md_data().
-This copy function is called by EVP_MD_CTX_copy() and
-EVP_MD_CTX_copy_ex().
-
-EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra
-cleanup before the method's private data structure is cleaned out and
-freed.
-Note that the cleanup function is passed a B<EVP_MD_CTX *>, the
-private data structure is then available with EVP_MD_CTX_md_data().
-This cleanup function is called by EVP_MD_CTX_reset() and
-EVP_MD_CTX_free().
-
-EVP_MD_meth_set_ctrl() sets the control function for B<md>.
-
-
-EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
-EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
-EVP_MD_meth_get_init(), EVP_MD_meth_get_update(),
-EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(),
-EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
-to retrieve the method data given with the EVP_MD_meth_set_*()
-functions above.
-
-=head1 SEE ALSO
-
-L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
-
-=head1 HISTORY
-
-The B<EVP_MD> structure was openly available in OpenSSL before version
-1.1. The functions described here were added in OpenSSL version 1.1.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_OpenInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *ek,
- int ekl, unsigned char *iv, EVP_PKEY *priv);
- int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl, unsigned char *in, int inl);
- int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl);
-
-=head1 DESCRIPTION
-
-The EVP envelope routines are a high level interface to envelope
-decryption. They decrypt a public key encrypted symmetric key and
-then decrypt data using it.
-
-EVP_OpenInit() initializes a cipher context B<ctx> for decryption
-with cipher B<type>. It decrypts the encrypted symmetric key of length
-B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>.
-The IV is supplied in the B<iv> parameter.
-
-EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties
-as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as
-documented on the L<EVP_EncryptInit(3)> manual
-page.
-
-=head1 NOTES
-
-It is possible to call EVP_OpenInit() twice in the same way as
-EVP_DecryptInit(). The first call should have B<priv> set to NULL
-and (after setting any cipher parameters) it should be called again
-with B<type> set to NULL.
-
-If the cipher passed in the B<type> parameter is a variable length
-cipher then the key length will be set to the value of the recovered
-key length. If the cipher is a fixed length cipher then the recovered
-key length must match the fixed cipher length.
-
-=head1 RETURN VALUES
-
-EVP_OpenInit() returns 0 on error or a non zero integer (actually the
-recovered secret key size) if successful.
-
-EVP_OpenUpdate() returns 1 for success or 0 for failure.
-
-EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success.
-
-=head1 SEE ALSO
-
-L<evp(3)>, L<rand(3)>,
-L<EVP_EncryptInit(3)>,
-L<EVP_SealInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str,
-EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding,
-EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits,
-EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits,
-EVP_PKEY_CTX_set_dh_paramgen_prime_len,
-EVP_PKEY_CTX_set_dh_paramgen_generator,
-EVP_PKEY_CTX_set_ec_paramgen_curve_nid,
-EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
- int cmd, int p1, void *p2);
- int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,
- const char *value);
-
- #include <openssl/rsa.h>
-
- int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
-
- int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
- int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
- int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
- int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
-
- #include <openssl/dsa.h>
- int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
-
- #include <openssl/dh.h>
- int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
- int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
-
- #include <openssl/ec.h>
- int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
- int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
-
-=head1 DESCRIPTION
-
-The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
-B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter
-B<optype> is a mask indicating which operations the control can be applied to.
-The control command is indicated in B<cmd> and any additional arguments in
-B<p1> and B<p2>.
-
-Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will
-instead call one of the algorithm specific macros below.
-
-The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm
-specific control operation to a context B<ctx> in string form. This is
-intended to be used for options specified on the command line or in text
-files. The commands supported are documented in the openssl utility
-command line pages for the option B<-pkeyopt> which is supported by the
-B<pkeyutl>, B<genpkey> and B<req> commands.
-
-All the remaining "functions" are implemented as macros.
-
-The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used
-in a signature. It can be used with any public key algorithm supporting
-signature operations.
-
-The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>.
-The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding,
-RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding,
-RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only),
-RSA_X931_PADDING for X9.31 padding (signature operations only) and
-RSA_PKCS1_PSS_PADDING (sign and verify only).
-
-Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md()
-is used. If this macro is called for PKCS#1 padding the plaintext buffer is
-an actual digest value and is encapsulated in a DigestInfo structure according
-to PKCS#1 when signing and this structure is expected (and stripped off) when
-verifying. If this control is not used with RSA and PKCS#1 padding then the
-supplied data is used directly and not encapsulated. In the case of X9.31
-padding for RSA the algorithm identifier byte is added or checked and removed
-if this control is called. If it is not called then the first byte of the plaintext
-buffer is expected to be the algorithm identifier byte.
-
-The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to
-B<len> as its name implies it is only supported for PSS padding. Two special
-values are supported: -1 sets the salt length to the digest length. When
-signing -2 sets the salt length to the maximum permissible value. When
-verifying -2 causes the salt length to be automatically determined based on the
-B<PSS> block structure. If this macro is not called a salt length value of -2
-is used by default.
-
-The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for
-RSA key generation to B<bits>. If not specified 1024 bits is used.
-
-The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value
-for RSA key generation to B<pubexp> currently it should be an odd integer. The
-B<pubexp> pointer is used internally by this function so it should not be
-modified or free after the call. If this macro is not called then 65537 is used.
-
-The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used
-for DSA parameter generation to B<bits>. If not specified 1024 is used.
-
-The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH
-prime parameter B<p> for DH parameter generation. If this macro is not called
-then 1024 is used.
-
-The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen>
-for DH parameter generation. If not specified 2 is used.
-
-The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
-generation to B<nid>. For EC parameter generation this macro must be called
-or an error occurs because there is no default curve.
-This function can also be called to set the curve explicitly when
-generating an EC key.
-
-The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to
-B<param_enc> when generating EC parameters or an EC key. The encoding can be
-B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions
-of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form.
-For maximum compatibility the named curve form should be used. Note: the
-B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous
-versions should use 0 instead.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0
-or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>
-L<EVP_PKEY_keygen(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
- EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
- EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx);
- void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_CTX_new() function allocates public key algorithm context using
-the algorithm specified in B<pkey> and ENGINE B<e>.
-
-The EVP_PKEY_CTX_new_id() function allocates public key algorithm context
-using the algorithm specified by B<id> and ENGINE B<e>. It is normally used
-when no B<EVP_PKEY> structure is associated with the operations, for example
-during parameter generation of key generation for some algorithms.
-
-EVP_PKEY_CTX_dup() duplicates the context B<ctx>.
-
-EVP_PKEY_CTX_free() frees up the context B<ctx>.
-If B<ctx> is NULL, nothing is done.
-
-=head1 NOTES
-
-The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used
-by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between
-threads: that is it is not permissible to use the same context simultaneously
-in two threads.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either
-the newly allocated B<EVP_PKEY_CTX> structure of B<NULL> if an error occurred.
-
-EVP_PKEY_CTX_free() does not return a value.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_new(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt,
-EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info -
-HMAC-based Extract-and-Expand key derivation algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/kdf.h>
-
- int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
-
- int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
- int saltlen);
-
- int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key,
- int keylen);
-
- int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info,
- int infolen);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function.
-HKDF follows the "extract-then-expand" paradigm, where the KDF logically
-consists of two modules. The first stage takes the input keying material
-and "extracts" from it a fixed-length pseudorandom key K. The second stage
-"expands" the key K into several additional pseudorandom keys (the output
-of the KDF).
-
-EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF.
-
-EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the
-buffer B<salt>. Any existing value is replaced.
-
-EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer
-B<key>. Any existing value is replaced.
-
-EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the
-buffer B<info>. If a value is already set, it is appended to the existing
-value.
-
-=head1 STRING CTRLS
-
-HKDF also supports string based control operations via
-L<EVP_PKEY_CTX_ctrl_str(3)>.
-The B<type> parameter "md" uses the supplied B<value> as the name of the digest
-algorithm to use.
-The B<type> parameters "salt", "key" and "info" use the supplied B<value>
-parameter as a B<seed>, B<key> or B<info> value.
-The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex
-string which is converted to binary.
-
-=head1 NOTES
-
-All these functions are implemented as macros.
-
-A context for HKDF can be obtained by calling:
-
- EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_HKDF, NULL);
-
-The digest, key, salt and info values must be set before a key is derived or
-an error occurs.
-
-The total length of the info buffer cannot exceed 1024 bytes in length: this
-should be more than enough for any normal use of HKDF.
-
-The output length of the KDF is specified via the length parameter to the
-L<EVP_PKEY_derive(3)> function.
-Since the HKDF output length is variable, passing a B<NULL> buffer as a means
-to obtain the requisite length is not meaningful with HKDF.
-Instead, the caller must allocate a buffer of the desired length, and pass that
-buffer to L<EVP_PKEY_derive(3)> along with (a pointer initialized to) the
-desired length.
-
-Optimised versions of HKDF can be implemented in an ENGINE.
-
-=head1 RETURN VALUES
-
-All these functions return 1 for success and 0 or a negative value for failure.
-In particular a return value of -2 indicates the operation is not supported by
-the public key algorithm.
-
-=head1 EXAMPLE
-
-This example derives 10 bytes using SHA-256 with the secret key "secret",
-salt value "salt" and info value "label":
-
- EVP_PKEY_CTX *pctx;
- unsigned char out[10];
- size_t outlen = sizeof(out);
- pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
-
- if (EVP_PKEY_derive_init(pctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set1_salt(pctx, "salt", 4) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set1_key(pctx, "secret", 6) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 6) <= 0)
- /* Error */
- if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
- /* Error */
-
-=head1 CONFORMING TO
-
-RFC 5869
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_CTX_ctrl_str(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_CTX_set_tls1_prf_md,
-EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed -
-TLS PRF key derivation algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/kdf.h>
-
- int EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
- int EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx,
- unsigned char *sec, int seclen);
- int EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx, seed, seedlen)
- unsigned char *seed, int seedlen);
-
-=head1 DESCRIPTION
-
-The B<EVP_PKEY_TLS1_PRF> algorithm implements the PRF key derivation function for
-TLS. It has no associated private key and only implements key derivation
-using EVP_PKEY_derive().
-
-EVP_PKEY_set_tls1_prf_md() sets the message digest associated with the
-TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF
-algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
-
-EVP_PKEY_CTX_set_tls1_prf_secret() sets the secret value of the TLS PRF
-to B<seclen> bytes of the buffer B<sec>. Any existing secret value is replaced
-and any seed is reset.
-
-EVP_PKEY_CTX_add1_tls1_prf_seed() sets the seed to B<seedlen> bytes of B<seed>.
-If a seed is already set it is appended to the existing value.
-
-=head1 STRING CTRLS
-
-The TLS PRF also supports string based control operations using
-L<EVP_PKEY_CTX_ctrl_str(3)>.
-The B<type> parameter "md" uses the supplied B<value> as the name of the digest
-algorithm to use.
-The B<type> parameters "secret" and "seed" use the supplied B<value> parameter
-as a secret or seed value.
-The names "hexsecret" and "hexseed" are similar except they take a hex string
-which is converted to binary.
-
-=head1 NOTES
-
-All these functions are implemented as macros.
-
-A context for the TLS PRF can be obtained by calling:
-
- EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_TLS1_PRF, NULL);
-
-The digest, secret value and seed must be set before a key is derived or an
-error occurs.
-
-The total length of all seeds cannot exceed 1024 bytes in length: this should
-be more than enough for any normal use of the TLS PRF.
-
-The output length of the PRF is specified by the length parameter in the
-EVP_PKEY_derive() function. Since the output length is variable, setting
-the buffer to B<NULL> is not meaningful for the TLS PRF.
-
-Optimised versions of the TLS PRF can be implemented in an ENGINE.
-
-=head1 RETURN VALUES
-
-All these functions return 1 for success and 0 or a negative value for failure.
-In particular a return value of -2 indicates the operation is not supported by
-the public key algorithm.
-
-=head1 EXAMPLE
-
-This example derives 10 bytes using SHA-256 with the secret key "secret"
-and seed value "seed":
-
- EVP_PKEY_CTX *pctx;
- unsigned char out[10];
- size_t outlen = sizeof(out);
- pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL);
- if (EVP_PKEY_derive_init(pctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0)
- /* Error */
- if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
- /* Error */
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_CTX_ctrl_str(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters,
-EVP_PKEY_cmp - public key parameter and comparison functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey);
- int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from);
-
- int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b);
- int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b);
-
-=head1 DESCRIPTION
-
-The function EVP_PKEY_missing_parameters() returns 1 if the public key
-parameters of B<pkey> are missing and 0 if they are present or the algorithm
-doesn't use parameters.
-
-The function EVP_PKEY_copy_parameters() copies the parameters from key
-B<from> to key B<to>. An error is returned if the parameters are missing in
-B<from> or present in both B<from> and B<to> and mismatch. If the parameters
-in B<from> and B<to> are both present and match this function has no effect.
-
-The function EVP_PKEY_cmp_parameters() compares the parameters of keys
-B<a> and B<b>.
-
-The function EVP_PKEY_cmp() compares the public key components and parameters
-(if present) of keys B<a> and B<b>.
-
-=head1 NOTES
-
-The main purpose of the functions EVP_PKEY_missing_parameters() and
-EVP_PKEY_copy_parameters() is to handle public keys in certificates where the
-parameters are sometimes omitted from a public key if they are inherited from
-the CA that signed it.
-
-Since OpenSSL private keys contain public key components too the function
-EVP_PKEY_cmp() can also be used to determine if a private key matches
-a public key.
-
-=head1 RETURN VALUES
-
-The function EVP_PKEY_missing_parameters() returns 1 if the public key
-parameters of B<pkey> are missing and 0 if they are present or the algorithm
-doesn't use parameters.
-
-These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for
-failure.
-
-The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the
-keys match, 0 if they don't match, -1 if the key types are different and
--2 if the operation is not supported.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_keygen(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx,
- unsigned char *out, size_t *outlen,
- const unsigned char *in, size_t inlen);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_decrypt_init() function initializes a public key algorithm
-context using key B<pkey> for a decryption operation.
-
-The EVP_PKEY_decrypt() function performs a public key decryption operation
-using B<ctx>. The data to be decrypted is specified using the B<in> and
-B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output
-buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then
-before the call the B<outlen> parameter should contain the length of the
-B<out> buffer, if the call is successful the decrypted data is written to
-B<out> and the amount of data written to B<outlen>.
-
-=head1 NOTES
-
-After the call to EVP_PKEY_decrypt_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
-
-The function EVP_PKEY_decrypt() can be called more than once on the same
-context if several operations are performed using the same parameters.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0
-or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
-
-=head1 EXAMPLE
-
-Decrypt data using OAEP (for RSA keys):
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
-
- EVP_PKEY_CTX *ctx;
- unsigned char *out, *in;
- size_t outlen, inlen;
- EVP_PKEY *key;
- /* NB: assumes key in, inlen are already set up
- * and that key is an RSA private key
- */
- ctx = EVP_PKEY_CTX_new(key);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_decrypt_init(ctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0)
- /* Error */
-
- /* Determine buffer length */
- if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0)
- /* Error */
-
- out = OPENSSL_malloc(outlen);
-
- if (!out)
- /* malloc failure */
-
- if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0)
- /* Error */
-
- /* Decrypted data is outlen bytes written to buffer out */
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
- int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_derive_init() function initializes a public key algorithm
-context using key B<pkey> for shared secret derivation.
-
-The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
-be a public key.
-
-The EVP_PKEY_derive() derives a shared secret using B<ctx>.
-If B<key> is B<NULL> then the maximum size of the output buffer is written to
-the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
-B<keylen> parameter should contain the length of the B<key> buffer, if the call
-is successful the shared secret is written to B<key> and the amount of data
-written to B<keylen>.
-
-=head1 NOTES
-
-After the call to EVP_PKEY_derive_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
-
-The function EVP_PKEY_derive() can be called more than once on the same
-context if several operations are performed using the same parameters.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
-or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
-
-=head1 EXAMPLE
-
-Derive shared secret (for example DH or EC keys):
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
-
- EVP_PKEY_CTX *ctx;
- unsigned char *skey;
- size_t skeylen;
- EVP_PKEY *pkey, *peerkey;
- /* NB: assumes pkey, peerkey have been already set up */
-
- ctx = EVP_PKEY_CTX_new(pkey);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_derive_init(ctx) <= 0)
- /* Error */
- if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
- /* Error */
-
- /* Determine buffer length */
- if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
- /* Error */
-
- skey = OPENSSL_malloc(skeylen);
-
- if (!skey)
- /* malloc failure */
-
- if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
- /* Error */
-
- /* Shared secret is skey bytes written to buffer skey */
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx,
- unsigned char *out, size_t *outlen,
- const unsigned char *in, size_t inlen);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_encrypt_init() function initializes a public key algorithm
-context using key B<pkey> for an encryption operation.
-
-The EVP_PKEY_encrypt() function performs a public key encryption operation
-using B<ctx>. The data to be encrypted is specified using the B<in> and
-B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output
-buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then
-before the call the B<outlen> parameter should contain the length of the
-B<out> buffer, if the call is successful the encrypted data is written to
-B<out> and the amount of data written to B<outlen>.
-
-=head1 NOTES
-
-After the call to EVP_PKEY_encrypt_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
-
-The function EVP_PKEY_encrypt() can be called more than once on the same
-context if several operations are performed using the same parameters.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0
-or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
-
-=head1 EXAMPLE
-
-Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or
-L<d2i_X509(3)> for means to load a public key. You may also simply
-set 'eng = NULL;' to start with the default OpenSSL RSA implementation:
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
- #include <openssl/engine.h>
-
- EVP_PKEY_CTX *ctx;
- ENGINE *eng;
- unsigned char *out, *in;
- size_t outlen, inlen;
- EVP_PKEY *key;
- /* NB: assumes eng, key, in, inlen are already set up,
- * and that key is an RSA public key
- */
- ctx = EVP_PKEY_CTX_new(key, eng);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_encrypt_init(ctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0)
- /* Error */
-
- /* Determine buffer length */
- if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0)
- /* Error */
-
- out = OPENSSL_malloc(outlen);
-
- if (!out)
- /* malloc failure */
-
- if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0)
- /* Error */
-
- /* Encrypted data is outlen bytes written to buffer out */
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<engine(3)>,
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_get_default_digest_nid - get default signature digest
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
- int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_get_default_digest_nid() function sets B<pnid> to the default
-message digest NID for the public key signature operations associated with key
-B<pkey>.
-
-=head1 NOTES
-
-For all current standard OpenSSL public key algorithms SHA1 is returned.
-
-=head1 RETURN VALUES
-
-The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest
-is advisory (that is other digests can be used) and 2 if it is mandatory (other
-digests can not be used). It returns 0 or a negative value for failure. In
-particular a return value of -2 indicates the operation is not supported by the
-public key algorithm.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-
-=head1 HISTORY
-
-This function was first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
-EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
-EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
-EVP_PKEY_CTX_get_app_data - key and parameter generation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
- int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
-
- typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
-
- void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
- EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
-
- int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
-
- void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
- void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_keygen_init() function initializes a public key algorithm
-context using key B<pkey> for a key generation operation.
-
-The EVP_PKEY_keygen() function performs a key generation operation, the
-generated key is written to B<ppkey>.
-
-The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar
-except parameters are generated.
-
-The function EVP_PKEY_set_cb() sets the key or parameter generation callback
-to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
-generation callback.
-
-The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated
-with the generation operation. If B<idx> is -1 the total number of
-parameters available is returned. Any non negative value returns the value of
-that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
-B<idx> should only be called within the generation callback.
-
-If the callback returns 0 then the key generation operation is aborted and an
-error occurs. This might occur during a time consuming operation where
-a user clicks on a "cancel" button.
-
-The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set
-and retrieve an opaque pointer. This can be used to set some application
-defined value which can be retrieved in the callback: for example a handle
-which is used to update a "progress dialog".
-
-=head1 NOTES
-
-After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
-specific control operations can be performed to set any appropriate parameters
-for the operation.
-
-The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than
-once on the same context if several operations are performed using the same
-parameters.
-
-The meaning of the parameters passed to the callback will depend on the
-algorithm and the specific implementation of the algorithm. Some might not
-give any useful information at all during key or parameter generation. Others
-might not even call the callback.
-
-The operation performed by key or parameter generation depends on the algorithm
-used. In some cases (e.g. EC with a supplied named curve) the "generation"
-option merely sets the appropriate fields in an EVP_PKEY structure.
-
-In OpenSSL an EVP_PKEY structure containing a private key also contains the
-public key components and parameters (if any). An OpenSSL private key is
-equivalent to what some libraries call a "key pair". A private key can be used
-in functions which require the use of a public key or parameters.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
-EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
-In particular a return value of -2 indicates the operation is not supported by
-the public key algorithm.
-
-=head1 EXAMPLES
-
-Generate a 2048 bit RSA key:
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
-
- EVP_PKEY_CTX *ctx;
- EVP_PKEY *pkey = NULL;
- ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_keygen_init(ctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
- /* Error */
-
- /* Generate key */
- if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
- /* Error */
-
-Generate a key from a set of parameters:
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
-
- EVP_PKEY_CTX *ctx;
- EVP_PKEY *pkey = NULL, *param;
- /* Assumed param is set up already */
- ctx = EVP_PKEY_CTX_new(param);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_keygen_init(ctx) <= 0)
- /* Error */
-
- /* Generate key */
- if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
- /* Error */
-
-Example of generation callback for OpenSSL public key implementations:
-
- /* Application data is a BIO to output status to */
-
- EVP_PKEY_CTX_set_app_data(ctx, status_bio);
-
- static int genpkey_cb(EVP_PKEY_CTX *ctx)
- {
- char c = '*';
- BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
- int p;
- p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
- if (p == 0) c = '.';
- if (p == 1) c = '+';
- if (p == 2) c = '*';
- if (p == 3) c = '\n';
- BIO_write(b, &c, 1);
- (void)BIO_flush(b);
- return 1;
- }
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_free - private key allocation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_PKEY *EVP_PKEY_new(void);
- int EVP_PKEY_up_ref(EVP_PKEY *key);
- void EVP_PKEY_free(EVP_PKEY *key);
-
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is
-used by OpenSSL to store private keys. The reference count is set to B<1>.
-
-EVP_PKEY_up_ref() increments the reference count of B<key>.
-
-EVP_PKEY_free() decrements the reference count of B<key> and, if the reference
-count is zero, frees it up. If B<key> is NULL, nothing is done.
-
-=head1 NOTES
-
-The B<EVP_PKEY> structure is used by various OpenSSL functions which require a
-general private key without reference to any particular algorithm.
-
-The structure returned by EVP_PKEY_new() is empty. To add a private key to this
-empty structure the functions described in L<EVP_PKEY_set1_RSA(3)> should be
-used.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> structure or
-B<NULL> if an error occurred.
-
-EVP_PKEY_up_ref() returns 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_set1_RSA(3)>
-
-=head1 HISTORY
-
-EVP_PKEY_new() and EVP_PKEY_free() exist in all versions of OpenSSL.
-
-EVP_PKEY_up_ref() was first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public key algorithm printing routines
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey,
- int indent, ASN1_PCTX *pctx);
- int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey,
- int indent, ASN1_PCTX *pctx);
- int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey,
- int indent, ASN1_PCTX *pctx);
-
-=head1 DESCRIPTION
-
-The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and
-EVP_PKEY_print_params() print out the public, private or parameter components
-of key B<pkey> respectively. The key is sent to BIO B<out> in human readable
-form. The parameter B<indent> indicated how far the printout should be indented.
-
-The B<pctx> parameter allows the print output to be finely tuned by using
-ASN1 printing options. If B<pctx> is set to NULL then default values will
-be used.
-
-=head1 NOTES
-
-Currently no public key algorithms include any options in the B<pctx> parameter
-parameter.
-
-If the key does not include all the components indicated by the function then
-only those contained in the key will be printed. For example passing a public
-key to EVP_PKEY_print_private() will only print the public components.
-
-=head1 RETURN VALUES
-
-These functions all return 1 for success and 0 or a negative value for failure.
-In particular a return value of -2 indicates the operation is not supported by
-the public key algorithm.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_keygen(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
-EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
-EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
-EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY,
-EVP_PKEY_get0_hmac,
-EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id
-- EVP_PKEY assignment functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
- int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
- int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
- int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
-
- RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
- DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
- DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
- EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
-
- const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
- RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey);
- DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey);
- DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey);
- EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey);
-
- int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
- int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
- int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
- int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
-
- int EVP_PKEY_id(const EVP_PKEY *pkey);
- int EVP_PKEY_base_id(const EVP_PKEY *pkey);
- int EVP_PKEY_type(int type);
-
-=head1 DESCRIPTION
-
-EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
-EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>.
-
-EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
-EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
-B<NULL> if the key is not of the correct type.
-
-EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(),
-EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the
-referenced key in B<pkey> or B<NULL> if the key is not of the
-correct type but the reference count of the returned key is
-B<not> incremented and so must not be freed up after use.
-
-EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
-and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
-however these use the supplied B<key> internally and so B<key>
-will be freed when the parent B<pkey> is freed.
-
-EVP_PKEY_base_id() returns the type of B<pkey>. For example
-an RSA key will return B<EVP_PKEY_RSA>.
-
-EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys
-using the same algorithm could use different OIDs. For example an RSA key could
-use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to
-B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of
-alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not
-often seen in practice.
-
-EVP_PKEY_type() returns the underlying type of the NID B<type>. For example
-EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
-
-=head1 NOTES
-
-In accordance with the OpenSSL naming convention the key obtained
-from or assigned to the B<pkey> using the B<1> functions must be
-freed as well as B<pkey>.
-
-EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
-and EVP_PKEY_assign_EC_KEY() are implemented as macros.
-
-Most applications wishing to know a key type will simply call
-EVP_PKEY_base_id() and will not care about the actual type:
-which will be identical in almost all cases.
-
-Previous versions of this document suggested using EVP_PKEY_type(pkey->type)
-to determine the type of a key. Since B<EVP_PKEY> is now opaque this
-is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
-
-=head1 RETURN VALUES
-
-EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
-EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
-
-EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
-EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
-an error occurred.
-
-EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
-and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
-
-EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key
-type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
- unsigned char *sig, size_t *siglen,
- const unsigned char *tbs, size_t tbslen);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_sign_init() function initializes a public key algorithm
-context using key B<pkey> for a signing operation.
-
-The EVP_PKEY_sign() function performs a public key signing operation
-using B<ctx>. The data to be signed is specified using the B<tbs> and
-B<tbslen> parameters. If B<sig> is B<NULL> then the maximum size of the output
-buffer is written to the B<siglen> parameter. If B<sig> is not B<NULL> then
-before the call the B<siglen> parameter should contain the length of the
-B<sig> buffer, if the call is successful the signature is written to
-B<sig> and the amount of data written to B<siglen>.
-
-=head1 NOTES
-
-EVP_PKEY_sign() does not hash the data to be signed, and therefore is
-normally used to sign digests. For signing arbitrary messages, see the
-L<EVP_DigestSignInit(3)> and
-L<EVP_SignInit(3)> signing interfaces instead.
-
-After the call to EVP_PKEY_sign_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation (see L<EVP_PKEY_CTX_ctrl(3)>).
-
-The function EVP_PKEY_sign() can be called more than once on the same
-context if several operations are performed using the same parameters.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0
-or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
-
-=head1 EXAMPLE
-
-Sign data using RSA with PKCS#1 padding and SHA256 digest:
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
-
- EVP_PKEY_CTX *ctx;
- /* md is a SHA-256 digest in this example. */
- unsigned char *md, *sig;
- size_t mdlen = 32, siglen;
- EVP_PKEY *signing_key;
-
- /*
- * NB: assumes signing_key and md are set up before the next
- * step. signing_key must be an RSA private key and md must
- * point to the SHA-256 digest to be signed.
- */
- ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_sign_init(ctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
- /* Error */
-
- /* Determine buffer length */
- if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)
- /* Error */
-
- sig = OPENSSL_malloc(siglen);
-
- if (!sig)
- /* malloc failure */
-
- if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)
- /* Error */
-
- /* Signature is siglen bytes written to buffer sig */
-
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_CTX_ctrl(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
- const unsigned char *sig, size_t siglen,
- const unsigned char *tbs, size_t tbslen);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_verify_init() function initializes a public key algorithm
-context using key B<pkey> for a signature verification operation.
-
-The EVP_PKEY_verify() function performs a public key verification operation
-using B<ctx>. The signature is specified using the B<sig> and
-B<siglen> parameters. The verified data (i.e. the data believed originally
-signed) is specified using the B<tbs> and B<tbslen> parameters.
-
-=head1 NOTES
-
-After the call to EVP_PKEY_verify_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
-
-The function EVP_PKEY_verify() can be called more than once on the same
-context if several operations are performed using the same parameters.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was
-successful and 0 if it failed. Unlike other functions the return value 0 from
-EVP_PKEY_verify() only indicates that the signature did not not verify
-successfully (that is tbs did not match the original data or the signature was
-of invalid form) it is not an indication of a more serious error.
-
-A negative value indicates an error other that signature verification failure.
-In particular a return value of -2 indicates the operation is not supported by
-the public key algorithm.
-
-=head1 EXAMPLE
-
-Verify signature using PKCS#1 and SHA256 digest:
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
-
- EVP_PKEY_CTX *ctx;
- unsigned char *md, *sig;
- size_t mdlen, siglen;
- EVP_PKEY *verify_key;
- /* NB: assumes verify_key, sig, siglen md and mdlen are already set up
- * and that verify_key is an RSA public key
- */
- ctx = EVP_PKEY_CTX_new(verify_key);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_verify_init(ctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
- /* Error */
-
- /* Perform operation */
- ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);
-
- /* ret == 1 indicates success, 0 verify failure and < 0 for some
- * other error.
- */
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
- unsigned char *rout, size_t *routlen,
- const unsigned char *sig, size_t siglen);
-
-=head1 DESCRIPTION
-
-The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
-context using key B<pkey> for a verify recover operation.
-
-The EVP_PKEY_verify_recover() function recovers signed data
-using B<ctx>. The signature is specified using the B<sig> and
-B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output
-buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then
-before the call the B<routlen> parameter should contain the length of the
-B<rout> buffer, if the call is successful recovered data is written to
-B<rout> and the amount of data written to B<routlen>.
-
-=head1 NOTES
-
-Normally an application is only interested in whether a signature verification
-operation is successful in those cases the EVP_verify() function should be
-used.
-
-Sometimes however it is useful to obtain the data originally signed using a
-signing operation. Only certain public key algorithms can recover a signature
-in this way (for example RSA in PKCS padding mode).
-
-After the call to EVP_PKEY_verify_recover_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
-
-The function EVP_PKEY_verify_recover() can be called more than once on the same
-context if several operations are performed using the same parameters.
-
-=head1 RETURN VALUES
-
-EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for success
-and 0 or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
-
-=head1 EXAMPLE
-
-Recover digest originally signed using PKCS#1 and SHA256 digest:
-
- #include <openssl/evp.h>
- #include <openssl/rsa.h>
-
- EVP_PKEY_CTX *ctx;
- unsigned char *rout, *sig;
- size_t routlen, siglen;
- EVP_PKEY *verify_key;
- /* NB: assumes verify_key, sig and siglen are already set up
- * and that verify_key is an RSA public key
- */
- ctx = EVP_PKEY_CTX_new(verify_key);
- if (!ctx)
- /* Error occurred */
- if (EVP_PKEY_verify_recover_init(ctx) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
- /* Error */
- if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
- /* Error */
-
- /* Determine buffer length */
- if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0)
- /* Error */
-
- rout = OPENSSL_malloc(routlen);
-
- if (!rout)
- /* malloc failure */
-
- if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0)
- /* Error */
-
- /* Recovered data is routlen bytes written to buffer rout */
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_derive(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
- unsigned char **ek, int *ekl, unsigned char *iv,
- EVP_PKEY **pubk, int npubk);
- int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl, unsigned char *in, int inl);
- int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
- int *outl);
-
-=head1 DESCRIPTION
-
-The EVP envelope routines are a high level interface to envelope
-encryption. They generate a random key and IV (if required) then
-"envelope" it by using public key encryption. Data can then be
-encrypted using this key.
-
-EVP_SealInit() initializes a cipher context B<ctx> for encryption
-with cipher B<type> using a random secret key and IV. B<type> is normally
-supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted
-using one or more public keys, this allows the same encrypted data to be
-decrypted using any of the corresponding private keys. B<ek> is an array of
-buffers where the public key encrypted secret key will be written, each buffer
-must contain enough room for the corresponding encrypted key: that is
-B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual
-size of each encrypted secret key is written to the array B<ekl>. B<pubk> is
-an array of B<npubk> public keys.
-
-The B<iv> parameter is a buffer where the generated IV is written to. It must
-contain enough room for the corresponding cipher's IV, as determined by (for
-example) EVP_CIPHER_iv_length(type).
-
-If the cipher does not require an IV then the B<iv> parameter is ignored
-and can be B<NULL>.
-
-EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties
-as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as
-documented on the L<EVP_EncryptInit(3)> manual
-page.
-
-=head1 RETURN VALUES
-
-EVP_SealInit() returns 0 on error or B<npubk> if successful.
-
-EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for
-failure.
-
-=head1 NOTES
-
-Because a random secret key is generated the random number generator
-must be seeded before calling EVP_SealInit().
-
-The public key must be RSA because it is the only OpenSSL public key
-algorithm that supports key transport.
-
-Envelope encryption is the usual method of using public key encryption
-on large amounts of data, this is because public key encryption is slow
-but symmetric encryption is fast. So symmetric encryption is used for
-bulk encryption and the small random symmetric key used is transferred
-using public key encryption.
-
-It is possible to call EVP_SealInit() twice in the same way as
-EVP_EncryptInit(). The first call should have B<npubk> set to 0
-and (after setting any cipher parameters) it should be called again
-with B<type> set to NULL.
-
-=head1 SEE ALSO
-
-L<evp(3)>, L<rand(3)>,
-L<EVP_EncryptInit(3)>,
-L<EVP_OpenInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_PKEY_size,
-EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing
-functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
- int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
- int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s, EVP_PKEY *pkey);
-
- void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
-
- int EVP_PKEY_size(EVP_PKEY *pkey);
-
-=head1 DESCRIPTION
-
-The EVP signature routines are a high level interface to digital
-signatures.
-
-EVP_SignInit_ex() sets up signing context B<ctx> to use digest
-B<type> from ENGINE B<impl>. B<ctx> must be created with
-EVP_MD_CTX_new() before calling this function.
-
-EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
-signature context B<ctx>. This function can be called several times on the
-same B<ctx> to include additional data.
-
-EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
-places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey)
-bytes in size. B<s> is an OUT parameter, and not used as an IN parameter.
-The number of bytes of data written (i.e. the length of the signature)
-will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
-will be written.
-
-EVP_SignInit() initializes a signing context B<ctx> to use the default
-implementation of digest B<type>.
-
-EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
-signature returned by EVP_SignFinal() may be smaller.
-
-=head1 RETURN VALUES
-
-EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
-for success and 0 for failure.
-
-EVP_PKEY_size() returns the maximum size of a signature in bytes.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 NOTES
-
-The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
-transparent to the algorithm used and much more flexible.
-
-Due to the link between message digests and public key algorithms the correct
-digest algorithm must be used with the correct public key type. A list of
-algorithms and associated public key algorithms appears in
-L<EVP_DigestInit(3)>.
-
-When signing with DSA private keys the random number generator must be seeded
-or the operation will fail. The random number generator does not need to be
-seeded for RSA signatures.
-
-The call to EVP_SignFinal() internally finalizes a copy of the digest context.
-This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called
-later to digest and sign additional data.
-
-Since only a copy of the digest context is ever finalized the context must
-be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
-will occur.
-
-=head1 BUGS
-
-Older versions of this documentation wrongly stated that calls to
-EVP_SignUpdate() could not be made after calling EVP_SignFinal().
-
-Since the private key is passed in the call to EVP_SignFinal() any error
-relating to the private key (for example an unsuitable key and digest
-combination) will not be indicated until after potentially large amounts of
-data have been passed through EVP_SignUpdate().
-
-It is not possible to change the signing parameters using these function.
-
-The previous two bugs are fixed in the newer EVP_SignDigest*() function.
-
-=head1 SEE ALSO
-
-L<EVP_VerifyInit(3)>,
-L<EVP_DigestInit(3)>, L<err(3)>,
-L<evp(3)>, L<hmac(3)>, L<md2(3)>,
-L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
-L<sha(3)>, L<dgst(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_VerifyInit_ex,
-EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal
-- EVP signature verification functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
- int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
- int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen, EVP_PKEY *pkey);
-
- int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
-
-=head1 DESCRIPTION
-
-The EVP signature verification routines are a high level interface to digital
-signatures.
-
-EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest
-B<type> from ENGINE B<impl>. B<ctx> must be created by calling
-EVP_MD_CTX_new() before calling this function.
-
-EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
-verification context B<ctx>. This function can be called several times on the
-same B<ctx> to include additional data.
-
-EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey>
-and against the B<siglen> bytes at B<sigbuf>.
-
-EVP_VerifyInit() initializes verification context B<ctx> to use the default
-implementation of digest B<type>.
-
-=head1 RETURN VALUES
-
-EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for
-failure.
-
-EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some
-other error occurred.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 NOTES
-
-The B<EVP> interface to digital signatures should almost always be used in
-preference to the low level interfaces. This is because the code then becomes
-transparent to the algorithm used and much more flexible.
-
-Due to the link between message digests and public key algorithms the correct
-digest algorithm must be used with the correct public key type. A list of
-algorithms and associated public key algorithms appears in
-L<EVP_DigestInit(3)>.
-
-The call to EVP_VerifyFinal() internally finalizes a copy of the digest context.
-This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called
-later to digest and verify additional data.
-
-Since only a copy of the digest context is ever finalized the context must
-be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
-will occur.
-
-=head1 BUGS
-
-Older versions of this documentation wrongly stated that calls to
-EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().
-
-Since the public key is passed in the call to EVP_SignFinal() any error
-relating to the private key (for example an unsuitable key and digest
-combination) will not be indicated until after potentially large amounts of
-data have been passed through EVP_SignUpdate().
-
-It is not possible to change the signing parameters using these function.
-
-The previous two bugs are fixed in the newer EVP_VerifyDigest*() function.
-
-=head1 SEE ALSO
-
-L<evp(3)>,
-L<EVP_SignInit(3)>,
-L<EVP_DigestInit(3)>, L<err(3)>,
-L<evp(3)>, L<hmac(3)>, L<md2(3)>,
-L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
-L<sha(3)>, L<dgst(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-HMAC,
-HMAC_CTX_new,
-HMAC_CTX_reset,
-HMAC_CTX_free,
-HMAC_Init,
-HMAC_Init_ex,
-HMAC_Update,
-HMAC_Final,
-HMAC_CTX_copy,
-HMAC_CTX_set_flags,
-HMAC_CTX_get_md
-- HMAC message authentication code
-
-=head1 SYNOPSIS
-
- #include <openssl/hmac.h>
-
- unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
- int key_len, const unsigned char *d, int n,
- unsigned char *md, unsigned int *md_len);
-
- HMAC_CTX *HMAC_CTX_new(void);
- int HMAC_CTX_reset(HMAC_CTX *ctx);
-
- int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
- const EVP_MD *md, ENGINE *impl);
- int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
- int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
-
- void HMAC_CTX_free(HMAC_CTX *ctx);
-
- int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx);
- void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags);
- const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
- const EVP_MD *md);
- #endif
-
-=head1 DESCRIPTION
-
-HMAC is a MAC (message authentication code), i.e. a keyed hash
-function used for message authentication, which is based on a hash
-function.
-
-HMAC() computes the message authentication code of the B<n> bytes at
-B<d> using the hash function B<evp_md> and the key B<key> which is
-B<key_len> bytes long.
-
-It places the result in B<md> (which must have space for the output of
-the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes).
-If B<md> is NULL, the digest is placed in a static array. The size of
-the output is placed in B<md_len>, unless it is B<NULL>.
-
-B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
-
-HMAC_CTX_new() creates a new HMAC_CTX in heap memory.
-
-HMAC_CTX_reset() zeroes an existing B<HMAC_CTX> and associated
-resources, making it suitable for new computations as if it was newly
-created with HMAC_CTX_new().
-
-HMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>,
-releases any associated resources and finally frees the B<HMAC_CTX>
-itself.
-
-The following functions may be used if the message is not completely
-stored in memory:
-
-HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
-function B<evp_md> and the key B<key> which is B<key_len> bytes
-long. It is deprecated and only included for backward compatibility
-with OpenSSL 0.9.6b.
-
-HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash
-function B<evp_md> and key B<key>. If both are NULL (or B<evp_md> is the same
-as the previous digest used by B<ctx> and B<key> is NULL) the existing key is
-reused. B<ctx> must have been created with HMAC_CTX_new() before the first use
-of an B<HMAC_CTX> in this function. B<N.B. HMAC_Init() had this undocumented
-behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex()
-in programs that expect it will cause them to stop working>.
-
-B<NOTE:> If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the
-same as the previous digest used by B<ctx> then an error is returned
-because reuse of an existing key with a different digest is not supported.
-
-HMAC_Update() can be called repeatedly with chunks of the message to
-be authenticated (B<len> bytes at B<data>).
-
-HMAC_Final() places the message authentication code in B<md>, which
-must have space for the hash function output.
-
-HMAC_CTX_copy() copies all of the internal state from B<sctx> into B<dctx>.
-
-HMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTXs.
-These flags have the same meaning as for L<EVP_MD_CTX_set_flags(3)>.
-
-HMAC_CTX_get_md() returns the EVP_MD that has previously been set for the
-supplied HMAC_CTX.
-
-=head1 RETURN VALUES
-
-HMAC() returns a pointer to the message authentication code or NULL if
-an error occurred.
-
-HMAC_CTX_new() returns a pointer to a new B<HMAC_CTX> on success or
-B<NULL> if an error occurred.
-
-HMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and
-HMAC_CTX_copy() return 1 for success or 0 if an error occurred.
-
-HMAC_CTX_get_md() return the EVP_MD previously set for the supplied HMAC_CTX or
-NULL if no EVP_MD has been set.
-
-=head1 CONFORMING TO
-
-RFC 2104
-
-=head1 SEE ALSO
-
-L<sha(3)>, L<evp(3)>
-
-=head1 HISTORY
-
-HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL versions 1.1.0.
-
-HMAC_CTX_cleanup() existed in OpenSSL versions before 1.1.0.
-
-HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL version
-1.1.0.
-
-HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in
-versions of OpenSSL before 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update,
-MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions
-
-=head1 SYNOPSIS
-
- #include <openssl/md2.h>
-
- unsigned char *MD2(const unsigned char *d, unsigned long n,
- unsigned char *md);
-
- int MD2_Init(MD2_CTX *c);
- int MD2_Update(MD2_CTX *c, const unsigned char *data,
- unsigned long len);
- int MD2_Final(unsigned char *md, MD2_CTX *c);
-
-
- #include <openssl/md4.h>
-
- unsigned char *MD4(const unsigned char *d, unsigned long n,
- unsigned char *md);
-
- int MD4_Init(MD4_CTX *c);
- int MD4_Update(MD4_CTX *c, const void *data,
- unsigned long len);
- int MD4_Final(unsigned char *md, MD4_CTX *c);
-
-
- #include <openssl/md5.h>
-
- unsigned char *MD5(const unsigned char *d, unsigned long n,
- unsigned char *md);
-
- int MD5_Init(MD5_CTX *c);
- int MD5_Update(MD5_CTX *c, const void *data,
- unsigned long len);
- int MD5_Final(unsigned char *md, MD5_CTX *c);
-
-=head1 DESCRIPTION
-
-MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output.
-
-MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest
-of the B<n> bytes at B<d> and place it in B<md> (which must have space
-for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16
-bytes of output). If B<md> is NULL, the digest is placed in a static
-array.
-
-The following functions may be used if the message is not completely
-stored in memory:
-
-MD2_Init() initializes a B<MD2_CTX> structure.
-
-MD2_Update() can be called repeatedly with chunks of the message to
-be hashed (B<len> bytes at B<data>).
-
-MD2_Final() places the message digest in B<md>, which must have space
-for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>.
-
-MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and
-MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure.
-
-Applications should use the higher level functions
-L<EVP_DigestInit(3)>
-etc. instead of calling the hash functions directly.
-
-=head1 NOTE
-
-MD2, MD4, and MD5 are recommended only for compatibility with existing
-applications. In new applications, SHA-1 or RIPEMD-160 should be
-preferred.
-
-=head1 RETURN VALUES
-
-MD2(), MD4(), and MD5() return pointers to the hash value.
-
-MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(),
-MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for
-success, 0 otherwise.
-
-=head1 CONFORMING TO
-
-RFC 1319, RFC 1320, RFC 1321
-
-=head1 SEE ALSO
-
-L<EVP_DigestInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function
-
-=head1 SYNOPSIS
-
- #include <openssl/mdc2.h>
-
- unsigned char *MDC2(const unsigned char *d, unsigned long n,
- unsigned char *md);
-
- int MDC2_Init(MDC2_CTX *c);
- int MDC2_Update(MDC2_CTX *c, const unsigned char *data,
- unsigned long len);
- int MDC2_Final(unsigned char *md, MDC2_CTX *c);
-
-=head1 DESCRIPTION
-
-MDC2 is a method to construct hash functions with 128 bit output from
-block ciphers. These functions are an implementation of MDC2 with
-DES.
-
-MDC2() computes the MDC2 message digest of the B<n>
-bytes at B<d> and places it in B<md> (which must have space for
-MDC2_DIGEST_LENGTH == 16 bytes of output). If B<md> is NULL, the digest
-is placed in a static array.
-
-The following functions may be used if the message is not completely
-stored in memory:
-
-MDC2_Init() initializes a B<MDC2_CTX> structure.
-
-MDC2_Update() can be called repeatedly with chunks of the message to
-be hashed (B<len> bytes at B<data>).
-
-MDC2_Final() places the message digest in B<md>, which must have space
-for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MDC2_CTX>.
-
-Applications should use the higher level functions
-L<EVP_DigestInit(3)> etc. instead of calling the
-hash functions directly.
-
-=head1 RETURN VALUES
-
-MDC2() returns a pointer to the hash value.
-
-MDC2_Init(), MDC2_Update() and MDC2_Final() return 1 for success, 0 otherwise.
-
-=head1 CONFORMING TO
-
-ISO/IEC 10118-2, with DES
-
-=head1 SEE ALSO
-
-L<EVP_DigestInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-i2t_ASN1_OBJECT,
-OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln,
-OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp,
-OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup
-- ASN1 object utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/objects.h>
-
- ASN1_OBJECT *OBJ_nid2obj(int n);
- const char *OBJ_nid2ln(int n);
- const char *OBJ_nid2sn(int n);
-
- int OBJ_obj2nid(const ASN1_OBJECT *o);
- int OBJ_ln2nid(const char *ln);
- int OBJ_sn2nid(const char *sn);
-
- int OBJ_txt2nid(const char *s);
-
- ASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name);
- int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
-
- int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a);
-
- int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b);
- ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o);
-
- int OBJ_create(const char *oid, const char *sn, const char *ln);
-
- size_t OBJ_length(const ASN1_OBJECT *obj);
- const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void OBJ_cleanup(void)
- #endif
-
-=head1 DESCRIPTION
-
-The ASN1 object utility functions process ASN1_OBJECT structures which are
-a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
-For convenience, OIDs are usually represented in source code as numeric
-identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that
-are generated when the library is built, and their corresponding NIDs
-are available as defined constants. For the functions below, application
-code should treat all returned values -- OIDs, NIDs, or names -- as
-constants.
-
-OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
-an ASN1_OBJECT structure, its long name and its short name respectively,
-or B<NULL> is an error occurred.
-
-OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
-for the object B<o>, the long name <ln> or the short name <sn> respectively
-or NID_undef if an error occurred.
-
-OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
-a long name, a short name or the numerical representation of an object.
-
-OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
-If B<no_name> is 0 then long names and short names will be interpreted
-as well as numerical forms. If B<no_name> is 1 only the numerical form
-is acceptable.
-
-OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.
-The representation is written as a null terminated string to B<buf>
-at most B<buf_len> bytes are written, truncating the result if necessary.
-The total amount of space required is returned. If B<no_name> is 0 then
-if the object has a long or short name then that will be used, otherwise
-the numerical form will be used. If B<no_name> is 1 then the numerical
-form will always be used.
-
-i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero.
-
-OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
-
-OBJ_dup() returns a copy of B<o>.
-
-OBJ_create() adds a new object to the internal table. B<oid> is the
-numerical form of the object, B<sn> the short name and B<ln> the
-long name. A new NID is returned for the created object.
-
-OBJ_length() returns the size of the content octets of B<obj>.
-
-OBJ_get0_data() returns a pointer to the content octets of B<obj>.
-The returned pointer is an internal pointer which B<must not> be freed.
-
-In OpenSSL versions prior to 1.1.0 OBJ_cleanup() cleaned up OpenSSLs internal
-object table and was called before an application exits if any new objects were
-added using OBJ_create(). This function is deprecated in version 1.1.0 and now
-does nothing if called. No explicit de-initialisation is now required. See
-L<OPENSSL_init_crypto(3)> for further information.
-
-=head1 NOTES
-
-Objects in OpenSSL can have a short name, a long name and a numerical
-identifier (NID) associated with them. A standard set of objects is
-represented in an internal table. The appropriate values are defined
-in the header file B<objects.h>.
-
-For example the OID for commonName has the following definitions:
-
- #define SN_commonName "CN"
- #define LN_commonName "commonName"
- #define NID_commonName 13
-
-New objects can be added by calling OBJ_create().
-
-Table objects have certain advantages over other objects: for example
-their NIDs can be used in a C language switch statement. They are
-also static constant structures which are shared: that is there
-is only a single constant structure for each table object.
-
-Objects which are not in the table have the NID value NID_undef.
-
-Objects do not need to be in the internal tables to be processed,
-the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical
-form of an OID.
-
-Some objects are used to represent algorithms which do not have a
-corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently
-exists for a particular algorithm). As a result they B<cannot> be encoded or
-decoded as part of ASN.1 structures. Applications can determine if there
-is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.
-
-These functions cannot return B<const> because an B<ASN1_OBJECT> can
-represent both an internal, constant, OID and a dynamically-created one.
-The latter cannot be constant because it needs to be freed after use.
-
-=head1 EXAMPLES
-
-Create an object for B<commonName>:
-
- ASN1_OBJECT *o;
- o = OBJ_nid2obj(NID_commonName);
-
-Check if an object is B<commonName>
-
- if (OBJ_obj2nid(obj) == NID_commonName)
- /* Do something */
-
-Create a new NID and initialize an object from it:
-
- int new_nid;
- ASN1_OBJECT *obj;
-
- new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
-
- obj = OBJ_nid2obj(new_nid);
-
-Create a new object directly:
-
- obj = OBJ_txt2obj("1.2.3.4", 1);
-
-=head1 BUGS
-
-OBJ_obj2txt() is awkward and messy to use: it doesn't follow the
-convention of other OpenSSL functions where the buffer can be set
-to B<NULL> to determine the amount of data that should be written.
-Instead B<buf> must point to a valid buffer and B<buf_len> should
-be set to a positive value. A buffer length of 80 should be more
-than enough to handle any OID encountered in practice.
-
-=head1 RETURN VALUES
-
-OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
-error occurred.
-
-OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
-on error.
-
-OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
-a NID or B<NID_undef> on error.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-
-=head1 HISTORY
-
-OBJ_cleanup() was deprecated in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign,
-OCSP_request_add1_cert, OCSP_request_onereq_count,
-OCSP_request_onereq_get0 - OCSP request functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ocsp.h>
-
- OCSP_REQUEST *OCSP_REQUEST_new(void);
- void OCSP_REQUEST_free(OCSP_REQUEST *req);
-
- OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid);
-
- int OCSP_request_sign(OCSP_REQUEST *req,
- X509 *signer, EVP_PKEY *key, const EVP_MD *dgst,
- STACK_OF(X509) *certs, unsigned long flags);
-
- int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert);
-
- int OCSP_request_onereq_count(OCSP_REQUEST *req);
- OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i);
-
-=head1 DESCRIPTION
-
-OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure.
-
-OCSP_REQUEST_free() frees up the request structure B<req>.
-
-OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns
-the B<OCSP_ONEREQ> structure added so an application can add additional
-extensions to the request. The B<id> parameter B<MUST NOT> be freed up after
-the operation.
-
-OCSP_request_sign() signs OCSP request B<req> using certificate
-B<signer>, private key B<key>, digest B<dgst> and additional certificates
-B<certs>. If the B<flags> option B<OCSP_NOCERTS> is set then no certificates
-will be included in the request.
-
-OCSP_request_add1_cert() adds certificate B<cert> to request B<req>. The
-application is responsible for freeing up B<cert> after use.
-
-OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
-structures in B<req>.
-
-OCSP_request_onereq_get0() returns an internal pointer to the B<OCSP_ONEREQ>
-contained in B<req> of index B<i>. The index value B<i> runs from 0 to
-OCSP_request_onereq_count(req) - 1.
-
-=head1 RETURN VALUES
-
-OCSP_REQUEST_new() returns an empty B<OCSP_REQUEST> structure or B<NULL> if
-an error occurred.
-
-OCSP_request_add0_id() returns the B<OCSP_ONEREQ> structure containing B<cid>
-or B<NULL> if an error occurred.
-
-OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0
-for failure.
-
-OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
-structures in B<req>.
-
-OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure
-or B<NULL> if the index value is out or range.
-
-=head1 NOTES
-
-An OCSP request structure contains one or more B<OCSP_ONEREQ> structures
-corresponding to each certificate.
-
-OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
-OCSP responders.
-
-=head1 EXAMPLE
-
-Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
-B<issuer>:
-
- OCSP_REQUEST *req;
- OCSP_ID *cid;
-
- req = OCSP_REQUEST_new();
- if (req == NULL)
- /* error */
- cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);
- if (cid == NULL)
- /* error */
-
- if (OCSP_REQUEST_add0_id(req, cid) == NULL)
- /* error */
-
- /* Do something with req, e.g. query responder */
-
- OCSP_REQUEST_free(req);
-
-=head1 SEE ALSO
-
-L<crypto(3)>,
-L<OCSP_cert_to_id(3)>,
-L<OCSP_request_add1_nonce(3)>,
-L<OCSP_response_find_status(3)>,
-L<OCSP_response_status(3)>,
-L<OCSP_sendreq_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OCSP_cert_to_id, OCSP_cert_id_new, OCSP_CERTID_free, OCSP_id_issuer_cmp,
-OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ocsp.h>
-
- OCSP_CERTID *OCSP_cert_to_id(const EVP_MD *dgst,
- X509 *subject, X509 *issuer);
-
- OCSP_CERTID *OCSP_cert_id_new(const EVP_MD *dgst,
- X509_NAME *issuerName,
- ASN1_BIT_STRING *issuerKey,
- ASN1_INTEGER *serialNumber);
-
- void OCSP_CERTID_free(OCSP_CERTID *id);
-
- int OCSP_id_issuer_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
- int OCSP_id_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
-
- int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd,
- ASN1_OCTET_STRING **pikeyHash,
- ASN1_INTEGER **pserial, OCSP_CERTID *cid);
-
-
-=head1 DESCRIPTION
-
-OCSP_cert_to_id() creates and returns a new B<OCSP_CERTID> structure using
-message digest B<dgst> for certificate B<subject> with issuer B<issuer>. If
-B<dgst> is B<NULL> then SHA1 is used.
-
-OCSP_cert_id_new() creates and returns a new B<OCSP_CERTID> using B<dgst> and
-issuer name B<issuerName>, issuer key hash B<issuerKey> and serial number
-B<serialNumber>.
-
-OCSP_CERTID_free() frees up B<id>.
-
-OCSP_id_cmp() compares B<OCSP_CERTID> B<a> and B<b>.
-
-OCSP_id_issuer_cmp() compares only the issuer name of B<OCSP_CERTID> B<a> and B<b>.
-
-OCSP_id_get0_info() returns the issuer name hash, hash OID, issuer key hash and
-serial number contained in B<cid>. If any of the values are not required the
-corresponding parameter can be set to B<NULL>.
-
-=head1 RETURN VALUES
-
-OCSP_cert_to_id() and OCSP_cert_id_new() return either a pointer to a valid
-B<OCSP_CERTID> structure or B<NULL> if an error occurred.
-
-OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and non-zero
-otherwise.
-
-OCSP_CERTID_free() does not return a value.
-
-OCSP_id_get0_info() returns 1 for success and 0 for failure.
-
-=head1 NOTES
-
-OCSP clients will typically only use OCSP_cert_to_id() or OCSP_cert_id_new():
-the other functions are used by responder applications.
-
-The values returned by OCSP_id_get0_info() are internal pointers and B<MUST
-NOT> be freed up by an application: they will be freed when the corresponding
-B<OCSP_CERTID> structure is freed.
-
-=head1 SEE ALSO
-
-L<crypto(3)>,
-L<OCSP_request_add1_nonce(3)>,
-L<OCSP_REQUEST_new(3)>,
-L<OCSP_response_find_status(3)>,
-L<OCSP_response_status(3)>,
-L<OCSP_sendreq_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce - OCSP nonce functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ocsp.h>
-
- int OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len);
- int OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len);
- int OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req);
- int OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp);
-
-=head1 DESCRIPTION
-
-OCSP_request_add1_nonce() adds a nonce of value B<val> and length B<len> to
-OCSP request B<req>. If B<val> is B<NULL> a random nonce is used. If B<len>
-is zero or negative a default length will be used (currently 16 bytes).
-
-OCSP_basic_add1_nonce() is identical to OCSP_request_add1_nonce() except
-it adds a nonce to OCSP basic response B<resp>.
-
-OCSP_check_nonce() compares the nonce value in B<req> and B<resp>.
-
-OCSP_copy_nonce() copys any nonce value present in B<req> to B<resp>.
-
-=head1 RETURN VALUES
-
-OCSP_request_add1_nonce() and OCSP_basic_add1_nonce() return 1 for success
-and 0 for failure.
-
-OCSP_copy_nonce() returns 1 if a nonce was successfully copied, 2 if no nonce
-was present in B<req> and 0 if an error occurred.
-
-OCSP_check_nonce() returns the result of the nonce comparison between B<req>
-and B<resp>. The return value indicates the result of the comparison. If
-nonces are present and equal 1 is returned. If the nonces are absent 2 is
-returned. If a nonce is present in the response only 3 is returned. If nonces
-are present and unequal 0 is returned. If the nonce is present in the request
-only then -1 is returned.
-
-=head1 NOTES
-
-For most purposes the nonce value in a request is set to a random value so
-the B<val> parameter in OCSP_request_add1_nonce() is usually NULL.
-
-An OCSP nonce is typically added to an OCSP request to thwart replay attacks
-by checking the same nonce value appears in the response.
-
-Some responders may include a nonce in all responses even if one is not
-supplied.
-
-Some responders cache OCSP responses and do not sign each response for
-performance reasons. As a result they do not support nonces.
-
-The return values of OCSP_check_nonce() can be checked to cover each case. A
-positive return value effectively indicates success: nonces are both present
-and match, both absent or present in the response only. A non-zero return
-additionally covers the case where the nonce is present in the request only:
-this will happen if the responder doesn't support nonces. A zero return value
-indicates present and mismatched nonces: this should be treated as an error
-condition.
-
-=head1 SEE ALSO
-
-L<crypto(3)>,
-L<OCSP_cert_to_id(3)>,
-L<OCSP_REQUEST_new(3)>,
-L<OCSP_response_find_status(3)>,
-L<OCSP_response_status(3)>,
-L<OCSP_sendreq_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OCSP_resp_get0_certs,
-OCSP_resp_get0_id,
-OCSP_resp_get0_produced_at,
-OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find,
-OCSP_single_get0_status, OCSP_check_validity
-- OCSP response utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ocsp.h>
-
- int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,
- int *reason,
- ASN1_GENERALIZEDTIME **revtime,
- ASN1_GENERALIZEDTIME **thisupd,
- ASN1_GENERALIZEDTIME **nextupd);
-
- int OCSP_resp_count(OCSP_BASICRESP *bs);
- OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx);
- int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last);
- int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,
- ASN1_GENERALIZEDTIME **revtime,
- ASN1_GENERALIZEDTIME **thisupd,
- ASN1_GENERALIZEDTIME **nextupd);
-
- const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(
- const OCSP_BASICRESP* single);
-
- const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs);
-
- int OCSP_resp_get0_id(const OCSP_BASICRESP *bs,
- const ASN1_OCTET_STRING **pid,
- const X509_NAME **pname);
-
- int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,
- ASN1_GENERALIZEDTIME *nextupd,
- long sec, long maxsec);
-
-=head1 DESCRIPTION
-
-OCSP_resp_find_status() searches B<bs> for an OCSP response for B<id>. If it is
-successful the fields of the response are returned in B<*status>, B<*reason>,
-B<*revtime>, B<*thisupd> and B<*nextupd>. The B<*status> value will be one of
-B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or
-B<V_OCSP_CERTSTATUS_UNKNOWN>. The B<*reason> and B<*revtime> fields are only
-set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the B<*reason> field
-will be set to the revocation reason which will be one of
-B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>,
-B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>,
-B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>,
-B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>,
-B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>.
-
-OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in B<bs>.
-
-OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in B<bs>
-corresponding to index B<idx>. Where B<idx> runs from 0 to
-OCSP_resp_count(bs) - 1.
-
-OCSP_resp_find() searches B<bs> for B<id> and returns the index of the first
-matching entry after B<last> or starting from the beginning if B<last> is -1.
-
-OCSP_single_get0_status() extracts the fields of B<single> in B<*reason>,
-B<*revtime>, B<*thisupd> and B<*nextupd>.
-
-OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the
-single response B<bs>.
-
-OCSP_resp_get0_certs() returns any certificates included in B<bs>.
-
-OCSP_resp_get0_id() gets the responder id of <bs>. If the responder ID is
-a name then <*pname> is set to the name and B<*pid> is set to NULL. If the
-responder ID is by key ID then B<*pid> is set to the key ID and B<*pname>
-is set to NULL.
-
-OCSP_check_validity() checks the validity of B<thisupd> and B<nextupd> values
-which will be typically obtained from OCSP_resp_find_status() or
-OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds
-leeway should be allowed in the check. If B<maxsec> is positive it indicates
-the maximum age of B<thisupd> in seconds.
-
-=head1 RETURN VALUES
-
-OCSP_resp_find_status() returns 1 if B<id> is found in B<bs> and 0 otherwise.
-
-OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in
-B<bs>.
-
-OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or
-B<NULL> if B<idx> is out of range.
-
-OCSP_resp_find() returns the index of B<id> in B<bs> (which may be 0) or -1 if
-B<id> was not found.
-
-OCSP_single_get0_status() returns the status of B<single> or -1 if an error
-occurred.
-
-=head1 NOTES
-
-Applications will typically call OCSP_resp_find_status() using the certificate
-ID of interest and then check its validity using OCSP_check_validity(). They
-can then take appropriate action based on the status of the certificate.
-
-An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate>
-fields. Normally the current time should be between these two values. To
-account for clock skew the B<maxsec> field can be set to non-zero in
-OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this
-would otherwise mean an ancient response would be considered valid: the
-B<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted
-age of responses.
-
-The values written to B<*revtime>, B<*thisupd> and B<*nextupd> by
-OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers
-which B<MUST NOT> be freed up by the calling application. Any or all of these
-parameters can be set to NULL if their value is not required.
-
-=head1 SEE ALSO
-
-L<crypto(3)>,
-L<OCSP_cert_to_id(3)>,
-L<OCSP_request_add1_nonce(3)>,
-L<OCSP_REQUEST_new(3)>,
-L<OCSP_response_status(3)>,
-L<OCSP_sendreq_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create,
-OCSP_RESPONSE_free, OCSP_RESPID_set_by_name,
-OCSP_RESPID_set_by_key, OCSP_RESPID_match - OCSP response functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ocsp.h>
-
- int OCSP_response_status(OCSP_RESPONSE *resp);
- OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp);
- OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs);
- void OCSP_RESPONSE_free(OCSP_RESPONSE *resp);
-
- int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert);
- int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert);
- int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert);
-
-=head1 DESCRIPTION
-
-OCSP_response_status() returns the OCSP response status of B<resp>. It returns
-one of the values: B<OCSP_RESPONSE_STATUS_SUCCESSFUL>,
-B<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>,
-B<OCSP_RESPONSE_STATUS_INTERNALERROR>, B<OCSP_RESPONSE_STATUS_TRYLATER>
-B<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or B<OCSP_RESPONSE_STATUS_UNAUTHORIZED>.
-
-OCSP_response_get1_basic() decodes and returns the B<OCSP_BASICRESP> structure
-contained in B<resp>.
-
-OCSP_response_create() creates and returns an B<OCSP_RESPONSE> structure for
-B<status> and optionally including basic response B<bs>.
-
-OCSP_RESPONSE_free() frees up OCSP response B<resp>.
-
-OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the
-subject name in the supplied X509 certificate B<cert> for the OCSP responder.
-
-OCSP_RESPID_set_by_key() sets the key of the OCSP_RESPID to be the same as the
-key in the supplied X509 certificate B<cert> for the OCSP responder. The key is
-stored as a SHA1 hash.
-
-Note that an OCSP_RESPID can only have one of the name, or the key set. Calling
-OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing
-setting.
-
-OCSP_RESPID_match() tests whether the OCSP_RESPID given in B<respid> matches
-with the X509 certificate B<cert>.
-
-=head1 RETURN VALUES
-
-OCSP_RESPONSE_status() returns a status value.
-
-OCSP_response_get1_basic() returns an B<OCSP_BASICRESP> structure pointer or
-B<NULL> if an error occurred.
-
-OCSP_response_create() returns an B<OCSP_RESPONSE> structure pointer or B<NULL>
-if an error occurred.
-
-OCSP_RESPONSE_free() does not return a value.
-
-OCSP_RESPID_set_by_name() and OCSP_RESPID_set_by_key() return 1 on success or 0
-on failure.
-
-OCSP_RESPID_match() returns 1 if the OCSP_RESPID and the X509 certificate match
-or 0 otherwise.
-
-=head1 NOTES
-
-OCSP_response_get1_basic() is only called if the status of a response is
-B<OCSP_RESPONSE_STATUS_SUCCESSFUL>.
-
-=head1 SEE ALSO
-
-L<crypto(3)>
-L<OCSP_cert_to_id(3)>
-L<OCSP_request_add1_nonce(3)>
-L<OCSP_REQUEST_new(3)>
-L<OCSP_response_find_status(3)>
-L<OCSP_sendreq_new(3)>
-L<OCSP_RESPID_new(3)>
-L<OCSP_RESPID_free(3)>
-
-=head1 HISTORY
-
-The OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key() and OCSP_RESPID_match()
-functions were added in OpenSSL version 1.1.0a.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_REQ_CTX_free,
-OCSP_set_max_response_length, OCSP_REQ_CTX_add1_header,
-OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ocsp.h>
-
- OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req,
- int maxline);
-
- int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx);
-
- void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx);
-
- void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len);
-
- int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx,
- const char *name, const char *value);
-
- int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req);
-
- OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req,
- int maxline);
-
-=head1 DESCRIPTION
-
-The function OCSP_sendreq_new() returns an B<OCSP_CTX> structure using the
-responder B<io>, the URL path B<path>, the OCSP request B<req> and with a
-response header maximum line length of B<maxline>. If B<maxline> is zero a
-default value of 4k is used. The OCSP request B<req> may be set to B<NULL>
-and provided later if required.
-
-OCSP_sendreq_nbio() performs non-blocking I/O on the OCSP request context
-B<rctx>. When the operation is complete it returns the response in B<*presp>.
-
-OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>.
-
-OCSP_set_max_response_length() sets the maximum response length for B<rctx>
-to B<len>. If the response exceeds this length an error occurs. If not
-set a default value of 100k is used.
-
-OCSP_REQ_CTX_add1_header() adds header B<name> with value B<value> to the
-context B<rctx>. It can be called more than once to add multiple headers.
-It B<MUST> be called before any calls to OCSP_sendreq_nbio(). The B<req>
-parameter in the initial to OCSP_sendreq_new() call MUST be set to B<NULL> if
-additional headers are set.
-
-OCSP_REQ_CTX_set1_req() sets the OCSP request in B<rctx> to B<req>. This
-function should be called after any calls to OCSP_REQ_CTX_add1_header().
-
-OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL
-path B<path>, the OCSP request B<req> and with a response header maximum line
-length of B<maxline>. If B<maxline> is zero a default value of 4k is used.
-
-=head1 RETURN VALUES
-
-OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL> if
-an error occurred.
-
-OCSP_sendreq_nbio() returns B<1> if the operation was completed successfully,
-B<-1> if the operation should be retried and B<0> if an error occurred.
-
-OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req() return B<1> for success
-and B<0> for failure.
-
-OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the
-responder or B<NULL> if an error occurred.
-
-OCSP_REQ_CTX_free() and OCSP_set_max_response_length() do not return values.
-
-=head1 NOTES
-
-These functions only perform a minimal HTTP query to a responder. If an
-application wishes to support more advanced features it should use an
-alternative more complete HTTP library.
-
-Currently only HTTP POST queries to responders are supported.
-
-The arguments to OCSP_sendreq_new() correspond to the components of the URL.
-For example if the responder URL is B<http://ocsp.com/ocspreq> the BIO
-B<io> should be connected to host B<ocsp.com> on port 80 and B<path>
-should be set to B<"/ocspreq">
-
-The headers added with OCSP_REQ_CTX_add1_header() are of the form
-"B<name>: B<value>" or just "B<name>" if B<value> is B<NULL>. So to add
-a Host header for B<ocsp.com> you would call:
-
- OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
-
-If OCSP_sendreq_nbio() indicates an operation should be retried the
-corresponding BIO can be examined to determine which operation (read or
-write) should be retried and appropriate action taken (for example a select()
-call on the underlying socket).
-
-OCSP_sendreq_bio() does not support retries and so cannot handle non-blocking
-I/O efficiently. It is retained for compatibility and its use in new
-applications is not recommended.
-
-=head1 SEE ALSO
-
-L<crypto(3)>,
-L<OCSP_cert_to_id(3)>,
-L<OCSP_request_add1_nonce(3)>,
-L<OCSP_REQUEST_new(3)>,
-L<OCSP_response_find_status(3)>,
-L<OCSP_response_status(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_Applink - glue between OpenSSL BIO and Win32 compiler run-time
-
-=head1 SYNOPSIS
-
- __declspec(dllexport) void **OPENSSL_Applink();
-
-=head1 DESCRIPTION
-
-OPENSSL_Applink is application-side interface which provides a glue
-between OpenSSL BIO layer and Win32 compiler run-time environment.
-Even though it appears at application side, it's essentially OpenSSL
-private interface. For this reason application developers are not
-expected to implement it, but to compile provided module with
-compiler of their choice and link it into the target application.
-The referred module is available as F<applink.c>, located alongside
-the public header files (only on the platforms where applicable).
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DECLARE_LHASH_OF,
-OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC,
-LHASH_DOALL_ARG_FN_TYPE,
-IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN,
-lh_TYPE_new, lh_TYPE_free,
-lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve,
-lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- #include <openssl/lhash.h>
-
- DECLARE_LHASH_OF(TYPE);
-
- LHASH *lh_TYPE_new();
- void lh_TYPE_free(LHASH_OF(TYPE *table);
-
- TYPE *lh_TYPE_insert(LHASH_OF(TYPE *table, TYPE *data);
- TYPE *lh_TYPE_delete(LHASH_OF(TYPE *table, TYPE *data);
- TYPE *lh_retrieve(LHASH_OFTYPE *table, TYPE *data);
-
- void lh_TYPE_doall(LHASH_OF(TYPE *table, OPENSSL_LH_DOALL_FUNC func);
- void lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func,
- TYPE, TYPE *arg);
-
- int lh_TYPE_error(LHASH_OF(TYPE) *table);
-
- typedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *);
- typedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *);
- typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *);
- typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);
-
-=head1 DESCRIPTION
-
-This library implements type-checked dynamic hash tables. The hash
-table entries can be arbitrary structures. Usually they consist of key
-and value fields. In the description here, I<TYPE> is used a placeholder
-for any of the OpenSSL datatypes, such as I<SSL_SESSION>.
-
-lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store
-arbitrary data entries, and specifies the 'hash' and 'compare'
-callbacks to be used in organising the table's entries. The B<hash>
-callback takes a pointer to a table entry as its argument and returns
-an unsigned long hash value for its key field. The hash value is
-normally truncated to a power of 2, so make sure that your hash
-function returns well mixed low order bits. The B<compare> callback
-takes two arguments (pointers to two hash table entries), and returns
-0 if their keys are equal, non-zero otherwise.
-
-If your hash table
-will contain items of some particular type and the B<hash> and
-B<compare> callbacks hash/compare these types, then the
-B<IMPLEMENT_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be
-used to create callback wrappers of the prototypes required by
-lh_TYPE_new() as shown in this example:
-
- /*
- * Implement the hash and compare functions; "stuff" can be any word.
- */
- static unsigned long stuff_hash(const TYPE *a)
- {
- ...
- }
- static int stuff_cmp(const TYPE *a, const TYPE *b)
- {
- ...
- }
-
- /*
- * Implement the wrapper functions.
- */
- static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE)
- static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE)
-
-If the type is going to be used in several places, the following macros
-can be used in a common header file to declare the function wrappers:
-
- DECLARE_LHASH_HASH_FN(stuff, TYPE)
- DECLARE_LHASH_COMP_FN(stuff, TYPE)
-
-Then a hash table of TYPE objects can be created using this:
-
- LHASH_OF(TYPE) *htable;
-
- htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
-
-lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure
-B<table>. Allocated hash table entries will not be freed; consider
-using lh_TYPE_doall() to deallocate any remaining entries in the
-hash table (see below).
-
-lh_TYPE_insert() inserts the structure pointed to by B<data> into
-B<table>. If there already is an entry with the same key, the old
-value is replaced. Note that lh_TYPE_insert() stores pointers, the
-data are not copied.
-
-lh_TYPE_delete() deletes an entry from B<table>.
-
-lh_TYPE_retrieve() looks up an entry in B<table>. Normally, B<data>
-is a structure with the key field(s) set; the function will return a
-pointer to a fully populated structure.
-
-lh_TYPE_doall() will, for every entry in the hash table, call
-B<func> with the data item as its parameter.
-For example:
-
- /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */
- void TYPE_cleanup_doall(TYPE *a);
-
- /* Implement a prototype-compatible wrapper for "TYPE_cleanup" */
- IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE)
-
- /* Call "TYPE_cleanup" against all items in a hash table. */
- lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup));
-
- /* Then the hash table itself can be deallocated */
- lh_TYPE_free(hashtable);
-
-When doing this, be careful if you delete entries from the hash table
-in your callbacks: the table may decrease in size, moving the item
-that you are currently on down lower in the hash table - this could
-cause some entries to be skipped during the iteration. The second
-best solution to this problem is to set hash-E<gt>down_load=0 before
-you start (which will stop the hash table ever decreasing in size).
-The best solution is probably to avoid deleting items from the hash
-table inside a "doall" callback!
-
-lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that
-B<func> will be called with B<arg> as the second argument and B<func>
-should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype
-that is passed both the table entry and an extra argument). As with
-lh_doall(), you can instead choose to declare your callback with a
-prototype matching the types you are dealing with and use the
-declare/implement macros to create compatible wrappers that cast
-variables before calling your type-specific callbacks. An example of
-this is demonstrated here (printing all hash table entries to a BIO
-that is provided by the caller):
-
- /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */
- void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio);
-
- /* Implement a prototype-compatible wrapper for "TYPE_print" */
- static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO)
-
- /* Print out the entire hashtable to a particular BIO */
- lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO,
- logging_bio);
-
-
-lh_TYPE_error() can be used to determine if an error occurred in the last
-operation.
-
-=head1 RETURN VALUES
-
-lh_TYPE_new() returns B<NULL> on error, otherwise a pointer to the new
-B<LHASH> structure.
-
-When a hash table entry is replaced, lh_TYPE_insert() returns the value
-being replaced. B<NULL> is returned on normal operation and on error.
-
-lh_TYPE_delete() returns the entry being deleted. B<NULL> is returned if
-there is no such value in the hash table.
-
-lh_TYPE_retrieve() returns the hash table entry if it has been found,
-B<NULL> otherwise.
-
-lh_TYPE_error() returns 1 if an error occurred in the last operation, 0
-otherwise.
-
-lh_TYPE_free(), lh_TYPE_doall() and lh_TYPE_doall_arg() return no values.
-
-=head1 NOTE
-
-The various LHASH macros and callback types exist to make it possible
-to write type-checked code without resorting to function-prototype
-casting - an evil that makes application code much harder to
-audit/verify and also opens the window of opportunity for stack
-corruption and other hard-to-find bugs. It also, apparently, violates
-ANSI-C.
-
-The LHASH code regards table entries as constant data. As such, it
-internally represents lh_insert()'d items with a "const void *"
-pointer type. This is why callbacks such as those used by lh_doall()
-and lh_doall_arg() declare their prototypes with "const", even for the
-parameters that pass back the table items' data pointers - for
-consistency, user-provided data is "const" at all times as far as the
-LHASH code is concerned. However, as callers are themselves providing
-these pointers, they can choose whether they too should be treating
-all such parameters as constant.
-
-As an example, a hash table may be maintained by code that, for
-reasons of encapsulation, has only "const" access to the data being
-indexed in the hash table (ie. it is returned as "const" from
-elsewhere in their code) - in this case the LHASH prototypes are
-appropriate as-is. Conversely, if the caller is responsible for the
-life-time of the data in question, then they may well wish to make
-modifications to table item passed back in the lh_doall() or
-lh_doall_arg() callbacks (see the "TYPE_cleanup" example above). If
-so, the caller can either cast the "const" away (if they're providing
-the raw callbacks themselves) or use the macros to declare/implement
-the wrapper functions without "const" types.
-
-Callers that only have "const" access to data they're indexing in a
-table, yet declare callbacks without constant types (or cast the
-"const" away themselves), are therefore creating their own risks/bugs
-without being encouraged to do so by the API. On a related note,
-those auditing code should pay special attention to any instances of
-DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types
-without any "const" qualifiers.
-
-=head1 BUGS
-
-lh_TYPE_insert() returns B<NULL> both for success and error.
-
-=head1 SEE ALSO
-
-L<lh_stats(3)>
-
-=head1 HISTORY
-
-In OpenSSL 1.0.0, the lhash interface was revamped for better
-type checking.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_LH_stats, OPENSSL_LH_node_stats, OPENSSL_LH_node_usage_stats,
-OPENSSL_LH_stats_bio,
-OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics
-
-=head1 SYNOPSIS
-
- #include <openssl/lhash.h>
-
- void OPENSSL_LH_stats(LHASH *table, FILE *out);
- void OPENSSL_LH_node_stats(LHASH *table, FILE *out);
- void OPENSSL_LH_node_usage_stats(LHASH *table, FILE *out);
-
- void OPENSSL_LH_stats_bio(LHASH *table, BIO *out);
- void OPENSSL_LH_node_stats_bio(LHASH *table, BIO *out);
- void OPENSSL_LH_node_usage_stats_bio(LHASH *table, BIO *out);
-
-=head1 DESCRIPTION
-
-The B<LHASH> structure records statistics about most aspects of
-accessing the hash table. This is mostly a legacy of Eric Young
-writing this library for the reasons of implementing what looked like
-a nice algorithm rather than for a particular software product.
-
-OPENSSL_LH_stats() prints out statistics on the size of the hash table, how
-many entries are in it, and the number and result of calls to the
-routines in this library.
-
-OPENSSL_LH_node_stats() prints the number of entries for each 'bucket' in the
-hash table.
-
-OPENSSL_LH_node_usage_stats() prints out a short summary of the state of the
-hash table. It prints the 'load' and the 'actual load'. The load is
-the average number of data items per 'bucket' in the hash table. The
-'actual load' is the average number of items per 'bucket', but only
-for buckets which contain entries. So the 'actual load' is the
-average number of searches that will need to find an item in the hash
-table, while the 'load' is the average number that will be done to
-record a miss.
-
-OPENSSL_LH_stats_bio(), OPENSSL_LH_node_stats_bio() and OPENSSL_LH_node_usage_stats_bio()
-are the same as the above, except that the output goes to a B<BIO>.
-
-=head1 RETURN VALUES
-
-These functions do not return values.
-
-=head1 SEE ALSO
-
-L<bio(3)>, L<lhash(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_VERSION_NUMBER, OpenSSL_version,
-OpenSSL_version_num - get OpenSSL version number
-
-=head1 SYNOPSIS
-
- #include <openssl/opensslv.h>
- #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL
-
- #include <openssl/crypto.h>
-
- unsigned long OpenSSL_version_num();
- const char *OpenSSL_version(int t);
-
-=head1 DESCRIPTION
-
-OPENSSL_VERSION_NUMBER is a numeric release version identifier:
-
- MNNFFPPS: major minor fix patch status
-
-The status nibble has one of the values 0 for development, 1 to e for betas
-1 to 14, and f for release.
-
-for example
-
- 0x000906000 == 0.9.6 dev
- 0x000906023 == 0.9.6b beta 3
- 0x00090605f == 0.9.6e release
-
-Versions prior to 0.9.3 have identifiers E<lt> 0x0930.
-Versions between 0.9.3 and 0.9.5 had a version identifier with this
-interpretation:
-
- MMNNFFRBB major minor fix final beta/patch
-
-for example
-
- 0x000904100 == 0.9.4 release
- 0x000905000 == 0.9.5 dev
-
-Version 0.9.5a had an interim interpretation that is like the current one,
-except the patch level got the highest bit set, to keep continuity. The
-number was therefore 0x0090581f.
-
-OpenSSL_version_num() returns the version number.
-
-OpenSSL_version() returns different strings depending on B<t>:
-
-=over 4
-
-=item OPENSSL_VERSION
-
-The text variant of the version number and the release date. For example,
-"OpenSSL 1.0.1a 15 Oct 2015".
-
-=item OPENSSL_CFLAGS
-
-The compiler flags set for the compilation process in the form
-"compiler: ..." if available or "compiler: information not available"
-otherwise.
-
-=item OPENSSL_BUILT_ON
-
-The date of the build process in the form "built on: ..." if available
-or "built on: date not available" otherwise.
-
-=item OPENSSL_PLATFORM
-
-The "Configure" target of the library build in the form "platform: ..."
-if available or "platform: information not available" otherwise.
-
-=item OPENSSL_DIR
-
-The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "...""
-if available or "OPENSSLDIR: N/A" otherwise.
-
-=item OPENSSL_ENGINES_DIR
-
-The "ENGINESDIR" setting of the library build in the form "ENGINESDIR: "...""
-if available or "ENGINESDIR: N/A" otherwise.
-
-=back
-
-For an unknown B<t>, the text "not available" is returned.
-
-=head1 RETURN VALUE
-
-The version number.
-
-=head1 SEE ALSO
-
-L<crypto(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
-
-=head1 SYNOPSIS
-
- #include <openssl/conf.h>
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void OPENSSL_config(const char *appname);
- void OPENSSL_no_config(void);
- #endif
-
-=head1 DESCRIPTION
-
-OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> and
-reads from the application section B<appname>. If B<appname> is NULL then
-the default section, B<openssl_conf>, will be used.
-Errors are silently ignored.
-Multiple calls have no effect.
-
-OPENSSL_no_config() disables configuration. If called before OPENSSL_config()
-no configuration takes place.
-
-If the application is built with B<OPENSSL_LOAD_CONF> defined, then a
-call to OpenSSL_add_all_algorithms() will implicitly call OPENSSL_config()
-first.
-
-=head1 NOTES
-
-The OPENSSL_config() function is designed to be a very simple "call it and
-forget it" function.
-It is however B<much> better than nothing. Applications which need finer
-control over their configuration functionality should use the configuration
-functions such as CONF_modules_load() directly. This function is deprecated
-and its use should be avoided.
-Applications should instead call CONF_modules_load() during
-initialization (that is before starting any threads).
-
-There are several reasons why calling the OpenSSL configuration routines is
-advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs).
-However very few applications currently support the control interface and so
-very few can load and use dynamic ENGINEs. Equally in future more sophisticated
-ENGINEs will require certain control operations to customize them. If an
-application calls OPENSSL_config() it doesn't need to know or care about
-ENGINE control operations because they can be performed by editing a
-configuration file.
-
-=head1 RETURN VALUES
-
-Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
-
-=head1 SEE ALSO
-
-L<conf(5)>,
-L<CONF_modules_load_file(3)>
-
-=head1 HISTORY
-
-The OPENSSL_no_config() and OPENSSL_config() functions were
-deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto().
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_ia32cap - the x86[_64] processor capabilities vector
-
-=head1 SYNOPSIS
-
- env OPENSSL_ia32cap=... <application>
-
-=head1 DESCRIPTION
-
-OpenSSL supports a range of x86[_64] instruction set extensions. These
-extensions are denoted by individual bits in capability vector returned
-by processor in EDX:ECX register pair after executing CPUID instruction
-with EAX=1 input value (see Intel Application Note #241618). This vector
-is copied to memory upon toolkit initialization and used to choose
-between different code paths to provide optimal performance across wide
-range of processors. For the moment of this writing following bits are
-significant:
-
-=over
-
-=item bit #4 denoting presence of Time-Stamp Counter.
-
-=item bit #19 denoting availability of CLFLUSH instruction;
-
-=item bit #20, reserved by Intel, is used to choose among RC4 code paths;
-
-=item bit #23 denoting MMX support;
-
-=item bit #24, FXSR bit, denoting availability of XMM registers;
-
-=item bit #25 denoting SSE support;
-
-=item bit #26 denoting SSE2 support;
-
-=item bit #28 denoting Hyperthreading, which is used to distinguish
-cores with shared cache;
-
-=item bit #30, reserved by Intel, denotes specifically Intel CPUs;
-
-=item bit #33 denoting availability of PCLMULQDQ instruction;
-
-=item bit #41 denoting SSSE3, Supplemental SSE3, support;
-
-=item bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs);
-
-=item bit #54 denoting availability of MOVBE instruction;
-
-=item bit #57 denoting AES-NI instruction set extension;
-
-=item bit #58, XSAVE bit, lack of which in combination with MOVBE is used
-to identify Atom Silvermont core;
-
-=item bit #59, OSXSAVE bit, denoting availability of YMM registers;
-
-=item bit #60 denoting AVX extension;
-
-=item bit #62 denoting availability of RDRAND instruction;
-
-=back
-
-For example, in 32-bit application context clearing bit #26 at run-time
-disables high-performance SSE2 code present in the crypto library, while
-clearing bit #24 disables SSE2 code operating on 128-bit XMM register
-bank. You might have to do the latter if target OpenSSL application is
-executed on SSE2 capable CPU, but under control of OS that does not
-enable XMM registers. Historically address of the capability vector copy
-was exposed to application through OPENSSL_ia32cap_loc(), but not
-anymore. Now the only way to affect the capability detection is to set
-OPENSSL_ia32cap environment variable prior target application start. To
-give a specific example, on Intel P4 processor 'env
-OPENSSL_ia32cap=0x16980010 apps/openssl', or better yet 'env
-OPENSSL_ia32cap=~0x1000000 apps/openssl' would achieve the desired
-effect. Alternatively you can reconfigure the toolkit with no-sse2
-option and recompile.
-
-Less intuitive is clearing bit #28, or ~0x10000000 in the "environment
-variable" terms. The truth is that it's not copied from CPUID output
-verbatim, but is adjusted to reflect whether or not the data cache is
-actually shared between logical cores. This in turn affects the decision
-on whether or not expensive countermeasures against cache-timing attacks
-are applied, most notably in AES assembler module.
-
-The capability vector is further extended with EBX value returned by
-CPUID with EAX=7 and ECX=0 as input. Following bits are significant:
-
-=over
-
-=item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;
-
-=item bit #64+5 denoting availability of AVX2 instructions;
-
-=item bit #64+8 denoting availability of BMI2 instructions, e.g. MULX
-and RORX;
-
-=item bit #64+16 denoting availability of AVX512F extension;
-
-=item bit #64+18 denoting availability of RDSEED instruction;
-
-=item bit #64+19 denoting availability of ADCX and ADOX instructions;
-
-=item bit #64+29 denoting availability of SHA extension;
-
-=item bit #64+30 denoting availability of AVX512BW extension;
-
-=item bit #64+31 denoting availability of AVX512VL extension;
-
-=back
-
-To control this extended capability word use ':' as delimiter when
-setting up OPENSSL_ia32cap environment variable. For example assigning
-':~0x20' would disable AVX2 code paths, and ':0' - all post-AVX
-extensions.
-
-It should be noted that whether or not some of the most "fancy"
-extension code paths are actually assembled depends on current assembler
-version. Base minimum of AES-NI/PCLMULQDQ, SSSE3 and SHA extension code
-paths are always assembled. Besides that, minimum assembler version
-requirements are summarized in below table:
-
- Extension | GNU as | nasm | llvm
- ------------+--------+--------+--------
- AVX | 2.19 | 2.09 | 3.0
- AVX2 | 2.22 | 2.10 | 3.1
- ADCX/ADOX | 2.23 | 2.10 | 3.3
- AVX512 | 2.25 | 2.11.8 | 3.6
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_init_new, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_free,
-OPENSSL_init_crypto, OPENSSL_cleanup,
-OPENSSL_atexit, OPENSSL_thread_stop - OpenSSL
-initialisation and deinitialisation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/crypto.h>
-
- void OPENSSL_cleanup(void);
- int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
- int OPENSSL_atexit(void (*handler)(void));
- void OPENSSL_thread_stop(void);
-
- OPENSSL_INIT_SETTINGS *OPENSSL_init_new(void);
- int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,
- const char* name);
- void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);
-
-=head1 DESCRIPTION
-
-During normal operation OpenSSL (libcrypto) will allocate various resources at
-start up that must, subsequently, be freed on close down of the library.
-Additionally some resources are allocated on a per thread basis (if the
-application is multi-threaded), and these resources must be freed prior to the
-thread closing.
-
-As of version 1.1.0 OpenSSL will automatically allocate all resources that it
-needs so no explicit initialisation is required. Similarly it will also
-automatically deinitialise as required.
-
-However, there way be situations when explicit initialisation is desirable or
-needed, for example when some non-default initialisation is required. The
-function OPENSSL_init_crypto() can be used for this purpose for
-libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl
-equivalent).
-
-Numerous internal OpenSSL functions call OPENSSL_init_crypto().
-Therefore, in order to perform non-default initialisation,
-OPENSSL_init_crypto() MUST be called by application code prior to
-any other OpenSSL function calls.
-
-The B<opts> parameter specifies which aspects of libcrypto should be
-initialised. Valid options are:
-
-=over 4
-
-=item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS
-
-Suppress automatic loading of the libcrypto error strings. This option is
-not a default option. Once selected subsequent calls to
-OPENSSL_init_crypto() with the option
-B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored.
-
-=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS
-
-Automatic loading of the libcrypto error strings. With this option the
-library will automatically load the libcrypto error strings.
-This option is a default option. Once selected subsequent calls to
-OPENSSL_init_crypto() with the option
-B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> will be ignored.
-
-=item OPENSSL_INIT_ADD_ALL_CIPHERS
-
-With this option the library will automatically load and make available all
-libcrypto ciphers. This option is a default option. Once selected subsequent
-calls to OPENSSL_init_crypto() with the option
-B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
-
-=item OPENSSL_INIT_ADD_ALL_DIGESTS
-
-With this option the library will automatically load and make available all
-libcrypto digests. This option is a default option. Once selected subsequent
-calls to OPENSSL_init_crypto() with the option
-B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
-
-=item OPENSSL_INIT_NO_ADD_ALL_CIPHERS
-
-With this option the library will suppress automatic loading of libcrypto
-ciphers. This option is not a default option. Once selected subsequent
-calls to OPENSSL_init_crypto() with the option
-B<OPENSSL_INIT_ADD_ALL_CIPHERS> will be ignored.
-
-=item OPENSSL_INIT_NO_ADD_ALL_DIGESTS
-
-With this option the library will suppress automatic loading of libcrypto
-digests. This option is not a default option. Once selected subsequent
-calls to OPENSSL_init_crypto() with the option
-B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored.
-
-=item OPENSSL_INIT_LOAD_CONFIG
-
-With this option an OpenSSL configuration file will be automatically loaded and
-used by calling OPENSSL_config(). This is not a default option.
-See the description of OPENSSL_init_new(), below.
-
-=item OPENSSL_INIT_NO_LOAD_CONFIG
-
-With this option the loading of OpenSSL configuration files will be suppressed.
-It is the equivalent of calling OPENSSL_no_config(). This is not a default
-option.
-
-=item OPENSSL_INIT_ASYNC
-
-With this option the library with automatically initialise the libcrypto async
-sub-library (see L<ASYNC_start_job(3)>). This is a default option.
-
-=item OPENSSL_INIT_ENGINE_RDRAND
-
-With this option the library will automatically load and initialise the
-RDRAND engine (if available). This not a default option.
-
-=item OPENSSL_INIT_ENGINE_DYNAMIC
-
-With this option the library will automatically load and initialise the
-dynamic engine. This not a default option.
-
-=item OPENSSL_INIT_ENGINE_OPENSSL
-
-With this option the library will automatically load and initialise the
-openssl engine. This not a default option.
-
-=item OPENSSL_INIT_ENGINE_CRYPTODEV
-
-With this option the library will automatically load and initialise the
-cryptodev engine (if available). This not a default option.
-
-=item OPENSSL_INIT_ENGINE_CAPI
-
-With this option the library will automatically load and initialise the
-CAPI engine (if available). This not a default option.
-
-=item OPENSSL_INIT_ENGINE_PADLOCK
-
-With this option the library will automatically load and initialise the
-padlock engine (if available). This not a default option.
-
-=item OPENSSL_INIT_ENGINE_DASYNC
-
-With this option the library will automatically load and initialise the
-DASYNC engine. This not a default option.
-
-=item OPENSSL_INIT_ENGINE_ALL_BUILTIN
-
-With this option the library will automatically load and initialise all the
-built in engines listed above with the exception of the openssl and dasync
-engines. This not a default option.
-
-=back
-
-Multiple options may be combined together in a single call to
-OPENSSL_init_crypto(). For example:
-
- OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
- | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
-
-The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto
-and libssl). All resources allocated by OpenSSL are freed. Typically there
-should be no need to call this function directly as it is initiated
-automatically on application exit. This is done via the standard C library
-L<atexit(3)> function. In the event that the application will close in a manner
-that will not call the registered atexit() handlers then the application should
-call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL
-are discouraged from calling this function and should instead, typically, rely
-on auto-deinitialisation. This is to avoid error conditions where both an
-application and a library it depends on both use OpenSSL, and the library
-deinitialises it before the application has finished using it.
-
-Once OPENSSL_cleanup() has been called the library cannot be reinitialised.
-Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error
-will be added to the error stack. Note that because initialisation has failed
-OpenSSL error strings will not be available, only an error code. This code can
-be put through the openssl errstr command line application to produce a human
-readable error (see L<errstr(1)>).
-
-The OPENSSL_atexit() function enables the registration of a
-function to be called during OPENSSL_cleanup(). Stop handlers are
-called after deinitialisation of resources local to a thread, but before other
-process wide resources are freed. In the event that multiple stop handlers are
-registered, no guarantees are made about the order of execution.
-
-The OPENSSL_thread_stop() function deallocates resources associated
-with the current thread. Typically this function will be called automatically by
-the library when the thread exits. This should only be called directly if
-resources should be freed at an earlier time, or under the circumstances
-described in the NOTES section below.
-
-The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a default configuration
-file. To specify a different file, an B<OPENSSL_INIT_SETTINGS> must
-be created and used. The routines
-OPENSSL_init_new() and OPENSSL_INIT_set_config_appname() can be used to
-allocate the object and set the application name, and then the
-object can be released with OPENSSL_INIT_free() when done.
-
-=head1 NOTES
-
-Resources local to a thread are deallocated automatically when the thread exits
-(e.g. in a pthreads environment, when pthread_exit() is called). On Windows
-platforms this is done in response to a DLL_THREAD_DETACH message being sent to
-the libcrypto32.dll entry point. Some windows functions may cause threads to exit
-without sending this message (for example ExitProcess()). If the application
-uses such functions, then the application must free up OpenSSL resources
-directly via a call to OPENSSL_thread_stop() on each thread. Similarly this
-message will also not be sent if OpenSSL is linked statically, and therefore
-applications using static linking should also call OPENSSL_thread_stop() on each
-thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the
-threads are not destroyed until after FreeLibrary() is called then each thread
-should call OPENSSL_thread_stop() prior to the FreeLibrary() call.
-
-On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is
-multi-threaded and if dlclose() is subsequently called prior to the threads
-being destroyed then OpenSSL will not be able to deallocate resources associated
-with those threads. The application should either call OPENSSL_thread_stop() on
-each thread prior to the dlclose() call, or alternatively the original dlopen()
-call should use the RTLD_NODELETE flag (where available on the platform).
-
-=head1 RETURN VALUES
-
-The functions OPENSSL_init_crypto, OPENSSL_atexit() and
-OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error.
-
-=head1 SEE ALSO
-
-L<OPENSSL_init_ssl(3)>
-
-=head1 HISTORY
-
-The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(),
-OPENSSL_thread_stop(), OPENSSL_init_new(), OPENSSL_INIT_set_config_appname()
-and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memory bus
-
-=head1 SYNOPSIS
-
- #ifdef OPENSSL_CPUID_OBJ
- size_t OPENSSL_instrument_bus(int *vector, size_t num);
- size_t OPENSSL_instrument_bus2(int *vector, size_t num, size_t max);
- #endif
-
-=head1 DESCRIPTION
-
-It was empirically found that timings of references to primary memory
-are subject to irregular, apparently non-deterministic variations. The
-subroutines in question instrument these references for purposes of
-gathering entropy for random number generator. In order to make it
-bus-bound a 'flush cache line' instruction is used between probes. In
-addition probes are added to B<vector> elements in atomic or
-interlocked manner, which should contribute additional noise on
-multi-processor systems. This also means that B<vector[num]> should be
-zeroed upon invocation (if you want to retrieve actual probe values).
-
-OPENSSL_instrument_bus() performs B<num> probes and records the number of
-oscillator cycles every probe took.
-
-OPENSSL_instrument_bus2() on the other hand B<accumulates> consecutive
-probes with the same value, i.e. in a way it records duration of
-periods when probe values appeared deterministic. The subroutine
-performs at most B<max> probes in attempt to fill the B<vector[num]>,
-with B<max> value of 0 meaning "as many as it takes."
-
-=head1 RETURN VALUE
-
-Return value of 0 indicates that CPU is not capable of performing the
-benchmark, either because oscillator counter or 'flush cache line' is
-not available on current platform. For reference, on x86 'flush cache
-line' was introduced with the SSE2 extensions.
-
-Otherwise number of recorded values is returned.
-
-=head1 COPYRIGHT
-
-Copyright 2011-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules
-
-=head1 SYNOPSIS
-
- #include <openssl/conf.h>
-
- void OPENSSL_load_builtin_modules(void);
- void ASN1_add_oid_module(void);
- ENGINE_add_conf_module();
-
-=head1 DESCRIPTION
-
-The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL
-configuration modules to the internal list. They can then be used by the
-OpenSSL configuration code.
-
-ASN1_add_oid_module() adds just the ASN1 OBJECT module.
-
-ENGINE_add_conf_module() adds just the ENGINE configuration module.
-
-=head1 NOTES
-
-If the simple configuration function OPENSSL_config() is called then
-OPENSSL_load_builtin_modules() is called automatically.
-
-Applications which use the configuration functions directly will need to
-call OPENSSL_load_builtin_modules() themselves I<before> any other
-configuration code.
-
-Applications should call OPENSSL_load_builtin_modules() to load all
-configuration modules instead of adding modules selectively: otherwise
-functionality may be missing from the application if an when new
-modules are added.
-
-=head1 RETURN VALUE
-
-None of the functions return a value.
-
-=head1 SEE ALSO
-
-L<conf(3)>, L<OPENSSL_config(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_malloc_init,
-OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
-OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
-CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
-OPENSSL_strdup, OPENSSL_strndup,
-OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat,
-OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int,
-CRYPTO_strdup, CRYPTO_strndup,
-OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
-CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
-CRYPTO_clear_realloc, CRYPTO_clear_free,
-CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
-CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
-CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/crypto.h>
-
- int OPENSSL_malloc_init(void)
-
- void *OPENSSL_malloc(size_t num)
- void *OPENSSL_zalloc(size_t num)
- void *OPENSSL_realloc(void *addr, size_t num)
- void OPENSSL_free(void *addr)
- char *OPENSSL_strdup(const char *str)
- char *OPENSSL_strndup(const char *str, size_t s)
- size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
- size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
- void *OPENSSL_memdup(void *data, size_t s)
- void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num)
- void OPENSSL_clear_free(void *str, size_t num)
- void OPENSSL_cleanse(void *ptr, size_t len);
-
- unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
- char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len);
- int OPENSSL_hexchar2int(unsigned char c);
-
- void *CRYPTO_malloc(size_t num, const char *file, int line)
- void *CRYPTO_zalloc(size_t num, const char *file, int line)
- void *CRYPTO_realloc(void *p, size_t num, const char *file, int line)
- void CRYPTO_free(void *str, const char *, int)
- char *CRYPTO_strdup(const char *p, const char *file, int line)
- char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line)
- void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, const char *file, int line)
- void CRYPTO_clear_free(void *str, size_t num, const char *, int)
-
- void CRYPTO_get_mem_functions(
- void *(**m)(size_t, const char *, int),
- void *(**r)(void *, size_t, const char *, int),
- void (**f)(void *, const char *, int))
- int CRYPTO_set_mem_functions(
- void *(*m)(size_t, const char *, int),
- void *(*r)(void *, size_t, const char *, int),
- void (*f)(void *, const char *, int))
-
- int CRYPTO_set_mem_debug(int onoff)
-
- int CRYPTO_mem_ctrl(int mode);
-
- int OPENSSL_mem_debug_push(const char *info)
- int OPENSSL_mem_debug_pop(void);
-
- int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
- int CRYPTO_mem_debug_pop(void);
-
- void CRYPTO_mem_leaks(BIO *b);
- void CRYPTO_mem_leaks_fp(FILE *fp);
-
-=head1 DESCRIPTION
-
-OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are
-generally macro's that add the standard C B<__FILE__> and B<__LINE__>
-parameters and call a lower-level B<CRYPTO_xxx> API.
-Some functions do not add those parameters, but exist for consistency.
-
-OPENSSL_malloc_init() sets the lower-level memory allocation functions
-to their default implementation.
-It is generally not necessary to call this, except perhaps in certain
-shared-library situations.
-
-OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the
-C malloc(), realloc(), and free() functions.
-OPENSSL_zalloc() calls memset() to zero the memory before returning.
-
-OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used
-when the buffer at B<addr> holds sensitive information.
-The old buffer is filled with zero's by calling OPENSSL_cleanse()
-before ultimately calling OPENSSL_free().
-
-OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's.
-Use OPENSSL_cleanse() with care if the memory is a mapping of a file.
-If the storage controller uses write compression, then its possible
-that sensitive tail bytes will survive zeroization because the block of
-zeros will be compressed. If the storage controller uses wear leveling,
-then the old sensitive data will not be overwritten; rather, a block of
-0's will be written at a new physical location.
-
-OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the
-equivalent C functions, except that memory is allocated by calling the
-OPENSSL_malloc() and should be released by calling OPENSSL_free().
-
-OPENSSL_strlcpy(),
-OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C
-library functions and are provided for portability.
-
-OPENSSL_hexstr2buf() parses B<str> as a hex string and returns a
-pointer to the parsed value. The memory is allocated by calling
-OPENSSL_malloc() and should be released by calling OPENSSL_free().
-If B<len> is not NULL, it is filled in with the output length.
-Colons between two-character hex "bytes" are ignored.
-An odd number of hex digits is an error.
-
-OPENSSL_buf2hexstr() takes the specified buffer and length, and returns
-a hex string for value, or NULL on error.
-B<Buffer> cannot be NULL; if B<len> is 0 an empty string is returned.
-
-OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent,
-or returns -1 on error.
-
-If no allocations have been done, it is possible to "swap out" the default
-implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free()
-and replace them with alternate versions (hooks).
-CRYPTO_get_mem_functions() function fills in the given arguments with the
-function pointers for the current implementations.
-With CRYPTO_set_mem_functions(), you can specify a different set of functions.
-If any of B<m>, B<r>, or B<f> are NULL, then the function is not changed.
-
-The default implementation can include some debugging capability (if enabled
-at build-time).
-This adds some overhead by keeping a list of all memory allocations, and
-removes items from the list when they are free'd.
-This is most useful for identifying memory leaks.
-CRYPTO_set_mem_debug() turns this tracking on and off. It is normally
-called at startup, but can be called at any time.
-
-CRYPTO_mem_ctrl() provides fine-grained control of memory leak tracking.
-To enable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
-the B<CRYPTO_MEM_CHECK_ON>.
-To disable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
-the B<CRYPTO_MEM_CHECK_OFF>.
-
-While checking memory, it can be useful to store additional context
-about what is being done.
-For example, identifying the field names when parsing a complicated
-data structure.
-OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push())
-attachs an identifying string to the allocation stack.
-This must be a global or other static string; it is not copied.
-OPENSSL_mem_debug_pop() removes identifying state from the stack.
-
-At the end of the program, calling CRYPTO_mem_leaks() or
-CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it
-to the specified BIO B<b> or FILE B<fp>. These functions return 1 if
-there are no leaks, 0 if there are leaks and -1 if an error occurred.
-
-=head1 RETURN VALUES
-
-OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
-CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
-return no value.
-
-CRYPTO_mem_leaks() and CRYPTO_mem_leaks_fp() return 1 if there
-are no leaks, 0 if there are leaks and -1 if an error occurred.
-
-OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
-OPENSSL_clear_realloc(),
-CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(),
-CRYPTO_clear_realloc(),
-OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(),
-OPENSSL_strdup(), and OPENSSL_strndup()
-return a pointer to allocated memory or NULL on error.
-
-CRYPTO_set_mem_functions() and CRYPTO_set_mem_debug()
-return 1 on success or 0 on failure (almost
-always because allocations have already happened).
-
-CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the
-previous value of the mode.
-
-OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop()
-return 1 on success or 0 on failure.
-
-=head1 NOTES
-
-While it's permitted to swap out only a few and not all the functions
-with CRYPTO_set_mem_functions(), it's recommended to swap them all out
-at once. I<This applies specially if OpenSSL was built with the
-configuration option> C<crypto-mdebug> I<enabled. In case, swapping out
-only, say, the malloc() implementation is outright dangerous.>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized,
-CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc,
-OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free,
-CRYPTO_secure_free, OPENSSL_secure_actual_size, OPENSSL_secure_allocated,
-CYRPTO_secure_used - secure heap storage
-
-=head1 SYNOPSIS
-
- #include <openssl/crypto.h>
-
- int CRYPTO_secure_malloc_init(size_t size, int minsize);
-
- int CRYPTO_secure_malloc_initialized();
-
- int CRYPTO_secure_malloc_done();
-
- void *OPENSSL_secure_malloc(size_t num);
- void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
-
- void *OPENSSL_secure_zalloc(size_t num);
- void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
-
- void OPENSSL_secure_free(void* ptr);
- void CRYPTO_secure_free(void *ptr, const char *, int);
-
- size_t OPENSSL_secure_actual_size(const void *ptr);
- int OPENSSL_secure_allocated(const void *ptr);
-
- size_t CYRPTO_secure_used();
-
-=head1 DESCRIPTION
-
-In order to help protect applications (particularly long-running servers)
-from pointer overruns or underruns that could return arbitrary data from
-the program's dynamic memory area, where keys and other sensitive
-information might be stored, OpenSSL supports the concept of a "secure heap."
-The level and type of security guarantees depend on the operating system.
-It is a good idea to review the code and see if it addresses your
-threat model and concerns.
-
-If a secure heap is used, then private key B<BIGNUM> values are stored there.
-This protects long-term storage of private keys, but will not necessarily
-put all intermediate values and computations there.
-
-CRYPTO_secure_malloc_init() creates the secure heap, with the specified
-C<size> in bytes. The C<minsize> parameter is the minimum size to
-allocate from the heap. Both C<size> and C<minsize> must be a power
-of two.
-
-CRYPTO_secure_malloc_initialized() indicates whether or not the secure
-heap as been initialized and is available.
-
-CRYPTO_secure_malloc_done() releases the heap and makes the memory unavailable
-to the process if all secure memory has been freed.
-It can take noticeably long to complete.
-
-OPENSSL_secure_malloc() allocates C<num> bytes from the heap.
-If CRYPTO_secure_malloc_init() is not called, this is equivalent to
-calling OPENSSL_malloc().
-It is a macro that expands to
-CRYPTO_secure_malloc() and adds the C<__FILE__> and C<__LINE__> parameters.
-
-OPENSSL_secure_zalloc() and CRYPTO_secure_zalloc() are like
-OPENSSL_secure_malloc() and CRYPTO_secure_malloc(), respectively,
-except that they call memset() to zero the memory before returning.
-
-OPENSSL_secure_free() releases the memory at C<ptr> back to the heap.
-It must be called with a value previously obtained from
-OPENSSL_secure_malloc().
-If CRYPTO_secure_malloc_init() is not called, this is equivalent to
-calling OPENSSL_free().
-It exists for consistency with OPENSSL_secure_malloc() , and
-is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__>
-and C<__LINE__> parameters..
-
-OPENSSL_secure_allocated() tells whether or not a pointer is within
-the secure heap.
-OPENSSL_secure_actual_size() tells the actual size allocated to the
-pointer; implementations may allocate more space than initially
-requested, in order to "round up" and reduce secure heap fragmentation.
-
-CRYPTO_secure_used() returns the number of bytes allocated in the
-secure heap.
-
-=head1 RETURN VALUES
-
-CRYPTO_secure_malloc_init() returns 0 on failure, 1 if successful,
-and 2 if successful but the heap could not be protected by memory
-mapping.
-
-CRYPTO_secure_malloc_initialized() returns 1 if the secure heap is
-available (that is, if CRYPTO_secure_malloc_init() has been called,
-but CRYPTO_secure_malloc_done() has not been called or failed) or 0 if not.
-
-OPENSSL_secure_malloc() and OPENSSL_secure_zalloc() return a pointer into
-the secure heap of the requested size, or C<NULL> if memory could not be
-allocated.
-
-CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 if not.
-
-CRYPTO_secure_malloc_done() returns 1 if the secure memory area is released, or 0 if not.
-
-OPENSSL_secure_free() returns no values.
-
-=head1 SEE ALSO
-
-L<OPENSSL_malloc(3)>,
-L<BN_new(3)>,
-L<bn_internal(3)>.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup -
-add algorithms to internal table
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
-Deprecated:
-
- # if OPENSSL_API_COMPAT < 0x10100000L
- void OpenSSL_add_all_algorithms(void);
- void OpenSSL_add_all_ciphers(void);
- void OpenSSL_add_all_digests(void);
-
- void EVP_cleanup(void)
-# endif
-
-=head1 DESCRIPTION
-
-OpenSSL keeps an internal table of digest algorithms and ciphers. It uses
-this table to lookup ciphers via functions such as EVP_get_cipher_byname(). In
-OpenSSL versions prior to 1.1.0 these functions initialised and de-initialised
-this table. From OpenSSL 1.1.0 they are deprecated. No explicit initialisation
-or de-initialisation is required. See L<OPENSSL_init_crypto(3)> for further
-information.
-
-OpenSSL_add_all_digests() adds all digest algorithms to the table.
-
-OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and
-ciphers).
-
-OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including
-password based encryption algorithms.
-
-In versions prior to 1.1.0 EVP_cleanup() removed all ciphers and digests from
-the table. It no longer has any effect in OpenSSL 1.1.0.
-
-=head1 RETURN VALUES
-
-None of the functions return a value.
-
-=head1 NOTES
-
-A typical application will call OpenSSL_add_all_algorithms() initially and
-EVP_cleanup() before exiting.
-
-An application does not need to add algorithms to use them explicitly, for example
-by EVP_sha1(). It just needs to add them if it (or any of the functions it calls)
-needs to lookup algorithms.
-
-The cipher and digest lookup functions are used in many parts of the library. If
-the table is not initialized several functions will misbehave and complain they
-cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries.
-This is a common query in the OpenSSL mailing lists.
-
-Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a
-statically linked executable can be quite large. If this is important it is possible
-to just add the required ciphers and digests.
-
-=head1 BUGS
-
-Although the functions do not return error codes it is possible for them to fail.
-This will only happen as a result of a memory allocation failure so this is not
-too much of a problem in practice.
-
-=head1 SEE ALSO
-
-L<evp(3)>, L<EVP_DigestInit(3)>,
-L<EVP_EncryptInit(3)>
-
-=head1 HISTORY
-
-The OpenSSL_add_all_algorithms(), OpenSSL_add_all_ciphers(),
-OpenSSL_add_all_digests(), and EVP_cleanup(), functions
-were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto().
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PEM_write, PEM_write_bio,
-PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO
-- PEM encoding routines
-
-=head1 SYNOPSIS
-
- #include <openssl/pem.h>
-
- int PEM_write(FILE *fp, const char *name, const char *header,
- const unsigned char *data, long len)
- int PEM_write_bio(BIO *bp, const char *name, const char *header,
- const unsigned char *data, long len)
-
- int PEM_read(FILE *fp, char **name, char **header,
- unsigned char **data, long *len);
- int PEM_read_bio(BIO *bp, char **name, char **header,
- unsigned char **data, long *len);
-
- int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo);
- int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len,
- pem_password_cb *cb, void *u);
-
-=head1 DESCRIPTION
-
-These functions read and write PEM-encoded objects, using the PEM
-type B<name>, any additional B<header> information, and the raw
-B<data> of length B<len>.
-
-PEM is the term used for binary content encoding first defined in IETF
-RFC 1421. The content is a series of base64-encoded lines, surrounded
-by begin/end markers each on their own line. For example:
-
- -----BEGIN PRIVATE KEY-----
- MIICdg....
- ... bhTQ==
- -----END PRIVATE KEY-----
-
-Optional header line(s) may appear after the begin line, and their
-existence depends on the type of object being written or read.
-
-PEM_write() writes to the file B<fp>, while PEM_write_bio() writes to
-the BIO B<bp>. The B<name> is the name to use in the marker, the
-B<header> is the header value or NULL, and B<data> and B<len> specify
-the data and its length.
-
-The final B<data> buffer is typically an ASN.1 object which can be decoded with
-the B<d2i> function appropriate to the type B<name>; see L<d2i_X509(3)>
-for examples.
-
-PEM_read() reads from the file B<fp>, while PEM_read_bio() reads
-from the BIO B<bp>.
-Both skip any non-PEM data that precedes the start of the next PEM object.
-When an object is successfully retrieved, the type name from the "----BEGIN
-<type>-----" is returned via the B<name> argument, any encapsulation headers
-are returned in B<header> and the base64-decoded content and its length are
-returned via B<data> and B<len> respectively.
-The B<name>, B<header> and B<data> pointers are allocated via OPENSSL_malloc()
-and should be freed by the caller via OPENSSL_free() when no longer needed.
-
-PEM_get_EVP_CIPHER_INFO() can be used to determine the B<data> returned by
-PEM_read() or PEM_read_bio() is encrypted and to retrieve the associated cipher
-and IV.
-The caller passes a pointer to structure of type B<EVP_CIPHER_INFO> via the
-B<cinfo> argument and the B<header> returned via PEM_read() or PEM_read_bio().
-If the call is successful 1 is returned and the cipher and IV are stored at the
-address pointed to by B<cinfo>.
-When the header is malformed, or not supported or when the cipher is unknown
-or some internal error happens 0 is returned.
-This function is deprecated, see B<NOTES> below.
-
-PEM_do_header() can then be used to decrypt the data if the header
-indicates encryption.
-The B<cinfo> argument is a pointer to the structure initialized by the previous
-call to PEM_get_EVP_CIPHER_INFO().
-The B<data> and B<len> arguments are those returned by the previous call to
-PEM_read() or PEM_read_bio().
-The B<cb> and B<u> arguments make it possible to override the default password
-prompt function as described in L<PEM_read_PrivateKey(3)>.
-On successful completion the B<data> is decrypted in place, and B<len> is
-updated to indicate the plaintext length.
-This function is deprecated, see B<NOTES> below.
-
-If the data is a priori known to not be encrypted, then neither PEM_do_header()
-nor PEM_get_EVP_CIPHER_INFO() need be called.
-
-=head1 RETURN VALUES
-
-PEM_read() and PEM_read_bio() return 1 on success and 0 on failure, the latter
-includes the case when no more PEM objects remain in the input file.
-To distinguish end of file from more serious errors the caller must peek at the
-error stack and check for B<PEM_R_NO_START_LINE>, which indicates that no more
-PEM objects were found. See L<ERR_peek_last_error(3)>, L<ERR_GET_REASON(3)>.
-
-PEM_get_EVP_CIPHER_INFO() and PEM_do_header() return 1 on success, and 0 on
-failure.
-The B<data> is likely meaningless if these functions fail.
-
-=head1 NOTES
-
-The PEM_get_EVP_CIPHER_INFO() and PEM_do_header() functions are deprecated.
-This is because the underlying PEM encryption format is obsolete, and should
-be avoided.
-It uses an encryption format with an OpenSSL-specific key-derivation function,
-which employs MD5 with an iteration count of 1!
-Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5
-v2.0 PBE.
-See L<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>.
-
-=head1 SEE ALSO
-
-L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>,
-L<d2i_PKCS8PrivateKey_bio(3)>.
-
-=head1 COPYRIGHT
-
-Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DECLARE_PEM_rw,
-PEM_read_CMS,
-PEM_read_bio_CMS,
-PEM_write_CMS,
-PEM_write_bio_CMS,
-PEM_write_DHxparams,
-PEM_write_bio_DHxparams,
-PEM_read_ECPKParameters,
-PEM_read_bio_ECPKParameters,
-PEM_write_ECPKParameters,
-PEM_write_bio_ECPKParameters,
-PEM_read_ECPrivateKey,
-PEM_write_ECPrivateKey,
-PEM_write_bio_ECPrivateKey,
-PEM_read_EC_PUBKEY,
-PEM_read_bio_EC_PUBKEY,
-PEM_write_EC_PUBKEY,
-PEM_write_bio_EC_PUBKEY,
-PEM_read_NETSCAPE_CERT_SEQUENCE,
-PEM_read_bio_NETSCAPE_CERT_SEQUENCE,
-PEM_write_NETSCAPE_CERT_SEQUENCE,
-PEM_write_bio_NETSCAPE_CERT_SEQUENCE,
-PEM_read_PKCS8,
-PEM_read_bio_PKCS8,
-PEM_write_PKCS8,
-PEM_write_bio_PKCS8,
-PEM_write_PKCS8_PRIV_KEY_INFO,
-PEM_read_bio_PKCS8_PRIV_KEY_INFO,
-PEM_read_PKCS8_PRIV_KEY_INFO,
-PEM_write_bio_PKCS8_PRIV_KEY_INFO,
-PEM_read_SSL_SESSION,
-PEM_read_bio_SSL_SESSION,
-PEM_write_SSL_SESSION,
-PEM_write_bio_SSL_SESSION
-- PEM object encoding routines
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- #include <openssl/pem.h>
-
- DECLARE_PEM_rw(name, TYPE)
-
- TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u);
- TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u);
- int PEM_write_TYPE(FILE *fp, const TYPE *a);
- int PEM_write_bio_TYPE(BIO *bp, const TYPE *a);
-
-=head1 DESCRIPTION
-
-In the description below, I<TYPE> is used
-as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
-The macro B<DECLARE_PEM_rw> expands to the set of declarations shown in
-the next four lines of the synopsis.
-
-These routines convert between local instances of ASN1 datatypes and
-the PEM encoding. For more information on the templates, see
-L<ASN1_ITEM(3)>. For more information on the lower-level routines used
-by the functions here, see L<PEM_read(3)>.
-
-PEM_read_TYPE() reads a PEM-encoded object of I<TYPE> from the file B<fp>
-and returns it. The B<cb> and B<u> parameters are as described in
-L<pem_password_cb(3)>.
-
-PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B<bp>.
-
-PEM_write_TYPE() writes the PEM encoding of the object B<a> to the file B<fp>.
-
-PEM_write_bio_TYPE() similarly writes to the BIO B<bp>.
-
-=head1 RETURN VALUES
-
-PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated
-object, which should be released by calling TYPE_free(), or NULL on error.
-
-PEM_write_TYPE() and PEM_write_bio_TYPE() return the number of bytes written
-or zero on error.
-
-=head1 SEE ALSO
-
-L<PEM_read(3)>
-
-=head1 COPYRIGHT
-
-Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-pem_password_cb,
-PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
-PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey,
-PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
-PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
-PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY,
-PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey,
-PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
-PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey,
-PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
-PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
-PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
-PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
-PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
-PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
-PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
-PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
-PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX,
-PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ,
-PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,
-PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,
-PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,
-PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
-
-=head1 SYNOPSIS
-
- #include <openssl/pem.h>
-
- typedef int (*pem_password_cb)(char *buf, int size, int rwflag, void *u);
-
- EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
- pem_password_cb *cb, void *u);
- EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
- unsigned char *kstr, int klen,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x,
- const EVP_CIPHER *enc,
- unsigned char *kstr, int klen,
- pem_password_cb *cb, void *u);
- int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
- unsigned char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
- int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
- int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
- int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
- EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
- pem_password_cb *cb, void *u);
- EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
- int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
-
- RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
- pem_password_cb *cb, void *u);
- RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
- unsigned char *kstr, int klen,
- pem_password_cb *cb, void *u);
- int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
- unsigned char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
- RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
- pem_password_cb *cb, void *u);
- RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
- int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
-
- RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
- pem_password_cb *cb, void *u);
- RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
- int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
-
- DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
- pem_password_cb *cb, void *u);
- DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
- unsigned char *kstr, int klen,
- pem_password_cb *cb, void *u);
- int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
- unsigned char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
- DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
- pem_password_cb *cb, void *u);
- DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
- int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
-
- DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
- DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
- int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
- int PEM_write_DSAparams(FILE *fp, DSA *x);
-
- DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
- DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
- int PEM_write_bio_DHparams(BIO *bp, DH *x);
- int PEM_write_DHparams(FILE *fp, DH *x);
-
- X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
- X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
- int PEM_write_bio_X509(BIO *bp, X509 *x);
- int PEM_write_X509(FILE *fp, X509 *x);
-
- X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
- X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
- int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
- int PEM_write_X509_AUX(FILE *fp, X509 *x);
-
- X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
- pem_password_cb *cb, void *u);
- X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
- int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
- int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
- int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
-
- X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
- pem_password_cb *cb, void *u);
- X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
- pem_password_cb *cb, void *u);
- int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
- int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
-
- PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
- PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
- int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
- int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
-
-=head1 DESCRIPTION
-
-The PEM functions read or write structures in PEM format. In
-this sense PEM format is simply base64 encoded data surrounded
-by header lines.
-
-For more details about the meaning of arguments see the
-B<PEM FUNCTION ARGUMENTS> section.
-
-Each operation has four functions associated with it. For
-clarity the term "B<foobar> functions" will be used to collectively
-refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
-PEM_write_bio_foobar() and PEM_write_foobar() functions.
-
-The B<PrivateKey> functions read or write a private key in PEM format using an
-EVP_PKEY structure. The write routines use PKCS#8 private key format and are
-equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
-handle traditional and PKCS#8 format encrypted and unencrypted keys.
-
-PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy
-"traditional" format.
-
-PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
-key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
-PKCS#5 v2.0 password based encryption algorithms. The B<cipher> argument
-specifies the encryption algorithm to use: unlike some other PEM routines the
-encryption is applied at the PKCS#8 level and not in the PEM headers. If
-B<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
-structure is used instead.
-
-PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
-also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
-it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
-to use is specified in the B<nid> parameter and should be the NID of the
-corresponding OBJECT IDENTIFIER (see NOTES section).
-
-The B<PUBKEY> functions process a public key using an EVP_PKEY
-structure. The public key is encoded as a SubjectPublicKeyInfo
-structure.
-
-The B<RSAPrivateKey> functions process an RSA private key using an
-RSA structure. The write routines uses traditional format. The read
-routines handles the same formats as the B<PrivateKey>
-functions but an error occurs if the private key is not RSA.
-
-The B<RSAPublicKey> functions process an RSA public key using an
-RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
-structure.
-
-The B<RSA_PUBKEY> functions also process an RSA public key using
-an RSA structure. However the public key is encoded using a
-SubjectPublicKeyInfo structure and an error occurs if the public
-key is not RSA.
-
-The B<DSAPrivateKey> functions process a DSA private key using a
-DSA structure. The write routines uses traditional format. The read
-routines handles the same formats as the B<PrivateKey>
-functions but an error occurs if the private key is not DSA.
-
-The B<DSA_PUBKEY> functions process a DSA public key using
-a DSA structure. The public key is encoded using a
-SubjectPublicKeyInfo structure and an error occurs if the public
-key is not DSA.
-
-The B<DSAparams> functions process DSA parameters using a DSA
-structure. The parameters are encoded using a Dss-Parms structure
-as defined in RFC2459.
-
-The B<DHparams> functions process DH parameters using a DH
-structure. The parameters are encoded using a PKCS#3 DHparameter
-structure.
-
-The B<X509> functions process an X509 certificate using an X509
-structure. They will also process a trusted X509 certificate but
-any trust settings are discarded.
-
-The B<X509_AUX> functions process a trusted X509 certificate using
-an X509 structure.
-
-The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
-certificate request using an X509_REQ structure. The B<X509_REQ>
-write functions use B<CERTIFICATE REQUEST> in the header whereas
-the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
-(as required by some CAs). The B<X509_REQ> read functions will
-handle either form so there are no B<X509_REQ_NEW> read functions.
-
-The B<X509_CRL> functions process an X509 CRL using an X509_CRL
-structure.
-
-The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
-structure.
-
-=head1 PEM FUNCTION ARGUMENTS
-
-The PEM functions have many common arguments.
-
-The B<bp> BIO parameter (if present) specifies the BIO to read from
-or write to.
-
-The B<fp> FILE parameter (if present) specifies the FILE pointer to
-read from or write to.
-
-The PEM read functions all take an argument B<TYPE **x> and return
-a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
-uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
-NULL but B<*x> is NULL then the structure returned will be written
-to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
-to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
-Irrespective of the value of B<x> a pointer to the structure is always
-returned (or NULL if an error occurred).
-
-The PEM functions which write private keys take an B<enc> parameter
-which specifies the encryption algorithm to use, encryption is done
-at the PEM level. If this parameter is set to NULL then the private
-key is written in unencrypted form.
-
-The B<cb> argument is the callback to use when querying for the pass
-phrase used for encrypted PEM structures (normally only private keys).
-
-For the PEM write routines if the B<kstr> parameter is not NULL then
-B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
-ignored.
-
-If the B<cb> parameters is set to NULL and the B<u> parameter is not
-NULL then the B<u> parameter is interpreted as a null terminated string
-to use as the passphrase. If both B<cb> and B<u> are NULL then the
-default callback routine is used which will typically prompt for the
-passphrase on the current terminal with echoing turned off.
-
-The default passphrase callback is sometimes inappropriate (for example
-in a GUI application) so an alternative can be supplied. The callback
-routine has the following form:
-
- int cb(char *buf, int size, int rwflag, void *u);
-
-B<buf> is the buffer to write the passphrase to. B<size> is the maximum
-length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
-which is set to 0 when reading and 1 when writing. A typical routine
-will ask the user to verify the passphrase (for example by prompting
-for it twice) if B<rwflag> is 1. The B<u> parameter has the same
-value as the B<u> parameter passed to the PEM routine. It allows
-arbitrary data to be passed to the callback by the application
-(for example a window handle in a GUI application). The callback
-B<must> return the number of characters in the passphrase or 0 if
-an error occurred.
-
-=head1 EXAMPLES
-
-Although the PEM routines take several arguments in almost all applications
-most of them are set to 0 or NULL.
-
-Read a certificate in PEM format from a BIO:
-
- X509 *x;
- x = PEM_read_bio_X509(bp, NULL, 0, NULL);
- if (x == NULL) {
- /* Error */
- }
-
-Alternative method:
-
- X509 *x = NULL;
- if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
- /* Error */
- }
-
-Write a certificate to a BIO:
-
- if (!PEM_write_bio_X509(bp, x)) {
- /* Error */
- }
-
-Write a private key (using traditional format) to a BIO using
-triple DES encryption, the pass phrase is prompted for:
-
- if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) {
- /* Error */
- }
-
-Write a private key (using PKCS#8 format) to a BIO using triple
-DES encryption, using the pass phrase "hello":
-
- if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) {
- /* Error */
- }
-
-Read a private key from a BIO using a pass phrase callback:
-
- key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
- if (key == NULL) {
- /* Error */
- }
-
-Skeleton pass phrase callback:
-
- int pass_cb(char *buf, int size, int rwflag, void *u)
- {
- int len;
- char *tmp;
-
- /* We'd probably do something else if 'rwflag' is 1 */
- printf("Enter pass phrase for \"%s\"\n", (char *)u);
-
- /* get pass phrase, length 'len' into 'tmp' */
- tmp = "hello";
- len = strlen(tmp);
- if (len <= 0)
- return 0;
-
- if (len > size)
- len = size;
- memcpy(buf, tmp, len);
- return len;
- }
-
-=head1 NOTES
-
-The old B<PrivateKey> write routines are retained for compatibility.
-New applications should write private keys using the
-PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
-because they are more secure (they use an iteration count of 2048 whereas
-the traditional routines use a count of 1) unless compatibility with older
-versions of OpenSSL is important.
-
-The B<PrivateKey> read routines can be used in all applications because
-they handle all formats transparently.
-
-A frequent cause of problems is attempting to use the PEM routines like
-this:
-
- X509 *x;
- PEM_read_bio_X509(bp, &x, 0, NULL);
-
-this is a bug because an attempt will be made to reuse the data at B<x>
-which is an uninitialised pointer.
-
-=head1 PEM ENCRYPTION FORMAT
-
-These old B<PrivateKey> routines use a non standard technique for encryption.
-
-The private key (or other data) takes the following form:
-
- -----BEGIN RSA PRIVATE KEY-----
- Proc-Type: 4,ENCRYPTED
- DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
-
- ...base64 encoded data...
- -----END RSA PRIVATE KEY-----
-
-The line beginning with I<Proc-Type> contains the version and the
-protection on the encapsulated data. The line beginning I<DEK-Info>
-contains two comma separated values: the encryption algorithm name as
-used by EVP_get_cipherbyname() and an initialization vector used by the
-cipher encoded as a set of hexadecimal digits. After those two lines is
-the base64-encoded encrypted data.
-
-The encryption key is derived using EVP_BytesToKey(). The cipher's
-initialization vector is passed to EVP_BytesToKey() as the B<salt>
-parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used
-(regardless of the size of the initialization vector). The user's
-password is passed to EVP_BytesToKey() using the B<data> and B<datal>
-parameters. Finally, the library uses an iteration count of 1 for
-EVP_BytesToKey().
-
-The B<key> derived by EVP_BytesToKey() along with the original initialization
-vector is then used to decrypt the encrypted data. The B<iv> produced by
-EVP_BytesToKey() is not utilized or needed, and NULL should be passed to
-the function.
-
-The pseudo code to derive the key would look similar to:
-
- EVP_CIPHER* cipher = EVP_des_ede3_cbc();
- EVP_MD* md = EVP_md5();
-
- unsigned int nkey = EVP_CIPHER_key_length(cipher);
- unsigned int niv = EVP_CIPHER_iv_length(cipher);
- unsigned char key[nkey];
- unsigned char iv[niv];
-
- memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv);
- rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/);
- if (rc != nkey) {
- /* Error */
- }
-
- /* On success, use key and iv to initialize the cipher */
-
-=head1 BUGS
-
-The PEM read routines in some versions of OpenSSL will not correctly reuse
-an existing structure. Therefore the following:
-
- PEM_read_bio_X509(bp, &x, 0, NULL);
-
-where B<x> already contains a valid certificate, may not work, whereas:
-
- X509_free(x);
- x = PEM_read_bio_X509(bp, NULL, 0, NULL);
-
-is guaranteed to work.
-
-=head1 RETURN CODES
-
-The read routines return either a pointer to the structure read or NULL
-if an error occurred.
-
-The write routines return 1 for success or 0 for failure.
-
-=head1 HISTORY
-
-The old Netscape certificate sequences were no longer documented
-in OpenSSL 1.1; applications should use the PKCS7 standard instead
-as they will be formally deprecated in a future releases.
-
-=head1 SEE ALSO
-
-L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format.
-
-It is otherwise identical to the function SMIME_write_CMS().
-
-=head1 NOTES
-
-This function is effectively a version of the PEM_write_bio_CMS() supporting
-streaming.
-
-=head1 RETURN VALUES
-
-PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>,
-L<CMS_verify(3)>, L<CMS_encrypt(3)>
-L<CMS_decrypt(3)>,
-L<PEM_write(3)>,
-L<SMIME_write_CMS(3)>,
-L<i2d_CMS_bio_stream(3)>
-
-=head1 HISTORY
-
-PEM_write_bio_CMS_stream() was added to OpenSSL 1.0.0
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format.
-
-It is otherwise identical to the function SMIME_write_PKCS7().
-
-=head1 NOTES
-
-This function is effectively a version of the PEM_write_bio_PKCS7() supporting
-streaming.
-
-=head1 RETURN VALUES
-
-PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
-L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
-L<PKCS7_decrypt(3)>,
-L<SMIME_write_PKCS7(3)>,
-L<i2d_PKCS7_bio_stream(3)>
-
-=head1 HISTORY
-
-PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0
-
-=head1 COPYRIGHT
-
-Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS12_create - create a PKCS#12 structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs12.h>
-
- PKCS12 *PKCS12_create(const char *pass, const char *name, EVP_PKEY *pkey,
- X509 *cert, STACK_OF(X509) *ca,
- int nid_key, int nid_cert, int iter, int mac_iter, int keytype);
-
-=head1 DESCRIPTION
-
-PKCS12_create() creates a PKCS#12 structure.
-
-B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for
-the supplied certificate and key. B<pkey> is the private key to include in
-the structure and B<cert> its corresponding certificates. B<ca>, if not B<NULL>
-is an optional set of certificates to also include in the structure.
-
-B<nid_key> and B<nid_cert> are the encryption algorithms that should be used
-for the key and certificate respectively. B<iter> is the encryption algorithm
-iteration count to use and B<mac_iter> is the MAC iteration count to use.
-B<keytype> is the type of key.
-
-=head1 NOTES
-
-The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype>
-can all be set to zero and sensible defaults will be used.
-
-These defaults are: 40 bit RC2 encryption for certificates, triple DES
-encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER
-(currently 2048) and a MAC iteration count of 1.
-
-The default MAC iteration count is 1 in order to retain compatibility with
-old software which did not interpret MAC iteration counts. If such compatibility
-is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER.
-
-B<keytype> adds a flag to the store private key. This is a non standard extension
-that is only currently interpreted by MSIE. If set to zero the flag is omitted,
-if set to B<KEY_SIG> the key can be used for signing only, if set to B<KEY_EX>
-it can be used for signing and encryption. This option was useful for old
-export grade software which could use signing only keys of arbitrary size but
-had restrictions on the permissible sizes of keys which could be used for
-encryption.
-
-If a certificate contains an B<alias> or B<keyid> then this will be
-used for the corresponding B<friendlyName> or B<localKeyID> in the
-PKCS12 structure.
-
-Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or
-certificate is required. In previous versions both had to be present or
-a fatal error is returned.
-
-B<nid_key> or B<nid_cert> can be set to -1 indicating that no encryption
-should be used.
-
-B<mac_iter> can be set to -1 and the MAC will then be omitted entirely.
-
-=head1 SEE ALSO
-
-L<d2i_PKCS12(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS12_newpass - change the password of a PKCS12 structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs12.h>
-
- int PKCS12_newpass(PKCS12 *p12, const char *oldpass, const char *newpass);
-
-=head1 DESCRIPTION
-
-PKCS12_newpass() changes the password of a PKCS12 structure.
-
-B<p12> is a pointer to a PKCS12 structure. B<oldpass> is the existing password
-and B<newpass> is the new password.
-
-=head1 RETURN VALUES
-
-PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
-retrieve the most recent error from PKCS12_newpass() with ERR_get_error().
-
-=head1 EXAMPLE
-
-This example loads a PKCS#12 file, changes its password and writes out
-the result to a new file.
-
- #include <stdio.h>
- #include <stdlib.h>
- #include <openssl/pem.h>
- #include <openssl/err.h>
- #include <openssl/pkcs12.h>
-
- int main(int argc, char **argv)
- {
- FILE *fp;
- PKCS12 *p12;
- if (argc != 5) {
- fprintf(stderr, "Usage: pkread p12file password newpass opfile\n");
- return 1;
- }
- if ((fp = fopen(argv[1], "rb")) == NULL) {
- fprintf(stderr, "Error opening file %s\n", argv[1]);
- return 1;
- }
- p12 = d2i_PKCS12_fp(fp, NULL);
- fclose(fp);
- if (p12 == NULL) {
- fprintf(stderr, "Error reading PKCS#12 file\n");
- ERR_print_errors_fp(stderr);
- return 1;
- }
- if (PKCS12_newpass(p12, argv[2], argv[3]) == 0) {
- fprintf(stderr, "Error changing password\n");
- ERR_print_errors_fp(stderr);
- PKCS12_free(p12);
- return 1;
- }
- if ((fp = fopen(argv[4], "wb")) == NULL) {
- fprintf(stderr, "Error opening file %s\n", argv[4]);
- PKCS12_free(p12);
- return 1;
- }
- i2d_PKCS12_fp(fp, p12);
- PKCS12_free(p12);
- fclose(fp);
- return 0;
- }
-
-
-=head1 NOTES
-
-If the PKCS#12 structure does not have a password, then you must use the empty
-string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
-PKCS12_newpass() failure.
-
-If the wrong password is used for B<oldpass> then the function will fail,
-with a MAC verification error. In rare cases the PKCS12 structure does not
-contain a MAC: in this case it will usually fail with a decryption padding
-error.
-
-=head1 BUGS
-
-The password format is a NULL terminated ASCII string which is converted to
-Unicode form internally. As a result some passwords cannot be supplied to
-this function.
-
-=head1 SEE ALSO
-
-L<PKCS12_create(3)>, L<ERR_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS12_parse - parse a PKCS#12 structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs12.h>
-
-int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca);
-
-=head1 DESCRIPTION
-
-PKCS12_parse() parses a PKCS12 structure.
-
-B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use.
-If successful the private key will be written to B<*pkey>, the corresponding
-certificate to B<*cert> and any additional certificates to B<*ca>.
-
-=head1 NOTES
-
-The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in
-which case additional certificates will be discarded. B<*ca> can also be a
-valid STACK in which case additional certificates are appended to B<*ca>. If
-B<*ca> is B<NULL> a new STACK will be allocated.
-
-The B<friendlyName> and B<localKeyID> attributes (if present) on each
-certificate will be stored in the B<alias> and B<keyid> attributes of the
-B<X509> structure.
-
-=head1 RETURN VALUES
-
-PKCS12_parse() returns 1 for success and zero if an error occurred.
-
-The error can be obtained from L<ERR_get_error(3)>
-
-=head1 BUGS
-
-Only a single private key and corresponding certificate is returned by this
-function. More complex PKCS#12 files with multiple private keys will only
-return the first match.
-
-Only B<friendlyName> and B<localKeyID> attributes are currently stored in
-certificates. Other attributes are discarded.
-
-Attributes currently cannot be stored in the private key B<EVP_PKEY> structure.
-
-=head1 SEE ALSO
-
-L<d2i_PKCS12(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- int PKCS5_PBKDF2_HMAC(const char *pass, int passlen,
- const unsigned char *salt, int saltlen, int iter,
- const EVP_MD *digest,
- int keylen, unsigned char *out);
-
-int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen,
- const unsigned char *salt, int saltlen, int iter,
- int keylen, unsigned char *out);
-
-=head1 DESCRIPTION
-
-PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count
-as specified in RFC 2898.
-
-B<pass> is the password used in the derivation of length B<passlen>. B<pass>
-is an optional parameter and can be NULL. If B<passlen> is -1, then the
-function will calculate the length of B<pass> using strlen().
-
-B<salt> is the salt used in the derivation of length B<saltlen>. If the
-B<salt> is NULL, then B<saltlen> must be 0. The function will not
-attempt to calculate the length of the B<salt> because it is not assumed to
-be NULL terminated.
-
-B<iter> is the iteration count and its value should be greater than or
-equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
-B<iter> less than 1 is treated as a single iteration.
-
-B<digest> is the message digest function used in the derivation. Values include
-any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls
-PKCS5_PBKDF2_HMAC() with EVP_sha1().
-
-The derived key will be written to B<out>. The size of the B<out> buffer
-is specified via B<keylen>.
-
-=head1 NOTES
-
-A typical application of this function is to derive keying material for an
-encryption algorithm from a password in the B<pass>, a salt in B<salt>,
-and an iteration count.
-
-Increasing the B<iter> parameter slows down the algorithm which makes it
-harder for an attacker to perform a brute force attack using a large number
-of candidate passwords.
-
-=head1 RETURN VALUES
-
-PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error.
-
-=head1 SEE ALSO
-
-L<evp(3)>, L<rand(3)>,
-L<EVP_BytesToKey(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData
-structure. B<pkey> is the private key of the recipient, B<cert> is the
-recipients certificate, B<data> is a BIO to write the content to and
-B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-Although the recipients certificate is not needed to decrypt the data it is needed
-to locate the appropriate (of possible several) recipients in the PKCS#7 structure.
-
-The following flags can be passed in the B<flags> parameter.
-
-If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
-from the content. If the content is not of type B<text/plain> then an error is
-returned.
-
-=head1 RETURN VALUES
-
-PKCS7_decrypt() returns either 1 for success or 0 for failure.
-The error can be obtained from ERR_get_error(3)
-
-=head1 BUGS
-
-PKCS7_decrypt() must be passed the correct recipient key and certificate. It would
-be better if it could look up the correct key and certificate from a database.
-
-The lack of single pass processing and need to hold all data in memory as
-mentioned in PKCS7_sign() also applies to PKCS7_verify().
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_encrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS7_encrypt - create a PKCS#7 envelopedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);
-
-=head1 DESCRIPTION
-
-PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs>
-is a list of recipient certificates. B<in> is the content to be encrypted.
-B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
-certificates supplied to this function must all contain RSA public keys, though
-they do not have to be signed using the RSA algorithm.
-
-EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
-because most clients will support it.
-
-Some old "export grade" clients may only support weak encryption using 40 or 64
-bit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc()
-respectively.
-
-The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
-its parameters.
-
-Many browsers implement a "sign and encrypt" option which is simply an S/MIME
-envelopedData containing an S/MIME signed message. This can be readily produced
-by storing the S/MIME signed message in a memory BIO and passing it to
-PKCS7_encrypt().
-
-The following flags can be passed in the B<flags> parameter.
-
-If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are
-prepended to the data.
-
-Normally the supplied content is translated into MIME canonical format (as
-required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation
-occurs. This option should be used if the supplied data is in binary format
-otherwise the translation will corrupt it. If B<PKCS7_BINARY> is set then
-B<PKCS7_TEXT> is ignored.
-
-If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output
-suitable for streaming I/O: no data is read from the BIO B<in>.
-
-=head1 NOTES
-
-If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
-complete and outputting its contents via a function that does not
-properly finalize the B<PKCS7> structure will give unpredictable
-results.
-
-Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
-PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
-can be performed by obtaining the streaming ASN1 B<BIO> directly using
-BIO_new_PKCS7().
-
-=head1 RETURN VALUES
-
-PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred.
-The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_decrypt(3)>
-
-=head1 HISTORY
-
-The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0.
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS7_sign - create a PKCS#7 signedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is
-the certificate to sign with, B<pkey> is the corresponding private key.
-B<certs> is an optional additional set of certificates to include in the PKCS#7
-structure (for example any intermediate CAs in the chain).
-
-The data to be signed is read from BIO B<data>.
-
-B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-Any of the following flags (ored together) can be passed in the B<flags>
-parameter.
-
-Many S/MIME clients expect the signed content to include valid MIME headers. If
-the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
-to the data.
-
-If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
-PKCS7 structure, the signer's certificate must still be supplied in the
-B<signcert> parameter though. This can reduce the size of the signature if the
-signers certificate can be obtained by other means: for example a previously
-signed message.
-
-The data being signed is included in the PKCS7 structure, unless
-B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7
-detached signatures which are used in S/MIME plaintext signed messages for
-example.
-
-Normally the supplied content is translated into MIME canonical format (as
-required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation
-occurs. This option should be used if the supplied data is in binary format
-otherwise the translation will corrupt it.
-
-The signedData structure includes several PKCS#7 autenticatedAttributes
-including the signing time, the PKCS#7 content type and the supported list of
-ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
-authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
-the SMIMECapabilities are omitted.
-
-If present the SMIMECapabilities attribute indicates support for the following
-algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
-these algorithms is disabled then it will not be included.
-
-If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is
-just initialized ready to perform the signing operation. The signing is however
-B<not> performed and the data to be signed is not read from the B<data>
-parameter. Signing is deferred until after the data has been written. In this
-way data can be signed in a single pass.
-
-If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
-which additional signers and capabilities can be added before finalization.
-
-
-=head1 NOTES
-
-If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
-complete and outputting its contents via a function that does not properly
-finalize the B<PKCS7> structure will give unpredictable results.
-
-Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
-PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
-can be performed by obtaining the streaming ASN1 B<BIO> directly using
-BIO_new_PKCS7().
-
-If a signer is specified it will use the default digest for the signing
-algorithm. This is B<SHA1> for both RSA and DSA keys.
-
-The B<certs>, B<signcert> and B<pkey> parameters can all be
-B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added
-using the function PKCS7_sign_add_signer(). PKCS7_final() must also be
-called to finalize the structure if streaming is not enabled. Alternative
-signing digests can also be specified using this method.
-
-If B<signcert> and B<pkey> are NULL then a certificates only
-PKCS#7 structure is output.
-
-In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must
-B<NOT> be NULL.
-
-=head1 BUGS
-
-Some advanced attributes such as counter signatures are not supported.
-
-=head1 RETURN VALUES
-
-PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error
-occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_verify(3)>
-
-=head1 HISTORY
-
-The B<PKCS7_PARTIAL> flag, and the ability for B<certs>, B<signcert>,
-and B<pkey> parameters to be B<NULL> to be was added in OpenSSL 1.0.0
-
-The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS7_sign_add_signer - add a signer PKCS7 signed data structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags);
-
-
-=head1 DESCRIPTION
-
-PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private
-key B<pkey> using message digest B<md> to a PKCS7 signed data structure
-B<p7>.
-
-The PKCS7 structure should be obtained from an initial call to PKCS7_sign()
-with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7
-signed data structure.
-
-If the B<md> parameter is B<NULL> then the default digest for the public
-key algorithm will be used.
-
-Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure
-is not complete and must be finalized either by streaming (if applicable) or
-a call to PKCS7_final().
-
-
-=head1 NOTES
-
-The main purpose of this function is to provide finer control over a PKCS#7
-signed data structure where the simpler PKCS7_sign() function defaults are
-not appropriate. For example if multiple signers or non default digest
-algorithms are needed.
-
-Any of the following flags (ored together) can be passed in the B<flags>
-parameter.
-
-If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content
-digest value from the PKCS7 structure: to add a signer to an existing structure.
-An error occurs if a matching digest value cannot be found to copy. The
-returned PKCS7 structure will be valid and finalized when this flag is set.
-
-If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the
-B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes
-can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is
-needed to finalize it.
-
-If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
-PKCS7 structure, the signer's certificate must still be supplied in the
-B<signcert> parameter though. This can reduce the size of the signature if the
-signers certificate can be obtained by other means: for example a previously
-signed message.
-
-The signedData structure includes several PKCS#7 autenticatedAttributes
-including the signing time, the PKCS#7 content type and the supported list of
-ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
-authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
-the SMIMECapabilities are omitted.
-
-If present the SMIMECapabilities attribute indicates support for the following
-algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
-these algorithms is disabled then it will not be included.
-
-
-PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
-structure just added, this can be used to set additional attributes
-before it is finalized.
-
-=head1 RETURN VALUES
-
-PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
-structure just added or NULL if an error occurs.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
-L<PKCS7_final(3)>,
-
-=head1 HISTORY
-
-PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0
-
-=head1 COPYRIGHT
-
-Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags);
-
- STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
-
-=head1 DESCRIPTION
-
-PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7
-structure to verify. B<certs> is a set of certificates in which to search for
-the signer's certificate. B<store> is a trusted certificate store (used for
-chain verification). B<indata> is the signed data if the content is not
-present in B<p7> (that is it is detached). The content is written to B<out>
-if it is not NULL.
-
-B<flags> is an optional set of flags, which can be used to modify the verify
-operation.
-
-PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does
-B<not> check their validity or whether any signatures are valid. The B<certs>
-and B<flags> parameters have the same meanings as in PKCS7_verify().
-
-=head1 VERIFY PROCESS
-
-Normally the verify process proceeds as follows.
-
-Initially some sanity checks are performed on B<p7>. The type of B<p7> must
-be signedData. There must be at least one signature on the data and if
-the content is detached B<indata> cannot be B<NULL>. If the content is
-not detached and B<indata> is not B<NULL>, then the structure has both
-embedded and external content. To treat this as an error, use the flag
-B<PKCS7_NO_DUAL_CONTENT>.
-The default behavior allows this, for compatibility with older
-versions of OpenSSL.
-
-An attempt is made to locate all the signer's certificates, first looking in
-the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates
-contained in the B<p7> structure itself. If any signer's certificates cannot be
-located the operation fails.
-
-Each signer's certificate is chain verified using the B<smimesign> purpose and
-the supplied trusted certificate store. Any internal certificates in the message
-are used as untrusted CAs. If any chain verify fails an error code is returned.
-
-Finally the signed content is read (and written to B<out> is it is not NULL) and
-the signature's checked.
-
-If all signature's verify correctly then the function is successful.
-
-Any of the following flags (ored together) can be passed in the B<flags> parameter
-to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is
-meaningful to PKCS7_get0_signers().
-
-If B<PKCS7_NOINTERN> is set the certificates in the message itself are not
-searched when locating the signer's certificate. This means that all the signers
-certificates must be in the B<certs> parameter.
-
-If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
-from the content. If the content is not of type B<text/plain> then an error is
-returned.
-
-If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified.
-
-If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are
-not used as untrusted CAs. This means that the whole verify chain (apart from
-the signer's certificate) must be contained in the trusted store.
-
-If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked.
-
-=head1 NOTES
-
-One application of B<PKCS7_NOINTERN> is to only accept messages signed by
-a small number of certificates. The acceptable certificates would be passed
-in the B<certs> parameter. In this case if the signer is not one of the
-certificates supplied in B<certs> then the verify will fail because the
-signer cannot be found.
-
-Care should be taken when modifying the default verify behaviour, for example
-setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification
-and any signed message will be considered valid. This combination is however
-useful if one merely wishes to write the content to B<out> and its validity
-is not considered important.
-
-Chain verification should arguably be performed using the signing time rather
-than the current time. However since the signing time is supplied by the
-signer it cannot be trusted without additional evidence (such as a trusted
-timestamp).
-
-=head1 RETURN VALUES
-
-PKCS7_verify() returns one for a successful verification and zero
-if an error occurs.
-
-PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred.
-
-The error can be obtained from L<ERR_get_error(3)>
-
-=head1 BUGS
-
-The trusted certificate store is not searched for the signers certificate,
-this is primarily due to the inadequacies of the current B<X509_STORE>
-functionality.
-
-The lack of single pass processing and need to hold all data in memory as
-mentioned in PKCS7_sign() also applies to PKCS7_verify().
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_sign(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add
-entropy to the PRNG
-
-=head1 SYNOPSIS
-
- #include <openssl/rand.h>
-
- void RAND_seed(const void *buf, int num);
-
- void RAND_add(const void *buf, int num, double entropy);
-
- int RAND_status(void);
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
- void RAND_screen(void);
- #endif
-
-=head1 DESCRIPTION
-
-RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus,
-if the data at B<buf> are unpredictable to an adversary, this
-increases the uncertainty about the state and makes the PRNG output
-less predictable. Suitable input comes from user interaction (random
-key presses, mouse movements) and certain hardware events. The
-B<entropy> argument is (the lower bound of) an estimate of how much
-randomness is contained in B<buf>, measured in bytes. Details about
-sources of randomness and how to estimate their entropy can be found
-in the literature, e.g. RFC 1750.
-
-RAND_add() may be called with sensitive data such as user entered
-passwords. The seed values cannot be recovered from the PRNG output.
-
-OpenSSL makes sure that the PRNG state is unique for each thread. On
-systems that provide C</dev/urandom>, the randomness device is used
-to seed the PRNG transparently. However, on all other systems, the
-application is responsible for seeding the PRNG by calling RAND_add(),
-L<RAND_egd(3)>
-or L<RAND_load_file(3)>.
-
-RAND_seed() is equivalent to RAND_add() when B<num == entropy>.
-
-RAND_event() and RAND_screen() are deprecated and should not be called.
-
-=head1 RETURN VALUES
-
-RAND_status() returns 1 if the PRNG has been seeded
-with enough data, 0 otherwise.
-
-RAND_event() calls RAND_poll() and returns RAND_status().
-
-RAND_screen calls RAND_poll().
-
-The other functions do not return values.
-
-=head1 HISTORY
-
-RAND_event() and RAND_screen() are deprecated since OpenSSL
-1.1.0. Use the functions described above instead.
-
-=head1 SEE ALSO
-
-L<rand(3)>, L<RAND_egd(3)>,
-L<RAND_load_file(3)>, L<RAND_cleanup(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RAND_bytes, RAND_pseudo_bytes - generate random data
-
-=head1 SYNOPSIS
-
- #include <openssl/rand.h>
-
- int RAND_bytes(unsigned char *buf, int num);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- int RAND_pseudo_bytes(unsigned char *buf, int num);
- #endif
-
-=head1 DESCRIPTION
-
-RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
-into B<buf>. An error occurs if the PRNG has not been seeded with
-enough randomness to ensure an unpredictable byte sequence.
-
-RAND_pseudo_bytes() has been deprecated. Users should use RAND_bytes() instead.
-RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>.
-Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be
-unique if they are of sufficient length, but are not necessarily
-unpredictable. They can be used for non-cryptographic purposes and for
-certain purposes in cryptographic protocols, but usually not for key
-generation etc.
-
-The contents of B<buf> is mixed into the entropy pool before retrieving
-the new pseudo-random bytes unless disabled at compile time (see FAQ).
-
-=head1 RETURN VALUES
-
-RAND_bytes() returns 1 on success, 0 otherwise. The error code can be
-obtained by L<ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the
-bytes generated are cryptographically strong, 0 otherwise. Both
-functions return -1 if they are not supported by the current RAND
-method.
-
-=head1 SEE ALSO
-
-L<rand(3)>, L<ERR_get_error(3)>,
-L<RAND_add(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RAND_cleanup - erase the PRNG state
-
-=head1 SYNOPSIS
-
- #include <openssl/rand.h>
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void RAND_cleanup(void)
- #endif
-
-=head1 DESCRIPTION
-
-Prior to OpenSSL 1.1.0 RAND_cleanup() erases the memory used by the PRNG. This
-function is deprecated and as of version 1.1.0 does nothing. No explicit
-initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>.
-
-=head1 RETURN VALUE
-
-RAND_cleanup() returns no value.
-
-=head1 SEE ALSO
-
-L<rand(3)>
-
-=head1 HISTORY
-
-RAND_cleanup() was deprecated in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
-
-=head1 SYNOPSIS
-
- #include <openssl/rand.h>
-
- int RAND_egd(const char *path);
- int RAND_egd_bytes(const char *path, int bytes);
-
- int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);
-
-=head1 DESCRIPTION
-
-RAND_egd() queries the entropy gathering daemon EGD on socket B<path>.
-It queries 255 bytes and uses L<RAND_add(3)> to seed the
-OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for
-RAND_egd_bytes(path, 255);
-
-RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>.
-It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the
-OpenSSL built-in PRNG.
-This function is more flexible than RAND_egd().
-When only one secret key must
-be generated, it is not necessary to request the full amount 255 bytes from
-the EGD socket. This can be advantageous, since the amount of entropy
-that can be retrieved from EGD over time is limited.
-
-RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket
-B<path>. If B<buf> is given, B<bytes> bytes are queried and written into
-B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the
-OpenSSL built-in PRNG using L<RAND_add(3)>.
-
-=head1 NOTES
-
-On systems without /dev/*random devices providing entropy from the kernel,
-the EGD entropy gathering daemon can be used to collect entropy. It provides
-a socket interface through which entropy can be gathered in chunks up to
-255 bytes. Several chunks can be queried during one connection.
-
-EGD is available from http://www.lothar.com/tech/crypto/ (C<perl
-Makefile.PL; make; make install> to install). It is run as B<egd>
-I<path>, where I<path> is an absolute path designating a socket. When
-RAND_egd() is called with that path as an argument, it tries to read
-random bytes that EGD has collected. RAND_egd() retrieves entropy from the
-daemon using the daemon's "non-blocking read" command which shall
-be answered immediately by the daemon without waiting for additional
-entropy to be collected. The write and read socket operations in the
-communication are blocking.
-
-Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is
-available from
-http://prngd.sourceforge.net/ .
-PRNGD does employ an internal PRNG itself and can therefore never run
-out of entropy.
-
-OpenSSL automatically queries EGD when entropy is requested via RAND_bytes()
-or the status is checked via RAND_status() for the first time, if the socket
-is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.
-
-=head1 RETURN VALUE
-
-RAND_egd() and RAND_egd_bytes() return the number of bytes read from the
-daemon on success, and -1 if the connection failed or the daemon did not
-return enough data to fully seed the PRNG.
-
-RAND_query_egd_bytes() returns the number of bytes read from the daemon on
-success, and -1 if the connection failed. The PRNG state is not considered.
-
-=head1 SEE ALSO
-
-L<rand(3)>, L<RAND_add(3)>,
-L<RAND_cleanup(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file
-
-=head1 SYNOPSIS
-
- #include <openssl/rand.h>
-
- const char *RAND_file_name(char *buf, size_t num);
-
- int RAND_load_file(const char *filename, long max_bytes);
-
- int RAND_write_file(const char *filename);
-
-=head1 DESCRIPTION
-
-RAND_file_name() generates a default path for the random seed
-file. B<buf> points to a buffer of size B<num> in which to store the
-filename.
-
-On all systems, if the environment variable B<RANDFILE> is set, its
-value will be used as the seed file name.
-
-Otherwise, the file is called ".rnd", found in platform dependent locations:
-
-=over 4
-
-=item On Windows (in order of preference)
-
-%HOME%, %USERPROFILE%, %SYSTEMROOT%, C:\
-
-=item On VMS
-
-SYS$LOGIN:
-
-=item On all other systems
-
-$HOME
-
-=back
-
-If C<$HOME> (on non-Windows and non-VMS system) is not set either, or
-B<num> is too small for the path name, an error occurs.
-
-RAND_load_file() reads a number of bytes from file B<filename> and
-adds them to the PRNG. If B<max_bytes> is non-negative,
-up to B<max_bytes> are read;
-if B<max_bytes> is -1, the complete file is read.
-
-RAND_write_file() writes a number of random bytes (currently 1024) to
-file B<filename> which can be used to initialize the PRNG by calling
-RAND_load_file() in a later session.
-
-=head1 RETURN VALUES
-
-RAND_load_file() returns the number of bytes read.
-
-RAND_write_file() returns the number of bytes written, and -1 if the
-bytes written were generated without appropriate seed.
-
-RAND_file_name() returns a pointer to B<buf> on success, and NULL on
-error.
-
-=head1 SEE ALSO
-
-L<rand(3)>, L<RAND_add(3)>, L<RAND_cleanup(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method
-
-=head1 SYNOPSIS
-
- #include <openssl/rand.h>
-
- void RAND_set_rand_method(const RAND_METHOD *meth);
-
- const RAND_METHOD *RAND_get_rand_method(void);
-
- RAND_METHOD *RAND_OpenSSL(void);
-
-=head1 DESCRIPTION
-
-A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number
-generation. By modifying the method, alternative implementations such as
-hardware RNGs may be used. IMPORTANT: See the NOTES section for important
-information about how these RAND API functions are affected by the use of
-B<ENGINE> API calls.
-
-Initially, the default RAND_METHOD is the OpenSSL internal implementation, as
-returned by RAND_OpenSSL().
-
-RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is
-true only whilst no ENGINE has been set as a default for RAND, so this function
-is no longer recommended.
-
-RAND_get_default_method() returns a pointer to the current RAND_METHOD.
-However, the meaningfulness of this result is dependent on whether the ENGINE
-API is being used, so this function is no longer recommended.
-
-=head1 THE RAND_METHOD STRUCTURE
-
- typedef struct rand_meth_st
- {
- void (*seed)(const void *buf, int num);
- int (*bytes)(unsigned char *buf, int num);
- void (*cleanup)(void);
- void (*add)(const void *buf, int num, int entropy);
- int (*pseudorand)(unsigned char *buf, int num);
- int (*status)(void);
- } RAND_METHOD;
-
-The components point to method implementations used by (or called by), in order,
-RAND_seed(), RAND_bytes(), internal RAND cleanup, RAND_add(), RAND_pseudo_rand()
-and RAND_status().
-Each component may be NULL if the function is not implemented.
-
-=head1 RETURN VALUES
-
-RAND_set_rand_method() returns no value. RAND_get_rand_method() and
-RAND_OpenSSL() return pointers to the respective methods.
-
-=head1 NOTES
-
-RAND_METHOD implementations are grouped together with other
-algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
-default ENGINE is specified for RAND functionality using an ENGINE API function,
-that will override any RAND defaults set using the RAND API (ie.
-RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way
-to control default implementations for use in RAND and other cryptographic
-algorithms.
-
-=head1 SEE ALSO
-
-L<rand(3)>, L<engine(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RC4_set_key, RC4 - RC4 encryption
-
-=head1 SYNOPSIS
-
- #include <openssl/rc4.h>
-
- void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data);
-
- void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata,
- unsigned char *outdata);
-
-=head1 DESCRIPTION
-
-This library implements the Alleged RC4 cipher, which is described for
-example in I<Applied Cryptography>. It is believed to be compatible
-with RC4[TM], a proprietary cipher of RSA Security Inc.
-
-RC4 is a stream cipher with variable key length. Typically, 128 bit
-(16 byte) keys are used for strong encryption, but shorter insecure
-key sizes have been widely used due to export restrictions.
-
-RC4 consists of a key setup phase and the actual encryption or
-decryption phase.
-
-RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long
-key at B<data>.
-
-RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using
-B<key> and places the result at B<outdata>. Repeated RC4() calls with
-the same B<key> yield a continuous key stream.
-
-Since RC4 is a stream cipher (the input is XORed with a pseudo-random
-key stream to produce the output), decryption uses the same function
-calls as encryption.
-
-=head1 RETURN VALUES
-
-RC4_set_key() and RC4() do not return values.
-
-=head1 NOTE
-
-Applications should use the higher level functions
-L<EVP_EncryptInit(3)> etc. instead of calling these
-functions directly.
-
-It is difficult to securely use stream ciphers. For example, do not perform
-multiple encryptions using the same key stream.
-
-=head1 SEE ALSO
-
-L<EVP_EncryptInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final -
-RIPEMD-160 hash function
-
-=head1 SYNOPSIS
-
- #include <openssl/ripemd.h>
-
- unsigned char *RIPEMD160(const unsigned char *d, unsigned long n,
- unsigned char *md);
-
- int RIPEMD160_Init(RIPEMD160_CTX *c);
- int RIPEMD160_Update(RIPEMD_CTX *c, const void *data,
- unsigned long len);
- int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c);
-
-=head1 DESCRIPTION
-
-RIPEMD-160 is a cryptographic hash function with a
-160 bit output.
-
-RIPEMD160() computes the RIPEMD-160 message digest of the B<n>
-bytes at B<d> and places it in B<md> (which must have space for
-RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
-is placed in a static array.
-
-The following functions may be used if the message is not completely
-stored in memory:
-
-RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure.
-
-RIPEMD160_Update() can be called repeatedly with chunks of the message to
-be hashed (B<len> bytes at B<data>).
-
-RIPEMD160_Final() places the message digest in B<md>, which must have
-space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases
-the B<RIPEMD160_CTX>.
-
-=head1 RETURN VALUES
-
-RIPEMD160() returns a pointer to the hash value.
-
-RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for
-success, 0 otherwise.
-
-=head1 NOTE
-
-Applications should use the higher level functions
-L<EVP_DigestInit(3)> etc. instead of calling these
-functions directly.
-
-=head1 CONFORMING TO
-
-ISO/IEC 10118-3 (draft) (??)
-
-=head1 SEE ALSO
-
-L<EVP_DigestInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
-
- void RSA_blinding_off(RSA *rsa);
-
-=head1 DESCRIPTION
-
-RSA is vulnerable to timing attacks. In a setup where attackers can
-measure the time of RSA decryption or signature operations, blinding
-must be used to protect the RSA operation from that attack.
-
-RSA_blinding_on() turns blinding on for key B<rsa> and generates a
-random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
-initialized B<BN_CTX>. The random number generator must be seeded
-prior to calling RSA_blinding_on().
-
-RSA_blinding_off() turns blinding off and frees the memory used for
-the blinding factor.
-
-=head1 RETURN VALUES
-
-RSA_blinding_on() returns 1 on success, and 0 if an error occurred.
-
-RSA_blinding_off() returns no value.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_check_key_ex, RSA_check_key - validate private RSA keys
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_check_key_ex(RSA *rsa, BN_GENCB *cb);
-
- int RSA_check_key(RSA *rsa);
-
-=head1 DESCRIPTION
-
-RSA_check_key_ex() function validates RSA keys.
-It checks that B<p> and B<q> are
-in fact prime, and that B<n = p*q>.
-
-It does not work on RSA public keys that have only the modulus
-and public exponent elements populated.
-It also checks that B<d*e = 1 mod (p-1*q-1)>,
-and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>.
-It performs integrity checks on all
-the RSA key material, so the RSA key structure must contain all the private
-key data too.
-Therefore, it cannot be used with any arbitrary RSA key object,
-even if it is otherwise fit for regular RSA operation.
-
-The B<cb> parameter is a callback that will be invoked in the same
-manner as L<BN_is_prime_ex(3)>.
-
-RSA_check_key() is equivalent to RSA_check_key_ex() with a NULL B<cb>.
-
-=head1 RETURN VALUE
-
-RSA_check_key_ex() and RSA_check_key()
-return 1 if B<rsa> is a valid RSA key, and 0 otherwise.
-They return -1 if an error occurs while checking the key.
-
-If the key is invalid or an error occurred, the reason code can be
-obtained using L<ERR_get_error(3)>.
-
-=head1 NOTES
-
-Unlike most other RSA functions, this function does B<not> work
-transparently with any underlying ENGINE implementation because it uses the
-key data in the RSA structure directly. An ENGINE implementation can
-override the way key data is stored and handled, and can even provide
-support for HSM keys - in which case the RSA structure may contain B<no>
-key data at all! If the ENGINE in question is only being used for
-acceleration or analysis purposes, then in all likelihood the RSA key data
-is complete and untouched, but this can't be assumed in the general case.
-
-=head1 BUGS
-
-A method of verifying the RSA key using opaque RSA API functions might need
-to be considered. Right now RSA_check_key() simply uses the RSA structure
-elements directly, bypassing the RSA_METHOD table altogether (and
-completely violating encapsulation and object-orientation in the process).
-The best fix will probably be to introduce a "check_key()" handler to the
-RSA_METHOD function table so that alternative implementations can also
-provide their own verifiers.
-
-=head1 SEE ALSO
-
-L<BN_is_prime_ex(3)>,
-L<ERR_get_error(3)>
-
-=head1 HISTORY
-
-RSA_check_key_ex() appeared after OpenSSL 1.0.2.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_generate_key_ex, RSA_generate_key - generate RSA key pair
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x00908000L
- RSA *RSA_generate_key(int num, unsigned long e,
- void (*callback)(int, int, void *), void *cb_arg);
- #endif
-
-=head1 DESCRIPTION
-
-RSA_generate_key_ex() generates a key pair and stores it in the B<RSA>
-structure provided in B<rsa>. The pseudo-random number generator must
-be seeded prior to calling RSA_generate_key_ex().
-
-The modulus size will be of length B<bits>, and the public exponent will be
-B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
-The exponent is an odd number, typically 3, 17 or 65537.
-
-A callback function may be used to provide feedback about the
-progress of the key generation. If B<cb> is not B<NULL>, it
-will be called as follows using the BN_GENCB_call() function
-described on the L<BN_generate_prime(3)> page.
-
-=over 4
-
-=item *
-
-While a random prime number is generated, it is called as
-described in L<BN_generate_prime(3)>.
-
-=item *
-
-When the n-th randomly generated prime is rejected as not
-suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
-
-=item *
-
-When a random p has been found with p-1 relatively prime to B<e>,
-it is called as B<BN_GENCB_call(cb, 3, 0)>.
-
-=back
-
-The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
-
-RSA_generate_key is deprecated (new applications should use
-RSA_generate_key_ex instead). RSA_generate_key works in the same was as
-RSA_generate_key_ex except it uses "old style" call backs. See
-L<BN_generate_prime(3)> for further details.
-
-=head1 RETURN VALUE
-
-If key generation fails, RSA_generate_key() returns B<NULL>.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 BUGS
-
-B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
-
-RSA_generate_key() goes into an infinite loop for illegal input values.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<rand(3)>,
-L<RSA_generate_key(3)>, L<BN_generate_prime(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key,
-RSA_get0_factors, RSA_get0_crt_params, RSA_clear_flags,
-RSA_test_flags, RSA_set_flags, RSA_get0_engine - Routines for getting
-and setting data in an RSA object
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_set0_key(RSA *r, BIGNUM *n, BIGNUM *e, BIGNUM *d);
- int RSA_set0_factors(RSA *r, BIGNUM *p, BIGNUM *q);
- int RSA_set0_crt_params(RSA *r, BIGNUM *dmp1, BIGNUM *dmq1, BIGNUM *iqmp);
- void RSA_get0_key(const RSA *r,
- const BIGNUM **n, const BIGNUM **e, const BIGNUM **d);
- void RSA_get0_factors(const RSA *r, const BIGNUM **p, const BIGNUM **q);
- void RSA_get0_crt_params(const RSA *r,
- const BIGNUM **dmp1, const BIGNUM **dmq1,
- const BIGNUM **iqmp);
- void RSA_clear_flags(RSA *r, int flags);
- int RSA_test_flags(const RSA *r, int flags);
- void RSA_set_flags(RSA *r, int flags);
- ENGINE *RSA_get0_engine(RSA *r);
-
-=head1 DESCRIPTION
-
-An RSA object contains the components for the public and private key,
-B<n>, B<e>, B<d>, B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp>. B<n> is
-the modulus common to both public and private key, B<e> is the public
-exponent and B<d> is the private exponent. B<p>, B<q>, B<dmp1>,
-B<dmq1> and B<iqmp> are the factors for the second representation of a
-private key (see PKCS#1 section 3 Key Types), where B<p> and B<q> are
-the first and second factor of B<n> and B<dmp1>, B<dmq1> and B<iqmp>
-are the exponents and coefficient for CRT calculations.
-
-The B<n>, B<e> and B<d> parameters can be obtained by calling
-RSA_get0_key(). If they have not been set yet, then B<*n>, B<*e> and
-B<*d> will be set to NULL. Otherwise, they are set to pointers to
-their respective values. These point directly to the internal
-representations of the values and therefore should not be freed
-by the caller.
-
-The B<n>, B<e> and B<d> parameter values can be set by calling
-RSA_set0_key() and passing the new values for B<n>, B<e> and B<d> as
-parameters to the function. The values B<n> and B<e> must be non-NULL
-the first time this function is called on a given RSA object. The
-value B<d> may be NULL. On subsequent calls any of these values may be
-NULL which means the corresponding RSA field is left untouched.
-Calling this function transfers the memory management of the values to
-the RSA object, and therefore the values that have been passed in
-should not be freed by the caller after this function has been called.
-
-In a similar fashion, the B<p> and B<q> parameters can be obtained and
-set with RSA_get0_factors() and RSA_set0_factors(), and the B<dmp1>,
-B<dmq1> and B<iqmp> parameters can be obtained and set with
-RSA_get0_crt_params() and RSA_set0_crt_params().
-
-RSA_set_flags() sets the flags in the B<flags> parameter on the RSA
-object. Multiple flags can be passed in one go (bitwise ORed together).
-Any flags that are already set are left set. RSA_test_flags() tests to
-see whether the flags passed in the B<flags> parameter are currently
-set in the RSA object. Multiple flags can be tested in one go. All
-flags that are currently set are returned, or zero if none of the
-flags are set. RSA_clear_flags() clears the specified flags within the
-RSA object.
-
-RSA_get0_engine() returns a handle to the ENGINE that has been set for
-this RSA object, or NULL if no such ENGINE has been set.
-
-=head1 NOTES
-
-Values retrieved with RSA_get0_key() are owned by the RSA object used
-in the call and may therefore I<not> be passed to RSA_set0_key(). If
-needed, duplicate the received value using BN_dup() and pass the
-duplicate. The same applies to RSA_get0_factors() and RSA_set0_factors()
-as well as RSA_get0_crt_params() and RSA_set0_crt_params().
-
-=head1 RETURN VALUES
-
-RSA_set0_key(), RSA_set0_factors and RSA_set0_crt_params() return 1 on
-success or 0 on failure.
-
-RSA_test_flags() returns the current state of the flags in the RSA object.
-
-RSA_get0_engine() returns the ENGINE set for the RSA object or NULL if no
-ENGINE has been set.
-
-=head1 SEE ALSO
-
-L<rsa(3)>, L<RSA_new(3)>, L<RSA_size(3)>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_meth_get0_app_data, RSA_meth_set0_app_data,
-RSA_meth_new, RSA_meth_free, RSA_meth_dup, RSA_meth_get0_name,
-RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags,
-RSA_meth_get_pub_enc,
-RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec,
-RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec,
-RSA_meth_set_priv_dec, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp,
-RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_init,
-RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish,
-RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify,
-RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen
-- Routines to build up RSA methods
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- RSA_METHOD *RSA_meth_new(const char *name, int flags);
- void RSA_meth_free(RSA_METHOD *meth);
- RSA_METHOD *RSA_meth_dup(const RSA_METHOD *meth);
- const char *RSA_meth_get0_name(const RSA_METHOD *meth);
- int RSA_meth_set1_name(RSA_METHOD *meth, const char *name);
- int RSA_meth_get_flags(RSA_METHOD *meth);
- int RSA_meth_set_flags(RSA_METHOD *meth, int flags);
- void *RSA_meth_get0_app_data(const RSA_METHOD *meth);
- int RSA_meth_set0_app_data(RSA_METHOD *meth, void *app_data);
- int (*RSA_meth_get_pub_enc(const RSA_METHOD *meth))
- (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
- int RSA_meth_set_pub_enc(RSA_METHOD *rsa,
- int (*pub_enc) (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa,
- int padding));
- int (*RSA_meth_get_pub_dec(const RSA_METHOD *meth))
- (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
- int RSA_meth_set_pub_dec(RSA_METHOD *rsa,
- int (*pub_dec) (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa,
- int padding));
- int (*RSA_meth_get_priv_enc(const RSA_METHOD *meth))
- (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
- int RSA_meth_set_priv_enc(RSA_METHOD *rsa,
- int (*priv_enc) (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa,
- int padding));
- int (*RSA_meth_get_priv_dec(const RSA_METHOD *meth))
- (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
- int RSA_meth_set_priv_dec(RSA_METHOD *rsa,
- int (*priv_dec) (int flen, const unsigned char *from,
- unsigned char *to, RSA *rsa,
- int padding));
- /* Can be null */
- int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))
- (BIGNUM *r0, const BIGNUM *I, RSA *rsa, BN_CTX *ctx);
- int RSA_meth_set_mod_exp(RSA_METHOD *rsa,
- int (*mod_exp) (BIGNUM *r0, const BIGNUM *I, RSA *rsa,
- BN_CTX *ctx));
- /* Can be null */
- int (*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))
- (BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
- const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
- int RSA_meth_set_bn_mod_exp(RSA_METHOD *rsa,
- int (*bn_mod_exp) (BIGNUM *r,
- const BIGNUM *a,
- const BIGNUM *p,
- const BIGNUM *m,
- BN_CTX *ctx,
- BN_MONT_CTX *m_ctx));
- /* called at new */
- int (*RSA_meth_get_init(const RSA_METHOD *meth)) (RSA *rsa);
- int RSA_meth_set_init(RSA_METHOD *rsa, int (*init) (RSA *rsa));
- /* called at free */
- int (*RSA_meth_get_finish(const RSA_METHOD *meth)) (RSA *rsa);
- int RSA_meth_set_finish(RSA_METHOD *rsa, int (*finish) (RSA *rsa));
- int (*RSA_meth_get_sign(const RSA_METHOD *meth))
- (int type,
- const unsigned char *m, unsigned int m_length,
- unsigned char *sigret, unsigned int *siglen,
- const RSA *rsa);
- int RSA_meth_set_sign(RSA_METHOD *rsa,
- int (*sign) (int type, const unsigned char *m,
- unsigned int m_length,
- unsigned char *sigret, unsigned int *siglen,
- const RSA *rsa));
- int (*RSA_meth_get_verify(const RSA_METHOD *meth))
- (int dtype, const unsigned char *m,
- unsigned int m_length, const unsigned char *sigbuf,
- unsigned int siglen, const RSA *rsa);
- int RSA_meth_set_verify(RSA_METHOD *rsa,
- int (*verify) (int dtype, const unsigned char *m,
- unsigned int m_length,
- const unsigned char *sigbuf,
- unsigned int siglen, const RSA *rsa));
- int (*RSA_meth_get_keygen(const RSA_METHOD *meth))
- (RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
- int RSA_meth_set_keygen(RSA_METHOD *rsa,
- int (*keygen) (RSA *rsa, int bits, BIGNUM *e,
- BN_GENCB *cb));
-
-=head1 DESCRIPTION
-
-The B<RSA_METHOD> type is a structure used for the provision of custom
-RSA implementations. It provides a set of of functions used by OpenSSL
-for the implementation of the various RSA capabilities. See the L<rsa>
-page for more information.
-
-RSA_meth_new() creates a new B<RSA_METHOD> structure. It should be
-given a unique B<name> and a set of B<flags>. The B<name> should be a
-NULL terminated string, which will be duplicated and stored in the
-B<RSA_METHOD> object. It is the callers responsibility to free the
-original string. The flags will be used during the construction of a
-new B<RSA> object based on this B<RSA_METHOD>. Any new B<RSA> object
-will have those flags set by default.
-
-RSA_meth_dup() creates a duplicate copy of the B<RSA_METHOD> object
-passed as a parameter. This might be useful for creating a new
-B<RSA_METHOD> based on an existing one, but with some differences.
-
-RSA_meth_free() destroys an B<RSA_METHOD> structure and frees up any
-memory associated with it.
-
-RSA_meth_get0_name() will return a pointer to the name of this
-RSA_METHOD. This is a pointer to the internal name string and so
-should not be freed by the caller. RSA_meth_set1_name() sets the name
-of the RSA_METHOD to B<name>. The string is duplicated and the copy is
-stored in the RSA_METHOD structure, so the caller remains responsible
-for freeing the memory associated with the name.
-
-RSA_meth_get_flags() returns the current value of the flags associated
-with this RSA_METHOD. RSA_meth_set_flags() provides the ability to set
-these flags.
-
-The functions RSA_meth_get0_app_data() and RSA_meth_set0_app_data()
-provide the ability to associate implementation specific data with the
-RSA_METHOD. It is the application's responsibility to free this data
-before the RSA_METHOD is freed via a call to RSA_meth_free().
-
-RSA_meth_get_sign() and RSA_meth_set_sign() get and set the function
-used for creating an RSA signature respectively. This function will be
-called in response to the application calling RSA_sign(). The
-parameters for the function have the same meaning as for RSA_sign().
-
-RSA_meth_get_verify() and RSA_meth_set_verify() get and set the
-function used for verifying an RSA signature respectively. This
-function will be called in response to the application calling
-RSA_verify(). The parameters for the function have the same meaning as
-for RSA_verify().
-
-RSA_meth_get_mod_exp() and RSA_meth_set_mod_exp() get and set the
-function used for CRT computations.
-
-RSA_meth_get_bn_mod_exp() and RSA_meth_set_bn_mod_exp() get and set
-the function used for CRT computations, specifically the following
-value:
-
- r = a ^ p mod m
-
-Both the mod_exp() and bn_mod_exp() functions are called by the
-default OpenSSL method during encryption, decryption, signing and
-verification.
-
-RSA_meth_get_init() and RSA_meth_set_init() get and set the function
-used for creating a new RSA instance respectively. This function will
-be called in response to the application calling RSA_new() (if the
-current default RSA_METHOD is this one) or RSA_new_method(). The
-RSA_new() and RSA_new_method() functions will allocate the memory for
-the new RSA object, and a pointer to this newly allocated structure
-will be passed as a parameter to the function. This function may be
-NULL.
-
-RSA_meth_get_finish() and RSA_meth_set_finish() get and set the
-function used for destroying an instance of an RSA object respectively.
-This function will be called in response to the application calling
-RSA_free(). A pointer to the RSA to be destroyed is passed as a
-parameter. The destroy function should be used for RSA implementation
-specific clean up. The memory for the RSA itself should not be freed
-by this function. This function may be NULL.
-
-RSA_meth_get_keygen() and RSA_meth_set_keygen() get and set the
-function used for generating a new RSA key pair respectively. This
-function will be called in response to the application calling
-RSA_generate_key(). The parameter for the function has the same
-meaning as for RSA_generate_key().
-
-RSA_meth_get_pub_enc(), RSA_meth_set_pub_enc(),
-RSA_meth_get_pub_dec(), RSA_meth_set_pub_dec(),
-RSA_meth_get_priv_enc(), RSA_meth_set_priv_enc(),
-RSA_meth_get_priv_dec(), RSA_meth_set_priv_dec() get and set the
-functions used for public and private key encryption and decryption.
-These functions will be called in response to the application calling
-RSA_public_encrypt(), RSA_private_decrypt(), RSA_private_encrypt() and
-RSA_public_decrypt() and take the same parameters as those.
-
-
-=head1 RETURN VALUES
-
-RSA_meth_new() and RSA_meth_dup() return the newly allocated
-RSA_METHOD object or NULL on failure.
-
-RSA_meth_get0_name() and RSA_meth_get_flags() return the name and
-flags associated with the RSA_METHOD respectively.
-
-All other RSA_meth_get_*() functions return the appropriate function
-pointer that has been set in the RSA_METHOD, or NULL if no such
-pointer has yet been set.
-
-RSA_meth_set1_name and all RSA_meth_set_*() functions return 1 on
-success or 0 on failure.
-
-=head1 SEE ALSO
-
-L<RSA_new(3)>, L<RSA_generate_key(3)>, L<RSA_sign(3)>,
-L<RSA_set_method(3)>, L<RSA_size(3)>, L<RSA_get0_key(3)>
-
-=head1 HISTORY
-
-The functions described here were added in OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_new, RSA_free - allocate and free RSA objects
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- RSA * RSA_new(void);
-
- void RSA_free(RSA *rsa);
-
-=head1 DESCRIPTION
-
-RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to
-calling RSA_new_method(NULL).
-
-RSA_free() frees the B<RSA> structure and its components. The key is
-erased before the memory is returned to the system.
-If B<rsa> is NULL nothing is done.
-
-=head1 RETURN VALUES
-
-If the allocation fails, RSA_new() returns B<NULL> and sets an error
-code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns
-a pointer to the newly allocated structure.
-
-RSA_free() returns no value.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<RSA_generate_key(3)>,
-L<RSA_new_method(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
-RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
-RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
-RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
-RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
-padding
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
- unsigned char *f, int fl);
-
- int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
-
- int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
- unsigned char *f, int fl);
-
- int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
-
- int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
- unsigned char *f, int fl, unsigned char *p, int pl);
-
- int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl);
-
- int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
- unsigned char *f, int fl);
-
- int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
-
- int RSA_padding_add_none(unsigned char *to, int tlen,
- unsigned char *f, int fl);
-
- int RSA_padding_check_none(unsigned char *to, int tlen,
- unsigned char *f, int fl, int rsa_len);
-
-=head1 DESCRIPTION
-
-The RSA_padding_xxx_xxx() functions are called from the RSA encrypt,
-decrypt, sign and verify functions. Normally they should not be called
-from application programs.
-
-However, they can also be called directly to implement padding for other
-asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and
-RSA_padding_check_PKCS1_OAEP() may be used in an application combined
-with B<RSA_NO_PADDING> in order to implement OAEP with an encoding
-parameter.
-
-RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into
-B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl>
-does not meet the size requirements of the encoding method.
-
-The following encoding methods are implemented:
-
-=over 4
-
-=item PKCS1_type_1
-
-PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures
-
-=item PKCS1_type_2
-
-PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
-
-=item PKCS1_OAEP
-
-PKCS #1 v2.0 EME-OAEP
-
-=item SSLv23
-
-PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
-
-=item none
-
-simply copy the data
-
-=back
-
-The random number generator must be seeded prior to calling
-RSA_padding_add_xxx().
-
-RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
-a valid encoding for a B<rsa_len> byte RSA key in the respective
-encoding method and stores the recovered data of at most B<tlen> bytes
-(for B<RSA_NO_PADDING>: of size B<tlen>)
-at B<to>.
-
-For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
-of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
-
-=head1 RETURN VALUES
-
-The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
-The RSA_padding_check_xxx() functions return the length of the
-recovered data, -1 on error. Error codes can be obtained by calling
-L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<RSA_public_encrypt(3)>,
-L<RSA_private_decrypt(3)>,
-L<RSA_sign(3)>, L<RSA_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_print, RSA_print_fp,
-DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp,
-DHparams_print, DHparams_print_fp - print cryptographic parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_print(BIO *bp, RSA *x, int offset);
- int RSA_print_fp(FILE *fp, RSA *x, int offset);
-
- #include <openssl/dsa.h>
-
- int DSAparams_print(BIO *bp, DSA *x);
- int DSAparams_print_fp(FILE *fp, DSA *x);
- int DSA_print(BIO *bp, DSA *x, int offset);
- int DSA_print_fp(FILE *fp, DSA *x, int offset);
-
- #include <openssl/dh.h>
-
- int DHparams_print(BIO *bp, DH *x);
- int DHparams_print_fp(FILE *fp, DH *x);
-
-=head1 DESCRIPTION
-
-A human-readable hexadecimal output of the components of the RSA
-key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>.
-
-The output lines are indented by B<offset> spaces.
-
-=head1 RETURN VALUES
-
-These functions return 1 on success, 0 on error.
-
-=head1 SEE ALSO
-
-L<BN_bn2bin(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_private_encrypt, RSA_public_decrypt - low level signature operations
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_private_encrypt(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
- int RSA_public_decrypt(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
-=head1 DESCRIPTION
-
-These functions handle RSA signatures at a low level.
-
-RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a
-message digest with an algorithm identifier) using the private key
-B<rsa> and stores the signature in B<to>. B<to> must point to
-B<RSA_size(rsa)> bytes of memory.
-
-B<padding> denotes one of the following modes:
-
-=over 4
-
-=item RSA_PKCS1_PADDING
-
-PKCS #1 v1.5 padding. This function does not handle the
-B<algorithmIdentifier> specified in PKCS #1. When generating or
-verifying PKCS #1 signatures, L<RSA_sign(3)> and L<RSA_verify(3)> should be
-used.
-
-=item RSA_NO_PADDING
-
-Raw RSA signature. This mode should I<only> be used to implement
-cryptographically sound padding modes in the application code.
-Signing user data directly with RSA is insecure.
-
-=back
-
-RSA_public_decrypt() recovers the message digest from the B<flen>
-bytes long signature at B<from> using the signer's public key
-B<rsa>. B<to> must point to a memory section large enough to hold the
-message digest (which is smaller than B<RSA_size(rsa) -
-11>). B<padding> is the padding mode that was used to sign the data.
-
-=head1 RETURN VALUES
-
-RSA_private_encrypt() returns the size of the signature (i.e.,
-RSA_size(rsa)). RSA_public_decrypt() returns the size of the
-recovered message digest.
-
-On error, -1 is returned; the error codes can be
-obtained by L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<RSA_sign(3)>, L<RSA_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_public_encrypt(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
- int RSA_private_decrypt(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
-=head1 DESCRIPTION
-
-RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a
-session key) using the public key B<rsa> and stores the ciphertext in
-B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory.
-
-B<padding> denotes one of the following modes:
-
-=over 4
-
-=item RSA_PKCS1_PADDING
-
-PKCS #1 v1.5 padding. This currently is the most widely used mode.
-
-=item RSA_PKCS1_OAEP_PADDING
-
-EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty
-encoding parameter. This mode is recommended for all new applications.
-
-=item RSA_SSLV23_PADDING
-
-PKCS #1 v1.5 padding with an SSL-specific modification that denotes
-that the server is SSL3 capable.
-
-=item RSA_NO_PADDING
-
-Raw RSA encryption. This mode should I<only> be used to implement
-cryptographically sound padding modes in the application code.
-Encrypting user data directly with RSA is insecure.
-
-=back
-
-B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
-based padding modes, less than RSA_size(B<rsa>) - 41 for
-RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING.
-The random number generator must be seeded prior to calling
-RSA_public_encrypt().
-
-RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the
-private key B<rsa> and stores the plaintext in B<to>. B<to> must point
-to a memory section large enough to hold the decrypted data (which is
-smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that
-was used to encrypt the data.
-
-=head1 RETURN VALUES
-
-RSA_public_encrypt() returns the size of the encrypted data (i.e.,
-RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the
-recovered plaintext.
-
-On error, -1 is returned; the error codes can be
-obtained by L<ERR_get_error(3)>.
-
-=head1 CONFORMING TO
-
-SSL, PKCS #1 v2.0
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<rand(3)>,
-L<RSA_size(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_set_default_method, RSA_get_default_method, RSA_set_method,
-RSA_get_method, RSA_PKCS1_OpenSSL, RSA_null_method, RSA_flags,
-RSA_new_method - select RSA method
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- void RSA_set_default_method(const RSA_METHOD *meth);
-
- RSA_METHOD *RSA_get_default_method(void);
-
- int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
-
- RSA_METHOD *RSA_get_method(const RSA *rsa);
-
- RSA_METHOD *RSA_PKCS1_OpenSSL(void);
-
- RSA_METHOD *RSA_null_method(void);
-
- int RSA_flags(const RSA *rsa);
-
- RSA *RSA_new_method(ENGINE *engine);
-
-=head1 DESCRIPTION
-
-An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
-operations. By modifying the method, alternative implementations such as
-hardware accelerators may be used. IMPORTANT: See the NOTES section for
-important information about how these RSA API functions are affected by the
-use of B<ENGINE> API calls.
-
-Initially, the default RSA_METHOD is the OpenSSL internal implementation,
-as returned by RSA_PKCS1_OpenSSL().
-
-RSA_set_default_method() makes B<meth> the default method for all RSA
-structures created later. B<NB>: This is true only whilst no ENGINE has
-been set as a default for RSA, so this function is no longer recommended.
-
-RSA_get_default_method() returns a pointer to the current default
-RSA_METHOD. However, the meaningfulness of this result is dependent on
-whether the ENGINE API is being used, so this function is no longer
-recommended.
-
-RSA_set_method() selects B<meth> to perform all operations using the key
-B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the
-previous method was supplied by an ENGINE, the handle to that ENGINE will
-be released during the change. It is possible to have RSA keys that only
-work with certain RSA_METHOD implementations (eg. from an ENGINE module
-that supports embedded hardware-protected keys), and in such cases
-attempting to change the RSA_METHOD for the key can have unexpected
-results.
-
-RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>.
-This method may or may not be supplied by an ENGINE implementation, but if
-it is, the return value can only be guaranteed to be valid as long as the
-RSA key itself is valid and does not have its implementation changed by
-RSA_set_method().
-
-RSA_flags() returns the B<flags> that are set for B<rsa>'s current
-RSA_METHOD. See the BUGS section.
-
-RSA_new_method() allocates and initializes an RSA structure so that
-B<engine> will be used for the RSA operations. If B<engine> is NULL, the
-default ENGINE for RSA operations is used, and if no default ENGINE is set,
-the RSA_METHOD controlled by RSA_set_default_method() is used.
-
-RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
-
-RSA_new_method() allocates and initializes an B<RSA> structure so that
-B<method> will be used for the RSA operations. If B<method> is B<NULL>,
-the default method is used.
-
-=head1 THE RSA_METHOD STRUCTURE
-
- typedef struct rsa_meth_st
- {
- /* name of the implementation */
- const char *name;
-
- /* encrypt */
- int (*rsa_pub_enc)(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
- /* verify arbitrary data */
- int (*rsa_pub_dec)(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
- /* sign arbitrary data */
- int (*rsa_priv_enc)(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
- /* decrypt */
- int (*rsa_priv_dec)(int flen, unsigned char *from,
- unsigned char *to, RSA *rsa, int padding);
-
- /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
- implementations) */
- int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
-
- /* compute r = a ^ p mod m (May be NULL for some implementations) */
- int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
- const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
-
- /* called at RSA_new */
- int (*init)(RSA *rsa);
-
- /* called at RSA_free */
- int (*finish)(RSA *rsa);
-
- /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key
- * operations, even if p,q,dmp1,dmq1,iqmp
- * are NULL
- * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
- */
- int flags;
-
- char *app_data; /* ?? */
-
- int (*rsa_sign)(int type,
- const unsigned char *m, unsigned int m_length,
- unsigned char *sigret, unsigned int *siglen, const RSA *rsa);
- int (*rsa_verify)(int dtype,
- const unsigned char *m, unsigned int m_length,
- const unsigned char *sigbuf, unsigned int siglen,
- const RSA *rsa);
- /* keygen. If NULL builtin RSA key generation will be used */
- int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
-
- } RSA_METHOD;
-
-=head1 RETURN VALUES
-
-RSA_PKCS1_OpenSSL(), RSA_PKCS1_null_method(), RSA_get_default_method()
-and RSA_get_method() return pointers to the respective RSA_METHODs.
-
-RSA_set_default_method() returns no value.
-
-RSA_set_method() returns a pointer to the old RSA_METHOD implementation
-that was replaced. However, this return value should probably be ignored
-because if it was supplied by an ENGINE, the pointer could be invalidated
-at any time if the ENGINE is unloaded (in fact it could be unloaded as a
-result of the RSA_set_method() function releasing its handle to the
-ENGINE). For this reason, the return type may be replaced with a B<void>
-declaration in a future release.
-
-RSA_new_method() returns NULL and sets an error code that can be obtained
-by L<ERR_get_error(3)> if the allocation fails. Otherwise
-it returns a pointer to the newly allocated structure.
-
-=head1 BUGS
-
-The behaviour of RSA_flags() is a mis-feature that is left as-is for now
-to avoid creating compatibility problems. RSA functionality, such as the
-encryption functions, are controlled by the B<flags> value in the RSA key
-itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key
-(which is what this function returns). If the flags element of an RSA key
-is changed, the changes will be honoured by RSA functionality but will not
-be reflected in the return value of the RSA_flags() function - in effect
-RSA_flags() behaves more like an RSA_default_flags() function (which does
-not currently exist).
-
-=head1 SEE ALSO
-
-L<RSA_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_sign, RSA_verify - RSA signatures
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_sign(int type, const unsigned char *m, unsigned int m_len,
- unsigned char *sigret, unsigned int *siglen, RSA *rsa);
-
- int RSA_verify(int type, const unsigned char *m, unsigned int m_len,
- unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
-
-=head1 DESCRIPTION
-
-RSA_sign() signs the message digest B<m> of size B<m_len> using the
-private key B<rsa> as specified in PKCS #1 v2.0. It stores the
-signature in B<sigret> and the signature size in B<siglen>. B<sigret>
-must point to RSA_size(B<rsa>) bytes of memory.
-Note that PKCS #1 adds meta-data, placing limits on the size of the
-key that can be used.
-See L<RSA_private_encrypt(3)> for lower-level
-operations.
-
-B<type> denotes the message digest algorithm that was used to generate
-B<m>.
-If B<type> is B<NID_md5_sha1>,
-an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding
-and no algorithm identifier) is created.
-
-RSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
-matches a given message digest B<m> of size B<m_len>. B<type> denotes
-the message digest algorithm that was used to generate the signature.
-B<rsa> is the signer's public key.
-
-=head1 RETURN VALUES
-
-RSA_sign() returns 1 on success.
-RSA_verify() returns 1 on successful verification.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 CONFORMING TO
-
-SSL, PKCS #1 v2.0
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<RSA_private_encrypt(3)>,
-L<RSA_public_decrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
- unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
- RSA *rsa);
-
- int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
- unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
- RSA *rsa);
-
-=head1 DESCRIPTION
-
-RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size
-B<m_len> using the private key B<rsa> represented in DER using PKCS #1
-padding. It stores the signature in B<sigret> and the signature size
-in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of
-memory.
-
-B<dummy> is ignored.
-
-The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING().
-
-RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf>
-of size B<siglen> is the DER representation of a given octet string
-B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's
-public key.
-
-=head1 RETURN VALUES
-
-RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise.
-RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0
-otherwise.
-
-The error codes can be obtained by L<ERR_get_error(3)>.
-
-=head1 BUGS
-
-These functions serve no recognizable purpose.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>,
-L<rand(3)>, L<RSA_sign(3)>,
-L<RSA_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-RSA_size, RSA_bits - get RSA modulus size
-
-=head1 SYNOPSIS
-
-#include <openssl/rsa.h>
-
-int RSA_size(const RSA *rsa);
-
-int RSA_bits(const RSA *rsa);
-
-=head1 DESCRIPTION
-
-RSA_size() returns the RSA modulus size in bytes. It can be used to
-determine how much memory must be allocated for an RSA encrypted
-value.
-
-RSA_bits() returns the number of significant bits.
-
-B<rsa> and B<rsa-E<gt>n> must not be B<NULL>.
-
-=head1 RETURN VALUE
-
-The size.
-
-=head1 SEE ALSO
-
-L<BN_num_bits(3)>
-
-=head1 HISTORY
-
-RSA_bits() was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free,
-SCT_get_version, SCT_set_version,
-SCT_get_log_entry_type, SCT_set_log_entry_type,
-SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id,
-SCT_get_timestamp, SCT_set_timestamp,
-SCT_get_signature_nid, SCT_set_signature_nid,
-SCT_get0_signature, SCT_set0_signature, SCT_set1_signature,
-SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions,
-SCT_get_source, SCT_set_source
- - A Certificate Transparency Signed Certificate Timestamp
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- typedef enum {
- CT_LOG_ENTRY_TYPE_NOT_SET = -1,
- CT_LOG_ENTRY_TYPE_X509 = 0,
- CT_LOG_ENTRY_TYPE_PRECERT = 1
- } ct_log_entry_type_t;
-
- typedef enum {
- SCT_VERSION_NOT_SET = -1,
- SCT_VERSION_V1 = 0
- } sct_version_t;
-
- typedef enum {
- SCT_SOURCE_UNKNOWN,
- SCT_SOURCE_TLS_EXTENSION,
- SCT_SOURCE_X509V3_EXTENSION,
- SCT_SOURCE_OCSP_STAPLED_RESPONSE
- } sct_source_t;
-
- SCT *SCT_new(void);
- SCT *SCT_new_from_base64(unsigned char version,
- const char *logid_base64,
- ct_log_entry_type_t entry_type,
- uint64_t timestamp,
- const char *extensions_base64,
- const char *signature_base64);
-
- void SCT_free(SCT *sct);
- void SCT_LIST_free(STACK_OF(SCT) *a);
-
- sct_version_t SCT_get_version(const SCT *sct);
- int SCT_set_version(SCT *sct, sct_version_t version);
-
- ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
- int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);
-
- size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
- int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
- int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);
-
- uint64_t SCT_get_timestamp(const SCT *sct);
- void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
-
- int SCT_get_signature_nid(const SCT *sct);
- int SCT_set_signature_nid(SCT *sct, int nid);
-
- size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
- void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
- int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);
-
- size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
- void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
- int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);
-
- sct_source_t SCT_get_source(const SCT *sct);
- int SCT_set_source(SCT *sct, sct_source_t source);
-
-=head1 DESCRIPTION
-
-Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2.
-They constitute a promise by a Certificate Transparency (CT) log to publicly
-record a certificate. By cryptographically verifying that a log did indeed issue
-an SCT, some confidence can be gained that the certificate is publicly known.
-
-An internal representation of an SCT can be created in one of two ways.
-The first option is to create a blank SCT, using SCT_new(), and then populate
-it using:
-
-=over
-
-=item * SCT_set_version() to set the SCT version.
-
-Only SCT_VERSION_V1 is currently supported.
-
-=item * SCT_set_log_entry_type() to set the type of certificate the SCT was issued for:
-
-B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
-B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
-
-=item * SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from.
-
-The former takes ownership, whereas the latter makes a copy.
-See RFC 6962, Section 3.2 for the definition of LogID.
-
-=item * SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds).
-
-=item * SCT_set_signature_nid() to set the NID of the signature.
-
-=item * SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.
-
-The former takes ownership, whereas the latter makes a copy.
-
-=item * SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions.
-
-The former takes ownership, whereas the latter makes a copy.
-
-=back
-
-Alternatively, the SCT can be pre-populated from the following data using
-SCT_new_from_base64():
-
-=over
-
-=item * The SCT version (only SCT_VERSION_V1 is currently supported).
-
-=item * The LogID (see RFC 6962, Section 3.2), base64 encoded.
-
-=item * The type of certificate the SCT was issued for:
-
-B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
-B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
-
-=item * The time that the SCT was issued (epoch time in milliseconds).
-
-=item * The SCT extensions, base64 encoded.
-
-=item * The SCT signature, base64 encoded.
-
-=back
-
-SCT_set_source() can be used to record where the SCT was found
-(TLS extension, X.509 certificate extension or OCSP response). This is not
-required for verifying the SCT.
-
-=head1 NOTES
-
-Some of the setters return int, instead of void. These will all return 1 on
-success, 0 on failure. They will not make changes on failure.
-
-All of the setters will reset the validation status of the SCT to
-SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_validate(3)>).
-
-SCT_set_source() will call SCT_set_log_entry_type() if the type of
-certificate the SCT was issued for can be inferred from where the SCT was found.
-For example, an SCT found in an X.509 extension must have been issued for a pre-
-certificate.
-
-SCT_set_source() will not refuse unknown values.
-
-=head1 RETURN VALUES
-
-SCT_set_version() returns 1 if the specified version is supported, 0 otherwise.
-
-SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise.
-
-SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a
-valid SHA-256 hash, 0 otherwise. Aditionally, B<SCT_set1_log_id> returns 0 if
-malloc fails.
-
-B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise.
-
-B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer
-is copied successfully, 0 otherwise (i.e. if malloc fails).
-
-B<SCT_set_source> returns 1 on success, 0 otherwise.
-
-=head1 SEE ALSO
-
-L<ct(3)>,
-L<SCT_verify(3)>,
-L<OBJ_nid2obj(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SCT_print, SCT_LIST_print, SCT_validation_status_string -
-Prints Signed Certificate Timestamps in a human-readable way
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- void SCT_print(const SCT *sct, BIO *out, int indent, const CTLOG_STORE *logs);
- void SCT_LIST_print(const STACK_OF(SCT) *sct_list, BIO *out, int indent,
- const char *separator, const CTLOG_STORE *logs);
- const char *SCT_validation_status_string(const SCT *sct);
-
-=head1 DESCRIPTION
-
-SCT_print() prints a single Signed Certificate Timestamp (SCT) to a L<bio> in
-a human-readable format. SCT_LIST_print() prints an entire list of SCTs in a
-similar way. A separator can be specified to delimit each SCT in the output.
-
-The output can be indented by a specified number of spaces. If a B<CTLOG_STORE>
-is provided, it will be used to print the description of the CT log that issued
-each SCT (if that log is in the CTLOG_STORE). Alternatively, NULL can be passed
-as the CTLOG_STORE parameter to disable this feature.
-
-SCT_validation_status_string() will return the validation status of an SCT as
-a human-readable string. Call SCT_validate() or SCT_LIST_validate()
-beforehand in order to set the validation status of an SCT first.
-
-=head1 SEE ALSO
-
-L<ct(3)>,
-L<bio(3)>,
-L<CTLOG_STORE_new(3)>,
-L<SCT_validate(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SCT_validate, SCT_LIST_validate, SCT_get_validation_status -
-checks Signed Certificate Timestamps (SCTs) are valid
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- typedef enum {
- SCT_VALIDATION_STATUS_NOT_SET,
- SCT_VALIDATION_STATUS_UNKNOWN_LOG,
- SCT_VALIDATION_STATUS_VALID,
- SCT_VALIDATION_STATUS_INVALID,
- SCT_VALIDATION_STATUS_UNVERIFIED,
- SCT_VALIDATION_STATUS_UNKNOWN_VERSION
- } sct_validation_status_t;
-
- int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx);
- int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx);
- sct_validation_status_t SCT_get_validation_status(const SCT *sct);
-
-=head1 DESCRIPTION
-
-SCT_validate() will check that an SCT is valid and verify its signature.
-SCT_LIST_validate() performs the same checks on an entire stack of SCTs.
-The result of the validation checks can be obtained by passing the SCT to
-SCT_get_validation_status().
-
-A CT_POLICY_EVAL_CTX must be provided that specifies:
-
-=over
-
-=item * The certificate the SCT was issued for.
-
-Failure to provide the certificate will result in the validation status being
-SCT_VALIDATION_STATUS_UNVERIFIED.
-
-=item * The issuer of that certificate.
-
-This is only required if the SCT was issued for a pre-certificate
-(see RFC 6962). If it is required but not provided, the validation status will
-be SCT_VALIDATION_STATUS_UNVERIFIED.
-
-=item * A CTLOG_STORE that contains the CT log that issued this SCT.
-
-If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
-status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.
-
-=back
-
-If the SCT is of an unsupported version (only v1 is currently supported), the
-validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION.
-
-If the SCT's signature is incorrect, the validation status will be
-SCT_VALIDATION_STATUS_INVALID. Otherwise, if all checks have passed, the
-validation status will be SCT_VALIDATION_STATUS_VALID.
-
-=head1 NOTES
-
-A return value of 0 from SCT_LIST_validate() should not be interpreted as a
-failure. At a minimum, only one valid SCT may provide sufficient confidence
-that a certificate has been publicly logged.
-
-=head1 RETURN VALUES
-
-SCT_validate() returns a negative integer if an internal error occurs, 0 if the
-SCT fails validation, or 1 if the SCT passes validation.
-
-SCT_LIST_validate() returns a negative integer if an internal error occurs, 0
-if any of SCTs fails validation, or 1 if they all pass validation.
-
-SCT_get_validation_status() returns the validation status of the SCT.
-If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the
-returned value will be SCT_VALIDATION_STATUS_NOT_SET.
-
-=head1 SEE ALSO
-
-L<ct(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update,
-SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384,
-SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update,
-SHA512_Final - Secure Hash Algorithm
-
-=head1 SYNOPSIS
-
- #include <openssl/sha.h>
-
- int SHA1_Init(SHA_CTX *c);
- int SHA1_Update(SHA_CTX *c, const void *data, size_t len);
- int SHA1_Final(unsigned char *md, SHA_CTX *c);
- unsigned char *SHA1(const unsigned char *d, size_t n,
- unsigned char *md);
-
- int SHA224_Init(SHA256_CTX *c);
- int SHA224_Update(SHA256_CTX *c, const void *data, size_t len);
- int SHA224_Final(unsigned char *md, SHA256_CTX *c);
- unsigned char *SHA224(const unsigned char *d, size_t n,
- unsigned char *md);
-
- int SHA256_Init(SHA256_CTX *c);
- int SHA256_Update(SHA256_CTX *c, const void *data, size_t len);
- int SHA256_Final(unsigned char *md, SHA256_CTX *c);
- unsigned char *SHA256(const unsigned char *d, size_t n,
- unsigned char *md);
-
- int SHA384_Init(SHA512_CTX *c);
- int SHA384_Update(SHA512_CTX *c, const void *data, size_t len);
- int SHA384_Final(unsigned char *md, SHA512_CTX *c);
- unsigned char *SHA384(const unsigned char *d, size_t n,
- unsigned char *md);
-
- int SHA512_Init(SHA512_CTX *c);
- int SHA512_Update(SHA512_CTX *c, const void *data, size_t len);
- int SHA512_Final(unsigned char *md, SHA512_CTX *c);
- unsigned char *SHA512(const unsigned char *d, size_t n,
- unsigned char *md);
-
-=head1 DESCRIPTION
-
-Applications should use the higher level functions
-L<EVP_DigestInit(3)> etc. instead of calling the hash
-functions directly.
-
-SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a
-160 bit output.
-
-SHA1() computes the SHA-1 message digest of the B<n>
-bytes at B<d> and places it in B<md> (which must have space for
-SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
-is placed in a static array. Note: setting B<md> to NULL is B<not thread safe>.
-
-The following functions may be used if the message is not completely
-stored in memory:
-
-SHA1_Init() initializes a B<SHA_CTX> structure.
-
-SHA1_Update() can be called repeatedly with chunks of the message to
-be hashed (B<len> bytes at B<data>).
-
-SHA1_Final() places the message digest in B<md>, which must have space
-for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>.
-
-The SHA224, SHA256, SHA384 and SHA512 families of functions operate in the
-same way as for the SHA1 functions. Note that SHA224 and SHA256 use a
-B<SHA256_CTX> object instead of B<SHA_CTX>. SHA384 and SHA512 use B<SHA512_CTX>.
-The buffer B<md> must have space for the output from the SHA variant being used
-(defined by SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH and
-SHA512_DIGEST_LENGTH). Also note that, as for the SHA1() function above, the
-SHA224(), SHA256(), SHA384() and SHA512() functions are not thread safe if
-B<md> is NULL.
-
-The predecessor of SHA-1, SHA, is also implemented, but it should be
-used only when backward compatibility is required.
-
-=head1 RETURN VALUES
-
-SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash
-value.
-
-SHA1_Init(), SHA1_Update() and SHA1_Final() and equivalent SHA224, SHA256,
-SHA384 and SHA512 functions return 1 for success, 0 otherwise.
-
-=head1 CONFORMING TO
-
-US Federal Information Processing Standard FIPS PUB 180-4 (Secure Hash
-Standard),
-ANSI X9.30
-
-=head1 SEE ALSO
-
-L<EVP_DigestInit(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SMIME_read_CMS - parse S/MIME message
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont);
-
-=head1 DESCRIPTION
-
-SMIME_read_CMS() parses a message in S/MIME format.
-
-B<in> is a BIO to read the message from.
-
-If cleartext signing is used then the content is saved in a memory bio which is
-written to B<*bcont>, otherwise B<*bcont> is set to NULL.
-
-The parsed CMS_ContentInfo structure is returned or NULL if an
-error occurred.
-
-=head1 NOTES
-
-If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can
-then be passed to CMS_verify() with the B<CMS_DETACHED> flag set.
-
-Otherwise the type of the returned structure can be determined
-using CMS_get0_type().
-
-To support future functionality if B<bcont> is not NULL B<*bcont> should be
-initialized to NULL. For example:
-
- BIO *cont = NULL;
- CMS_ContentInfo *cms;
-
- cms = SMIME_read_CMS(in, &cont);
-
-=head1 BUGS
-
-The MIME parser used by SMIME_read_CMS() is somewhat primitive. While it will
-handle most S/MIME messages more complex compound formats may not work.
-
-The parser assumes that the CMS_ContentInfo structure is always base64 encoded
-and will not handle the case where it is in binary format or uses quoted
-printable format.
-
-The use of a memory BIO to hold the signed content limits the size of message
-which can be processed due to memory restraints: a streaming single pass option
-should be available.
-
-=head1 RETURN VALUES
-
-SMIME_read_CMS() returns a valid B<CMS_ContentInfo> structure or B<NULL>
-if an error occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_type(3)>
-L<SMIME_read_CMS(3)>, L<CMS_sign(3)>,
-L<CMS_verify(3)>, L<CMS_encrypt(3)>
-L<CMS_decrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SMIME_read_PKCS7 - parse S/MIME message
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont);
-
-=head1 DESCRIPTION
-
-SMIME_read_PKCS7() parses a message in S/MIME format.
-
-B<in> is a BIO to read the message from.
-
-If cleartext signing is used then the content is saved in
-a memory bio which is written to B<*bcont>, otherwise
-B<*bcont> is set to B<NULL>.
-
-The parsed PKCS#7 structure is returned or B<NULL> if an
-error occurred.
-
-=head1 NOTES
-
-If B<*bcont> is not B<NULL> then the message is clear text
-signed. B<*bcont> can then be passed to PKCS7_verify() with
-the B<PKCS7_DETACHED> flag set.
-
-Otherwise the type of the returned structure can be determined
-using PKCS7_type().
-
-To support future functionality if B<bcont> is not B<NULL>
-B<*bcont> should be initialized to B<NULL>. For example:
-
- BIO *cont = NULL;
- PKCS7 *p7;
-
- p7 = SMIME_read_PKCS7(in, &cont);
-
-=head1 BUGS
-
-The MIME parser used by SMIME_read_PKCS7() is somewhat primitive.
-While it will handle most S/MIME messages more complex compound
-formats may not work.
-
-The parser assumes that the PKCS7 structure is always base64
-encoded and will not handle the case where it is in binary format
-or uses quoted printable format.
-
-The use of a memory BIO to hold the signed content limits the size
-of message which can be processed due to memory restraints: a
-streaming single pass option should be available.
-
-=head1 RETURN VALUES
-
-SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL>
-is an error occurred. The error can be obtained from ERR_get_error(3).
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_type(3)>
-L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>,
-L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
-L<PKCS7_decrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SMIME_write_CMS - convert CMS structure to S/MIME format
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-SMIME_write_CMS() adds the appropriate MIME headers to a CMS
-structure to produce an S/MIME message.
-
-B<out> is the BIO to write the data to. B<cms> is the appropriate
-B<CMS_ContentInfo> structure. If streaming is enabled then the content must be
-supplied in the B<data> argument. B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-The following flags can be passed in the B<flags> parameter.
-
-If B<CMS_DETACHED> is set then cleartext signing will be used, this option only
-makes sense for SignedData where B<CMS_DETACHED> is also set when CMS_sign() is
-called.
-
-If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to
-the content, this only makes sense if B<CMS_DETACHED> is also set.
-
-If the B<CMS_STREAM> flag is set streaming is performed. This flag should only
-be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo
-creation function.
-
-If cleartext signing is being used and B<CMS_STREAM> not set then the data must
-be read twice: once to compute the signature in CMS_sign() and once to output
-the S/MIME message.
-
-If streaming is performed the content is output in BER format using indefinite
-length constructed encoding except in the case of signed data with detached
-content where the content is absent and DER format is used.
-
-=head1 BUGS
-
-SMIME_write_CMS() always base64 encodes CMS structures, there should be an
-option to disable this.
-
-=head1 RETURN VALUES
-
-SMIME_write_CMS() returns 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>,
-L<CMS_verify(3)>, L<CMS_encrypt(3)>
-L<CMS_decrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7
-structure to produce an S/MIME message.
-
-B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7>
-structure. If streaming is enabled then the content must be supplied in the
-B<data> argument. B<flags> is an optional set of flags.
-
-=head1 NOTES
-
-The following flags can be passed in the B<flags> parameter.
-
-If B<PKCS7_DETACHED> is set then cleartext signing will be used,
-this option only makes sense for signedData where B<PKCS7_DETACHED>
-is also set when PKCS7_sign() is also called.
-
-If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain>
-are added to the content, this only makes sense if B<PKCS7_DETACHED>
-is also set.
-
-If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should
-only be set if B<PKCS7_STREAM> was also set in the previous call to
-PKCS7_sign() or PKCS7_encrypt().
-
-If cleartext signing is being used and B<PKCS7_STREAM> not set then
-the data must be read twice: once to compute the signature in PKCS7_sign()
-and once to output the S/MIME message.
-
-If streaming is performed the content is output in BER format using indefinite
-length constructed encoding except in the case of signed data with detached
-content where the content is absent and DER format is used.
-
-=head1 BUGS
-
-SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there
-should be an option to disable this.
-
-=head1 RETURN VALUES
-
-SMIME_write_PKCS7() returns 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
-L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
-L<PKCS7_decrypt(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-UI, UI_METHOD,
-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, - 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);
-
- char *UI_construct_prompt(UI *ui_method,
- const char *object_desc, const char *object_name);
-
- void *UI_add_user_data(UI *ui, void *user_data);
- void *UI_get0_user_data(UI *ui);
-
- const char *UI_get0_result(UI *ui, int i);
-
- int UI_process(UI *ui);
-
- int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
-
- void UI_set_default_method(const UI_METHOD *meth);
- const UI_METHOD *UI_get_default_method(void);
- const UI_METHOD *UI_get_method(UI *ui);
- const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
-
- UI_METHOD *UI_OpenSSL(void);
-
-=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)>), 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.
-If B<ui> is NULL nothing is done.
-
-UI_add_input_string() and UI_add_verify_string() add a prompt to the UI,
-as well as flags and a result buffer and the desired minimum and maximum
-sizes of the result, not counting the final NUL character. The given
-information is used to prompt for information, for example a password,
-and to verify a password (i.e. having the user enter it twice and check
-that the same string was entered twice). UI_add_verify_string() takes
-and extra argument that should be a pointer to the result buffer of the
-input string that it's supposed to verify, or verification will fail.
-
-UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered
-in a boolean way, with a single character for yes and a different character
-for no. A set of characters that can be used to cancel the prompt is given
-as well. The prompt itself is divided in two, one part being the
-descriptive text (given through the I<prompt> argument) and one describing
-the possible answers (given through the I<action_desc> argument).
-
-UI_add_info_string() and UI_add_error_string() add strings that are shown at
-the same time as the prompt for extra information or to show an error string.
-The difference between the two is only conceptual. With the builtin method,
-there's no technical difference between them. Other methods may make a
-difference between them, however.
-
-The flags currently supported are B<UI_INPUT_FLAG_ECHO>, which is relevant for
-UI_add_input_string() and will have the users response be echoed (when
-prompting for a password, this flag should obviously not be used, and
-B<UI_INPUT_FLAG_DEFAULT_PWD>, which means that a default password of some
-sort will be used (completely depending on the application and the UI
-method).
-
-UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(),
-UI_dup_info_string() and UI_dup_error_string() are basically the same
-as their UI_add counterparts, except that they make their own copies
-of all strings.
-
-UI_construct_prompt() is a helper function that can be used to create
-a prompt from two pieces of information: an description and a name.
-The default constructor (if there is none provided by the method used)
-creates a string "Enter I<description> for I<name>:". With the
-description "pass phrase" and the file name "foo.key", that becomes
-"Enter pass phrase for foo.key:". Other methods may create whatever
-string and may include encodings that will be processed by the other
-method functions.
-
-UI_add_user_data() adds a piece of memory for the method to use at any
-time. The builtin UI method doesn't care about this info. Note that several
-calls to this function doesn't add data, it replaces the previous blob
-with the one given as argument.
-
-UI_get0_user_data() retrieves the data that has last been given to the
-UI with UI_add_user_data().
-
-UI_get0_result() returns a pointer to the result buffer associated with
-the information indexed by I<i>.
-
-UI_process() goes through the information given so far, does all the printing
-and prompting and returns.
-
-UI_ctrl() adds extra control for the application author. For now, it
-understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process()
-print the OpenSSL error stack as part of processing the UI, and
-B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can
-be used again or not.
-
-UI_set_default_method() changes the default UI method to the one given.
-
-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 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get0_extensions, X509_CRL_get0_extensions, X509_REVOKED_get0_extensions,
-X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d,
-X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i,
-X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i,
-X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509v3.h>
-
- void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit,
- int *idx);
- int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value,
- int crit, unsigned long flags);
-
- void *X509V3_EXT_d2i(X509_EXTENSION *ext);
- X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext);
-
- void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx);
- int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit,
- unsigned long flags);
-
- void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx);
- int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit,
- unsigned long flags);
-
- void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx);
- int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit,
- unsigned long flags);
-
- const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
- const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl);
- const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r);
-
-=head1 DESCRIPTION
-
-X509V3_get_ext_d2i() looks for an extension with OID B<nid> in the extensions
-B<x> and, if found, decodes it. If B<idx> is B<NULL> then only one
-occurrence of an extension is permissible otherwise the first extension after
-index B<*idx> is returned and B<*idx> updated to the location of the extension.
-If B<crit> is not B<NULL> then B<*crit> is set to a status value: -2 if the
-extension occurs multiple times (this is only returned if B<idx> is B<NULL>),
--1 if the extension could not be found, 0 if the extension is found and is
-not critical and 1 if critical. A pointer to an extension specific structure
-or B<NULL> is returned.
-
-X509V3_add1_i2d() adds extension B<value> to STACK B<*x> (allocating a new
-STACK if necessary) using OID B<nid> and criticality B<crit> according
-to B<flags>.
-
-X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension
-B<ext> and returns a pointer to an extension specific structure or B<NULL>
-if the extension could not be decoded (invalid syntax or not supported).
-
-X509V3_EXT_i2d() encodes the extension specific structure B<ext>
-with OID B<ext_nid> and criticality B<crit>.
-
-X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of
-certificate B<x>, they are otherwise identical to X509V3_get_d2i() and
-X509V3_add_i2d().
-
-X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions
-of CRL B<crl>, they are otherwise identical to X509V3_get_d2i() and
-X509V3_add_i2d().
-
-X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the
-extensions of B<X509_REVOKED> structure B<r> (i.e for CRL entry extensions),
-they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d().
-
-X509_get0_extensions(), X509_CRL_get0_extensions() and
-X509_REVOKED_get0_extensions() return a stack of all the extensions
-of a certificate a CRL or a CRL entry respectively.
-
-=head1 NOTES
-
-In almost all cases an extension can occur at most once and multiple
-occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>.
-
-The B<flags> parameter may be one of the following values.
-
-B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does
-not already exist. An error is returned if the extension does already
-exist.
-
-B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension
-already exists.
-
-B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise appends
-a new extension.
-
-B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists
-otherwise returns an error.
-
-B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does
-not already exist. An error B<is not> returned if the extension does already
-exist.
-
-B<X509V3_ADD_DELETE> extension B<nid> is deleted: no new extension is added.
-
-If B<X509V3_ADD_SILENT> is ored with B<flags>: any error returned will not
-be added to the error queue.
-
-The function X509V3_get_d2i() will return B<NULL> if the extension is not
-found, occurs multiple times or cannot be decoded. It is possible to
-determine the precise reason by checking the value of B<*crit>.
-
-=head1 SUPPORTED EXTENSIONS
-
-The following sections contain a list of all supported extensions
-including their name and NID.
-
-=head2 PKIX Certificate Extensions
-
-The following certificate extensions are defined in PKIX standards such as
-RFC5280.
-
- Basic Constraints NID_basic_constraints
- Key Usage NID_key_usage
- Extended Key Usage NID_ext_key_usage
-
- Subject Key Identifier NID_subject_key_identifier
- Authority Key Identifier NID_authority_key_identifier
-
- Private Key Usage Period NID_private_key_usage_period
-
- Subject Alternative Name NID_subject_alt_name
- Issuer Alternative Name NID_issuer_alt_name
-
- Authority Information Access NID_info_access
- Subject Information Access NID_sinfo_access
-
- Name Constraints NID_name_constraints
-
- Certificate Policies NID_certificate_policies
- Policy Mappings NID_policy_mappings
- Policy Constraints NID_policy_constraints
- Inhibit Any Policy NID_inhibit_any_policy
-
- TLS Feature NID_tlsfeature
-
-=head2 Netscape Certificate Extensions
-
-The following are (largely obsolete) Netscape certificate extensions.
-
- Netscape Cert Type NID_netscape_cert_type
- Netscape Base Url NID_netscape_base_url
- Netscape Revocation Url NID_netscape_revocation_url
- Netscape CA Revocation Url NID_netscape_ca_revocation_url
- Netscape Renewal Url NID_netscape_renewal_url
- Netscape CA Policy Url NID_netscape_ca_policy_url
- Netscape SSL Server Name NID_netscape_ssl_server_name
- Netscape Comment NID_netscape_comment
-
-=head2 Miscellaneous Certificate Extensions
-
- Strong Extranet ID NID_sxnet
- Proxy Certificate Information NID_proxyCertInfo
-
-=head2 PKIX CRL Extensions
-
-The following are CRL extensions from PKIX standards such as RFC5280.
-
- CRL Number NID_crl_number
- CRL Distribution Points NID_crl_distribution_points
- Delta CRL Indicator NID_delta_crl
- Freshest CRL NID_freshest_crl
- Invalidity Date NID_invalidity_date
- Issuing Distribution Point NID_issuing_distribution_point
-
-The following are CRL entry extensions from PKIX standards such as RFC5280.
-
- CRL Reason Code NID_crl_reason
- Certificate Issuer NID_certificate_issuer
-
-=head2 OCSP Extensions
-
- OCSP Nonce NID_id_pkix_OCSP_Nonce
- OCSP CRL ID NID_id_pkix_OCSP_CrlID
- Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses
- OCSP No Check NID_id_pkix_OCSP_noCheck
- OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff
- OCSP Service Locator NID_id_pkix_OCSP_serviceLocator
- Hold Instruction Code NID_hold_instruction_code
-
-=head2 Certificate Transparency Extensions
-
-The following extensions are used by certificate transparency, RFC6962
-
- CT Precertificate SCTs NID_ct_precert_scts
- CT Certificate SCTs NID_ct_cert_scts
-
-=head1 RETURN VALUES
-
-X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension
-specific structure of B<NULL> if an error occurs.
-
-X509V3_EXT_i2d() returns a pointer to an B<X509_EXTENSION> structure
-or B<NULL> if an error occurs.
-
-X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it
-fails due to a non-fatal error (extension not found, already exists,
-cannot be encoded) or -1 due to a fatal error such as a memory allocation
-failure.
-
-X509_get0_extensions(), X509_CRL_get0_extensions() and
-X509_REVOKED_get0_extensions() return a stack of extensions. They return
-NULL if no extensions are present.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509_verify_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0, X509_ALGOR_set_md, X509_ALGOR_cmp - AlgorithmIdentifier functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- X509_ALGOR *X509_ALGOR_dup(X509_ALGOR *alg);
- int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *aobj, int ptype, void *pval);
- void X509_ALGOR_get0(const ASN1_OBJECT **paobj, int *pptype,
- const void **ppval, const X509_ALGOR *alg);
- void X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md);
- int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b);
-
-=head1 DESCRIPTION
-
-X509_ALGOR_dup() returns a copy of B<alg>.
-
-X509_ALGOR_set0() sets the algorithm OID of B<alg> to B<aobj> and the
-associated parameter type to B<ptype> with value B<pval>. If B<ptype> is
-B<V_ASN1_UNDEF> the parameter is omitted, otherwise B<ptype> and B<pval> have
-the same meaning as the B<type> and B<value> parameters to ASN1_TYPE_set().
-All the supplied parameters are used internally so must B<NOT> be freed after
-this call.
-
-X509_ALGOR_get0() is the inverse of X509_ALGOR_set0(): it returns the
-algorithm OID in B<*paobj> and the associated parameter in B<*pptype>
-and B<*ppval> from the B<AlgorithmIdentifier> B<alg>.
-
-X509_ALGOR_set_md() sets the B<AlgorithmIdentifier> B<alg> to appropriate
-values for the message digest B<md>.
-
-X509_ALGOR_cmp() compares B<a> and B<b> and returns 0 if they have identical
-encodings and non-zero otherwise.
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_CRL_get0_by_serial, X509_CRL_get0_by_cert, X509_CRL_get_REVOKED,
-X509_REVOKED_get0_serialNumber, X509_REVOKED_get0_revocationDate,
-X509_REVOKED_set_serialNumber, X509_REVOKED_set_revocationDate,
-X509_CRL_add0_revoked, X509_CRL_sort - CRL revoked entry utility
-functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_CRL_get0_by_serial(X509_CRL *crl,
- X509_REVOKED **ret, ASN1_INTEGER *serial);
- int X509_CRL_get0_by_cert(X509_CRL *crl, X509_REVOKED **ret, X509 *x);
-
- STACK_OF(X509_REVOKED) *X509_CRL_get_REVOKED(X509_CRL *crl);
-
- const ASN1_INTEGER *X509_REVOKED_get0_serialNumber(const X509_REVOKED *r);
- const ASN1_TIME *X509_REVOKED_get0_revocationDate(const X509_REVOKED *r);
-
- int X509_REVOKED_set_serialNumber(X509_REVOKED *r, ASN1_INTEGER *serial);
- int X509_REVOKED_set_revocationDate(X509_REVOKED *r, ASN1_TIME *tm);
-
- int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
-
- int X509_CRL_sort(X509_CRL *crl);
-
-=head1 DESCRIPTION
-
-X509_CRL_get0_by_serial() attempts to find a revoked entry in B<crl> for
-serial number B<serial>. If it is successful it sets B<*ret> to the internal
-pointer of the matching entry, as a result B<*ret> must not be freed up
-after the call.
-
-X509_CRL_get0_by_cert() is similar to X509_get0_by_serial() except it
-looks for a revoked entry using the serial number of certificate B<x>.
-
-X509_CRL_get_REVOKED() returns an internal pointer to a stack of all
-revoked entries for B<crl>.
-
-X509_REVOKED_get0_serialNumber() returns an internal pointer to the
-serial number of B<r>.
-
-X509_REVOKED_get0_revocationDate() returns an internal pointer to the
-revocation date of B<r>.
-
-X509_REVOKED_set_serialNumber() sets the serial number of B<r> to B<serial>.
-The supplied B<serial> pointer is not used internally so it should be
-freed up after use.
-
-X509_REVOKED_set_revocationDate() sets the revocation date of B<r> to
-B<tm>. The supplied B<tm> pointer is not used internally so it should be
-freed up after use.
-
-X509_CRL_add0_revoked() appends revoked entry B<rev> to CRL B<crl>. The
-pointer B<rev> is used internally so it must not be freed up after the call:
-it is freed when the parent CRL is freed.
-
-X509_CRL_sort() sorts the revoked entries of B<crl> into ascending serial
-number order.
-
-=head1 NOTES
-
-Applications can determine the number of revoked entries returned by
-X509_CRL_get_revoked() using sk_X509_REVOKED_num() and examine each one
-in turn using sk_X509_REVOKED_value().
-
-=head1 RETURN VALUES
-
-X509_CRL_get0_by_serial(), X509_CRL_get0_by_cert(),
-X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(),
-X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for
-failure.
-
-X509_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> pointer.
-
-X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> value.
-
-X509_CRL_get_REVOKED() returns a STACK of revoked entries.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_EXTENSION_set_object, X509_EXTENSION_set_critical,
-X509_EXTENSION_set_data, X509_EXTENSION_create_by_NID,
-X509_EXTENSION_create_by_OBJ, X509_EXTENSION_get_object,
-X509_EXTENSION_get_critical, X509_EXTENSION_get_data - extension utility
-functions
-
-=head1 SYNOPSIS
-
- int X509_EXTENSION_set_object(X509_EXTENSION *ex, const ASN1_OBJECT *obj);
- int X509_EXTENSION_set_critical(X509_EXTENSION *ex, int crit);
- int X509_EXTENSION_set_data(X509_EXTENSION *ex, ASN1_OCTET_STRING *data);
-
- X509_EXTENSION *X509_EXTENSION_create_by_NID(X509_EXTENSION **ex,
- int nid, int crit,
- ASN1_OCTET_STRING *data);
- X509_EXTENSION *X509_EXTENSION_create_by_OBJ(X509_EXTENSION **ex,
- const ASN1_OBJECT *obj, int crit,
- ASN1_OCTET_STRING *data);
-
- ASN1_OBJECT *X509_EXTENSION_get_object(X509_EXTENSION *ex);
- int X509_EXTENSION_get_critical(const X509_EXTENSION *ex);
- ASN1_OCTET_STRING *X509_EXTENSION_get_data(X509_EXTENSION *ne);
-
-=head1 DESCRIPTION
-
-X509_EXTENSION_set_object() sets the extension type of B<ex> to B<obj>. The
-B<obj> pointer is duplicated internally so B<obj> should be freed up after use.
-
-X509_EXTENSION_set_critical() sets the criticality of B<ex> to B<crit>. If
-B<crit> is zero the extension in non-critical otherwise it is critical.
-
-X509_EXTENSION_set_data() sets the data in extension B<ex> to B<data>. The
-B<data> pointer is duplicated internally.
-
-X509_EXTENSION_create_by_NID() creates an extension of type B<nid>,
-criticality B<crit> using data B<data>. The created extension is returned and
-written to B<*ex> reusing or allocating a new extension if necessary so B<*ex>
-should either be B<NULL> or a valid B<X509_EXTENSION> structure it must
-B<not> be an uninitialised pointer.
-
-X509_EXTENSION_create_by_OBJ() is identical to X509_EXTENSION_create_by_NID()
-except it creates and extension using B<obj> instead of a NID.
-
-X509_EXTENSION_get_object() returns the extension type of B<ex> as an
-B<ASN1_OBJECT> pointer. The returned pointer is an internal value which must
-not be freed up.
-
-X509_EXTENSION_get_critical() returns the criticality of extension B<ex> it
-returns B<1> for critical and B<0> for non-critical.
-
-X509_EXTENSION_get_data() returns the data of extension B<ex>. The returned
-pointer is an internal value which must not be freed up.
-
-=head1 NOTES
-
-These functions manipulate the contents of an extension directly. Most
-applications will want to parse or encode and add an extension: they should
-use the extension encode and decode functions instead such as
-X509_add1_ext_i2d() and X509_get_ext_d2i().
-
-The B<data> associated with an extension is the extension encoding in an
-B<ASN1_OCTET_STRING> structure.
-
-=head1 RETURN VALUES
-
-X509_EXTENSION_set_object() X509_EXTENSION_set_critical() and
-X509_EXTENSION_set_data() return B<1> for success and B<0> for failure.
-
-X509_EXTENSION_create_by_NID() and X509_EXTENSION_create_by_OBJ() return
-an B<X509_EXTENSION> pointer or B<NULL> if an error occurs.
-
-X509_EXTENSION_get_object() returns an B<ASN1_OBJECT> pointer.
-
-X509_EXTENSION_get_critical() returns B<0> for non-critical and B<1> for
-critical.
-
-X509_EXTENSION_get_data() returns an B<ASN1_OCTET_STRING> pointer.
-
-=head1 SEE ALSO
-
-L<X509V3_get_d2i(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_LOOKUP_hash_dir, X509_LOOKUP_file,
-X509_load_cert_file,
-X509_load_crl_file,
-X509_load_cert_crl_file - Default OpenSSL certificate
-lookup methods
-
-=head1 SYNOPSIS
-
- #include <openssl/x509_vfy.h>
-
- X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
- X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
-
- int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
- int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
- int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
-
-=head1 DESCRIPTION
-
-B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate
-lookup methods to use with B<X509_STORE>, provided by OpenSSL library.
-
-Users of the library typically do not need to create instances of these
-methods manually, they would be created automatically by
-L<X509_STORE_load_locations(3)> or
-L<SSL_CTX_load_verify_locations(3)>
-functions.
-
-Internally loading of certificates and CRLs is implemented via functions
-B<X509_load_cert_crl_file>, B<X509_load_cert_file> and
-B<X509_load_crl_file>. These functions support parameter I<type>, which
-can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and
-B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified
-file into memory cache of B<X509_STORE> objects which given B<ctx>
-parameter is associated with.
-
-Functions B<X509_load_cert_file> and
-B<X509_load_crl_file> can load both PEM and DER formats depending of
-type value. Because DER format cannot contain more than one certificate
-or CRL object (while PEM can contain several concatenated PEM objects)
-B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to
-B<X509_load_cert_file>.
-
-Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions
-to load default certificate store file (see
-L<X509_STORE_set_default_paths(3)>.
-
-
-Functions return number of objects loaded from file or 0 in case of
-error.
-
-Both methods support adding several certificate locations into one
-B<X509_STORE>.
-
-This page documents certificate store formats used by these methods and
-caching policy.
-
-=head2 File Method
-
-The B<X509_LOOKUP_file> method loads all the certificates or CRLs
-present in a file into memory at the time the file is added as a
-lookup source.
-
-File format is ASCII text which contains concatenated PEM certificates
-and CRLs.
-
-This method should be used by applications which work with a small
-set of CAs.
-
-=head2 Hashed Directory Method
-
-B<X509_LOOKUP_hash_dir> is a more advanced method, which loads
-certificates and CRLs on demand, and caches them in memory once
-they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs
-upon each lookup, so that newer CRLs are as soon as they appear in
-the directory.
-
-The directory should contain one certificate or CRL per file in PEM format,
-with a file name of the form I<hash>.I<N> for a certificate, or
-I<hash>.B<r>I<N> for a CRL.
-The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied
-to the subject name for certificates or issuer name for CRLs.
-The hash can also be obtained via the B<-hash> option of the L<x509(1)> or
-L<crl(1)> commands.
-
-The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is
-incremented consecutively for each certificate or CRL with the same I<hash>
-value.
-Gaps in the sequence numbers are not supported, it is assumed that there are no
-more objects with the same hash beyond the first missing number in the
-sequence.
-
-Sequence numbers make it possible for the directory to contain multiple
-certificates with same subject name hash value.
-For example, it is possible to have in the store several certificates with same
-subject or several CRLs with same issuer (and, for example, different validity
-period).
-
-When checking for new CRLs once one CRL for given hash value is
-loaded, hash_dir lookup method checks only for certificates with
-sequence number greater than that of the already cached CRL.
-
-Note that the hash algorithm used for subject name hashing changed in OpenSSL
-1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
-0.9.8 to 1.0.0.
-
-OpenSSL includes a L<c_rehash(1)> utility which creates symlinks with correct
-hashed names for all files with .pem suffix in a given directory.
-
-=head1 SEE ALSO
-
-L<PEM_read_PrivateKey(3)>,
-L<d2i_X509_bio(3)>,
-L<X509_STORE_load_locations(3)>,
-L<X609_store_add_lookup(3)>,
-L<SSL_CTX_load_verify_locations(3)>,
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data,
-X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data,
-X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID,
-X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- ASN1_OBJECT * X509_NAME_ENTRY_get_object(const X509_NAME_ENTRY *ne);
- ASN1_STRING * X509_NAME_ENTRY_get_data(const X509_NAME_ENTRY *ne);
-
- int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, const ASN1_OBJECT *obj);
- int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len);
-
- X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len);
- X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type, const unsigned char *bytes, int len);
- X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len);
-
-=head1 DESCRIPTION
-
-X509_NAME_ENTRY_get_object() retrieves the field name of B<ne> in
-and B<ASN1_OBJECT> structure.
-
-X509_NAME_ENTRY_get_data() retrieves the field value of B<ne> in
-and B<ASN1_STRING> structure.
-
-X509_NAME_ENTRY_set_object() sets the field name of B<ne> to B<obj>.
-
-X509_NAME_ENTRY_set_data() sets the field value of B<ne> to string type
-B<type> and value determined by B<bytes> and B<len>.
-
-X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID()
-and X509_NAME_ENTRY_create_by_OBJ() create and return an
-B<X509_NAME_ENTRY> structure.
-
-=head1 NOTES
-
-X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be
-used to examine an B<X509_NAME_ENTRY> function as returned by
-X509_NAME_get_entry() for example.
-
-X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(),
-and X509_NAME_ENTRY_create_by_OBJ() create and return an
-
-X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(),
-X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data()
-are seldom used in practice because B<X509_NAME_ENTRY> structures
-are almost always part of B<X509_NAME> structures and the
-corresponding B<X509_NAME> functions are typically used to
-create and add new entries in a single operation.
-
-The arguments of these functions support similar options to the similarly
-named ones of the corresponding B<X509_NAME> functions such as
-X509_NAME_add_entry_by_txt(). So for example B<type> can be set to
-B<MBSTRING_ASC> but in the case of X509_set_data() the field name must be
-set first so the relevant field information can be looked up internally.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>,
-L<OBJ_nid2obj(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
-X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set);
-
- int X509_NAME_add_entry_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len, int loc, int set);
-
- int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, const unsigned char *bytes, int len, int loc, int set);
-
- int X509_NAME_add_entry(X509_NAME *name, const X509_NAME_ENTRY *ne, int loc, int set);
-
- X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc);
-
-=head1 DESCRIPTION
-
-X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and
-X509_NAME_add_entry_by_NID() add a field whose name is defined
-by a string B<field>, an object B<obj> or a NID B<nid> respectively.
-The field value to be added is in B<bytes> of length B<len>. If
-B<len> is -1 then the field length is calculated internally using
-strlen(bytes).
-
-The type of field is determined by B<type> which can either be a
-definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a
-standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is
-added to a position determined by B<loc> and B<set>.
-
-X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne>
-to B<name>. The new entry is added to a position determined by B<loc>
-and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after
-the call.
-
-X509_NAME_delete_entry() deletes an entry from B<name> at position
-B<loc>. The deleted entry is returned and must be freed up.
-
-=head1 NOTES
-
-The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8>
-is strongly recommended for the B<type> parameter. This allows the
-internal code to correctly determine the type of the field and to
-apply length checks according to the relevant standards. This is
-done using ASN1_STRING_set_by_NID().
-
-If instead an ASN1 type is used no checks are performed and the
-supplied data in B<bytes> is used directly.
-
-In X509_NAME_add_entry_by_txt() the B<field> string represents
-the field name using OBJ_txt2obj(field, 0).
-
-The B<loc> and B<set> parameters determine where a new entry should
-be added. For almost all applications B<loc> can be set to -1 and B<set>
-to 0. This adds a new entry to the end of B<name> as a single valued
-RelativeDistinguishedName (RDN).
-
-B<loc> actually determines the index where the new entry is inserted:
-if it is -1 it is appended.
-
-B<set> determines how the new type is added. If it is zero a
-new RDN is created.
-
-If B<set> is -1 or 1 it is added to the previous or next RDN
-structure respectively. This will then be a multivalued RDN:
-since multivalues RDNs are very seldom used B<set> is almost
-always set to zero.
-
-=head1 EXAMPLES
-
-Create an B<X509_NAME> structure:
-
-"C=UK, O=Disorganized Organization, CN=Joe Bloggs"
-
- X509_NAME *nm;
- nm = X509_NAME_new();
- if (nm == NULL)
- /* Some error */
- if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC,
- "UK", -1, -1, 0))
- /* Error */
- if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC,
- "Disorganized Organization", -1, -1, 0))
- /* Error */
- if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC,
- "Joe Bloggs", -1, -1, 0))
- /* Error */
-
-=head1 RETURN VALUES
-
-X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
-X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
-success of 0 if an error occurred.
-
-X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
-structure of B<NULL> if an error occurred.
-
-=head1 BUGS
-
-B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a
-different algorithm to determine field types. Since this form does
-not understand multicharacter types, performs no length checks and
-can result in invalid field types its use is strongly discouraged.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_NAME_get0_der - get X509_NAME DER encoding
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_NAME_get0_der(X509_NAME *nm, const unsigned char **pder,
- size_t *pderlen)
-
-
-=head1 DESCRIPTION
-
-The function X509_NAME_get0_der() returns an internal pointer to the
-encoding of an B<X509_NAME> structure in B<*pder> and consisting of
-B<*pderlen> bytes. It is useful for applications that wish to examine
-the encoding of an B<X509_NAME> structure without copying it.
-
-=head1 RETURN VALUES
-
-The function X509_NAME_get0_der() returns 1 for success and 0 if an error
-occurred.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
-X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ -
-X509_NAME lookup and enumeration functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_NAME_get_index_by_NID(X509_NAME *name, int nid, int lastpos);
- int X509_NAME_get_index_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int lastpos);
-
- int X509_NAME_entry_count(const X509_NAME *name);
- X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc);
-
- int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf, int len);
- int X509_NAME_get_text_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, char *buf, int len);
-
-=head1 DESCRIPTION
-
-These functions allow an B<X509_NAME> structure to be examined. The
-B<X509_NAME> structure is the same as the B<Name> type defined in
-RFC2459 (and elsewhere) and used for example in certificate subject
-and issuer names.
-
-X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve
-the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>
-should initially be set to -1. If there are no more entries -1 is returned.
-If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned.
-
-X509_NAME_entry_count() returns the total number of entries in B<name>.
-
-X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name>
-corresponding to index B<loc>. Acceptable values for B<loc> run from
-0 to (X509_NAME_entry_count(name) - 1). The value returned is an
-internal pointer which must not be freed.
-
-X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve
-the "text" from the first entry in B<name> which matches B<nid> or
-B<obj>, if no such entry exists -1 is returned. At most B<len> bytes
-will be written and the text written to B<buf> will be null
-terminated. The length of the output string written is returned
-excluding the terminating null. If B<buf> is <NULL> then the amount
-of space needed in B<buf> (excluding the final null) is returned.
-
-=head1 NOTES
-
-X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are
-legacy functions which have various limitations which make them
-of minimal use in practice. They can only find the first matching
-entry and will copy the contents of the field verbatim: this can
-be highly confusing if the target is a multicharacter string type
-like a BMPString or a UTF8String.
-
-For a more general solution X509_NAME_get_index_by_NID() or
-X509_NAME_get_index_by_OBJ() should be used followed by
-X509_NAME_get_entry() on any matching indices and then the
-various B<X509_NAME_ENTRY> utility functions on the result.
-
-The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in
-the source code header files E<lt>openssl/obj_mac.hE<gt> and/or
-E<lt>openssl/objects.hE<gt>.
-
-Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
-should check for the return value of -2. Alternatively the NID validity
-can be determined first by checking OBJ_nid2obj(nid) is not NULL.
-
-=head1 EXAMPLES
-
-Process all entries:
-
- int i;
- X509_NAME_ENTRY *e;
-
- for (i = 0; i < X509_NAME_entry_count(nm); i++)
- {
- e = X509_NAME_get_entry(nm, i);
- /* Do something with e */
- }
-
-Process all commonName entries:
-
- int 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_get_index_by_NID() can also return -2 if the supplied
-NID is invalid.
-
-X509_NAME_entry_count() returns the total number of entries.
-
-X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
-requested entry or B<NULL> if the index is invalid.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print,
-X509_NAME_oneline - X509_NAME printing routines
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_NAME_print_ex(BIO *out, const X509_NAME *nm, int indent, unsigned long flags);
- int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm, int indent, unsigned long flags);
- char * X509_NAME_oneline(const X509_NAME *a, char *buf, int size);
- int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase);
-
-=head1 DESCRIPTION
-
-X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each
-line (for multiline formats) is indented by B<indent> spaces. The output format
-can be extensively customised by use of the B<flags> parameter.
-
-X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is
-written to FILE pointer B<fp>.
-
-X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. 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)> manual page
-for UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example
-B<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used.
-
-The complete set of the flags supported by X509_NAME_print_ex() is listed below.
-
-Several options can be ored together.
-
-The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>,
-B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators
-to use. Two distinct separators are used between distinct RelativeDistinguishedName
-components and separate values in the same RDN for a multi-valued RDN. Multi-valued
-RDNs are currently very rare so the second separator will hardly ever be used.
-
-B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC>
-uses comma and plus with spaces: this is more readable that plain comma and plus.
-B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses
-spaced newline and plus respectively.
-
-If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order.
-
-The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>,
-B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will
-use the short name (e.g. CN) the long name (e.g. commonName) always
-use OID numerical form (normally OIDs are only used if the field name is not
-recognised) and no field name respectively.
-
-If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character
-separating field names and values.
-
-If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is
-printed instead of the values.
-
-If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this
-is only of use for multiline format.
-
-Additionally all the options supported by ASN1_STRING_print_ex() can be used to
-control how each field value is displayed.
-
-In addition a number options can be set for commonly used formats.
-
-B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it
-is equivalent to:
- B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS>
-
-
-B<XN_FLAG_ONELINE> is a more readable one line format which is the same as:
- B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN>
-
-B<XN_FLAG_MULTILINE> is a multiline format which is the same as:
- B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN>
-
-B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally.
-
-=head1 SEE ALSO
-
-L<ASN1_STRING_print_ex(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0,
-X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp,
-i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param,
-X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- X509_PUBKEY *X509_PUBKEY_new(void);
- void X509_PUBKEY_free(X509_PUBKEY *a);
-
- int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey);
- EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key);
- EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key);
-
- EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length);
- int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp);
-
- EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a);
- EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a);
-
- int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey);
- int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey);
-
- int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj,
- int ptype, void *pval,
- unsigned char *penc, int penclen);
- int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg,
- const unsigned char **pk, int *ppklen,
- X509_ALGOR **pa, X509_PUBKEY *pub);
-
-=head1 DESCRIPTION
-
-The B<X509_PUBKEY> structure represents the ASN.1 B<SubjectPublicKeyInfo>
-structure defined in RFC5280 and used in certificates and certificate requests.
-
-X509_PUBKEY_new() allocates and initializes an B<X509_PUBKEY> structure.
-
-X509_PUBKEY_free() frees up B<X509_PUBKEY> structure B<a>. If B<a> is NULL
-nothing is done.
-
-X509_PUBKEY_set() sets the public key in B<*x> to the public key contained
-in the B<EVP_PKEY> structure B<pkey>. If B<*x> is not NULL any existing
-public key structure will be freed.
-
-X509_PUBKEY_get0() returns the public key contained in B<key>. The returned
-value is an internal pointer which B<MUST NOT> be freed after use.
-
-X509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference
-count on the returned key is incremented so it B<MUST> be freed using
-EVP_PKEY_free() after use.
-
-d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B<EVP_PKEY> structure
-using B<SubjectPublicKeyInfo> format. They otherwise follow the conventions of
-other ASN.1 functions such as d2i_X509().
-
-d2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are
-similar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a
-B<BIO> or B<FILE> pointer.
-
-X509_PUBKEY_set0_param() sets the public key parameters of B<pub>. The
-OID associated with the algorithm is set to B<aobj>. The type of the
-algorithm parameters is set to B<type> using the structure B<pval>.
-The encoding of the public key itself is set to the B<penclen>
-bytes contained in buffer B<penc>. On success ownership of all the supplied
-parameters is passed to B<pub> so they must not be freed after the
-call.
-
-X509_PUBKEY_get0_param() retrieves the public key parameters from B<pub>,
-B<*ppkalg> is set to the associated OID and the encoding consists of
-B<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated
-AlgorithmIdentifier for the public key. If the value of any of these
-parameters is not required it can be set to B<NULL>. All of the
-retrieved pointers are internal and must not be freed after the
-call.
-
-=head1 NOTES
-
-The B<X509_PUBKEY> functions can be used to encode and decode public keys
-in a standard format.
-
-In many cases applications will not call the B<X509_PUBKEY> functions
-directly: they will instead call wrapper functions such as X509_get0_pubkey().
-
-=head1 RETURN VALUES
-
-If the allocation fails, X509_PUBKEY_new() returns B<NULL> and sets an error
-code that can be obtained by L<ERR_get_error(3)>.
-
-Otherwise it returns a pointer to the newly allocated structure.
-
-X509_PUBKEY_free() does not return a value.
-
-X509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B<EVP_PKEY>
-structure or B<NULL> if an error occurs.
-
-X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param()
-return 1 for success and 0 if an error occurred.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_get_pubkey(3)>,
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_SIG_get0, X509_SIG_getm - DigestInfo functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- void X509_SIG_get0(const X509_SIG *sig, const X509_ALGOR **palg,
- const ASN1_OCTET_STRING **pdigest);
- void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **palg,
- ASN1_OCTET_STRING **pdigest,
-
-=head1 DESCRIPTION
-
-X509_SIG_get0() returns pointers to the algorithm identifier and digest
-value in B<sig>. X509_SIG_getm() is identical to X509_SIG_get0()
-except the pointers returned are not constant and can be modified:
-for example to initialise them.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_STORE_CTX_get_error, X509_STORE_CTX_set_error,
-X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth,
-X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert,
-X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain,
-X509_verify_cert_error_string - get or set certificate verification status
-information
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx);
- void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s);
- int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx);
- void X509_STORE_CTX_set_error_depth(X509_STORE_CTX *ctx, int depth);
- X509 *X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx);
- void X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x);
- X509 *X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx);
-
- STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx);
-
- const char *X509_verify_cert_error_string(long n);
-
-=head1 DESCRIPTION
-
-These functions are typically called after X509_verify_cert() has indicated
-an error or in a verification callback to determine the nature of an error.
-
-X509_STORE_CTX_get_error() returns the error code of B<ctx>, see
-the B<ERROR CODES> section for a full description of all error codes.
-
-X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example
-it might be used in a verification callback to set an error based on additional
-checks.
-
-X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a
-non-negative integer representing where in the certificate chain the error
-occurred. If it is zero it occurred in the end entity certificate, one if
-it is the certificate which signed the end entity certificate and so on.
-
-X509_STORE_CTX_set_error_depth() sets the error B<depth>.
-This can be used in combination with X509_STORE_CTX_set_error() to set the
-depth at which an error condition was detected.
-
-X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which
-caused the error or B<NULL> if no certificate is relevant.
-
-X509_STORE_CTX_set_current_cert() sets the certificate B<x> in B<ctx> which
-caused the error.
-This value is not intended to remain valid for very long, and remains owned by
-the caller.
-It may be examined by a verification callback invoked to handle each error
-encountered during chain verification and is no longer required after such a
-callback.
-If a callback wishes the save the certificate for use after it returns, it
-needs to increment its reference count via L<X509_up_ref(3)>.
-Once such a I<saved> certificate is no longer needed it can be freed with
-L<X509_free(3)>.
-
-X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
-certificate being verified by the B<ctx>.
-
-X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous
-call to X509_verify_cert() is successful. If the call to X509_verify_cert()
-is B<not> successful the returned chain may be incomplete or invalid. The
-returned chain persists after the B<ctx> structure is freed, when it is
-no longer needed it should be free up using:
-
- sk_X509_pop_free(chain, X509_free);
-
-X509_verify_cert_error_string() returns a human readable error string for
-verification error B<n>.
-
-=head1 RETURN VALUES
-
-X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code.
-
-X509_STORE_CTX_get_error_depth() returns a non-negative error depth.
-
-X509_STORE_CTX_get_current_cert() returns the certificate which caused the
-error or B<NULL> if no certificate is relevant to the error.
-
-X509_verify_cert_error_string() returns a human readable error string for
-verification error B<n>.
-
-=head1 ERROR CODES
-
-A list of error codes and messages is shown below. Some of the
-error codes are defined but currently never returned: these are described as
-"unused".
-
-=over 4
-
-=item B<X509_V_OK: ok>
-
-the operation was successful.
-
-=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
-
-the issuer certificate could not be found: this occurs if the issuer certificate
-of an untrusted certificate cannot be found.
-
-=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
-
-the CRL of a certificate could not be found.
-
-=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
-
-the certificate signature could not be decrypted. This means that the actual
-signature value could not be determined rather than it not matching the
-expected value, this is only meaningful for RSA keys.
-
-=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
-
-the CRL signature could not be decrypted: this means that the actual signature
-value could not be determined rather than it not matching the expected value.
-Unused.
-
-=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
-
-the public key in the certificate SubjectPublicKeyInfo could not be read.
-
-=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
-
-the signature of the certificate is invalid.
-
-=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
-
-the signature of the certificate is invalid.
-
-=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
-
-the certificate is not yet valid: the notBefore date is after the current time.
-
-=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
-
-the certificate has expired: that is the notAfter date is before the current time.
-
-=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
-
-the CRL is not yet valid.
-
-=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
-
-the CRL has expired.
-
-=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
-
-the certificate notBefore field contains an invalid time.
-
-=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
-
-the certificate notAfter field contains an invalid time.
-
-=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
-
-the CRL lastUpdate field contains an invalid time.
-
-=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
-
-the CRL nextUpdate field contains an invalid time.
-
-=item B<X509_V_ERR_OUT_OF_MEM: out of memory>
-
-an error occurred trying to allocate memory. This should never happen.
-
-=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
-
-the passed certificate is self signed and the same certificate cannot be found
-in the list of trusted certificates.
-
-=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
-
-the certificate chain could be built up using the untrusted certificates but
-the root could not be found locally.
-
-=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
-
-the issuer certificate of a locally looked up certificate could not be found.
-This normally means the list of trusted certificates is not complete.
-
-=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
-
-no signatures could be verified because the chain contains only one certificate
-and it is not self signed.
-
-=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
-
-the certificate chain length is greater than the supplied maximum depth. Unused.
-
-=item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
-
-the certificate has been revoked.
-
-=item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
-
-a CA certificate is invalid. Either it is not a CA or its extensions are not
-consistent with the supplied purpose.
-
-=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
-
-the basicConstraints path-length parameter has been exceeded.
-
-=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
-
-the supplied certificate cannot be used for the specified purpose.
-
-=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
-
-the root CA is not marked as trusted for the specified purpose.
-
-=item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
-
-the root CA is marked to reject the specified purpose.
-
-=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
-
-the current candidate issuer certificate was rejected because its subject name
-did not match the issuer name of the current certificate. This is only set
-if issuer check debugging is enabled it is used for status notification and
-is B<not> in itself an error.
-
-=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
-
-the current candidate issuer certificate was rejected because its subject key
-identifier was present and did not match the authority key identifier current
-certificate. This is only set if issuer check debugging is enabled it is used
-for status notification and is B<not> in itself an error.
-
-=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
-
-the current candidate issuer certificate was rejected because its issuer name
-and serial number was present and did not match the authority key identifier of
-the current certificate. This is only set if issuer check debugging is enabled
-it is used for status notification and is B<not> in itself an error.
-
-=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
-
-the current candidate issuer certificate was rejected because its keyUsage
-extension does not permit certificate signing. This is only set if issuer check
-debugging is enabled it is used for status notification and is B<not> in itself
-an error.
-
-=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension>
-
-A certificate extension had an invalid value (for example an incorrect
-encoding) or some value inconsistent with other extensions.
-
-
-=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension>
-
-A certificate policies extension had an invalid value (for example an incorrect
-encoding) or some value inconsistent with other extensions. This error only
-occurs if policy processing is enabled.
-
-=item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy>
-
-The verification flags were set to require and explicit policy but none was
-present.
-
-=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope>
-
-The only CRLs that could be found did not match the scope of the certificate.
-
-=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature>
-
-Some feature of a certificate extension is not supported. Unused.
-
-=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
-
-A name constraint violation occurred in the permitted subtrees.
-
-=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
-
-A name constraint violation occurred in the excluded subtrees.
-
-=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported>
-
-A certificate name constraints extension included a minimum or maximum field:
-this is not supported.
-
-=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type>
-
-An unsupported name constraint type was encountered. OpenSSL currently only
-supports directory name, DNS name, email and URI types.
-
-=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax>
-
-The format of the name constraint is not recognised: for example an email
-address format of a form not mentioned in RFC3280. This could be caused by
-a garbage extension or some new feature not currently supported.
-
-=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
-
-An error occurred when attempting to verify the CRL path. This error can only
-happen if extended CRL checking is enabled.
-
-=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
-
-an application specific error. This will never be returned unless explicitly
-set by an application.
-
-=back
-
-=head1 NOTES
-
-The above functions should be used instead of directly referencing the fields
-in the B<X509_VERIFY_CTX> structure.
-
-In versions of OpenSSL before 1.0 the current certificate returned by
-X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should
-check the return value before printing out any debugging information relating
-to the current certificate.
-
-If an unrecognised error code is passed to X509_verify_cert_error_string() the
-numerical value of the unknown code is returned in a static buffer. This is not
-thread safe but will never happen unless an invalid code is passed.
-
-=head1 SEE ALSO
-
-L<X509_verify_cert(3)>,
-L<X509_up_ref(3)>,
-L<X509_free(3)>.
-
-=head1 COPYRIGHT
-
-Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free,
-X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert,
-X509_STORE_CTX_set0_crls,
-X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
-X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param,
-X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted,
-X509_STORE_CTX_get_num_untrusted,
-X509_STORE_CTX_set_default,
-X509_STORE_CTX_set_verify,
-X509_STORE_set_verify,
-X509_STORE_CTX_get_verify - X509_STORE_CTX initialisation
-
-=head1 SYNOPSIS
-
- #include <openssl/x509_vfy.h>
-
- X509_STORE_CTX *X509_STORE_CTX_new(void);
- void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
- void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
-
- int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store,
- X509 *x509, STACK_OF(X509) *chain);
-
- void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
-
- void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);
- STACK_OF(X509) *X509_STORE_CTX_get0_chain(X609_STORE_CTX *ctx);
- void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
- void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
-
- X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx);
- void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
- int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
-
- STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx);
- void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
-
- int X509_STORE_CTX_get_num_untrusted(X509_STORE_CTX *ctx);
-
- typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
- X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx);
- void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
-
- void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify verify);
-
-=head1 DESCRIPTION
-
-These functions initialise an B<X509_STORE_CTX> structure for subsequent use
-by X509_verify_cert().
-
-X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure.
-
-X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure.
-The context can then be reused with an new call to X509_STORE_CTX_init().
-
-X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx>
-is no longer valid.
-If B<ctx> is NULL nothing is done.
-
-X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation.
-It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only
-good for one call to X509_verify_cert(); if you want to verify a second
-certificate with the same B<ctx> then you must call X509_XTORE_CTX_cleanup()
-and then X509_STORE_CTX_init() again before the second call to
-X509_verify_cert(). The trusted certificate store is set to B<store>, the end
-entity certificate to be verified is set to B<x509> and a set of additional
-certificates (which will be untrusted but may be used to build the chain) in
-B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be
-B<NULL>.
-
-X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of
-B<ctx> to B<sk>. This is an alternative way of specifying trusted certificates
-instead of using an B<X509_STORE>.
-
-X509_STORE_CTX_set_cert() sets the certificate to be verified in B<ctx> to
-B<x>.
-
-X509_STORE_CTX_set0_verified_chain() sets the validated chain used
-by B<ctx> to be B<chain>.
-Ownership of the chain is transferred to B<ctx> and should not be
-free'd by the caller.
-X509_STORE_CTX_get0_chain() returns a the internal pointer used by the
-B<ctx> that contains the validated chain.
-
-X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate
-verification to B<sk>. These CRLs will only be used if CRL verification is
-enabled in the associated B<X509_VERIFY_PARAM> structure. This might be
-used where additional "useful" CRLs are supplied as part of a protocol,
-for example in a PKCS#7 structure.
-
-X509_STORE_CTX_get0_param() retrieves an internal pointer
-to the verification parameters associated with B<ctx>.
-
-X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the
-stack of untrusted certificates associated with B<ctx>.
-
-X509_STORE_CTX_set0_untrusted() sets the internal point to the stack
-of untrusted certificates associated with B<ctx> to B<sk>.
-
-X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
-to B<param>. After this call B<param> should not be used.
-
-X509_STORE_CTX_set_default() looks up and sets the default verification
-method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to
-find an appropriate set of parameters from B<name>.
-
-X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
-that were used in building the chain following a call to X509_verify_cert().
-
-X509_STORE_CTX_set_verify() provides the capability for overriding the default
-verify function. This function is responsible for verifying chain signatures and
-expiration times. X509_STORE_CTX_get_verify() obtains the current verify
-function being used.
-
-X509_STORE_set_verify() works in the same way as for X509_STORE_CTX_set_verify()
-but sets the default verify function to be used by all X509_STORE_CTX objects
-created for this X509_STORE.
-
-A verify function is defined as an X509_STORE_CTX_verify type which has the
-following signature:
-
- int (*verify)(X509_STORE_CTX *);
-
-This function should receive the current X509_STORE_CTX as a parameter and
-return 1 on success or 0 on failure.
-
-=head1 NOTES
-
-The certificates and CRLs in a store are used internally and should B<not>
-be freed up until after the associated B<X509_STORE_CTX> is freed.
-
-=head1 BUGS
-
-The certificates and CRLs in a context are used internally and should B<not>
-be freed up until after the associated B<X509_STORE_CTX> is freed. Copies
-should be made or reference counts increased instead.
-
-=head1 RETURN VALUES
-
-X509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an
-error occurred.
-
-X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred.
-
-X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM>
-structure or B<NULL> if an error occurred.
-
-X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(),
-X509_STORE_CTX_set0_trusted_stack(),
-X509_STORE_CTX_set_cert(),
-X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return
-values.
-
-X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred.
-
-X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
-used.
-
-X509_STORE_CTX_get_verify() returns the current verify function in use for this
-X509_STORE_CTX.
-
-=head1 SEE ALSO
-
-L<X509_verify_cert(3)>
-L<X509_VERIFY_PARAM_set_flags(3)>
-
-=head1 HISTORY
-
-X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0
-X509_STORE_CTX_get_num_untrusted() was first added to OpenSSL 1.1.0
-X509_STORE_set_verify() was first added to OpenSSL 1.1.0. It was previously
-available as a macro X509_STORE_set_verify_func(). This macro still exists but
-simply calls this function.
-
-=head1 COPYRIGHT
-
-Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_STORE_CTX_get_cleanup,
-X509_STORE_CTX_get_lookup_crls,
-X509_STORE_CTX_get_lookup_certs,
-X509_STORE_CTX_get_check_policy,
-X509_STORE_CTX_get_cert_crl,
-X509_STORE_CTX_get_check_crl,
-X509_STORE_CTX_get_get_crl,
-X509_STORE_CTX_get_check_revocation,
-X509_STORE_CTX_get_check_issued,
-X509_STORE_CTX_get_get_issuer,
-X509_STORE_CTX_get_verify,
-X509_STORE_CTX_get_verify_cb,
-X509_STORE_CTX_set_verify_cb - get and set verification callback
-
-=head1 SYNOPSIS
-
- #include <openssl/x509_vfy.h>
-
- typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *);
-
- X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx);
-
- void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx,
- X509_STORE_CTX_verify_cb verify_cb);
-
- X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx);
- X509_STORE_CTX_get_issuer_fn X509_STORE_CTX_get_get_issuer(X509_STORE_CTX *ctx);
- X509_STORE_CTX_check_issued_fn X509_STORE_CTX_get_check_issued(X509_STORE_CTX *ctx);
- X509_STORE_CTX_check_revocation_fn X509_STORE_CTX_get_check_revocation(X509_STORE_CTX *ctx);
- X509_STORE_CTX_get_crl_fn X509_STORE_CTX_get_get_crl(X509_STORE_CTX *ctx);
- X509_STORE_CTX_check_crl_fn X509_STORE_CTX_get_check_crl(X509_STORE_CTX *ctx);
- X509_STORE_CTX_cert_crl_fn X509_STORE_CTX_get_cert_crl(X509_STORE_CTX *ctx);
- X509_STORE_CTX_check_policy_fn X509_STORE_CTX_get_check_policy(X509_STORE_CTX *ctx);
- X509_STORE_CTX_lookup_certs_fn X509_STORE_CTX_get_lookup_certs(X509_STORE_CTX *ctx);
- X509_STORE_CTX_lookup_crls_fn X509_STORE_CTX_get_lookup_crls(X509_STORE_CTX *ctx);
- X509_STORE_CTX_cleanup_fn X509_STORE_CTX_get_cleanup(X509_STORE_CTX *ctx);
-
-=head1 DESCRIPTION
-
-X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to
-B<verify_cb> overwriting any existing callback.
-
-The verification callback can be used to customise the operation of certificate
-verification, either by overriding error conditions or logging errors for
-debugging purposes.
-
-However a verification callback is B<not> essential and the default operation
-is often sufficient.
-
-The B<ok> parameter to the callback indicates the value the callback should
-return to retain the default behaviour. If it is zero then an error condition
-is indicated. If it is 1 then no error occurred. If the flag
-B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the
-policy checking is complete.
-
-The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that
-is performing the verification operation. A callback can examine this
-structure and receive additional information about the error, for example
-by calling X509_STORE_CTX_get_current_cert(). Additional application data can
-be passed to the callback via the B<ex_data> mechanism.
-
-X509_STORE_CTX_get_verify_cb() returns the value of the current callback
-for the specific B<ctx>.
-
-X509_STORE_CTX_get_verify(), X509_STORE_CTX_get_get_issuer(),
-X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
-X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
-X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
-X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
-and X509_STORE_CTX_get_cleanup() return the function pointers cached
-from the corresponding B<X509_STORE>, please see
-L<X509_STORE_set_verify(3)> for more information.
-
-
-=head1 WARNING
-
-In general a verification callback should B<NOT> unconditionally return 1 in
-all circumstances because this will allow verification to succeed no matter
-what the error. This effectively removes all security from the application
-because B<any> certificate (including untrusted generated ones) will be
-accepted.
-
-=head1 NOTES
-
-The verification callback can be set and inherited from the parent structure
-performing the operation. In some cases (such as S/MIME verification) the
-B<X509_STORE_CTX> structure is created and destroyed internally and the
-only way to set a custom verification callback is by inheriting it from the
-associated B<X509_STORE>.
-
-=head1 RETURN VALUES
-
-X509_STORE_CTX_set_verify_cb() does not return a value.
-
-=head1 EXAMPLES
-
-Default callback operation:
-
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
- return ok;
- }
-
-Simple example, suppose a certificate in the chain is expired and we wish
-to continue after this error:
-
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
- /* Tolerate certificate expiration */
- if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED)
- return 1;
- /* Otherwise don't override */
- return ok;
- }
-
-More complex example, we don't wish to continue after B<any> certificate has
-expired just one specific case:
-
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
- int err = X509_STORE_CTX_get_error(ctx);
- X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);
- if (err == X509_V_ERR_CERT_HAS_EXPIRED)
- {
- if (check_is_acceptable_expired_cert(err_cert)
- return 1;
- }
- return ok;
- }
-
-Full featured logging callback. In this case the B<bio_err> is assumed to be
-a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using
-B<ex_data>.
-
- int verify_callback(int ok, X509_STORE_CTX *ctx)
- {
- X509 *err_cert;
- int err, depth;
-
- err_cert = X509_STORE_CTX_get_current_cert(ctx);
- err = X509_STORE_CTX_get_error(ctx);
- depth = X509_STORE_CTX_get_error_depth(ctx);
-
- BIO_printf(bio_err, "depth=%d ", depth);
- if (err_cert)
- {
- X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert),
- 0, XN_FLAG_ONELINE);
- BIO_puts(bio_err, "\n");
- }
- else
- BIO_puts(bio_err, "<no cert>\n");
- if (!ok)
- BIO_printf(bio_err, "verify error:num=%d:%s\n", err,
- X509_verify_cert_error_string(err));
- switch (err)
- {
- case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
- BIO_puts(bio_err, "issuer= ");
- X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert),
- 0, XN_FLAG_ONELINE);
- BIO_puts(bio_err, "\n");
- break;
- case X509_V_ERR_CERT_NOT_YET_VALID:
- case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
- BIO_printf(bio_err, "notBefore=");
- ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert));
- BIO_printf(bio_err, "\n");
- break;
- case X509_V_ERR_CERT_HAS_EXPIRED:
- case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
- BIO_printf(bio_err, "notAfter=");
- ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert));
- BIO_printf(bio_err, "\n");
- break;
- case X509_V_ERR_NO_EXPLICIT_POLICY:
- policies_print(bio_err, ctx);
- break;
- }
- if (err == X509_V_OK && ok == 2)
- /* print out policies */
-
- BIO_printf(bio_err, "verify return:%d\n", ok);
- return(ok);
- }
-
-=head1 SEE ALSO
-
-L<X509_STORE_CTX_get_error(3)>
-L<X509_STORE_set_verify_cb_func(3)>
-L<X509_STORE_CTX_get_ex_new_index(3)>
-
-=head1 HISTORY
-
-X509_STORE_CTX_get_verify(), X509_STORE_CTX_get_get_issuer(),
-X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
-X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
-X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
-X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
-and X509_STORE_CTX_get_cleanup() were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_STORE_get0_param, X509_STORE_set1_param,
-X509_STORE_get0_objects - X509_STORE setter and getter functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509_vfy.h>
-
- X509_VERIFY_PARAM *X509_STORE_get0_param(X509_STORE *ctx);
- int X509_STORE_set1_param(X509_STORE *ctx, X509_VERIFY_PARAM *pm);
- STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(X509_STORE *ctx);
-
-=head1 DESCRIPTION
-
-X509_STORE_set1_param() sets the verification parameters
-to B<pm> for B<ctx>.
-
-X509_STORE_get0_param() retrieves an internal pointer to the verification
-parameters for B<ctx>. The returned pointer must not be freed by the
-calling application
-
-X509_STORE_get0_objects() retrieve an internal pointer to the store's
-X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The
-returned pointer must not be freed by the calling application.
-
-
-=head1 RETURN VALUES
-
-X509_STORE_get0_param() returns a pointer to an
-B<X509_VERIFY_PARAM> structure.
-
-X509_STORE_set1_param() returns 1 for success and 0 for failure.
-
-X509_STORE_get0_objects() returns a pointer to a stack of B<X509_OBJECT>.
-
-=head1 SEE ALSO
-
-L<X509_STORE_new(3)>
-
-=head1 HISTORY
-
-B<X509_STORE_get0_param> and B<X509_STORE_get0_objects> were added in
-OpenSSL version 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_STORE_new, X509_STORE_up_ref, X509_STORE_free, X509_STORE_lock,
-X509_STORE_unlock - X509_STORE allocation, freeing and locking functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509_vfy.h>
-
- X509_STORE *X509_STORE_new(void);
- void X509_STORE_free(X509_STORE *v);
- int X509_STORE_lock(X509_STORE *v);
- int X509_STORE_unlock(X509_STORE *v);
- int X509_STORE_up_ref(X509_STORE *v);
-
-=head1 DESCRIPTION
-
-The X509_STORE_new() function returns a new X509_STORE.
-
-X509_STORE_up_ref() increments the reference count associated with the
-X509_STORE object.
-
-X509_STORE_lock() locks the store from modification by other threads,
-X509_STORE_unlock() locks it.
-
-X509_STORE_free() frees up a single X509_STORE object.
-
-=head1 RETURN VALUES
-
-X509_STORE_new() returns a newly created X509_STORE or NULL if the call fails.
-
-X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() return
-1 for success and 0 for failure.
-
-X509_STORE_free() does not return values.
-
-=head1 SEE ALSO
-
-L<X509_STORE_set_verify_cb_func(3)>
-L<X509_STORE_get0_param(3)>
-
-=head1 HISTORY
-
-The X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock()
-functions were added in OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_STORE_set_lookup_crls_cb,
-X509_STORE_set_verify_func,
-X509_STORE_get_cleanup,
-X509_STORE_set_cleanup,
-X509_STORE_get_lookup_crls,
-X509_STORE_set_lookup_crls,
-X509_STORE_get_lookup_certs,
-X509_STORE_set_lookup_certs,
-X509_STORE_get_check_policy,
-X509_STORE_set_check_policy,
-X509_STORE_get_cert_crl,
-X509_STORE_set_cert_crl,
-X509_STORE_get_check_crl,
-X509_STORE_set_check_crl,
-X509_STORE_get_get_crl,
-X509_STORE_set_get_crl,
-X509_STORE_get_check_revocation,
-X509_STORE_set_check_revocation,
-X509_STORE_get_check_issued,
-X509_STORE_set_check_issued,
-X509_STORE_get_get_issuer,
-X509_STORE_set_get_issuer,
-X509_STORE_CTX_get_verify,
-X509_STORE_set_verify,
-X509_STORE_get_verify_cb,
-X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb
-- set verification callback
-
-=head1 SYNOPSIS
-
- #include <openssl/x509_vfy.h>
-
- typedef int (*X509_STORE_CTX_verify_cb)(int ok, X509_STORE_CTX *ctx);
- typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *ctx);
- typedef int (*X509_STORE_CTX_get_issuer_fn)(X509 **issuer,
- X509_STORE_CTX *ctx, X509 *x);
- typedef int (*X509_STORE_CTX_check_issued_fn)(X509_STORE_CTX *ctx,
- X509 *x, X509 *issuer);
- typedef int (*X509_STORE_CTX_check_revocation_fn)(X509_STORE_CTX *ctx);
- typedef int (*X509_STORE_CTX_get_crl_fn)(X509_STORE_CTX *ctx,
- X509_CRL **crl, X509 *x);
- typedef int (*X509_STORE_CTX_check_crl_fn)(X509_STORE_CTX *ctx, X509_CRL *crl);
- typedef int (*X509_STORE_CTX_cert_crl_fn)(X509_STORE_CTX *ctx,
- X509_CRL *crl, X509 *x);
- typedef int (*X509_STORE_CTX_check_policy_fn)(X509_STORE_CTX *ctx);
- typedef STACK_OF(X509) *(*X509_STORE_CTX_lookup_certs_fn)(X509_STORE_CTX *ctx,
- X509_NAME *nm);
- typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(X509_STORE_CTX *ctx,
- X509_NAME *nm);
- typedef int (*X509_STORE_CTX_cleanup_fn)(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_verify_cb(X509_STORE *ctx,
- X509_STORE_CTX_verify_cb verify_cb);
- X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify_fn verify);
- X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_get_issuer(X509_STORE *ctx,
- X509_STORE_CTX_get_issuer_fn get_issuer);
- X509_STORE_CTX_get_issuer_fn X509_STORE_get_get_issuer(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_check_issued(X509_STORE *ctx,
- X509_STORE_CTX_check_issued_fn check_issued);
- X509_STORE_CTX_check_issued_fn X509_STORE_get_check_issued(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_check_revocation(X509_STORE *ctx,
- X509_STORE_CTX_check_revocation_fn check_revocation);
- X509_STORE_CTX_check_revocation_fn X509_STORE_get_check_revocation(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_get_crl(X509_STORE *ctx,
- X509_STORE_CTX_get_crl_fn get_crl);
- X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_check_crl(X509_STORE *ctx,
- X509_STORE_CTX_check_crl_fn check_crl);
- X509_STORE_CTX_check_crl_fn X509_STORE_get_check_crl(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_cert_crl(X509_STORE *ctx,
- X509_STORE_CTX_cert_crl_fn cert_crl);
- X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_check_policy(X509_STORE *ctx,
- X509_STORE_CTX_check_policy_fn check_policy);
- X509_STORE_CTX_check_policy_fn X509_STORE_get_check_policy(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_lookup_certs(X509_STORE *ctx,
- X509_STORE_CTX_lookup_certs_fn lookup_certs);
- X509_STORE_CTX_lookup_certs_fn X509_STORE_get_lookup_certs(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_lookup_crls(X509_STORE *ctx,
- X509_STORE_CTX_lookup_crls_fn lookup_crls);
- X509_STORE_CTX_lookup_crls_fn X509_STORE_get_lookup_crls(X509_STORE_CTX *ctx);
-
- void X509_STORE_set_cleanup(X509_STORE *ctx,
- X509_STORE_CTX_cleanup_fn cleanup);
- X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(X509_STORE_CTX *ctx);
-
- /* Aliases */
- void X509_STORE_set_verify_cb_func(X509_STORE *st,
- X509_STORE_CTX_verify_cb verify_cb);
- void X509_STORE_set_verify_func(X509_STORE *ctx,
- X509_STORE_CTX_verify_fn verify);
- void X509_STORE_set_lookup_crls_cb(X509_STORE *ctx,
- X509_STORE_CTX_lookup_crls_fn lookup_crls);
-
-=head1 DESCRIPTION
-
-X509_STORE_set_verify_cb() sets the verification callback of B<ctx> to
-B<verify_cb> overwriting the previous callback.
-The callback assigned with this function becomes a default for the one
-that can be assigned directly to the corresponding B<X509_STORE_CTX>,
-please see L<X509_STORE_CTX_set_verify_cb(3)> for further information.
-
-X509_STORE_set_verify() sets the final chain verification function for
-B<ctx> to B<verify>.
-Its purpose is to go through the chain of certificates and check that
-all signatures are valid and that the current time is within the
-limits of each certificate's first and last validity time.
-The final chain verification functions must return 0 on failure and 1
-on success.
-I<If no chain verification function is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_get_issuer() sets the function to get the issuer
-certificate that verifies the given certificate B<x>.
-When found, the issuer certificate must be assigned to B<*issuer>.
-This function must return 0 on failure and 1 on success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_check_issued() sets the function to check that a given
-certificate B<x> is issued with the issuer certificate B<issuer>.
-This function must return 0 on failure (among others if B<x> hasn't
-been issued with B<issuer>) and 1 on success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_check_revocation() sets the revocation checking
-function.
-Its purpose is to look through the final chain and check the
-revocation status for each certificate.
-It must return 0 on failure and 1 on success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_get_crl() sets the function to get the crl for a given
-certificate B<x>.
-When found, the crl must be assigned to B<*crl>.
-This function must return 0 on failure and 1 on success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_check_crl() sets the function to check the validity of
-the given B<crl>.
-This function must return 0 on failure and 1 on success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_cert_crl() sets the function to check the revocation
-status of the given certificate B<x> against the given B<crl>.
-This function must return 0 on failure and 1 on success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_check_policy() sets the function to check the policies
-of all the certificates in the final chain..
-This function must return 0 on failure and 1 on success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_lookup_certs() and X509_STORE_set_lookup_crls() set the
-functions to look up all the certs or all the CRLs that match the
-given name B<nm>.
-These functions return NULL on failure and a pointer to a stack of
-certificates (B<X509>) or to a stack of CRLs (B<X509_CRL>) on
-success.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_set_cleanup() sets the final cleanup function, which is
-called when the context (B<X509_STORE_CTX>) is being torn down.
-This function doesn't return any value.
-I<If no function to get the issuer is provided, the internal default
-function will be used instead.>
-
-X509_STORE_get_verify_cb(), X509_STORE_CTX_get_verify(),
-X509_STORE_get_get_issuer(), X509_STORE_get_check_issued(),
-X509_STORE_get_check_revocation(), X509_STORE_get_get_crl(),
-X509_STORE_get_check_crl(), X509_STORE_set_verify(),
-X509_STORE_set_get_issuer(), X509_STORE_get_cert_crl(),
-X509_STORE_get_check_policy(), X509_STORE_get_lookup_certs(),
-X509_STORE_get_lookup_crls() and X509_STORE_get_cleanup() all return
-the function pointer assigned with X509_STORE_set_check_issued(),
-X509_STORE_set_check_revocation(), X509_STORE_set_get_crl(),
-X509_STORE_set_check_crl(), X509_STORE_set_cert_crl(),
-X509_STORE_set_check_policy(), X509_STORE_set_lookup_certs(),
-X509_STORE_set_lookup_crls() and X509_STORE_set_cleanup(), or NULL if
-no assignment has been made.
-
-X509_STORE_set_verify_cb_func(), X509_STORE_set_verify_func() and
-X509_STORE_set_lookup_crls_cb() are aliases for
-X509_STORE_set_verify_cb(), X509_STORE_set_verify() and
-X509_STORE_set_lookup_crls, available as macros for backward
-compatibility.
-
-=head1 NOTES
-
-All the callbacks from a B<X509_STORE> are inherited by the
-corresponding B<X509_STORE_CTX> structure when it is initialized.
-See L<X509_STORE_CTX_set_verify_cb(3)> for further details.
-
-=head1 BUGS
-
-The macro version of this function was the only one available before
-OpenSSL 1.0.0.
-
-=head1 RETURN VALUES
-
-The X509_STORE_set_*() functions do not return a value.
-
-The X509_STORE_get_*() functions return a pointer of the appropriate
-function type.
-
-=head1 SEE ALSO
-
-L<X509_STORE_CTX_set_verify_cb(3)>, L<X509_STORE_CTX_get0_chain(3)>,
-L<CMS_verify(3)>
-
-=head1 HISTORY
-
-X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0.
-
-X509_STORE_set_verify_cb(), X509_STORE_get_verify_cb(),
-X509_STORE_set_verify(), X509_STORE_CTX_get_verify(),
-X509_STORE_set_get_issuer(), X509_STORE_get_get_issuer(),
-X509_STORE_set_check_issued(), X509_STORE_get_check_issued(),
-X509_STORE_set_check_revocation(), X509_STORE_get_check_revocation(),
-X509_STORE_set_get_crl(), X509_STORE_get_get_crl(),
-X509_STORE_set_check_crl(), X509_STORE_get_check_crl(),
-X509_STORE_set_cert_crl(), X509_STORE_get_cert_crl(),
-X509_STORE_set_check_policy(), X509_STORE_get_check_policy(),
-X509_STORE_set_lookup_certs(), X509_STORE_get_lookup_certs(),
-X509_STORE_set_lookup_crls(), X509_STORE_get_lookup_crls(),
-X509_STORE_set_cleanup() and X509_STORE_get_cleanup() were added in
-OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/x509_vfy.h>
-
- int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param,
- unsigned long flags);
- int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param,
- unsigned long flags);
- unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param);
-
- int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose);
- int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust);
-
- void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t);
-
- int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param,
- ASN1_OBJECT *policy);
- int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param,
- STACK_OF(ASN1_OBJECT) *policies);
-
- void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth);
- int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param);
-
- void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param,
- int auth_level);
- int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param);
-
- int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param,
- const char *name, size_t namelen);
- int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param,
- const char *name, size_t namelen);
- void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
- unsigned int flags);
- char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
- int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
- const char *email, size_t emaillen);
- int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
- const unsigned char *ip, size_t iplen);
- int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc);
-
-=head1 DESCRIPTION
-
-These functions manipulate the B<X509_VERIFY_PARAM> structure associated with
-a certificate verification operation.
-
-The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring
-it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete
-description of values the B<flags> parameter can take.
-
-X509_VERIFY_PARAM_get_flags() returns the flags in B<param>.
-
-X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>.
-
-X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>
-to B<purpose>. This determines the acceptable purpose of the certificate
-chain, for example SSL client or SSL server.
-
-X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to
-B<trust>.
-
-X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to
-B<t>. Normally the current time is used.
-
-X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled
-by default) and adds B<policy> to the acceptable policy set.
-
-X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled
-by default) and sets the acceptable policy set to B<policies>. Any existing
-policy set is cleared. The B<policies> parameter can be B<NULL> to clear
-an existing policy set.
-
-X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>.
-That is the maximum number of intermediate CA certificates that can appear in a
-chain.
-A maximal depth chain contains 2 more certificates than the limit, since
-neither the end-entity certificate nor the trust-anchor count against this
-limit.
-Thus a B<depth> limit of 0 only allows the end-entity certificate to be signed
-directly by the trust-anchor, while with a B<depth> limit of 1 there can be one
-intermediate CA certificate between the trust-anchor and the end-entity
-certificate.
-
-X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to
-B<auth_level>.
-The authentication security level determines the acceptable signature and public
-key strength when verifying certificate chains.
-For a certificate chain to validate, the public keys of all the certificates
-must meet the specified security level.
-The signature algorithm security level is not enforced for the chain's I<trust
-anchor> certificate, which is either directly trusted or validated by means other
-than its signature.
-See L<SSL_CTX_set_security_level(3)> for the definitions of the available
-levels.
-The default security level is -1, or "not set".
-At security level 0 or lower all algorithms are acceptable.
-Security level 1 requires at least 80-bit-equivalent security and is broadly
-interoperable, though it will, for example, reject MD5 signatures or RSA keys
-shorter than 1024 bits.
-
-X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to
-B<name> clearing any previously specified host name or names. If
-B<name> is NULL, or empty the list of hostnames is cleared, and
-name checks are not performed on the peer certificate. If B<name>
-is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>
-must be set to the length of B<name>. When a hostname is specified,
-certificate verification automatically invokes L<X509_check_host(3)>
-with flags equal to the B<flags> argument given to
-X509_VERIFY_PARAM_set_hostflags() (default zero). Applications
-are strongly advised to use this interface in preference to explicitly
-calling L<X509_check_host(3)>, hostname checks are out of scope
-with the DANE-EE(3) certificate usage, and the internal check will
-be suppressed as appropriate when DANE support is added to OpenSSL.
-
-X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference
-identifier that can match the peer's certificate. Any previous names
-set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host()
-are retained, no change is made if B<name> is NULL or empty. When
-multiple names are configured, the peer is considered verified when
-any name matches.
-
-X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject
-CommonName from the peer certificate that matched one of the reference
-identifiers. When wildcard matching is not disabled, or when a
-reference identifier specifies a parent domain (starts with ".")
-rather than a hostname, the peer name may be a wildcard name or a
-sub-domain of the reference identifier respectively. The return
-string is allocated by the library and is no longer valid once the
-associated B<param> argument is freed. Applications must not free
-the return value.
-
-X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to
-B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise
-B<emaillen> must be set to the length of B<email>. When an email address
-is specified, certificate verification automatically invokes
-L<X509_check_email(3)>.
-
-X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>.
-The B<ip> argument is in binary format, in network byte-order and
-B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
-address is specified, certificate verification automatically invokes
-L<X509_check_ip(3)>.
-
-X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to
-B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string:
-dotted decimal quad for IPv4 and colon-separated hexadecimal for
-IPv6. The condensed "::" notation is supported for IPv6 addresses.
-
-=head1 RETURN VALUES
-
-X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),
-X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(),
-X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(),
-X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(),
-X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and
-X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for
-failure.
-
-X509_VERIFY_PARAM_get_flags() returns the current verification flags.
-
-X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return
-values.
-
-X509_VERIFY_PARAM_get_depth() returns the current verification depth.
-
-X509_VERIFY_PARAM_get_auth_level() returns the current authentication security
-level.
-
-=head1 VERIFICATION FLAGS
-
-The verification flags consists of zero or more of the following flags
-ored together.
-
-B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf
-certificate. An error occurs if a suitable CRL cannot be found.
-
-B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate
-chain.
-
-B<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default
-any unhandled critical extensions in certificates or (if checked) CRLs results
-in a fatal error. If this flag is set unhandled critical extensions are
-ignored. B<WARNING> setting this option for anything other than debugging
-purposes can be a security risk. Finer control over which extensions are
-supported can be performed in the verification callback.
-
-The B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken
-certificates and makes the verification strictly apply B<X509> rules.
-
-B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification.
-
-B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default
-no policy checking is performed. Additional information is sent to the
-verification callback relating to policy checking.
-
-B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and
-B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any
-policy> and B<inhibit policy mapping> flags respectively as defined in
-B<RFC3280>. Policy checking is automatically enabled if any of these flags
-are set.
-
-If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful
-a special status code is set to the verification callback. This permits it
-to examine the valid policy tree and perform additional checks or simply
-log it for debugging purposes.
-
-By default some additional features such as indirect CRLs and CRLs signed by
-different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set
-they are enabled.
-
-If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to
-determine certificate status. If not set deltas are ignored.
-
-B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed
-certificate signature. By default this check is disabled because it doesn't
-add any additional security but in some cases applications might want to
-check the signature anyway. A side effect of not checking the root CA
-signature is that disabled or unsupported message digests on the root CA
-are not treated as fatal errors.
-
-If B<X509_V_FLAG_TRUSTED_FIRST> is set, when constructing the certificate chain,
-L<X509_verify_cert(3)> will search the trust store for issuer certificates before
-searching the provided untrusted certificates.
-As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
-
-The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
-chains.
-By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a
-certificate chain, if the first certificate chain found is not trusted, then
-OpenSSL will attempt to replace untrusted certificates supplied by the peer
-with certificates from the trust store to see if an alternative chain can be
-found that is trusted.
-As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
-has no effect.
-
-The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period
-of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time()
-is used to specify a verification time, the check is not suppressed.
-
-=head1 NOTES
-
-The above functions should be used to manipulate verification parameters
-instead of legacy functions which work in specific structures such as
-X509_STORE_CTX_set_flags().
-
-=head1 BUGS
-
-Delta CRL checking is currently primitive. Only a single delta can be used and
-(partly due to limitations of B<X509_STORE>) constructed CRLs are not
-maintained.
-
-If CRLs checking is enable CRLs are expected to be available in the
-corresponding B<X509_STORE> structure. No attempt is made to download
-CRLs from the CRL distribution points extension.
-
-=head1 EXAMPLE
-
-Enable CRL checking when performing certificate verification during SSL
-connections associated with an B<SSL_CTX> structure B<ctx>:
-
- X509_VERIFY_PARAM *param;
- param = X509_VERIFY_PARAM_new();
- X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK);
- SSL_CTX_set1_param(ctx, param);
- X509_VERIFY_PARAM_free(param);
-
-=head1 SEE ALSO
-
-L<X509_verify_cert(3)>,
-L<X509_check_host(3)>,
-L<X509_check_email(3)>,
-L<X509_check_ip(3)>
-
-=head1 HISTORY
-
-The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0
-The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of
-OpenSSL 1.1.0, and has no effect.
-
-=head1 COPYRIGHT
-
-Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_check_ca - check if given certificate is CA certificate
-
-=head1 SYNOPSIS
-
- #include <openssl/x509v3.h>
-
- int X509_check_ca(X509 *cert);
-
-=head1 DESCRIPTION
-
-This function checks if given certificate is CA certificate (can be used
-to sign other certificates).
-
-=head1 RETURN VALUE
-
-Function return 0, if it is not CA certificate, 1 if it is proper X509v3
-CA certificate with B<basicConstraints> extension CA:TRUE,
-3, if it is self-signed X509 v1 certificate, 4, if it is certificate with
-B<keyUsage> extension with bit B<keyCertSign> set, but without
-B<basicConstraints>, and 5 if it has outdated Netscape Certificate Type
-extension telling that it is CA certificate.
-
-Actually, any non-zero value means that this certificate could have been
-used to sign other certificates.
-
-=head1 SEE ALSO
-
-L<X509_verify_cert(3)>,
-L<X509_check_issued(3)>,
-L<X509_check_purpose(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_check_host(X509 *, const char *name, size_t namelen,
- unsigned int flags, char **peername);
- int X509_check_email(X509 *, const char *address, size_t addresslen,
- unsigned int flags);
- int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen,
- unsigned int flags);
- int X509_check_ip_asc(X509 *, const char *address, unsigned int flags);
-
-=head1 DESCRIPTION
-
-The certificate matching functions are used to check whether a
-certificate matches a given host name, email address, or IP address.
-The validity of the certificate and its trust level has to be checked by
-other means.
-
-X509_check_host() checks if the certificate Subject Alternative
-Name (SAN) or Subject CommonName (CN) matches the specified host
-name, which must be encoded in the preferred name syntax described
-in section 3.5 of RFC 1034. By default, wildcards are supported
-and they match only in the left-most label; but they may match
-part of that label with an explicit prefix or suffix. For example,
-by default, the host B<name> "www.example.com" would match a
-certificate with a SAN or CN value of "*.example.com", "w*.example.com"
-or "*w.example.com".
-
-Per section 6.4.2 of RFC 6125, B<name> values representing international
-domain names must be given in A-label form. The B<namelen> argument
-must be the number of characters in the name string or zero in which
-case the length is calculated with strlen(B<name>). When B<name> starts
-with a dot (e.g ".example.com"), it will be matched by a certificate
-valid for any sub-domain of B<name>, (see also
-B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below).
-
-When the certificate is matched, and B<peername> is not NULL, a
-pointer to a copy of the matching SAN or CN from the peer certificate
-is stored at the address passed in B<peername>. The application
-is responsible for freeing the peername via OPENSSL_free() when it
-is no longer needed.
-
-X509_check_email() checks if the certificate matches the specified
-email B<address>. Only the mailbox syntax of RFC 822 is supported,
-comments are not allowed, and no attempt is made to normalize quoted
-characters. The B<addresslen> argument must be the number of
-characters in the address string or zero in which case the length
-is calculated with strlen(B<address>).
-
-X509_check_ip() checks if the certificate matches a specified IPv4 or
-IPv6 address. The B<address> array is in binary format, in network
-byte order. The length is either 4 (IPv4) or 16 (IPv6). Only
-explicitly marked addresses in the certificates are considered; IP
-addresses stored in DNS names and Common Names are ignored.
-
-X509_check_ip_asc() is similar, except that the NUL-terminated
-string B<address> is first converted to the internal representation.
-
-The B<flags> argument is usually 0. It can be the bitwise OR of the
-flags:
-
-=over 4
-
-=item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>,
-
-=item B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT>,
-
-=item B<X509_CHECK_FLAG_NO_WILDCARDS>,
-
-=item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>,
-
-=item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>.
-
-=item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>.
-
-=back
-
-The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function
-to consider the subject DN even if the certificate contains at least
-one subject alternative name of the right type (DNS name or email
-address as appropriate); the default is to ignore the subject DN
-when at least one corresponding subject alternative names is present.
-
-The B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT> flag causes the function to never
-consider the subject DN even if the certificate contains no subject alternative
-names of the right type (DNS name or email address as appropriate); the default
-is to use the subject DN when no corresponding subject alternative names are
-present.
-
-If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard
-expansion; this only applies to B<X509_check_host>.
-
-If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support
-for "*" as wildcard pattern in labels that have a prefix or suffix,
-such as: "www*" or "*www"; this only applies to B<X509_check_host>.
-
-If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that
-constitutes the complete label of a DNS name (e.g. "*.example.com")
-to match more than one label in B<name>; this flag only applies
-to B<X509_check_host>.
-
-If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name>
-values which start with ".", that would otherwise match any sub-domain
-in the peer certificate, to only match direct child sub-domains.
-Thus, for instance, with this flag set a B<name> of ".example.com"
-would match a peer certificate with a DNS name of "www.example.com",
-but would not match a peer certificate with a DNS name of
-"www.sub.example.com"; this flag only applies to B<X509_check_host>.
-
-=head1 RETURN VALUES
-
-The functions return 1 for a successful match, 0 for a failed match
-and -1 for an internal error: typically a memory allocation failure
-or an ASN.1 decoding error.
-
-All functions can also return -2 if the input is malformed. For example,
-X509_check_host() returns -2 if the provided B<name> contains embedded
-NULs.
-
-=head1 NOTES
-
-Applications are encouraged to use X509_VERIFY_PARAM_set1_host()
-rather than explicitly calling L<X509_check_host(3)>. Host name
-checks are out of scope with the DANE-EE(3) certificate usage,
-and the internal checks will be suppressed as appropriate when
-DANE support is added to OpenSSL.
-
-=head1 SEE ALSO
-
-L<SSL_get_verify_result(3)>,
-L<X509_VERIFY_PARAM_set1_host(3)>,
-L<X509_VERIFY_PARAM_add1_host(3)>,
-L<X509_VERIFY_PARAM_set1_email(3)>,
-L<X509_VERIFY_PARAM_set1_ip(3)>,
-L<X509_VERIFY_PARAM_set1_ipasc(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.0.2.
-
-=head1 COPYRIGHT
-
-Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_check_issued - checks if certificate is issued by another
-certificate
-
-=head1 SYNOPSIS
-
- #include <openssl/x509v3.h>
-
- int X509_check_issued(X509 *issuer, X509 *subject);
-
-
-=head1 DESCRIPTION
-
-This function checks if certificate I<subject> was issued using CA
-certificate I<issuer>. This function takes into account not only
-matching of issuer field of I<subject> with subject field of I<issuer>,
-but also compares B<authorityKeyIdentifier> extension of I<subject> with
-B<subjectKeyIdentifier> of I<issuer> if B<authorityKeyIdentifier>
-present in the I<subject> certificate and checks B<keyUsage> field of
-I<issuer>.
-
-=head1 RETURN VALUE
-
-Function return B<X509_V_OK> if certificate I<subject> is issued by
-I<issuer> or some B<X509_V_ERR*> constant to indicate an error.
-
-=head1 SEE ALSO
-
-L<X509_verify_cert(3)>,
-L<X509_check_ca(3)>,
-L<verify(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DECLARE_ASN1_FUNCTIONS,
-IMPLEMENT_ASN1_FUNCTIONS,
-ASN1_ITEM,
-ACCESS_DESCRIPTION_free,
-ACCESS_DESCRIPTION_new,
-ASIdOrRange_free,
-ASIdOrRange_new,
-ASIdentifierChoice_free,
-ASIdentifierChoice_new,
-ASIdentifiers_free,
-ASIdentifiers_new,
-ASRange_free,
-ASRange_new,
-AUTHORITY_INFO_ACCESS_free,
-AUTHORITY_INFO_ACCESS_new,
-AUTHORITY_KEYID_free,
-AUTHORITY_KEYID_new,
-BASIC_CONSTRAINTS_free,
-BASIC_CONSTRAINTS_new,
-CERTIFICATEPOLICIES_free,
-CERTIFICATEPOLICIES_new,
-CMS_ContentInfo_free,
-CMS_ContentInfo_new,
-CMS_ContentInfo_print_ctx,
-CMS_ReceiptRequest_free,
-CMS_ReceiptRequest_new,
-CRL_DIST_POINTS_free,
-CRL_DIST_POINTS_new,
-DIRECTORYSTRING_free,
-DIRECTORYSTRING_new,
-DISPLAYTEXT_free,
-DISPLAYTEXT_new,
-DIST_POINT_NAME_free,
-DIST_POINT_NAME_new,
-DIST_POINT_free,
-DIST_POINT_new,
-DSAparams_dup,
-ECPARAMETERS_free,
-ECPARAMETERS_new,
-ECPKPARAMETERS_free,
-ECPKPARAMETERS_new,
-EDIPARTYNAME_free,
-EDIPARTYNAME_new,
-ESS_CERT_ID_dup,
-ESS_CERT_ID_free,
-ESS_CERT_ID_new,
-ESS_ISSUER_SERIAL_dup,
-ESS_ISSUER_SERIAL_free,
-ESS_ISSUER_SERIAL_new,
-ESS_SIGNING_CERT_dup,
-ESS_SIGNING_CERT_free,
-ESS_SIGNING_CERT_new,
-EXTENDED_KEY_USAGE_free,
-EXTENDED_KEY_USAGE_new,
-GENERAL_NAMES_free,
-GENERAL_NAMES_new,
-GENERAL_NAME_dup,
-GENERAL_NAME_free,
-GENERAL_NAME_new,
-GENERAL_SUBTREE_free,
-GENERAL_SUBTREE_new,
-IPAddressChoice_free,
-IPAddressChoice_new,
-IPAddressFamily_free,
-IPAddressFamily_new,
-IPAddressOrRange_free,
-IPAddressOrRange_new,
-IPAddressRange_free,
-IPAddressRange_new,
-ISSUING_DIST_POINT_free,
-ISSUING_DIST_POINT_new,
-NAME_CONSTRAINTS_free,
-NAME_CONSTRAINTS_new,
-NETSCAPE_CERT_SEQUENCE_free,
-NETSCAPE_CERT_SEQUENCE_new,
-NETSCAPE_SPKAC_free,
-NETSCAPE_SPKAC_new,
-NETSCAPE_SPKI_free,
-NETSCAPE_SPKI_new,
-NOTICEREF_free,
-NOTICEREF_new,
-OCSP_BASICRESP_free,
-OCSP_BASICRESP_new,
-OCSP_CERTID_dup,
-OCSP_CERTID_new,
-OCSP_CERTSTATUS_free,
-OCSP_CERTSTATUS_new,
-OCSP_CRLID_free,
-OCSP_CRLID_new,
-OCSP_ONEREQ_free,
-OCSP_ONEREQ_new,
-OCSP_REQINFO_free,
-OCSP_REQINFO_new,
-OCSP_RESPBYTES_free,
-OCSP_RESPBYTES_new,
-OCSP_RESPDATA_free,
-OCSP_RESPDATA_new,
-OCSP_RESPID_free,
-OCSP_RESPID_new,
-OCSP_RESPONSE_new,
-OCSP_REVOKEDINFO_free,
-OCSP_REVOKEDINFO_new,
-OCSP_SERVICELOC_free,
-OCSP_SERVICELOC_new,
-OCSP_SIGNATURE_free,
-OCSP_SIGNATURE_new,
-OCSP_SINGLERESP_free,
-OCSP_SINGLERESP_new,
-OTHERNAME_free,
-OTHERNAME_new,
-PBE2PARAM_free,
-PBE2PARAM_new,
-PBEPARAM_free,
-PBEPARAM_new,
-PBKDF2PARAM_free,
-PBKDF2PARAM_new,
-PKCS12_BAGS_free,
-PKCS12_BAGS_new,
-PKCS12_MAC_DATA_free,
-PKCS12_MAC_DATA_new,
-PKCS12_SAFEBAG_free,
-PKCS12_SAFEBAG_new,
-PKCS12_free,
-PKCS12_new,
-PKCS7_DIGEST_free,
-PKCS7_DIGEST_new,
-PKCS7_ENCRYPT_free,
-PKCS7_ENCRYPT_new,
-PKCS7_ENC_CONTENT_free,
-PKCS7_ENC_CONTENT_new,
-PKCS7_ENVELOPE_free,
-PKCS7_ENVELOPE_new,
-PKCS7_ISSUER_AND_SERIAL_free,
-PKCS7_ISSUER_AND_SERIAL_new,
-PKCS7_RECIP_INFO_free,
-PKCS7_RECIP_INFO_new,
-PKCS7_SIGNED_free,
-PKCS7_SIGNED_new,
-PKCS7_SIGNER_INFO_free,
-PKCS7_SIGNER_INFO_new,
-PKCS7_SIGN_ENVELOPE_free,
-PKCS7_SIGN_ENVELOPE_new,
-PKCS7_dup,
-PKCS7_free,
-PKCS7_new,
-PKCS7_print_ctx,
-PKCS8_PRIV_KEY_INFO_free,
-PKCS8_PRIV_KEY_INFO_new,
-PKEY_USAGE_PERIOD_free,
-PKEY_USAGE_PERIOD_new,
-POLICYINFO_free,
-POLICYINFO_new,
-POLICYQUALINFO_free,
-POLICYQUALINFO_new,
-POLICY_CONSTRAINTS_free,
-POLICY_CONSTRAINTS_new,
-POLICY_MAPPING_free,
-POLICY_MAPPING_new,
-PROXY_CERT_INFO_EXTENSION_free,
-PROXY_CERT_INFO_EXTENSION_new,
-PROXY_POLICY_free,
-PROXY_POLICY_new,
-RSAPrivateKey_dup,
-RSAPublicKey_dup,
-RSA_OAEP_PARAMS_free,
-RSA_OAEP_PARAMS_new,
-RSA_PSS_PARAMS_free,
-RSA_PSS_PARAMS_new,
-SCT_LIST_free,
-SXNETID_free,
-SXNETID_new,
-SXNET_free,
-SXNET_new,
-TLS_FEATURE_free,
-TLS_FEATURE_new,
-TS_ACCURACY_dup,
-TS_ACCURACY_free,
-TS_ACCURACY_new,
-TS_MSG_IMPRINT_dup,
-TS_MSG_IMPRINT_free,
-TS_MSG_IMPRINT_new,
-TS_REQ_dup,
-TS_REQ_free,
-TS_REQ_new,
-TS_RESP_dup,
-TS_RESP_free,
-TS_RESP_new,
-TS_STATUS_INFO_dup,
-TS_STATUS_INFO_free,
-TS_STATUS_INFO_new,
-TS_TST_INFO_dup,
-TS_TST_INFO_free,
-TS_TST_INFO_new,
-USERNOTICE_free,
-USERNOTICE_new,
-X509_ALGOR_free,
-X509_ALGOR_new,
-X509_ATTRIBUTE_dup,
-X509_ATTRIBUTE_free,
-X509_ATTRIBUTE_new,
-X509_CERT_AUX_free,
-X509_CERT_AUX_new,
-X509_CINF_free,
-X509_CINF_new,
-X509_CRL_INFO_free,
-X509_CRL_INFO_new,
-X509_CRL_METHOD_free,
-X509_CRL_METHOD_new,
-X509_CRL_dup,
-X509_CRL_free,
-X509_CRL_new,
-X509_EXTENSION_dup,
-X509_EXTENSION_free,
-X509_EXTENSION_new,
-X509_NAME_ENTRY_dup,
-X509_NAME_ENTRY_free,
-X509_NAME_ENTRY_new,
-X509_NAME_dup,
-X509_NAME_free,
-X509_NAME_new,
-X509_REQ_INFO_free,
-X509_REQ_INFO_new,
-X509_REQ_dup,
-X509_REQ_free,
-X509_REQ_new,
-X509_REVOKED_dup,
-X509_REVOKED_free,
-X509_REVOKED_new,
-X509_SIG_free,
-X509_SIG_new,
-X509_VAL_free,
-X509_VAL_new,
-X509_dup,
-- ASN1 object utilities
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- #include <openssl/asn1t.h>
-
- DECLARE_ASN1_FUNCTIONS(type)
- IMPLEMENT_ASN1_FUNCTIONS(stname)
-
- typedef struct ASN1_ITEM_st ASN1_ITEM;
-
- extern const ASN1_ITEM TYPE_it;
- TYPE *TYPE_new(void);
- TYPE *TYPE_dup(TYPE *a);
- void TYPE_free(TYPE *a);
- int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx);
-
-=head1 DESCRIPTION
-
-In the description below, I<TYPE> is used
-as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
-
-The OpenSSL ASN1 parsing library templates are like a data-driven bytecode
-interpreter.
-Every ASN1 object as a global variable, TYPE_it, that describes the item
-such as its fields. (On systems which cannot export variables from shared
-libraries, the global is instead a function which returns a pointer to a
-static variable.
-
-The macro DECLARE_ASN1_FUNCTIONS() is typically used in header files
-to generate the function declarations.
-
-The macro IMPLEMENT_ASN1_FUNCTIONS() is used once in a source file
-to generate the function bodies.
-
-
-TYPE_new() allocates an empty object of the indicated type.
-The object returned must be released by calling TYPE_free().
-
-TYPE_dup() copies an existing object.
-
-TYPE_free() releases the object and all pointers and sub-objects
-within it.
-
-TYPE_print_ctx() prints the object B<a> on the specified BIO B<out>.
-Each line will be prefixed with B<indent> spaces.
-The B<pctx> specifies the printing context and is for internal
-use; use NULL to get the default behavior. If a print function is
-user-defined, then pass in any B<pctx> down to any nested calls.
-
-=head1 RETURN VALUES
-
-TYPE_new() and TYPE_dup() return a pointer to the object or NULL on failure.
-
-TYPE_print_ctx() returns 1 on success or zero on failure.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get0_signature, X509_get_signature_nid, X509_get0_tbs_sigalg,
-X509_REQ_get0_signature, X509_REQ_get_signature_nid, X509_CRL_get0_signature,
-X509_CRL_get_signature_nid - signature information
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- void X509_get0_signature(const ASN1_BIT_STRING **psig,
- const X509_ALGOR **palg,
- const X509 *x);
- int X509_get_signature_nid(const X509 *x);
- const X509_ALGOR *X509_get0_tbs_sigalg(const X509 *x);
-
- void X509_REQ_get0_signature(const X509_REQ *crl,
- const ASN1_BIT_STRING **psig,
- const X509_ALGOR **palg);
- int X509_REQ_get_signature_nid(const X509_REQ *crl);
-
- void X509_CRL_get0_signature(const X509_CRL *crl,
- const ASN1_BIT_STRING **psig,
- const X509_ALGOR **palg);
- int X509_CRL_get_signature_nid(const X509_CRL *crl);
-
-=head1 DESCRIPTION
-
-X509_get0_signature() sets B<*psig> to the signature of B<x> and B<*palg>
-to the signature algorithm of B<x>. The values returned are internal
-pointers which B<MUST NOT> be freed up after the call.
-
-X509_get0_tbs_sigalg() returns the signature algorithm in the signed
-portion of B<x>.
-
-X509_get_signature_nid() returns the NID corresponding to the signature
-algorithm of B<x>.
-
-X509_REQ_get0_signature(), X509_REQ_get_signature_nid()
-X509_CRL_get0_signature() and X509_CRL_get_signature_nid() perform the
-same function for certificate requests and CRLs.
-
-=head1 NOTES
-
-These functions provide lower level access to signatures in certificates
-where an application wishes to analyse or generate a signature in a form
-where X509_sign() et al is not appropriate (for example a non standard
-or unsupported format).
-
-=head1 RETURN VALUES
-
-X509_get_signature_nid(), X509_REQ_get_signature_nid() and
-X509_CRL_get_signature_nid() return a NID.
-
-X509_get0_signature(), X509_REQ_get0_signature() and
-X509_CRL_get0_signature() do not return values.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 HISTORY
-
-X509_get0_signature() and X509_get_signature_nid() were first added to
-OpenSSL 1.0.2.
-
-X509_REQ_get0_signature(), X509_REQ_get_signature_nid(),
-X509_CRL_get0_signature() and X509_CRL_get_signature_nid() were first added
-to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get0_uids - get certificate unique identifiers
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- void X509_get0_uids(const X509 *x, const ASN1_BIT_STRING **piuid,
- const ASN1_BIT_STRING **psuid);
-
-=head1 DESCRIPTION
-
-X509_get0_uids() sets B<*piuid> and B<*psuid> to the issuer and subject unique
-identifiers of certificate B<x> or NULL if the fields are not present.
-
-=head1 NOTES
-
-The issuer and subject unique identifier fields are very rarely encountered in
-practice outside test cases.
-
-=head1 RETURN VALUES
-
-X509_get0_uids() does not return a value.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get0_subject_key_id,
-X509_get_pathlen,
-X509_get_extension_flags,
-X509_get_key_usage,
-X509_get_extended_key_usage,
-X509_set_proxy_flag,
-X509_set_proxy_pathlen,
-X509_get_proxy_pathlen - retrieve certificate extension data
-
-=head1 SYNOPSIS
-
- #include <openssl/x509v3.h>
-
- long X509_get_pathlen(X509 *x);
- uint32_t X509_get_extension_flags(X509 *x);
- uint32_t X509_get_key_usage(X509 *x);
- uint32_t X509_get_extended_key_usage(X509 *x);
- const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
- void X509_set_proxy_flag(X509 *x);
- void X509_set_proxy_pathlen(int l);
- long X509_get_proxy_pathlen(X509 *x);
-
-=head1 DESCRIPTION
-
-These functions retrieve information related to commonly used certificate extensions.
-
-X509_get_pathlen() retrieves the path length extension from a certificate.
-This extension is used to limit the length of a cert chain that may be
-issued from that CA.
-
-X509_get_extension_flags() retrieves general information about a certificate,
-it will return one or more of the following flags ored together.
-
-=over 4
-
-=item B<EXFLAG_V1>
-
-The certificate is an obsolete version 1 certificate.
-
-=item B<EXFLAG_BCONS>
-
-The certificate contains a basic constraints extension.
-
-=item B<EXFLAG_CA>
-
-The certificate contains basic constraints and asserts the CA flag.
-
-=item B<EXFLAG_PROXY>
-
-The certificate is a valid proxy certificate.
-
-=item B<EXFLAG_SI>
-
-The certificate is self issued (that is subject and issuer names match).
-
-=item B<EXFLAG_SS>
-
-The subject and issuer names match and extension values imply it is self
-signed.
-
-=item B<EXFLAG_FRESHEST>
-
-The freshest CRL extension is present in the certificate.
-
-=item B<EXFLAG_CRITICAL>
-
-The certificate contains an unhandled critical extension.
-
-=item B<EXFLAG_INVALID>
-
-Some certificate extension values are invalid or inconsistent. The
-certificate should be rejected.
-
-=item B<EXFLAG_KUSAGE>
-
-The certificate contains a key usage extension. The value can be retrieved
-using X509_get_key_usage().
-
-=item B<EXFLAG_XKUSAGE>
-
-The certificate contains an extended key usage extension. The value can be
-retrieved using X509_get_extended_key_usage().
-
-=back
-
-X509_get_key_usage() returns the value of the key usage extension. If key
-usage is present will return zero or more of the flags:
-B<KU_DIGITAL_SIGNATURE>, B<KU_NON_REPUDIATION>, B<KU_KEY_ENCIPHERMENT>,
-B<KU_DATA_ENCIPHERMENT>, B<KU_KEY_AGREEMENT>, B<KU_KEY_CERT_SIGN>,
-B<KU_CRL_SIGN>, B<KU_ENCIPHER_ONLY> or B<KU_DECIPHER_ONLY> corresponding to
-individual key usage bits. If key usage is absent then B<UINT32_MAX> is
-returned.
-
-X509_get_extended_key_usage() returns the value of the extended key usage
-extension. If extended key usage is present it will return zero or more of the
-flags: B<XKU_SSL_SERVER>, B<XKU_SSL_CLIENT>, B<XKU_SMIME>, B<XKU_CODE_SIGN>
-B<XKU_OCSP_SIGN>, B<XKU_TIMESTAMP>, B<XKU_DVCS> or B<XKU_ANYEKU>. These
-correspond to the OIDs B<id-kp-serverAuth>, B<id-kp-clientAuth>,
-B<id-kp-emailProtection>, B<id-kp-codeSigning>, B<id-kp-OCSPSigning>,
-B<id-kp-timeStamping>, B<id-kp-dvcs> and B<anyExtendedKeyUsage> respectively.
-Additionally B<XKU_SGC> is set if either Netscape or Microsoft SGC OIDs are
-present.
-
-X509_get_extended_key_usage() return an internal pointer to the subject key
-identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension
-is not present or cannot be parsed.
-
-X509_set_proxy_flag() marks the certificate with the B<EXFLAG_PROXY> flag.
-This is for the users who need to mark non-RFC3820 proxy certificates as
-such, as OpenSSL only detects RFC3820 compliant ones.
-
-X509_set_proxy_pathlen() sets the proxy certificate path length for the given
-certificate B<x>. This is for the users who need to mark non-RFC3820 proxy
-certificates as such, as OpenSSL only detects RFC3820 compliant ones.
-
-X509_get_proxy_pathlen() returns the proxy certificate path length for the
-given certificate B<x> if it is a proxy certificate.
-
-=head1 NOTES
-
-The value of the flags correspond to extension values which are cached
-in the B<X509> structure. If the flags returned do not provide sufficient
-information an application should examine extension values directly
-for example using X509_get_ext_d2i().
-
-If the key usage or extended key usage extension is absent then typically usage
-is unrestricted. For this reason X509_get_key_usage() and
-X509_get_extended_key_usage() return B<UINT32_MAX> when the corresponding
-extension is absent. Applications can additionally check the return value of
-X509_get_extension_flags() and take appropriate action is an extension is
-absent.
-
-If X509_get0_subject_key_id() returns B<NULL> then the extension may be
-absent or malformed. Applications can determine the precise reason using
-X509_get_ext_d2i().
-
-=head1 RETURN VALUE
-
-X509_get_pathlen() returns the path length value, or -1 if the extension
-is not present.
-
-X509_get_extension_flags(), X509_get_key_usage() and
-X509_get_extended_key_usage() return sets of flags corresponding to the
-certificate extension values.
-
-X509_get0_subject_key_id() returns the subject key identifier as a
-pointer to an B<ASN1_OCTET_STRING> structure or B<NULL> if the extension
-is absent or an error occurred during parsing.
-
-X509_get_proxy_pathlen() returns the path length value if the given
-certificate is a proxy one and has a path length set, and -1 otherwise.
-
-=head1 SEE ALSO
-
-L<X509_check_purpose(3)>
-
-=head1 HISTORY
-
-X509_get_pathlen(), X509_set_proxy_flag(), X509_set_proxy_pathlen() and
-X509_get_proxy_pathlen() were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get0_notBefore, X509_getm_notBefore, X509_get0_notAfter,
-X509_getm_notAfter, X509_set1_notBefore, X509_set1_notAfter,
-X509_CRL_get0_lastUpdate, X509_CRL_get0_nextUpdate, X509_CRL_set1_lastUpdate,
-X509_CRL_set1_nextUpdate - get or set certificate or CRL dates
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- const ASN1_TIME *X509_get0_notBefore(const X509 *x);
- const ASN1_TIME *X509_get0_notAfter(const X509 *x);
-
- ASN1_TIME *X509_getm_notBefore(const X509 *x);
- ASN1_TIME *X509_getm_notAfter(const X509 *x);
-
- int X509_set1_notBefore(X509 *x, const ASN1_TIME *tm);
- int X509_set1_notAfter(X509 *x, const ASN1_TIME *tm);
-
- const ASN1_TIME *X509_CRL_get0_lastUpdate(const X509_CRL *crl);
- const ASN1_TIME *X509_CRL_get0_nextUpdate(const X509_CRL *crl);
-
- int X509_CRL_set1_lastUpdate(X509_CRL *x, const ASN1_TIME *tm);
- int X509_CRL_set1_nextUpdate(X509_CRL *x, const ASN1_TIME *tm);
-
-=head1 DESCRIPTION
-
-X509_get0_notBefore() and X509_get0_notAfter() return the B<notBefore>
-and B<notAfter> fields of certificate B<x> respectively. The value
-returned is an internal pointer which must not be freed up after
-the call.
-
-X509_getm_notBefore() and X509_getm_notAfter() are similar to
-X509_get0_notBefore() and X509_get0_notAfter() except they return
-non-constant mutable references to the associated date field of
-the certficate.
-
-X509_set1_notBefore() and X509_set1_notAfter() set the B<notBefore>
-and B<notAfter> fields of B<x> to B<tm>. Ownership of the passed
-parameter B<tm> is not transferred by these functions so it must
-be freed up after the call.
-
-X509_CRL_get0_lastUpdate() and X509_CRL_get0_nextUpdate() return the
-B<lastUpdate> and B<nextUpdate> fields of B<crl>. The value
-returned is an internal pointer which must not be freed up after
-the call. If the B<nextUpdate> field is absent from B<crl> then
-B<NULL> is returned.
-
-X509_CRL_set1_lastUpdate() and X509_CRL_set1_nextUpdate() set the B<lastUpdate>
-and B<nextUpdate> fields of B<crl> to B<tm>. Ownership of the passed parameter
-B<tm> is not transferred by these functions so it must be freed up after the
-call.
-
-=head1 RETURN VALUES
-
-X509_get0_notBefore(), X509_get0_notAfter() and X509_CRL_get0_lastUpdate()
-return a pointer to an B<ASN1_TIME> structure.
-
-X509_CRL_get0_lastUpdate() return a pointer to an B<ASN1_TIME> structure
-or NULL if the B<lastUpdate> field is absent.
-
-X509_set1_notBefore(), X509_set1_notAfter(), X509_CRL_set1_lastUpdate() and
-X509_CRL_set1_nextUpdate() return 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 HISTORY
-
-These functions are available in all versions of OpenSSL.
-
-X509_get_notBefore() and X509_get_notAfter() were deprecated in OpenSSL
-1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get_pubkey, X509_get0_pubkey, X509_set_pubkey, X509_get_X509_PUBKEY,
-X509_REQ_get_pubkey, X509_REQ_get0_pubkey, X509_REQ_set_pubkey,
-X509_REQ_get_X509_PUBKEY - get or set certificate or certificate request
-public key
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- EVP_PKEY *X509_get_pubkey(X509 *x);
- EVP_PKEY *X509_get0_pubkey(const X509 *x);
- int X509_set_pubkey(X509 *x, EVP_PKEY *pkey);
- X509_PUBKEY *X509_get_X509_PUBKEY(X509 *x);
-
- EVP_PKEY *X509_REQ_get_pubkey(X509_REQ *req);
- EVP_PKEY *X509_REQ_get0_pubkey(X509_REQ *req);
- int X509_REQ_set_pubkey(X509_REQ *x, EVP_PKEY *pkey);
- X509_PUBKEY *X509_REQ_get_X509_PUBKEY(X509_REQ *x);
-
-=head1 DESCRIPTION
-
-X509_get_pubkey() attempts to decode the public key for certificate B<x>. If
-successful it returns the public key as an B<EVP_PKEY> pointer with its
-reference count incremented: this means the returned key must be freed up
-after use. X509_get0_pubkey() is similar except it does B<not> increment
-the reference count of the returned B<EVP_PKEY> so it must not be freed up
-after use.
-
-X509_get_X509_PUBKEY() returns an internal pointer to the B<X509_PUBKEY>
-structure which encodes the certificate of B<x>. The returned value
-must not be freed up after use.
-
-X509_set_pubkey() attempts to set the public key for certificate B<x> to
-B<pkey>. The key B<pkey> should be freed up after use.
-
-X509_REQ_get_pubkey(), X509_REQ_get0_pubkey(), X509_REQ_set_pubkey() and
-X509_REQ_get_X509_PUBKEY() are similar but operate on certificate request B<req>.
-
-=head1 NOTES
-
-The first time a public key is decoded the B<EVP_PKEY> structure is
-cached in the certificate or certificate request itself. Subsequent calls
-return the cached structure with its reference count incremented to
-improve performance.
-
-=head1 RETURN VALUES
-
-X509_get_pubkey(), X509_get0_pubkey(), X509_get_X509_PUBKEY(),
-X509_REQ_get_pubkey() and X509_REQ_get_X509_PUBKEY() return a public key or
-B<NULL> if an error occurred.
-
-X509_set_pubkey() and X509_REQ_set_pubkey() return 1 for success and 0
-for failure.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get_serialNumber,
-X509_get0_serialNumber,
-X509_set_serialNumber
-- get or set certificate serial number
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- ASN1_INTEGER *X509_get_serialNumber(X509 *x);
- const ASN1_INTEGER *X509_get0_serialNumber(const X509 *x);
- int X509_set_serialNumber(X509 *x, ASN1_INTEGER *serial);
-
-=head1 DESCRIPTION
-
-X509_get_serialNumber() returns the serial number of certificate B<x> as an
-B<ASN1_INTEGER> structure which can be examined or initialised. The value
-returned is an internal pointer which B<MUST NOT> be freed up after the call.
-
-X509_get0_serialNumber() is the same as X509_get_serialNumber() except it
-accepts a const parameter and returns a const result.
-
-X509_set_serialNumber() sets the serial number of certificate B<x> to
-B<serial>. A copy of the serial number is used internally so B<serial> should
-be freed up after use.
-
-=head1 RETURN VALUES
-
-X509_get_serialNumber() and X509_get0_serialNumber() return an B<ASN1_INTEGER>
-structure.
-
-X509_set_serialNumber() returns 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 HISTORY
-
-X509_get_serialNumber() and X509_set_serialNumber() are available in
-all versions of OpenSSL. X509_get0_serialNumber() was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get_subject_name, X509_set_subject_name, X509_get_issuer_name,
-X509_set_issuer_name, X509_REQ_get_subject_name, X509_REQ_set_subject_name,
-X509_CRL_get_issuer, X509_CRL_set_issuer_name - get and set issuer or
-subject names
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- X509_NAME *X509_get_subject_name(const X509 *x);
- int X509_set_subject_name(X509 *x, X509_NAME *name);
-
- X509_NAME *X509_get_issuer_name(const X509 *x);
- int X509_set_issuer_name(X509 *x, X509_NAME *name);
-
- X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req);
- int X509_REQ_set_subject_name(X509_REQ *req, X509_NAME *name);
-
- X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl);
- int X509_CRL_set_issuer_name(X509_CRL *x, X509_NAME *name);
-
-=head1 DESCRIPTION
-
-X509_get_subject_name() returns the subject name of certificate B<x>. The
-returned value is an internal pointer which B<MUST NOT> be freed.
-
-X509_set_subject_name() sets the issuer name of certificate B<x> to
-B<name>. The B<name> parameter is copied internally and should be freed
-up when it is no longer needed.
-
-X509_get_issuer_name() and X509_set_issuer_name() are identical to
-X509_get_subject_name() and X509_set_subject_name() except the get and
-set the issuer name of B<x>.
-
-Similarly X509_REQ_get_subject_name(), X509_REQ_set_subject_name(),
- X509_CRL_get_issuer() and X509_CRL_set_issuer_name() get or set the subject
-or issuer names of certificate requests of CRLs respectively.
-
-=head1 RETURN VALUES
-
-X509_get_subject_name(), X509_get_issuer_name(), X509_REQ_get_subject_name()
-and X509_CRL_get_issuer() return an B<X509_NAME> pointer.
-
-X509_set_subject_name(), X509_set_issuer_name(), X509_REQ_set_subject_name()
-and X509_CRL_set_issuer_name() return 1 for success and 0 for failure.
-
-=head1 HISTORY
-
-X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in
-earlier versions.
-
-X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was first added
-to OpenSSL 1.0.0 as a macro.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>, L<d2i_X509(3)>
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_get_version, X509_set_version, X509_REQ_get_version, X509_REQ_set_version,
-X509_CRL_get_version, X509_CRL_set_version - get or set certificate,
-certificate request or CRL version
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- long X509_get_version(const X509 *x);
- int X509_set_version(X509 *x, long version);
-
- long X509_REQ_get_version(const X509_REQ *req);
- int X509_REQ_set_version(X509_REQ *x, long version);
-
- long X509_CRL_get_version(const X509_CRL *crl);
- int X509_CRL_set_version(X509_CRL *x, long version);
-
-=head1 DESCRIPTION
-
-X509_get_version() returns the numerical value of the version field of
-certificate B<x>. Note: this is defined by standards (X.509 et al) to be one
-less than the certificate version. So a version 3 certificate will return 2 and
-a version 1 certificate will return 0.
-
-X509_set_version() sets the numerical value of the version field of certificate
-B<x> to B<version>.
-
-Similarly X509_REQ_get_version(), X509_REQ_set_version(),
-X509_CRL_get_version() and X509_CRL_set_version() get and set the version
-number of certificate requests and CRLs.
-
-=head1 NOTES
-
-The version field of certificates, certificate requests and CRLs has a
-DEFAULT value of B<v1(0)> meaning the field should be omitted for version
-1. This is handled transparently by these functions.
-
-=head1 RETURN VALUES
-
-X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version()
-return the numerical value of the version field.
-
-X509_set_version(), X509_REQ_set_version() and X509_CRL_set_version()
-return 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 HISTORY
-
-X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version() are
-functions in OpenSSL 1.1.0, in previous versions they were macros.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_chain_up_ref,
-X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- X509 *X509_new(void);
- void X509_free(X509 *a);
- int X509_up_ref(X509 *a);
- STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
-
-=head1 DESCRIPTION
-
-The X509 ASN1 allocation routines, allocate and free an
-X509 structure, which represents an X509 certificate.
-
-X509_new() allocates and initializes a X509 structure with reference count
-B<1>.
-
-X509_free() decrements the reference count of B<X509> structure B<a> and
-frees it up if the reference count is zero. If B<a> is NULL nothing is done.
-
-X509_up_ref() increments the reference count of B<a>.
-
-X509_chain_up_ref() increases the reference count of all certificates in
-chain B<x> and returns a copy of the stack.
-
-=head1 NOTES
-
-The function X509_up_ref() if useful if a certificate structure is being
-used by several different operations each of which will free it up after
-use: this avoids the need to duplicate the entire certificate structure.
-
-The function X509_chain_up_ref() doesn't just up the reference count of
-each certificate it also returns a copy of the stack, using sk_X509_dup(),
-but it serves a similar purpose: the returned chain persists after the
-original has been freed.
-
-=head1 RETURN VALUES
-
-If the allocation fails, X509_new() returns B<NULL> and sets an error
-code that can be obtained by L<ERR_get_error(3)>.
-Otherwise it returns a pointer to the newly allocated structure.
-
-X509_up_ref() returns 1 for success and 0 for failure.
-
-X509_chain_up_ref() returns a copy of the stack or B<NULL> if an error
-occurred.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_sign, X509_sign_ctx, X509_verify, X509_REQ_sign, X509_REQ_sign_ctx,
-X509_REQ_verify, X509_CRL_sign, X509_CRL_sign_ctx, X509_CRL_verify -
-sign or verify certificate, certificate request or CRL signature
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_sign(X509 *x, EVP_PKEY *pkey, const EVP_MD *md);
- int X509_sign_ctx(X509 *x, EVP_MD_CTX *ctx);
- int X509_verify(X509 *a, EVP_PKEY *r);
-
- int X509_REQ_sign(X509_REQ *x, EVP_PKEY *pkey, const EVP_MD *md);
- int X509_REQ_sign_ctx(X509_REQ *x, EVP_MD_CTX *ctx);
- int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r);
-
- int X509_CRL_sign(X509_CRL *x, EVP_PKEY *pkey, const EVP_MD *md);
- int X509_CRL_sign_ctx(X509_CRL *x, EVP_MD_CTX *ctx);
- int X509_CRL_verify(X509_CRL *a, EVP_PKEY *r);
-
-=head1 DESCRIPTION
-
-X509_sign() signs certificate B<x> using private key B<pkey> and message
-digest B<md> and sets the signature in B<x>. X509_sign_ctx() also signs
-certificate B<x> but uses the parameters contained in digest context B<ctx>.
-
-X509_verify() verifies the signature of certificate B<x> using public key
-B<pkey>. Only the signature is checked: no other checks (such as certificate
-chain validity) are performed.
-
-X509_REQ_sign(), X509_REQ_sign_ctx(), X509_REQ_verify(),
-X509_CRL_sign(), X509_CRL_sign_ctx() and X509_CRL_verify() sign and verify
-certificate requests and CRLs respectively.
-
-=head1 NOTES
-
-X509_sign_ctx() is used where the default parameters for the corresponding
-public key and digest are not suitable. It can be used to sign keys using
-RSA-PSS for example.
-
-For efficiency reasons and to work around ASN.1 encoding issues the encoding
-of the signed portion of a certificate, certificate request and CRL is cached
-internally. If the signed portion of the structure is modified the encoding
-is not always updated meaning a stale version is sometimes used. This is not
-normally a problem because modifying the signed portion will invalidate the
-signature and signing will always update the encoding.
-
-=head1 RETURN VALUES
-
-X509_sign(), X509_sign_ctx(), X509_REQ_sign(), X509_REQ_sign_ctx(),
-X509_CRL_sign() and X509_CRL_sign_ctx() return the size of the signature
-in bytes for success and zero for failure.
-
-X509_verify(), X509_REQ_verify() and X509_CRL_verify() return 1 if the
-signature is valid and 0 if the signature check fails. If the signature
-could not be checked at all because it was invalid or some other error
-occurred then -1 is returned.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>,
-L<ERR_get_error(3)>,
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 HISTORY
-
-X509_sign(), X509_REQ_sign() and X509_CRL_sign() are available in all
-versions of OpenSSL.
-
-X509_sign_ctx(), X509_REQ_sign_ctx() and X509_CRL_sign_ctx() were first added
-to OpenSSL 1.0.1.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509_verify_cert - discover and verify X509 certificate chain
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509_verify_cert(X509_STORE_CTX *ctx);
-
-=head1 DESCRIPTION
-
-The X509_verify_cert() function attempts to discover and validate a
-certificate chain based on parameters in B<ctx>. A complete description of
-the process is contained in the L<verify(1)> manual page.
-
-=head1 RETURN VALUES
-
-If a complete chain can be built and validated this function returns 1,
-otherwise it return zero, in exceptional circumstances it can also
-return a negative code.
-
-If the function fails additional error information can be obtained by
-examining B<ctx> using, for example X509_STORE_CTX_get_error().
-
-=head1 NOTES
-
-Applications rarely call this function directly but it is used by
-OpenSSL internally for certificate validation, in both the S/MIME and
-SSL/TLS code.
-
-A negative return value from X509_verify_cert() can occur if it is invoked
-incorrectly, such as with no certificate set in B<ctx>, or when it is called
-twice in succession without reinitialising B<ctx> for the second call.
-A negative return value can also happen due to internal resource problems or if
-a retry operation is requested during internal lookups (which never happens
-with standard lookup methods).
-Applications must check for <= 0 return value on error.
-
-=head1 BUGS
-
-This function uses the header B<x509.h> as opposed to most chain verification
-functions which use B<x509_vfy.h>.
-
-=head1 SEE ALSO
-
-L<X509_STORE_CTX_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID,
-X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext,
-X509v3_add_ext, X509_get_ext_count, X509_get_ext,
-X509_get_ext_by_NID, X509_get_ext_by_OBJ, X509_get_ext_by_critical,
-X509_delete_ext, X509_add_ext, X509_CRL_get_ext_count, X509_CRL_get_ext,
-X509_CRL_get_ext_by_NID, X509_CRL_get_ext_by_OBJ, X509_CRL_get_ext_by_critical,
-X509_CRL_delete_ext, X509_CRL_add_ext, X509_REVOKED_get_ext_count,
-X509_REVOKED_get_ext, X509_REVOKED_get_ext_by_NID, X509_REVOKED_get_ext_by_OBJ,
-X509_REVOKED_get_ext_by_critical, X509_REVOKED_delete_ext,
-X509_REVOKED_add_ext - extension stack utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x);
- X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc);
-
- int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x,
- int nid, int lastpos);
- int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x,
- const ASN1_OBJECT *obj, int lastpos);
- int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x,
- int crit, int lastpos);
- X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc);
- STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x,
- X509_EXTENSION *ex, int loc);
-
- int X509_get_ext_count(const X509 *x);
- X509_EXTENSION *X509_get_ext(const X509 *x, int loc);
- int X509_get_ext_by_NID(const X509 *x, int nid, int lastpos);
- int X509_get_ext_by_OBJ(const X509 *x, const ASN1_OBJECT *obj, int lastpos);
- int X509_get_ext_by_critical(const X509 *x, int crit, int lastpos);
- X509_EXTENSION *X509_delete_ext(X509 *x, int loc);
- int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc);
-
- int X509_CRL_get_ext_count(const X509_CRL *x);
- X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc);
- int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos);
- int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, int lastpos);
- int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos);
- X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc);
- int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc);
-
- int X509_REVOKED_get_ext_count(const X509_REVOKED *x);
- X509_EXTENSION *X509_REVOKED_get_ext(const X509_REVOKED *x, int loc);
- int X509_REVOKED_get_ext_by_NID(const X509_REVOKED *x, int nid, int lastpos);
- int X509_REVOKED_get_ext_by_OBJ(const X509_REVOKED *x, const ASN1_OBJECT *obj,
- int lastpos);
- int X509_REVOKED_get_ext_by_critical(const X509_REVOKED *x, int crit, int lastpos);
- X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc);
- int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc);
-
-=head1 DESCRIPTION
-
-X509v3_get_ext_count() retrieves the number of extensions in B<x>.
-
-X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc>
-can take any value from B<0> to X509_get_ext_count(x) - 1. The returned
-extension is an internal pointer which B<must not> be freed up by the
-application.
-
-X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension
-with B<nid> or B<obj> from extension stack B<x>. The search starts from the
-extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If
-the extension is found its index is returned otherwise B<-1> is returned.
-
-X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it
-looks for an extension of criticality B<crit>. A zero value for B<crit>
-looks for a non-critical extension a non-zero value looks for a critical
-extension.
-
-X509v3_delete_ext() deletes the extension with index B<loc> from B<x>. The
-deleted extension is returned and must be freed by the caller. If B<loc>
-is in invalid index value B<NULL> is returned.
-
-X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If
-B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL>
-a new stack will be allocated. The passed extension B<ex> is duplicated
-internally so it must be freed after use.
-
-X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(),
-X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext()
-and X509_add_ext() operate on the extensions of certificate B<x> they are
-otherwise identical to the X509v3 functions.
-
-X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(),
-X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(),
-X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of
-CRL B<x> they are otherwise identical to the X509v3 functions.
-
-X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(),
-X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(),
-X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and
-X509_REVOKED_add_ext() operate on the extensions of CRL entry B<x>
-they are otherwise identical to the X509v3 functions.
-
-=head1 NOTES
-
-These functions are used to examine stacks of extensions directly. Many
-applications will want to parse or encode and add an extension: they should
-use the extension encode and decode functions instead such as
-X509_add1_ext_i2d() and X509_get_ext_d2i().
-
-Extension indices start from zero, so a zero index return value is B<not> an
-error. These search functions start from the extension B<after> the B<lastpos>
-parameter so it should initially be set to B<-1>, if it is set to zero the
-initial extension will not be checked.
-
-=head1 RETURN VALUES
-
-X509v3_get_ext_count() returns the extension count.
-
-X509v3_get_ext() and X509v3_delete_ext() return an B<X509_EXTENSION> pointer
-or B<NULL> if an error occurs.
-
-X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and
-X509v3_get_ext_by_critical() return the an extension index or B<-1> if an
-error occurs.
-
-X509v3_add_ext() returns a stack of extensions or B<NULL> on error.
-
-=head1 SEE ALSO
-
-L<X509V3_get_d2i(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section 7
-
-=head1 NAME
-
-bio - Basic I/O abstraction
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
-=head1 DESCRIPTION
-
-A BIO is an I/O abstraction, it hides many of the underlying I/O
-details from an application. If an application uses a BIO for its
-I/O it can transparently handle SSL connections, unencrypted network
-connections and file I/O.
-
-There are two type of BIO, a source/sink BIO and a filter BIO.
-
-As its name implies a source/sink BIO is a source and/or sink of data,
-examples include a socket BIO and a file BIO.
-
-A filter BIO takes data from one BIO and passes it through to
-another, or the application. The data may be left unmodified (for
-example a message digest BIO) or translated (for example an
-encryption BIO). The effect of a filter BIO may change according
-to the I/O operation it is performing: for example an encryption
-BIO will encrypt data if it is being written to and decrypt data
-if it is being read from.
-
-BIOs can be joined together to form a chain (a single BIO is a chain
-with one component). A chain normally consist of one source/sink
-BIO and one or more filter BIOs. Data read from or written to the
-first BIO then traverses the chain to the end (normally a source/sink
-BIO).
-
-
-Some BIOs (such as memory BIOs) can be used immediately after calling
-BIO_new(). Others (such as file BIOs) need some additional initialization,
-and frequently a utility function exists to create and initialize such BIOs.
-
-If BIO_free() is called on a BIO chain it will only free one BIO resulting
-in a memory leak.
-
-Calling BIO_free_all() a single BIO has the same effect as calling BIO_free()
-on it other than the discarded return value.
-
-Normally the B<type> argument is supplied by a function which returns a
-pointer to a BIO_METHOD. There is a naming convention for such functions:
-a source/sink BIO is normally called BIO_s_*() and a filter BIO
-BIO_f_*();
-
-=head1 EXAMPLE
-
-Create a memory BIO:
-
- BIO *mem = BIO_new(BIO_s_mem());
-
-=head1 SEE ALSO
-
-L<BIO_ctrl(3)>,
-L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>,
-L<BIO_f_cipher(3)>, L<BIO_f_md(3)>,
-L<BIO_f_null(3)>, L<BIO_f_ssl(3)>,
-L<BIO_find_type(3)>, L<BIO_new(3)>,
-L<BIO_new_bio_pair(3)>,
-L<BIO_push(3)>, L<BIO_read(3)>,
-L<BIO_s_accept(3)>, L<BIO_s_bio(3)>,
-L<BIO_s_connect(3)>, L<BIO_s_fd(3)>,
-L<BIO_s_file(3)>, L<BIO_s_mem(3)>,
-L<BIO_s_mem(3)>,
-L<BIO_s_null(3)>, L<BIO_s_socket(3)>,
-L<BIO_set_callback(3)>,
-L<BIO_should_retry(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
-
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:7
-
-=head1 NAME
-
-crypto - OpenSSL cryptographic library
-
-=head1 SYNOPSIS
-
-See the individual manual pages for details.
-
-=head1 DESCRIPTION
-
-The OpenSSL B<crypto> library implements a wide range of cryptographic
-algorithms used in various Internet standards. The services provided
-by this library are used by the OpenSSL implementations of SSL, TLS
-and S/MIME, and they have also been used to implement SSH, OpenPGP, and
-other cryptographic standards.
-
-B<libcrypto> consists of a number of sub-libraries that implement the
-individual algorithms.
-
-The functionality includes symmetric encryption, public key
-cryptography and key agreement, certificate handling, cryptographic
-hash functions, cryptographic pseudo-random number generator, and
-various utilities.
-
-=head1 NOTES
-
-Some of the newer functions follow a naming convention using the numbers
-B<0> and B<1>. For example the functions:
-
- int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
- int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
-
-The B<0> version uses the supplied structure pointer directly
-in the parent and it will be freed up when the parent is freed.
-In the above example B<crl> would be freed but B<rev> would not.
-
-The B<1> function uses a copy of the supplied structure pointer
-(or in some cases increases its link count) in the parent and
-so both (B<x> and B<obj> above) should be freed up.
-
-=head1 RETURN VALUES
-
-See the individual manual pages for details.
-
-=head1 SEE ALSO
-
-L<openssl(1)>, L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:7
-
-=head1 NAME
-
-ct - Certificate Transparency
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
-=head1 DESCRIPTION
-
-This library implements Certificate Transparency (CT) verification for TLS
-clients, as defined in RFC 6962. This verification can provide some confidence
-that a certificate has been publicly logged in a set of CT logs.
-
-By default, these checks are disabled. They can be enabled using
-SSL_CTX_ct_enable() or SSL_ct_enable().
-
-This library can also be used to parse and examine CT data structures, such as
-Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are
-functions for:
-- decoding and encoding SCTs in DER and TLS wire format.
-- printing SCTs.
-- verifying the authenticity of SCTs.
-- loading a CT log list from a CONF file.
-
-=head1 SEE ALSO
-
-L<d2i_SCT_LIST(3)>,
-L<CTLOG_STORE_new(3)>,
-L<CTLOG_STORE_get0_log_by_id(3)>,
-L<SCT_new(3)>,
-L<SCT_print(3)>,
-L<SCT_verify(3)>,
-L<SCT_validate(3)>,
-L<CT_POLICY_EVAL_CTX(3)>,
-L<SSL_CTX_set_ct_validation_callback(3)>
-
-=head1 HISTORY
-
-This library was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions
-
-=head1 SYNOPSIS
-
- #include <openssl/dh.h>
-
- DH *d2i_DHparams(DH **a, unsigned char **pp, long length);
- int i2d_DHparams(DH *a, unsigned char **pp);
-
-=head1 DESCRIPTION
-
-These functions decode and encode PKCS#3 DH parameters using the
-DHparameter structure described in PKCS#3.
-
-Otherwise these behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)> manual page.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-i2d_Netscape_RSA,
-d2i_Netscape_RSA
-- insecure RSA public and private key encoding functions
-
-=head1 SYNOPSIS
-
- #include <openssl/rsa.h>
-
- int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
- RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)());
-
-=head1 DESCRIPTION
-
-These functions decode and encode an RSA private
-key in NET format. These functions are present to provide compatibility
-with very old software. This format has some severe security weaknesses
-and should be avoided if possible.
-
-These functions are similar to the B<d2i_RSAPrivateKey> functions.
-
-=head1 SEE ALSO
-
-L<d2i_RSAPrivateKey(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp,
-i2d_PKCS8PrivateKey_bio, i2d_PKCS8PrivateKey_fp,
-i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8 format private key functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u);
- EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u);
-
- int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
- int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
- int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
- int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid,
- char *kstr, int klen,
- pem_password_cb *cb, void *u);
-
-=head1 DESCRIPTION
-
-The PKCS#8 functions encode and decode private keys in PKCS#8 format using both
-PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms.
-
-Other than the use of DER as opposed to PEM these functions are identical to the
-corresponding B<PEM> function as described in L<PEM_read_PrivateKey(3)>.
-
-=head1 NOTES
-
-These functions are currently the only way to store encrypted private keys using DER format.
-
-Currently all the functions use BIOs or FILE pointers, there are no functions which
-work directly on memory: this can be readily worked around by converting the buffers
-to memory BIOs, see L<BIO_s_mem(3)> for details.
-
-=head1 SEE ALSO
-
-L<PEM_read_PrivateKey(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_PrivateKey, d2i_AutoPrivateKey, i2d_PrivateKey,
-d2i_PrivateKey_bio, d2i_PrivateKey_fp
-- decode and encode functions for reading and saving EVP_PKEY structures
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
- EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp,
- long length);
- EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp,
- long length);
- int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp);
-
- EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a);
- EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a)
-
-=head1 DESCRIPTION
-
-d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to
-use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The
-B<type> parameter should be a public key algorithm constant such as
-B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>.
-
-d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to
-automatically detect the private key format.
-
-i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is
-defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format.
-
-These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>.
-
-=head1 NOTES
-
-All these functions use DER format and unencrypted keys. Applications wishing
-to encrypt or decrypt private keys should use other functions such as
-d2i_PKC8PrivateKey() instead.
-
-If the B<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey()
-(i.e. an existing structure is being reused) and the key format is PKCS#8
-then B<*a> will be freed and replaced on a successful call.
-
-=head1 RETURN VALUES
-
-d2i_PrivateKey() and d2i_AutoPrivateKey() return a valid B<EVP_KEY> structure
-or B<NULL> if an error occurs. The error code can be obtained by calling
-L<ERR_get_error(3)>.
-
-i2d_PrivateKey() returns the number of bytes successfully encoded or a
-negative value if an error occurs. The error code can be obtained by calling
-L<ERR_get_error(3)>.
-
-=head1 SEE ALSO
-
-L<crypto(3)>,
-L<d2i_PKCS8PrivateKey(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_ACCESS_DESCRIPTION,
-d2i_ASIdOrRange,
-d2i_ASIdentifierChoice,
-d2i_ASIdentifiers,
-d2i_ASN1_BIT_STRING,
-d2i_ASN1_BMPSTRING,
-d2i_ASN1_ENUMERATED,
-d2i_ASN1_GENERALIZEDTIME,
-d2i_ASN1_GENERALSTRING,
-d2i_ASN1_IA5STRING,
-d2i_ASN1_INTEGER,
-d2i_ASN1_NULL,
-d2i_ASN1_OBJECT,
-d2i_ASN1_OCTET_STRING,
-d2i_ASN1_PRINTABLE,
-d2i_ASN1_PRINTABLESTRING,
-d2i_ASN1_SEQUENCE_ANY,
-d2i_ASN1_SET_ANY,
-d2i_ASN1_T61STRING,
-d2i_ASN1_TIME,
-d2i_ASN1_TYPE,
-d2i_ASN1_UINTEGER,
-d2i_ASN1_UNIVERSALSTRING,
-d2i_ASN1_UTCTIME,
-d2i_ASN1_UTF8STRING,
-d2i_ASN1_VISIBLESTRING,
-d2i_ASRange,
-d2i_AUTHORITY_INFO_ACCESS,
-d2i_AUTHORITY_KEYID,
-d2i_BASIC_CONSTRAINTS,
-d2i_CERTIFICATEPOLICIES,
-d2i_CMS_ContentInfo,
-d2i_CMS_ReceiptRequest,
-d2i_CMS_bio,
-d2i_CRL_DIST_POINTS,
-d2i_DHxparams,
-d2i_DIRECTORYSTRING,
-d2i_DISPLAYTEXT,
-d2i_DIST_POINT,
-d2i_DIST_POINT_NAME,
-d2i_DSAPrivateKey,
-d2i_DSAPrivateKey_bio,
-d2i_DSAPrivateKey_fp,
-d2i_DSAPublicKey,
-d2i_DSA_PUBKEY_bio,
-d2i_DSA_PUBKEY_fp,
-d2i_DSA_SIG,
-d2i_DSAparams,
-d2i_ECPKParameters,
-d2i_ECParameters,
-d2i_ECPrivateKey,
-d2i_ECPrivateKey_bio,
-d2i_ECPrivateKey_fp,
-d2i_EC_PUBKEY,
-d2i_EC_PUBKEY_bio,
-d2i_EC_PUBKEY_fp,
-d2i_EDIPARTYNAME,
-d2i_ESS_CERT_ID,
-d2i_ESS_ISSUER_SERIAL,
-d2i_ESS_SIGNING_CERT,
-d2i_EXTENDED_KEY_USAGE,
-d2i_GENERAL_NAME,
-d2i_GENERAL_NAMES,
-d2i_IPAddressChoice,
-d2i_IPAddressFamily,
-d2i_IPAddressOrRange,
-d2i_IPAddressRange,
-d2i_ISSUING_DIST_POINT,
-d2i_NETSCAPE_CERT_SEQUENCE,
-d2i_NETSCAPE_SPKAC,
-d2i_NETSCAPE_SPKI,
-d2i_NOTICEREF,
-d2i_OCSP_BASICRESP,
-d2i_OCSP_CERTID,
-d2i_OCSP_CERTSTATUS,
-d2i_OCSP_CRLID,
-d2i_OCSP_ONEREQ,
-d2i_OCSP_REQINFO,
-d2i_OCSP_REQUEST,
-d2i_OCSP_RESPBYTES,
-d2i_OCSP_RESPDATA,
-d2i_OCSP_RESPID,
-d2i_OCSP_RESPONSE,
-d2i_OCSP_REVOKEDINFO,
-d2i_OCSP_SERVICELOC,
-d2i_OCSP_SIGNATURE,
-d2i_OCSP_SINGLERESP,
-d2i_OTHERNAME,
-d2i_PBE2PARAM,
-d2i_PBEPARAM,
-d2i_PBKDF2PARAM,
-d2i_PKCS12,
-d2i_PKCS12_BAGS,
-d2i_PKCS12_MAC_DATA,
-d2i_PKCS12_SAFEBAG,
-d2i_PKCS12_bio,
-d2i_PKCS12_fp,
-d2i_PKCS7,
-d2i_PKCS7_DIGEST,
-d2i_PKCS7_ENCRYPT,
-d2i_PKCS7_ENC_CONTENT,
-d2i_PKCS7_ENVELOPE,
-d2i_PKCS7_ISSUER_AND_SERIAL,
-d2i_PKCS7_RECIP_INFO,
-d2i_PKCS7_SIGNED,
-d2i_PKCS7_SIGNER_INFO,
-d2i_PKCS7_SIGN_ENVELOPE,
-d2i_PKCS7_bio,
-d2i_PKCS7_fp,
-d2i_PKCS8_PRIV_KEY_INFO,
-d2i_PKCS8_PRIV_KEY_INFO_bio,
-d2i_PKCS8_PRIV_KEY_INFO_fp,
-d2i_PKCS8_bio,
-d2i_PKCS8_fp,
-d2i_PKEY_USAGE_PERIOD,
-d2i_POLICYINFO,
-d2i_POLICYQUALINFO,
-d2i_PROXY_CERT_INFO_EXTENSION,
-d2i_PROXY_POLICY,
-d2i_PublicKey,
-d2i_RSAPrivateKey,
-d2i_RSAPrivateKey_bio,
-d2i_RSAPrivateKey_fp,
-d2i_RSAPublicKey,
-d2i_RSAPublicKey_bio,
-d2i_RSAPublicKey_fp,
-d2i_RSA_OAEP_PARAMS,
-d2i_RSA_PSS_PARAMS,
-d2i_RSA_PUBKEY,
-d2i_RSA_PUBKEY_bio,
-d2i_RSA_PUBKEY_fp,
-d2i_SCT_LIST,
-d2i_SXNET,
-d2i_SXNETID,
-d2i_TS_ACCURACY,
-d2i_TS_MSG_IMPRINT,
-d2i_TS_MSG_IMPRINT_bio,
-d2i_TS_MSG_IMPRINT_fp,
-d2i_TS_REQ,
-d2i_TS_REQ_bio,
-d2i_TS_REQ_fp,
-d2i_TS_RESP,
-d2i_TS_RESP_bio,
-d2i_TS_RESP_fp,
-d2i_TS_STATUS_INFO,
-d2i_TS_TST_INFO,
-d2i_TS_TST_INFO_bio,
-d2i_TS_TST_INFO_fp,
-d2i_USERNOTICE,
-d2i_X509,
-d2i_X509_ALGOR,
-d2i_X509_ALGORS,
-d2i_X509_ATTRIBUTE,
-d2i_X509_CERT_AUX,
-d2i_X509_CINF,
-d2i_X509_CRL,
-d2i_X509_CRL_INFO,
-d2i_X509_CRL_bio,
-d2i_X509_CRL_fp,
-d2i_X509_EXTENSION,
-d2i_X509_EXTENSIONS,
-d2i_X509_NAME,
-d2i_X509_NAME_ENTRY,
-d2i_X509_PUBKEY,
-d2i_X509_REQ,
-d2i_X509_REQ_INFO,
-d2i_X509_REQ_bio,
-d2i_X509_REQ_fp,
-d2i_X509_REVOKED,
-d2i_X509_SIG,
-d2i_X509_VAL,
-i2d_ACCESS_DESCRIPTION,
-i2d_ASIdOrRange,
-i2d_ASIdentifierChoice,
-i2d_ASIdentifiers,
-i2d_ASN1_BIT_STRING,
-i2d_ASN1_BMPSTRING,
-i2d_ASN1_ENUMERATED,
-i2d_ASN1_GENERALIZEDTIME,
-i2d_ASN1_GENERALSTRING,
-i2d_ASN1_IA5STRING,
-i2d_ASN1_INTEGER,
-i2d_ASN1_NULL,
-i2d_ASN1_OBJECT,
-i2d_ASN1_OCTET_STRING,
-i2d_ASN1_PRINTABLE,
-i2d_ASN1_PRINTABLESTRING,
-i2d_ASN1_SEQUENCE_ANY,
-i2d_ASN1_SET_ANY,
-i2d_ASN1_T61STRING,
-i2d_ASN1_TIME,
-i2d_ASN1_TYPE,
-i2d_ASN1_UNIVERSALSTRING,
-i2d_ASN1_UTCTIME,
-i2d_ASN1_UTF8STRING,
-i2d_ASN1_VISIBLESTRING,
-i2d_ASN1_bio_stream,
-i2d_ASRange,
-i2d_AUTHORITY_INFO_ACCESS,
-i2d_AUTHORITY_KEYID,
-i2d_BASIC_CONSTRAINTS,
-i2d_CERTIFICATEPOLICIES,
-i2d_CMS_ContentInfo,
-i2d_CMS_ReceiptRequest,
-i2d_CMS_bio,
-i2d_CRL_DIST_POINTS,
-i2d_DHxparams,
-i2d_DIRECTORYSTRING,
-i2d_DISPLAYTEXT,
-i2d_DIST_POINT,
-i2d_DIST_POINT_NAME,
-i2d_DSAPrivateKey,
-i2d_DSAPrivateKey_bio,
-i2d_DSAPrivateKey_fp,
-i2d_DSAPublicKey,
-i2d_DSA_PUBKEY_bio,
-i2d_DSA_PUBKEY_fp,
-i2d_DSA_SIG,
-i2d_DSAparams,
-i2d_ECPKParameters,
-i2d_ECParameters,
-i2d_ECPrivateKey,
-i2d_ECPrivateKey_bio,
-i2d_ECPrivateKey_fp,
-i2d_EC_PUBKEY,
-i2d_EC_PUBKEY_bio,
-i2d_EC_PUBKEY_fp,
-i2d_EDIPARTYNAME,
-i2d_ESS_CERT_ID,
-i2d_ESS_ISSUER_SERIAL,
-i2d_ESS_SIGNING_CERT,
-i2d_EXTENDED_KEY_USAGE,
-i2d_GENERAL_NAME,
-i2d_GENERAL_NAMES,
-i2d_IPAddressChoice,
-i2d_IPAddressFamily,
-i2d_IPAddressOrRange,
-i2d_IPAddressRange,
-i2d_ISSUING_DIST_POINT,
-i2d_NETSCAPE_CERT_SEQUENCE,
-i2d_NETSCAPE_SPKAC,
-i2d_NETSCAPE_SPKI,
-i2d_NOTICEREF,
-i2d_OCSP_BASICRESP,
-i2d_OCSP_CERTID,
-i2d_OCSP_CERTSTATUS,
-i2d_OCSP_CRLID,
-i2d_OCSP_ONEREQ,
-i2d_OCSP_REQINFO,
-i2d_OCSP_REQUEST,
-i2d_OCSP_RESPBYTES,
-i2d_OCSP_RESPDATA,
-i2d_OCSP_RESPID,
-i2d_OCSP_RESPONSE,
-i2d_OCSP_REVOKEDINFO,
-i2d_OCSP_SERVICELOC,
-i2d_OCSP_SIGNATURE,
-i2d_OCSP_SINGLERESP,
-i2d_OTHERNAME,
-i2d_PBE2PARAM,
-i2d_PBEPARAM,
-i2d_PBKDF2PARAM,
-i2d_PKCS12,
-i2d_PKCS12_BAGS,
-i2d_PKCS12_MAC_DATA,
-i2d_PKCS12_SAFEBAG,
-i2d_PKCS12_bio,
-i2d_PKCS12_fp,
-i2d_PKCS7,
-i2d_PKCS7_DIGEST,
-i2d_PKCS7_ENCRYPT,
-i2d_PKCS7_ENC_CONTENT,
-i2d_PKCS7_ENVELOPE,
-i2d_PKCS7_ISSUER_AND_SERIAL,
-i2d_PKCS7_NDEF,
-i2d_PKCS7_RECIP_INFO,
-i2d_PKCS7_SIGNED,
-i2d_PKCS7_SIGNER_INFO,
-i2d_PKCS7_SIGN_ENVELOPE,
-i2d_PKCS7_bio,
-i2d_PKCS7_fp,
-i2d_PKCS8PrivateKeyInfo_bio,
-i2d_PKCS8PrivateKeyInfo_fp,
-i2d_PKCS8_PRIV_KEY_INFO,
-i2d_PKCS8_PRIV_KEY_INFO_bio,
-i2d_PKCS8_PRIV_KEY_INFO_fp,
-i2d_PKCS8_bio,
-i2d_PKCS8_fp,
-i2d_PKEY_USAGE_PERIOD,
-i2d_POLICYINFO,
-i2d_POLICYQUALINFO,
-i2d_PROXY_CERT_INFO_EXTENSION,
-i2d_PROXY_POLICY,
-i2d_PublicKey,
-i2d_RSAPrivateKey,
-i2d_RSAPrivateKey_bio,
-i2d_RSAPrivateKey_fp,
-i2d_RSAPublicKey,
-i2d_RSAPublicKey_bio,
-i2d_RSAPublicKey_fp,
-i2d_RSA_OAEP_PARAMS,
-i2d_RSA_PSS_PARAMS,
-i2d_RSA_PUBKEY,
-i2d_RSA_PUBKEY_bio,
-i2d_RSA_PUBKEY_fp,
-i2d_SCT_LIST,
-i2d_SXNET,
-i2d_SXNETID,
-i2d_TS_ACCURACY,
-i2d_TS_MSG_IMPRINT,
-i2d_TS_MSG_IMPRINT_bio,
-i2d_TS_MSG_IMPRINT_fp,
-i2d_TS_REQ,
-i2d_TS_REQ_bio,
-i2d_TS_REQ_fp,
-i2d_TS_RESP,
-i2d_TS_RESP_bio,
-i2d_TS_RESP_fp,
-i2d_TS_STATUS_INFO,
-i2d_TS_TST_INFO,
-i2d_TS_TST_INFO_bio,
-i2d_TS_TST_INFO_fp,
-i2d_USERNOTICE,
-i2d_X509,
-i2d_X509_ALGOR,
-i2d_X509_ALGORS,
-i2d_X509_ATTRIBUTE,
-i2d_X509_CERT_AUX,
-i2d_X509_CINF,
-i2d_X509_CRL,
-i2d_X509_CRL_INFO,
-i2d_X509_CRL_bio,
-i2d_X509_CRL_fp,
-i2d_X509_EXTENSION,
-i2d_X509_EXTENSIONS,
-i2d_X509_NAME,
-i2d_X509_NAME_ENTRY,
-i2d_X509_PUBKEY,
-i2d_X509_REQ,
-i2d_X509_REQ_INFO,
-i2d_X509_REQ_bio,
-i2d_X509_REQ_fp,
-i2d_X509_REVOKED,
-i2d_X509_SIG,
-i2d_X509_VAL,
-- convert objects from/to ASN.1/DER representation
-
-=for comment generic
-
-=head1 SYNOPSIS
-
- TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length);
- TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
- TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
-
- int i2d_TYPE(TYPE *a, unsigned char **pp);
- int i2d_TYPE_fp(FILE *fp, TYPE *a);
- int i2d_TYPE_bio(BIO *bp, TYPE *a);
-
-=head1 DESCRIPTION
-
-In the description here, I<TYPE> is used a placeholder
-for any of the OpenSSL datatypes, such as I<X509_CRL>.
-
-These functions convert OpenSSL objects to and from their ASN.1/DER
-encoding. Unlike the C structures which can have pointers to sub-objects
-within, the DER is a serialized encoding, suitable for sending over the
-network, writing to a file, and so on.
-
-d2i_TYPE() attempts to decode B<len> bytes at B<*in>. If successful a
-pointer to the B<TYPE> structure is returned and B<*in> is incremented to
-the byte following the parsed data. If B<a> is not B<NULL> then a pointer
-to the returned structure is also written to B<*a>. If an error occurred
-then B<NULL> is returned.
-
-On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
-contains a valid B<TYPE> structure and an attempt is made to reuse it. This
-"reuse" capability is present for historical compatibility but its use is
-B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
-VALUES section).
-
-d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
-to parse data from BIO B<bp>.
-
-d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
-to parse data from FILE pointer B<fp>.
-
-i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
-If B<out> is not B<NULL>, it writes the DER encoded data to the buffer
-at B<*out>, and increments it to point after the data just written.
-If the return value is negative an error occurred, otherwise it
-returns the length of the encoded data.
-
-If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded
-data written to it. In this case B<*out> is not incremented and it points
-to the start of the data just written.
-
-i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
-the encoding of the structure B<a> to BIO B<bp> and it
-returns 1 for success and 0 for failure.
-
-i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
-the encoding of the structure B<a> to BIO B<bp> and it
-returns 1 for success and 0 for failure.
-
-These routines do not encrypt private keys and therefore offer no
-security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
-
-=head1 NOTES
-
-The letters B<i> and B<d> in B<i2d_TYPE> stand for
-"internal" (that is, an internal C structure) and "DER" respectively.
-So B<i2d_TYPE> converts from internal to DER.
-
-The functions can also understand B<BER> forms.
-
-The actual TYPE structure passed to i2d_TYPE() must be a valid
-populated B<TYPE> structure -- it B<cannot> simply be fed with an
-empty structure such as that returned by TYPE_new().
-
-The encoded data is in binary form and may contain embedded zeroes.
-Therefore any FILE pointers or BIOs should be opened in binary mode.
-Functions such as strlen() will B<not> return the correct length
-of the encoded structure.
-
-The ways that B<*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 this-auto increment behaviour is to reflect a typical
-usage of ASN1 functions: after one structure is encoded or decoded
-another will be processed after it.
-
-The following points about the data types might be useful:
-
-=over
-
-=item B<ASN1_OBJECT>
-
-Represents an ASN1 OBJECT IDENTIFIER.
-
-=item B<DHparams>
-
-Represents a PKCS#3 DH parameters structure.
-
-=item B<DHparamx>
-
-Represents a ANSI X9.42 DH parameters structure.
-
-=item B<DSA_PUBKEY>
-
-Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
-
-=item B<DSAPublicKey, DSAPrivateKey>
-
-Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
-B<PEM_write_PrivateKey(3)>, or similar instead.
-
-=item B<RSAPublicKey>
-
-Represents a PKCS#1 RSA public key structure.
-
-=item B<X509_ALGOR>
-
-Represents an B<AlogrithmIdentifier> structure as used in IETF RFC 6960 and
-elsewhere.
-
-=item B<X509_Name>
-
-Represents a B<Name> type as used for subject and issuer names in
-IETF RFC 6960 and elsewhere.
-
-=item B<X509_REQ>
-
-Represents a PKCS#10 certificate request.
-
-=item B<X509_SIG>
-
-Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
-
-=back
-
-=head1 EXAMPLES
-
-Allocate and encode the DER encoding of an X509 structure:
-
- int len;
- unsigned char *buf;
-
- buf = NULL;
- len = i2d_X509(x, &buf);
- if (len < 0)
- /* error */
-
-Attempt to decode a buffer:
-
- X509 *x;
- unsigned char *buf, *p;
- int len;
-
- /* Set up buf and len to point to the input buffer. */
- p = buf;
- x = d2i_X509(NULL, &p, len);
- if (x == NULL)
- /* error */
-
-Alternative technique:
-
- X509 *x;
- unsigned char *buf, *p;
- int len;
-
- /* Set up buf and len to point to the input buffer. */
- p = buf;
- x = NULL;
-
- if (d2i_X509(&x, &p, len) == NULL)
- /* error */
-
-=head1 WARNINGS
-
-Using a temporary variable is mandatory. A common
-mistake is to attempt to use a buffer directly as follows:
-
- int len;
- unsigned char *buf;
-
- len = i2d_X509(x, NULL);
- buf = OPENSSL_malloc(len);
- ...
- i2d_X509(x, &buf);
- ...
- OPENSSL_free(buf);
-
-This code will result in B<buf> apparently containing garbage because
-it was incremented after the call to point after the data just written.
-Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
-and the subsequent call to OPENSSL_free() is likely to crash.
-
-Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
-
- X509 *x;
-
- if (d2i_X509(&x, &p, len) == NULL)
- /* error */
-
-This will probably crash somewhere in d2i_X509(). The reason for this
-is that the variable B<x> is uninitialized and an attempt will be made to
-interpret its (invalid) value as an B<X509> structure, typically causing
-a segmentation violation. If B<x> is set to NULL first then this will not
-happen.
-
-=head1 BUGS
-
-In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
-B<*px> is valid is broken and some parts of the reused structure may
-persist if they are not present in the new one. As a result the use
-of this "reuse" behaviour is strongly discouraged.
-
-i2d_TYPE() will not return an error in many versions of OpenSSL,
-if mandatory fields are not initialized due to a programming error
-then the encoded structure may contain invalid data or omit the
-fields entirely and will not be parsed by d2i_TYPE(). This may be
-fixed in future so code should not assume that i2d_TYPE() will
-always succeed.
-
-Any function which encodes a structure (i2d_TYPE(),
-i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
-structure has been modified after deserialization or previous
-serialization. This is because some objects cache the encoding for
-efficiency reasons.
-
-=head1 RETURN VALUES
-
-d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
-or B<NULL> if an error occurs. If the "reuse" capability has been used with
-a valid structure being passed in via B<a>, then the object is not freed in
-the event of error but may be in a potentially invalid or inconsistent state.
-
-i2d_TYPE() returns the number of bytes successfully encoded or a negative
-value if an error occurs.
-
-i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
-occurs.
-
-=head1 COPYRIGHT
-
-Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:7
-
-=head1 NAME
-
-des_modes - the variants of DES and other crypto algorithms of OpenSSL
-
-=head1 DESCRIPTION
-
-Several crypto algorithms for OpenSSL can be used in a number of modes. Those
-are used for using block ciphers in a way similar to stream ciphers, among
-other things.
-
-=head1 OVERVIEW
-
-=head2 Electronic Codebook Mode (ECB)
-
-Normally, this is found as the function I<algorithm>_ecb_encrypt().
-
-=over 2
-
-=item *
-
-64 bits are enciphered at a time.
-
-=item *
-
-The order of the blocks can be rearranged without detection.
-
-=item *
-
-The same plaintext block always produces the same ciphertext block
-(for the same key) making it vulnerable to a 'dictionary attack'.
-
-=item *
-
-An error will only affect one ciphertext block.
-
-=back
-
-=head2 Cipher Block Chaining Mode (CBC)
-
-Normally, this is found as the function I<algorithm>_cbc_encrypt().
-Be aware that des_cbc_encrypt() is not really DES CBC (it does
-not update the IV); use des_ncbc_encrypt() instead.
-
-=over 2
-
-=item *
-
-a multiple of 64 bits are enciphered at a time.
-
-=item *
-
-The CBC mode produces the same ciphertext whenever the same
-plaintext is encrypted using the same key and starting variable.
-
-=item *
-
-The chaining operation makes the ciphertext blocks dependent on the
-current and all preceding plaintext blocks and therefore blocks can not
-be rearranged.
-
-=item *
-
-The use of different starting variables prevents the same plaintext
-enciphering to the same ciphertext.
-
-=item *
-
-An error will affect the current and the following ciphertext blocks.
-
-=back
-
-=head2 Cipher Feedback Mode (CFB)
-
-Normally, this is found as the function I<algorithm>_cfb_encrypt().
-
-=over 2
-
-=item *
-
-a number of bits (j) <= 64 are enciphered at a time.
-
-=item *
-
-The CFB mode produces the same ciphertext whenever the same
-plaintext is encrypted using the same key and starting variable.
-
-=item *
-
-The chaining operation makes the ciphertext variables dependent on the
-current and all preceding variables and therefore j-bit variables are
-chained together and can not be rearranged.
-
-=item *
-
-The use of different starting variables prevents the same plaintext
-enciphering to the same ciphertext.
-
-=item *
-
-The strength of the CFB mode depends on the size of k (maximal if
-j == k). In my implementation this is always the case.
-
-=item *
-
-Selection of a small value for j will require more cycles through
-the encipherment algorithm per unit of plaintext and thus cause
-greater processing overheads.
-
-=item *
-
-Only multiples of j bits can be enciphered.
-
-=item *
-
-An error will affect the current and the following ciphertext variables.
-
-=back
-
-=head2 Output Feedback Mode (OFB)
-
-Normally, this is found as the function I<algorithm>_ofb_encrypt().
-
-=over 2
-
-
-=item *
-
-a number of bits (j) <= 64 are enciphered at a time.
-
-=item *
-
-The OFB mode produces the same ciphertext whenever the same
-plaintext enciphered using the same key and starting variable. More
-over, in the OFB mode the same key stream is produced when the same
-key and start variable are used. Consequently, for security reasons
-a specific start variable should be used only once for a given key.
-
-=item *
-
-The absence of chaining makes the OFB more vulnerable to specific attacks.
-
-=item *
-
-The use of different start variables values prevents the same
-plaintext enciphering to the same ciphertext, by producing different
-key streams.
-
-=item *
-
-Selection of a small value for j will require more cycles through
-the encipherment algorithm per unit of plaintext and thus cause
-greater processing overheads.
-
-=item *
-
-Only multiples of j bits can be enciphered.
-
-=item *
-
-OFB mode of operation does not extend ciphertext errors in the
-resultant plaintext output. Every bit error in the ciphertext causes
-only one bit to be in error in the deciphered plaintext.
-
-=item *
-
-OFB mode is not self-synchronizing. If the two operation of
-encipherment and decipherment get out of synchronism, the system needs
-to be re-initialized.
-
-=item *
-
-Each re-initialization should use a value of the start variable
-different from the start variable values used before with the same
-key. The reason for this is that an identical bit stream would be
-produced each time from the same parameters. This would be
-susceptible to a 'known plaintext' attack.
-
-=back
-
-=head2 Triple ECB Mode
-
-Normally, this is found as the function I<algorithm>_ecb3_encrypt().
-
-=over 2
-
-=item *
-
-Encrypt with key1, decrypt with key2 and encrypt with key3 again.
-
-=item *
-
-As for ECB encryption but increases the key length to 168 bits.
-There are theoretic attacks that can be used that make the effective
-key length 112 bits, but this attack also requires 2^56 blocks of
-memory, not very likely, even for the NSA.
-
-=item *
-
-If both keys are the same it is equivalent to encrypting once with
-just one key.
-
-=item *
-
-If the first and last key are the same, the key length is 112 bits.
-There are attacks that could reduce the effective key strength
-to only slightly more than 56 bits, but these require a lot of memory.
-
-=item *
-
-If all 3 keys are the same, this is effectively the same as normal
-ecb mode.
-
-=back
-
-=head2 Triple CBC Mode
-
-Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt().
-
-=over 2
-
-
-=item *
-
-Encrypt with key1, decrypt with key2 and then encrypt with key3.
-
-=item *
-
-As for CBC encryption but increases the key length to 168 bits with
-the same restrictions as for triple ecb mode.
-
-=back
-
-=head1 NOTES
-
-This text was been written in large parts by Eric Young in his original
-documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed
-it to:
-
- AS 2805.5.2
- Australian Standard
- Electronic funds transfer - Requirements for interfaces,
- Part 5.2: Modes of operation for an n-bit block cipher algorithm
- Appendix A
-
-=head1 SEE ALSO
-
-L<blowfish(3)>, L<des(3)>, L<idea(3)>,
-L<rc2(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:7
-
-=head1 NAME
-
-evp - high-level cryptographic functions
-
-=head1 SYNOPSIS
-
- #include <openssl/evp.h>
-
-=head1 DESCRIPTION
-
-The EVP library provides a high-level interface to cryptographic
-functions.
-
-L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and L<B<EVP_Open>I<...>|EVP_OpenInit(3)>
-provide public key encryption and decryption to implement digital "envelopes".
-
-The L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> and
-L<B<EVP_DigestVerify>I<...>|EVP_DigestVerifyInit(3)> functions implement
-digital signatures and Message Authentication Codes (MACs). Also see the older
-L<B<EVP_Sign>I<...>|EVP_SignInit(3)> and L<B<EVP_Verify>I<...>|EVP_VerifyInit(3)>
-functions.
-
-Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)>
-functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests.
-
-The B<EVP_PKEY>I<...> functions provide a high level interface to
-asymmetric algorithms. To create a new EVP_PKEY see
-L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated
-with a private key of a particular algorithm by using the functions
-described on the L<EVP_PKEY_set1_RSA(3)> page, or
-new keys can be generated using L<EVP_PKEY_keygen(3)>.
-EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using
-L<EVP_PKEY_print_private(3)>.
-
-The EVP_PKEY functions support the full range of asymmetric algorithm operations:
-
-=over
-
-=item For key agreement see L<EVP_PKEY_derive(3)>
-
-=item For signing and verifying see L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>.
-However, note that
-these functions do not perform a digest of the data to be signed. Therefore
-normally you would use the L<EVP_DigestSignInit(3)>
-functions for this purpose.
-
-=item For encryption and decryption see L<EVP_PKEY_encrypt(3)>
-and L<EVP_PKEY_decrypt(3)> respectively. However, note that
-these functions perform encryption and decryption only. As public key
-encryption is an expensive operation, normally you would wrap
-an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and
-L<EVP_OpenInit(3)> functions.
-
-=back
-
-The L<EVP_BytesToKey(3)> function provides some limited support for password
-based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible
-implementation. However, new applications should not typically use this (preferring, for example,
-PBKDF2 from PCKS#5).
-
-The L<B<EVP_Encode>I<...>|EVP_EncodeInit(3)> and
-L<B<EVP_Decode>I<...>|EVP_EncodeInit(3)> functions implement base 64 encoding
-and decoding.
-
-All the symmetric algorithms (ciphers), digests and asymmetric algorithms
-(public key algorithms) can be replaced by L<engine(3)> modules providing alternative
-implementations. If ENGINE implementations of ciphers or digests are registered
-as defaults, then the various EVP functions will automatically use those
-implementations automatically in preference to built in software
-implementations. For more information, consult the engine(3) man page.
-
-Although low level algorithm specific functions exist for many algorithms
-their use is discouraged. They cannot be used with an ENGINE and ENGINE
-versions of new algorithms cannot be accessed using the low level functions.
-Also makes code harder to adapt to new algorithms and some options are not
-cleanly supported at the low level and some operations are more efficient
-using the high level interface.
-
-=head1 SEE ALSO
-
-L<EVP_DigestInit(3)>,
-L<EVP_EncryptInit(3)>,
-L<EVP_OpenInit(3)>,
-L<EVP_SealInit(3)>,
-L<EVP_DigestSignInit(3)>,
-L<EVP_SignInit(3)>,
-L<EVP_VerifyInit(3)>,
-L<EVP_EncodeInit(3)>,
-L<EVP_PKEY_new(3)>,
-L<EVP_PKEY_set1_RSA(3)>,
-L<EVP_PKEY_keygen(3)>,
-L<EVP_PKEY_print_private(3)>,
-L<EVP_PKEY_decrypt(3)>,
-L<EVP_PKEY_encrypt(3)>,
-L<EVP_PKEY_sign(3)>,
-L<EVP_PKEY_verify(3)>,
-L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>,
-L<EVP_BytesToKey(3)>,
-L<engine(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format
-
-=head1 SYNOPSIS
-
- #include <openssl/cms.h>
-
- int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format.
-
-It is otherwise identical to the function SMIME_write_CMS().
-
-=head1 NOTES
-
-This function is effectively a version of the i2d_CMS_bio() supporting
-streaming.
-
-=head1 BUGS
-
-The prefix "i2d" is arguably wrong because the function outputs BER format.
-
-=head1 RETURN VALUES
-
-i2d_CMS_bio_stream() returns 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<CMS_sign(3)>,
-L<CMS_verify(3)>, L<CMS_encrypt(3)>
-L<CMS_decrypt(3)>,
-L<SMIME_write_CMS(3)>,
-L<PEM_write_bio_CMS_stream(3)>
-
-=head1 HISTORY
-
-i2d_CMS_bio_stream() was added to OpenSSL 1.0.0
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-i2d_PKCS7_bio_stream - output PKCS7 structure in BER format
-
-=head1 SYNOPSIS
-
- #include <openssl/pkcs7.h>
-
- int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags);
-
-=head1 DESCRIPTION
-
-i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format.
-
-It is otherwise identical to the function SMIME_write_PKCS7().
-
-=head1 NOTES
-
-This function is effectively a version of the d2i_PKCS7_bio() supporting
-streaming.
-
-=head1 BUGS
-
-The prefix "i2d" is arguably wrong because the function outputs BER format.
-
-=head1 RETURN VALUES
-
-i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
-L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
-L<PKCS7_decrypt(3)>,
-L<SMIME_write_PKCS7(3)>,
-L<PEM_write_bio_PKCS7_stream(3)>
-
-=head1 HISTORY
-
-i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0
-
-=head1 COPYRIGHT
-
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_X509_AUX, i2d_X509_AUX,
-i2d_re_X509_tbs, i2d_re_X509_CRL_tbs, i2d_re_X509_REQ_tbs
-- X509 encode and decode functions
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
- X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len);
- int i2d_X509_AUX(X509 *x, unsigned char **out);
- int i2d_re_X509_tbs(X509 *x, unsigned char **out);
- int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **pp);
- int i2d_re_X509_REQ_tbs(X509_REQ *req, unsigned char **pp);
-
-=head1 DESCRIPTION
-
-The X509 encode and decode routines encode and parse an
-B<X509> structure, which represents an X509 certificate.
-
-d2i_X509_AUX() is similar to L<d2i_X509(3)> but the input is expected to
-consist of an X509 certificate followed by auxiliary trust information.
-This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects.
-This function should not be called on untrusted input.
-
-i2d_X509_AUX() is similar to L<i2d_X509(3)>, but the encoded output
-contains both the certificate and any auxiliary trust information.
-This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects.
-Note that this is a non-standard OpenSSL-specific data format.
-
-i2d_re_X509_tbs() is similar to L<i2d_X509(3)> except it encodes only
-the TBSCertificate portion of the certificate. i2d_re_X509_CRL_tbs()
-and i2d_re_X509_REQ_tbs() are analogous for CRL and certificate request,
-respectively. The "re" in B<i2d_re_X509_tbs> stands for "re-encode",
-and ensures that a fresh encoding is generated in case the object has been
-modified after creation (see the BUGS section).
-
-The encoding of the TBSCertificate portion of a certificate is cached
-in the B<X509> structure internally to improve encoding performance
-and to ensure certificate signatures are verified correctly in some
-certificates with broken (non-DER) encodings.
-
-If, after modification, the B<X509> object is re-signed with X509_sign(),
-the encoding is automatically renewed. Otherwise, the encoding of the
-TBSCertificate portion of the B<X509> can be manually renewed by calling
-i2d_re_X509_tbs().
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)>
-L<X509_CRL_get0_by_serial(3)>,
-L<X509_get0_signature(3)>,
-L<X509_get_ext_d2i(3)>,
-L<X509_get_extension_flags(3)>,
-L<X509_get_pubkey(3)>,
-L<X509_get_subject_name(3)>,
-L<X509_get_version(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_get_index_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_new(3)>,
-L<X509_sign(3)>,
-L<X509V3_get_d2i(3)>,
-L<X509_verify_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-o2i_SCT_LIST, i2o_SCT_LIST, o2i_SCT, i2o_SCT -
-decode and encode Signed Certificate Timestamp lists in TLS wire format
-
-=head1 SYNOPSIS
-
- #include <openssl/ct.h>
-
- STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp, size_t len);
- int i2o_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp);
- SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len);
- int i2o_SCT(const SCT *sct, unsigned char **out);
-
-=head1 DESCRIPTION
-
-The SCT_LIST and SCT functions are very similar to the i2d and d2i family of
-functions, except that they convert to and from TLS wire format, as described in
-RFC 6962. See L<d2i_SCT_LIST> for more information about how the parameters are
-treated and the return values.
-
-=head1 RETURN VALUES
-
-All of the functions have return values consistent with those stated for
-L<d2i_SCT_LIST> and L<i2d_SCT_LIST>.
-
-=head1 SEE ALSO
-
-L<ct(3)>,
-L<d2i_SCT_LIST(3)>,
-L<i2d_SCT_LIST(3)>
-
-=head1 HISTORY
-
-These functions were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:7
-
-=head1 NAME
-
-x509 - X.509 certificate handling
-
-=head1 SYNOPSIS
-
- #include <openssl/x509.h>
-
-=head1 DESCRIPTION
-
-A X.509 certificate is a structured grouping of information about
-an individual, a device, or anything one can imagine. A X.509 CRL
-(certificate revocation list) is a tool to help determine if a
-certificate is still valid. The exact definition of those can be
-found in the X.509 document from ITU-T, or in RFC3280 from PKIX.
-In OpenSSL, the type X509 is used to express such a certificate, and
-the type X509_CRL is used to express a CRL.
-
-A related structure is a certificate request, defined in PKCS#10 from
-RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type
-X509_REQ is used to express such a certificate request.
-
-To handle some complex parts of a certificate, there are the types
-X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express
-a certificate attributes), X509_EXTENSION (to express a certificate
-extension) and a few more.
-
-Finally, there's the supertype X509_INFO, which can contain a CRL, a
-certificate and a corresponding private key.
-
-B<X509_>I<...>, B<d2i_X509_>I<...> and B<i2d_X509_>I<...> handle X.509
-certificates, with some exceptions, shown below.
-
-B<X509_CRL_>I<...>, B<d2i_X509_CRL_>I<...> and B<i2d_X509_CRL_>I<...>
-handle X.509 CRLs.
-
-B<X509_REQ_>I<...>, B<d2i_X509_REQ_>I<...> and B<i2d_X509_REQ_>I<...>
-handle PKCS#10 certificate requests.
-
-B<X509_NAME_>I<...> handle certificate names.
-
-B<X509_ATTRIBUTE_>I<...> handle certificate attributes.
-
-B<X509_EXTENSION_>I<...> handle certificate extensions.
-
-=head1 SEE ALSO
-
-L<X509_NAME_ENTRY_get_object(3)>,
-L<X509_NAME_add_entry_by_txt(3)>,
-L<X509_NAME_add_entry_by_NID(3)>,
-L<X509_NAME_print_ex(3)>,
-L<X509_NAME_new(3)>,
-L<d2i_X509(3)>,
-L<d2i_X509_ALGOR(3)>,
-L<d2i_X509_CRL(3)>,
-L<d2i_X509_NAME(3)>,
-L<d2i_X509_REQ(3)>,
-L<d2i_X509_SIG(3)>,
-L<crypto(3)>,
-L<x509v3(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CA.pl - friendlier interface for OpenSSL certificate programs
+
+=head1 SYNOPSIS
+
+B<CA.pl>
+[B<-?>]
+[B<-h>]
+[B<-help>]
+[B<-newcert>]
+[B<-newreq>]
+[B<-newreq-nodes>]
+[B<-newca>]
+[B<-xsign>]
+[B<-sign>]
+[B<-signreq>]
+[B<-signcert>]
+[B<-verify>]
+[B<files>]
+
+=head1 DESCRIPTION
+
+The B<CA.pl> script is a perl script that supplies the relevant command line
+arguments to the B<openssl> command for some common certificate operations.
+It is intended to simplify the process of certificate creation and management
+by the use of some simple options.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<?>, B<-h>, B<-help>
+
+prints a usage message.
+
+=item B<-newcert>
+
+creates a new self signed certificate. The private key is written to the file
+"newkey.pem" and the request written to the file "newreq.pem".
+
+=item B<-newreq>
+
+creates a new certificate request. The private key is written to the file
+"newkey.pem" and the request written to the file "newreq.pem".
+
+=item B<-newreq-nodes>
+
+is like B<-newreq> except that the private key will not be encrypted.
+
+=item B<-newca>
+
+creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert>
+and B<-xsign> options). The user is prompted to enter the filename of the CA
+certificates (which should also contain the private key) or by hitting ENTER
+details of the CA will be prompted for. The relevant files and directories
+are created in a directory called "demoCA" in the current directory.
+
+=item B<-pkcs12>
+
+create a PKCS#12 file containing the user certificate, private key and CA
+certificate. It expects the user certificate and private key to be in the
+file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem,
+it creates a file "newcert.p12". This command can thus be called after the
+B<-sign> option. The PKCS#12 file can be imported directly into a browser.
+If there is an additional argument on the command line it will be used as the
+"friendly name" for the certificate (which is typically displayed in the browser
+list box), otherwise the name "My Certificate" is used.
+
+=item B<-sign>, B<-signreq>, B<-xsign>
+
+calls the B<ca> program to sign a certificate request. It expects the request
+to be in the file "newreq.pem". The new certificate is written to the file
+"newcert.pem" except in the case of the B<-xsign> option when it is written
+to standard output.
+
+
+=item B<-signCA>
+
+this option is the same as the B<-signreq> option except it uses the configuration
+file section B<v3_ca> and so makes the signed request a valid CA certificate. This
+is useful when creating intermediate CA from a root CA.
+
+=item B<-signcert>
+
+this option is the same as B<-sign> except it expects a self signed certificate
+to be present in the file "newreq.pem".
+
+=item B<-crl>
+
+generate a CRL
+
+=item B<-revoke certfile [reason]>
+
+revoke the certificate contained in the specified B<certfile>. An optional
+reason may be specified, and must be one of: B<unspecified>,
+B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
+B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
+
+=item B<-verify>
+
+verifies certificates against the CA certificate for "demoCA". If no certificates
+are specified on the command line it tries to verify the file "newcert.pem".
+
+=item B<files>
+
+one or more optional certificate file names for use with the B<-verify> command.
+
+=back
+
+=head1 EXAMPLES
+
+Create a CA hierarchy:
+
+ CA.pl -newca
+
+Complete certificate creation example: create a CA, create a request, sign
+the request and finally create a PKCS#12 file containing it.
+
+ CA.pl -newca
+ CA.pl -newreq
+ CA.pl -signreq
+ CA.pl -pkcs12 "My Test Certificate"
+
+=head1 DSA CERTIFICATES
+
+Although the B<CA.pl> creates RSA CAs and requests it is still possible to
+use it with DSA certificates and requests using the L<req(1)> command
+directly. The following example shows the steps that would typically be taken.
+
+Create some DSA parameters:
+
+ openssl dsaparam -out dsap.pem 1024
+
+Create a DSA CA certificate and private key:
+
+ openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem
+
+Create the CA directories and files:
+
+ CA.pl -newca
+
+enter cacert.pem when prompted for the CA file name.
+
+Create a DSA certificate request and private key (a different set of parameters
+can optionally be created first):
+
+ openssl req -out newreq.pem -newkey dsa:dsap.pem
+
+Sign the request:
+
+ CA.pl -signreq
+
+=head1 NOTES
+
+Most of the filenames mentioned can be modified by editing the B<CA.pl> script.
+
+If the demoCA directory already exists then the B<-newca> command will not
+overwrite it and will do nothing. This can happen if a previous call using
+the B<-newca> option terminated abnormally. To get the correct behaviour
+delete the demoCA directory if it already exists.
+
+Under some environments it may not be possible to run the B<CA.pl> script
+directly (for example Win32) and the default configuration file location may
+be wrong. In this case the command:
+
+ perl -S CA.pl
+
+can be used and the B<OPENSSL_CONF> environment variable changed to point to
+the correct path of the configuration file "openssl.cnf".
+
+The script is intended as a simple front end for the B<openssl> program for use
+by a beginner. Its behaviour isn't always what is wanted. For more control over the
+behaviour of the certificate commands call the B<openssl> command directly.
+
+=head1 ENVIRONMENT VARIABLES
+
+The variable B<OPENSSL_CONF> if defined allows an alternative configuration
+file location to be specified, it should contain the full path to the
+configuration file, not just its directory.
+
+=head1 SEE ALSO
+
+L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>,
+L<config(5)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+asn1parse - ASN.1 parsing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<asn1parse>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-offset number>]
+[B<-length number>]
+[B<-i>]
+[B<-oid filename>]
+[B<-dump>]
+[B<-dlimit num>]
+[B<-strparse offset>]
+[B<-genstr string>]
+[B<-genconf file>]
+[B<-strictpem>]
+[B<-item name>]
+
+=head1 DESCRIPTION
+
+The B<asn1parse> command is a diagnostic utility that can parse ASN.1
+structures. It can also be used to extract data from ASN.1 formatted data.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform> B<DER|PEM>
+
+the input format. B<DER> is binary format and B<PEM> (the default) is base64
+encoded.
+
+=item B<-in filename>
+
+the input file, default is standard input
+
+=item B<-out filename>
+
+output file to place the DER encoded data into. If this
+option is not present then no data will be output. This is most useful when
+combined with the B<-strparse> option.
+
+=item B<-noout>
+
+don't output the parsed version of the input file.
+
+=item B<-offset number>
+
+starting offset to begin parsing, default is start of file.
+
+=item B<-length number>
+
+number of bytes to parse, default is until end of file.
+
+=item B<-i>
+
+indents the output according to the "depth" of the structures.
+
+=item B<-oid filename>
+
+a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
+file is described in the NOTES section below.
+
+=item B<-dump>
+
+dump unknown data in hex format.
+
+=item B<-dlimit num>
+
+like B<-dump>, but only the first B<num> bytes are output.
+
+=item B<-strparse offset>
+
+parse the contents octets of the ASN.1 object starting at B<offset>. This
+option can be used multiple times to "drill down" into a nested structure.
+
+=item B<-genstr string>, B<-genconf file>
+
+generate encoded data based on B<string>, B<file> or both using
+L<ASN1_generate_nconf(3)> format. If B<file> only is
+present then the string is obtained from the default section using the name
+B<asn1>. The encoded data is passed through the ASN1 parser and printed out as
+though it came from a file, the contents can thus be examined and written to a
+file using the B<out> option.
+
+=item B<-strictpem>
+
+If this option is used then B<-inform> will be ignored. Without this option any
+data in a PEM format input file will be treated as being base64 encoded and
+processed whether it has the normal PEM BEGIN and END markers or not. This
+option will ignore any data prior to the start of the BEGIN marker, or after an
+END marker in a PEM file.
+
+=item B<-item name>
+
+attempt to decode and print the data as B<ASN1_ITEM name>. This can be used to
+print out the fields of any supported ASN.1 structure if the type is known.
+
+=back
+
+=head2 Output
+
+The output will typically contain lines like this:
+
+ 0:d=0 hl=4 l= 681 cons: SEQUENCE
+
+.....
+
+ 229:d=3 hl=3 l= 141 prim: BIT STRING
+ 373:d=2 hl=3 l= 162 cons: cont [ 3 ]
+ 376:d=3 hl=3 l= 159 cons: SEQUENCE
+ 379:d=4 hl=2 l= 29 cons: SEQUENCE
+ 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier
+ 386:d=5 hl=2 l= 22 prim: OCTET STRING
+ 410:d=4 hl=2 l= 112 cons: SEQUENCE
+ 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier
+ 417:d=5 hl=2 l= 105 prim: OCTET STRING
+ 524:d=4 hl=2 l= 12 cons: SEQUENCE
+
+.....
+
+This example is part of a self-signed certificate. Each line starts with the
+offset in decimal. B<d=XX> specifies the current depth. The depth is increased
+within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
+(tag and length octets) of the current type. B<l=XX> gives the length of
+the contents octets.
+
+The B<-i> option can be used to make the output more readable.
+
+Some knowledge of the ASN.1 structure is needed to interpret the output.
+
+In this example the BIT STRING at offset 229 is the certificate public key.
+The contents octets of this will contain the public key information. This can
+be examined using the option B<-strparse 229> to yield:
+
+ 0:d=0 hl=3 l= 137 cons: SEQUENCE
+ 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
+ 135:d=1 hl=2 l= 3 prim: INTEGER :010001
+
+=head1 NOTES
+
+If an OID is not part of OpenSSL's internal table it will be represented in
+numerical form (for example 1.2.3.4). The file passed to the B<-oid> option
+allows additional OIDs to be included. Each line consists of three columns,
+the first column is the OID in numerical format and should be followed by white
+space. The second column is the "short name" which is a single word followed
+by white space. The final column is the rest of the line and is the
+"long name". B<asn1parse> displays the long name. Example:
+
+C<1.2.3.4 shortName A long name>
+
+=head1 EXAMPLES
+
+Parse a file:
+
+ openssl asn1parse -in file.pem
+
+Parse a DER file:
+
+ openssl asn1parse -inform DER -in file.der
+
+Generate a simple UTF8String:
+
+ openssl asn1parse -genstr 'UTF8:Hello World'
+
+Generate and write out a UTF8String, don't print parsed output:
+
+ openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der
+
+Generate using a config file:
+
+ openssl asn1parse -genconf asn1.cnf -noout -out asn1.der
+
+Example config file:
+
+ asn1=SEQUENCE:seq_sect
+
+ [seq_sect]
+
+ field1=BOOL:TRUE
+ field2=EXP:0, UTF8:some random string
+
+
+=head1 BUGS
+
+There should be options to change the format of output lines. The output of some
+ASN.1 types is not well handled (if at all).
+
+=head1 SEE ALSO
+
+L<ASN1_generate_nconf(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ca - sample minimal CA application
+
+=head1 SYNOPSIS
+
+B<openssl> B<ca>
+[B<-help>]
+[B<-verbose>]
+[B<-config filename>]
+[B<-name section>]
+[B<-gencrl>]
+[B<-revoke file>]
+[B<-valid file>]
+[B<-status serial>]
+[B<-updatedb>]
+[B<-crl_reason reason>]
+[B<-crl_hold instruction>]
+[B<-crl_compromise time>]
+[B<-crl_CA_compromise time>]
+[B<-crldays days>]
+[B<-crlhours hours>]
+[B<-crlexts section>]
+[B<-startdate date>]
+[B<-enddate date>]
+[B<-days arg>]
+[B<-md arg>]
+[B<-policy arg>]
+[B<-keyfile arg>]
+[B<-keyform PEM|DER>]
+[B<-key arg>]
+[B<-passin arg>]
+[B<-cert file>]
+[B<-selfsign>]
+[B<-in file>]
+[B<-out file>]
+[B<-notext>]
+[B<-outdir dir>]
+[B<-infiles>]
+[B<-spkac file>]
+[B<-ss_cert file>]
+[B<-preserveDN>]
+[B<-noemailDN>]
+[B<-batch>]
+[B<-msie_hack>]
+[B<-extensions section>]
+[B<-extfile section>]
+[B<-engine id>]
+[B<-subj arg>]
+[B<-utf8>]
+[B<-create_serial>]
+[B<-multivalue-rdn>]
+
+=head1 DESCRIPTION
+
+The B<ca> command is a minimal CA application. It can be used
+to sign certificate requests in a variety of forms and generate
+CRLs it also maintains a text database of issued certificates
+and their status.
+
+The options descriptions will be divided into each purpose.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-verbose>
+
+this prints extra details about the operations being performed.
+
+=item B<-config filename>
+
+specifies the configuration file to use.
+
+=item B<-name section>
+
+specifies the configuration file section to use (overrides
+B<default_ca> in the B<ca> section).
+
+=item B<-in filename>
+
+an input filename containing a single certificate request to be
+signed by the CA.
+
+=item B<-ss_cert filename>
+
+a single self-signed certificate to be signed by the CA.
+
+=item B<-spkac filename>
+
+a file containing a single Netscape signed public key and challenge
+and additional field values to be signed by the CA. See the B<SPKAC FORMAT>
+section for information on the required input and output format.
+
+=item B<-infiles>
+
+if present this should be the last option, all subsequent arguments
+are taken as the names of files containing certificate requests.
+
+=item B<-out filename>
+
+the output file to output certificates to. The default is standard
+output. The certificate details will also be printed out to this
+file in PEM format (except that B<-spkac> outputs DER format).
+
+=item B<-outdir directory>
+
+the directory to output certificates to. The certificate will be
+written to a filename consisting of the serial number in hex with
+".pem" appended.
+
+=item B<-cert>
+
+the CA certificate file.
+
+=item B<-keyfile filename>
+
+the private key to sign requests with.
+
+=item B<-keyform PEM|DER>
+
+the format of the data in the private key file.
+The default is PEM.
+
+=item B<-key password>
+
+the password used to encrypt the private key. Since on some
+systems the command line arguments are visible (e.g. Unix with
+the 'ps' utility) this option should be used with caution.
+
+=item B<-selfsign>
+
+indicates the issued certificates are to be signed with the key
+the certificate requests were signed with (given with B<-keyfile>).
+Certificate requests signed with a different key are ignored. If
+B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
+ignored.
+
+A consequence of using B<-selfsign> is that the self-signed
+certificate appears among the entries in the certificate database
+(see the configuration option B<database>), and uses the same
+serial number counter as all other certificates sign with the
+self-signed certificate.
+
+=item B<-passin arg>
+
+the key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-notext>
+
+don't output the text form of a certificate to the output file.
+
+=item B<-startdate date>
+
+this allows the start date to be explicitly set. The format of the
+date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+
+=item B<-enddate date>
+
+this allows the expiry date to be explicitly set. The format of the
+date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+
+=item B<-days arg>
+
+the number of days to certify the certificate for.
+
+=item B<-md alg>
+
+the message digest to use.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+This option also applies to CRLs.
+
+=item B<-policy arg>
+
+this option defines the CA "policy" to use. This is a section in
+the configuration file which decides which fields should be mandatory
+or match the CA certificate. Check out the B<POLICY FORMAT> section
+for more information.
+
+=item B<-msie_hack>
+
+this is a legacy option to make B<ca> work with very old versions of
+the IE certificate enrollment control "certenr3". It used UniversalStrings
+for almost everything. Since the old control has various security bugs
+its use is strongly discouraged. The newer control "Xenroll" does not
+need this option.
+
+=item B<-preserveDN>
+
+Normally the DN order of a certificate is the same as the order of the
+fields in the relevant policy section. When this option is set the order
+is the same as the request. This is largely for compatibility with the
+older IE enrollment control which would only accept certificates if their
+DNs match the order of the request. This is not needed for Xenroll.
+
+=item B<-noemailDN>
+
+The DN of a certificate can contain the EMAIL field if present in the
+request DN, however it is good policy just having the e-mail set into
+the altName extension of the certificate. When this option is set the
+EMAIL field is removed from the certificate' subject and set only in
+the, eventually present, extensions. The B<email_in_dn> keyword can be
+used in the configuration file to enable this behaviour.
+
+=item B<-batch>
+
+this sets the batch mode. In this mode no questions will be asked
+and all certificates will be certified automatically.
+
+=item B<-extensions section>
+
+the section of the configuration file containing certificate extensions
+to be added when a certificate is issued (defaults to B<x509_extensions>
+unless the B<-extfile> option is used). If no extension section is
+present then, a V1 certificate is created. If the extension section
+is present (even if it is empty), then a V3 certificate is created. See the:w
+L<x509v3_config(5)> manual page for details of the
+extension section format.
+
+=item B<-extfile file>
+
+an additional configuration file to read certificate extensions from
+(using the default section unless the B<-extensions> option is also
+used).
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<ca>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-subj arg>
+
+supersedes subject name given in the request.
+The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
+characters may be escaped by \ (backslash), no spaces are skipped.
+
+=item B<-utf8>
+
+this option causes field values to be interpreted as UTF8 strings, by
+default they are interpreted as ASCII. This means that the field
+values, whether prompted from a terminal or obtained from a
+configuration file, must be valid UTF8 strings.
+
+=item B<-create_serial>
+
+if reading serial from the text file as specified in the configuration
+fails, specifying this option creates a new random serial to be used as next
+serial number.
+
+=item B<-multivalue-rdn>
+
+This option causes the -subj argument to be interpreted with full
+support for multivalued RDNs. Example:
+
+I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
+
+If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
+
+=back
+
+=head1 CRL OPTIONS
+
+=over 4
+
+=item B<-gencrl>
+
+this option generates a CRL based on information in the index file.
+
+=item B<-crldays num>
+
+the number of days before the next CRL is due. That is the days from
+now to place in the CRL nextUpdate field.
+
+=item B<-crlhours num>
+
+the number of hours before the next CRL is due.
+
+=item B<-revoke filename>
+
+a filename containing a certificate to revoke.
+
+=item B<-valid filename>
+
+a filename containing a certificate to add a Valid certificate entry.
+
+=item B<-status serial>
+
+displays the revocation status of the certificate with the specified
+serial number and exits.
+
+=item B<-updatedb>
+
+Updates the database index to purge expired certificates.
+
+=item B<-crl_reason reason>
+
+revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
+B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
+B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
+insensitive. Setting any revocation reason will make the CRL v2.
+
+In practice B<removeFromCRL> is not particularly useful because it is only used
+in delta CRLs which are not currently implemented.
+
+=item B<-crl_hold instruction>
+
+This sets the CRL revocation reason code to B<certificateHold> and the hold
+instruction to B<instruction> which must be an OID. Although any OID can be
+used only B<holdInstructionNone> (the use of which is discouraged by RFC2459)
+B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used.
+
+=item B<-crl_compromise time>
+
+This sets the revocation reason to B<keyCompromise> and the compromise time to
+B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>.
+
+=item B<-crl_CA_compromise time>
+
+This is the same as B<crl_compromise> except the revocation reason is set to
+B<CACompromise>.
+
+=item B<-crlexts section>
+
+the section of the configuration file containing CRL extensions to
+include. If no CRL extension section is present then a V1 CRL is
+created, if the CRL extension section is present (even if it is
+empty) then a V2 CRL is created. The CRL extensions specified are
+CRL extensions and B<not> CRL entry extensions. It should be noted
+that some software (for example Netscape) can't handle V2 CRLs. See
+L<x509v3_config(5)> manual page for details of the
+extension section format.
+
+=back
+
+=head1 CONFIGURATION FILE OPTIONS
+
+The section of the configuration file containing options for B<ca>
+is found as follows: If the B<-name> command line option is used,
+then it names the section to be used. Otherwise the section to
+be used must be named in the B<default_ca> option of the B<ca> section
+of the configuration file (or in the default section of the
+configuration file). Besides B<default_ca>, the following options are
+read directly from the B<ca> section:
+ RANDFILE
+ preserve
+ msie_hack
+With the exception of B<RANDFILE>, this is probably a bug and may
+change in future releases.
+
+Many of the configuration file options are identical to command line
+options. Where the option is present in the configuration file
+and the command line the command line value is used. Where an
+option is described as mandatory then it must be present in
+the configuration file or the command line equivalent (if
+any) used.
+
+=over 4
+
+=item B<oid_file>
+
+This specifies a file containing additional B<OBJECT IDENTIFIERS>.
+Each line of the file should consist of the numerical form of the
+object identifier followed by white space then the short name followed
+by white space and finally the long name.
+
+=item B<oid_section>
+
+This specifies a section in the configuration file containing extra
+object identifiers. Each line should consist of the short name of the
+object identifier followed by B<=> and the numerical form. The short
+and long names are the same when this option is used.
+
+=item B<new_certs_dir>
+
+the same as the B<-outdir> command line option. It specifies
+the directory where new certificates will be placed. Mandatory.
+
+=item B<certificate>
+
+the same as B<-cert>. It gives the file containing the CA
+certificate. Mandatory.
+
+=item B<private_key>
+
+same as the B<-keyfile> option. The file containing the
+CA private key. Mandatory.
+
+=item B<RANDFILE>
+
+a file used to read and write random number seed information, or
+an EGD socket (see L<RAND_egd(3)>).
+
+=item B<default_days>
+
+the same as the B<-days> option. The number of days to certify
+a certificate for.
+
+=item B<default_startdate>
+
+the same as the B<-startdate> option. The start date to certify
+a certificate for. If not set the current time is used.
+
+=item B<default_enddate>
+
+the same as the B<-enddate> option. Either this option or
+B<default_days> (or the command line equivalents) must be
+present.
+
+=item B<default_crl_hours default_crl_days>
+
+the same as the B<-crlhours> and the B<-crldays> options. These
+will only be used if neither command line option is present. At
+least one of these must be present to generate a CRL.
+
+=item B<default_md>
+
+the same as the B<-md> option. Mandatory.
+
+=item B<database>
+
+the text database file to use. Mandatory. This file must be present
+though initially it will be empty.
+
+=item B<unique_subject>
+
+if the value B<yes> is given, the valid certificate entries in the
+database must have unique subjects. if the value B<no> is given,
+several valid certificate entries may have the exact same subject.
+The default value is B<yes>, to be compatible with older (pre 0.9.8)
+versions of OpenSSL. However, to make CA certificate roll-over easier,
+it's recommended to use the value B<no>, especially if combined with
+the B<-selfsign> command line option.
+
+=item B<serial>
+
+a text file containing the next serial number to use in hex. Mandatory.
+This file must be present and contain a valid serial number.
+
+=item B<crlnumber>
+
+a text file containing the next CRL number to use in hex. The crl number
+will be inserted in the CRLs only if this file exists. If this file is
+present, it must contain a valid CRL number.
+
+=item B<x509_extensions>
+
+the same as B<-extensions>.
+
+=item B<crl_extensions>
+
+the same as B<-crlexts>.
+
+=item B<preserve>
+
+the same as B<-preserveDN>
+
+=item B<email_in_dn>
+
+the same as B<-noemailDN>. If you want the EMAIL field to be removed
+from the DN of the certificate simply set this to 'no'. If not present
+the default is to allow for the EMAIL filed in the certificate's DN.
+
+=item B<msie_hack>
+
+the same as B<-msie_hack>
+
+=item B<policy>
+
+the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
+for more information.
+
+=item B<name_opt>, B<cert_opt>
+
+these options allow the format used to display the certificate details
+when asking the user to confirm signing. All the options supported by
+the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
+here, except the B<no_signame> and B<no_sigdump> are permanently set
+and cannot be disabled (this is because the certificate signature cannot
+be displayed because the certificate has not been signed at this point).
+
+For convenience the values B<ca_default> are accepted by both to produce
+a reasonable output.
+
+If neither option is present the format used in earlier versions of
+OpenSSL is used. Use of the old format is B<strongly> discouraged because
+it only displays fields mentioned in the B<policy> section, mishandles
+multicharacter string types and does not display extensions.
+
+=item B<copy_extensions>
+
+determines how extensions in certificate requests should be handled.
+If set to B<none> or this option is not present then extensions are
+ignored and not copied to the certificate. If set to B<copy> then any
+extensions present in the request that are not already present are copied
+to the certificate. If set to B<copyall> then all extensions in the
+request are copied to the certificate: if the extension is already present
+in the certificate it is deleted first. See the B<WARNINGS> section before
+using this option.
+
+The main use of this option is to allow a certificate request to supply
+values for certain extensions such as subjectAltName.
+
+=back
+
+=head1 POLICY FORMAT
+
+The policy section consists of a set of variables corresponding to
+certificate DN fields. If the value is "match" then the field value
+must match the same field in the CA certificate. If the value is
+"supplied" then it must be present. If the value is "optional" then
+it may be present. Any fields not mentioned in the policy section
+are silently deleted, unless the B<-preserveDN> option is set but
+this can be regarded more of a quirk than intended behaviour.
+
+=head1 SPKAC FORMAT
+
+The input to the B<-spkac> command line option is a Netscape
+signed public key and challenge. This will usually come from
+the B<KEYGEN> tag in an HTML form to create a new private key.
+It is however possible to create SPKACs using the B<spkac> utility.
+
+The file should contain the variable SPKAC set to the value of
+the SPKAC and also the required DN components as name value pairs.
+If you need to include the same component twice then it can be
+preceded by a number and a '.'.
+
+When processing SPKAC format, the output is DER if the B<-out>
+flag is used, but PEM format if sending to stdout or the B<-outdir>
+flag is used.
+
+=head1 EXAMPLES
+
+Note: these examples assume that the B<ca> directory structure is
+already set up and the relevant files already exist. This usually
+involves creating a CA certificate and private key with B<req>, a
+serial number file and an empty index file and placing them in
+the relevant directories.
+
+To use the sample configuration file below the directories demoCA,
+demoCA/private and demoCA/newcerts would be created. The CA
+certificate would be copied to demoCA/cacert.pem and its private
+key to demoCA/private/cakey.pem. A file demoCA/serial would be
+created containing for example "01" and the empty index file
+demoCA/index.txt.
+
+
+Sign a certificate request:
+
+ openssl ca -in req.pem -out newcert.pem
+
+Sign a certificate request, using CA extensions:
+
+ openssl ca -in req.pem -extensions v3_ca -out newcert.pem
+
+Generate a CRL
+
+ openssl ca -gencrl -out crl.pem
+
+Sign several requests:
+
+ openssl ca -infiles req1.pem req2.pem req3.pem
+
+Certify a Netscape SPKAC:
+
+ openssl ca -spkac spkac.txt
+
+A sample SPKAC file (the SPKAC line has been truncated for clarity):
+
+ SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
+ CN=Steve Test
+ emailAddress=steve@openssl.org
+ 0.OU=OpenSSL Group
+ 1.OU=Another Group
+
+A sample configuration file with the relevant sections for B<ca>:
+
+ [ ca ]
+ default_ca = CA_default # The default ca section
+
+ [ CA_default ]
+
+ dir = ./demoCA # top dir
+ database = $dir/index.txt # index file.
+ new_certs_dir = $dir/newcerts # new certs dir
+
+ certificate = $dir/cacert.pem # The CA cert
+ serial = $dir/serial # serial no file
+ private_key = $dir/private/cakey.pem# CA private key
+ RANDFILE = $dir/private/.rand # random number file
+
+ default_days = 365 # how long to certify for
+ default_crl_days= 30 # how long before next CRL
+ default_md = md5 # md to use
+
+ policy = policy_any # default policy
+ email_in_dn = no # Don't add the email into cert DN
+
+ name_opt = ca_default # Subject name display option
+ cert_opt = ca_default # Certificate display option
+ copy_extensions = none # Don't copy extensions from request
+
+ [ policy_any ]
+ countryName = supplied
+ stateOrProvinceName = optional
+ organizationName = optional
+ organizationalUnitName = optional
+ commonName = supplied
+ emailAddress = optional
+
+=head1 FILES
+
+Note: the location of all files can change either by compile time options,
+configuration file entries, environment variables or command line options.
+The values below reflect the default values.
+
+ /usr/local/ssl/lib/openssl.cnf - master configuration file
+ ./demoCA - main CA directory
+ ./demoCA/cacert.pem - CA certificate
+ ./demoCA/private/cakey.pem - CA private key
+ ./demoCA/serial - CA serial number file
+ ./demoCA/serial.old - CA serial number backup file
+ ./demoCA/index.txt - CA text database file
+ ./demoCA/index.txt.old - CA text database backup file
+ ./demoCA/certs - certificate output file
+ ./demoCA/.rnd - CA random seed information
+
+=head1 ENVIRONMENT VARIABLES
+
+B<OPENSSL_CONF> reflects the location of master configuration file it can
+be overridden by the B<-config> command line option.
+
+=head1 RESTRICTIONS
+
+The text database index file is a critical part of the process and
+if corrupted it can be difficult to fix. It is theoretically possible
+to rebuild the index file from all the issued certificates and a current
+CRL: however there is no option to do this.
+
+V2 CRL features like delta CRLs are not currently supported.
+
+Although several requests can be input and handled at once it is only
+possible to include one SPKAC or self-signed certificate.
+
+=head1 BUGS
+
+The use of an in-memory text database can cause problems when large
+numbers of certificates are present because, as the name implies
+the database has to be kept in memory.
+
+The B<ca> command really needs rewriting or the required functionality
+exposed at either a command or interface level so a more friendly utility
+(perl script or GUI) can handle things properly. The script
+B<CA.pl> helps a little but not very much.
+
+Any fields in a request that are not present in a policy are silently
+deleted. This does not happen if the B<-preserveDN> option is used. To
+enforce the absence of the EMAIL field within the DN, as suggested by
+RFCs, regardless the contents of the request' subject the B<-noemailDN>
+option can be used. The behaviour should be more friendly and
+configurable.
+
+Canceling some commands by refusing to certify a certificate can
+create an empty file.
+
+=head1 WARNINGS
+
+The B<ca> command is quirky and at times downright unfriendly.
+
+The B<ca> utility was originally meant as an example of how to do things
+in a CA. It was not supposed to be used as a full blown CA itself:
+nevertheless some people are using it for this purpose.
+
+The B<ca> command is effectively a single user command: no locking is
+done on the various files and attempts to run more than one B<ca> command
+on the same database can have unpredictable results.
+
+The B<copy_extensions> option should be used with caution. If care is
+not taken then it can be a security risk. For example if a certificate
+request contains a basicConstraints extension with CA:TRUE and the
+B<copy_extensions> value is set to B<copyall> and the user does not spot
+this when the certificate is displayed then this will hand the requester
+a valid CA certificate.
+
+This situation can be avoided by setting B<copy_extensions> to B<copy>
+and including basicConstraints with CA:FALSE in the configuration file.
+Then if the request contains a basicConstraints extension it will be
+ignored.
+
+It is advisable to also include values for other extensions such
+as B<keyUsage> to prevent a request supplying its own values.
+
+Additional restrictions can be placed on the CA certificate itself.
+For example if the CA certificate has:
+
+ basicConstraints = CA:TRUE, pathlen:0
+
+then even if a certificate is issued with CA:TRUE it will not be valid.
+
+=head1 SEE ALSO
+
+L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
+L<config(5)>, L<x509v3_config(5)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ciphers - SSL cipher display and cipher list tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<ciphers>
+[B<-help>]
+[B<-s>]
+[B<-v>]
+[B<-V>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<-tls1_1>]
+[B<-tls1_2>]
+[B<-s>]
+[B<-psk>]
+[B<-srp>]
+[B<-stdname>]
+[B<cipherlist>]
+
+=head1 DESCRIPTION
+
+The B<ciphers> command converts textual OpenSSL cipher lists into ordered
+SSL cipher preference lists. It can be used as a test tool to determine
+the appropriate cipherlist.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print a usage message.
+
+=item B<-s>
+
+Only list supported ciphers: those consistent with the security level, and
+minimum and maximum protocol version. This is closer to the actual cipher list
+an application will support.
+
+PSK and SRP ciphers are not enabled by default: they require B<-psk> or B<-srp>
+to enable them.
+
+It also does not change the default list of supported signature algorithms.
+
+On a server the list of supported ciphers might also exclude other ciphers
+depending on the configured certificates and presence of DH parameters.
+
+If this option is not used then all ciphers that match the cipherlist will be
+listed.
+
+=item B<-psk>
+
+When combined with B<-s> includes cipher suites which require PSK.
+
+=item B<-srp>
+
+When combined with B<-s> includes cipher suites which require SRP.
+
+=item B<-v>
+
+Verbose output: For each ciphersuite, list details as provided by
+L<SSL_CIPHER_description(3)>.
+
+=item B<-V>
+
+Like B<-v>, but include the official cipher suite values in hex.
+
+=item B<-tls1_2>
+
+In combination with the B<-s> option, list the ciphers which would be used if
+TLSv1.2 were negotiated.
+
+=item B<-ssl3>
+
+In combination with the B<-s> option, list the ciphers which would be used if
+SSLv3 were negotiated.
+
+=item B<-tls1>
+
+In combination with the B<-s> option, list the ciphers which would be used if
+TLSv1 were negotiated.
+
+=item B<-tls1_1>
+
+In combination with the B<-s> option, list the ciphers which would be used if
+TLSv1.1 were negotiated.
+
+=item B<-stdname>
+
+precede each ciphersuite by its standard name: only available is OpenSSL
+is built with tracing enabled (B<enable-ssl-trace> argument to Configure).
+
+=item B<cipherlist>
+
+a cipher list to convert to a cipher preference list. If it is not included
+then the default cipher list will be used. The format is described below.
+
+=back
+
+=head1 CIPHER LIST FORMAT
+
+The cipher list consists of one or more I<cipher strings> separated by colons.
+Commas or spaces are also acceptable separators but colons are normally used.
+
+The actual cipher string can take several different forms.
+
+It can consist of a single cipher suite such as B<RC4-SHA>.
+
+It can represent a list of cipher suites containing a certain algorithm, or
+cipher suites of a certain type. For example B<SHA1> represents all ciphers
+suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3
+algorithms.
+
+Lists of cipher suites can be combined in a single cipher string using the
+B<+> character. This is used as a logical B<and> operation. For example
+B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES
+algorithms.
+
+Each cipher string can be optionally preceded by the characters B<!>,
+B<-> or B<+>.
+
+If B<!> is used then the ciphers are permanently deleted from the list.
+The ciphers deleted can never reappear in the list even if they are
+explicitly stated.
+
+If B<-> is used then the ciphers are deleted from the list, but some or
+all of the ciphers can be added again by later options.
+
+If B<+> is used then the ciphers are moved to the end of the list. This
+option doesn't add any new ciphers it just moves matching existing ones.
+
+If none of these characters is present then the string is just interpreted
+as a list of ciphers to be appended to the current preference list. If the
+list includes any ciphers already present they will be ignored: that is they
+will not moved to the end of the list.
+
+The cipher string B<@STRENGTH> can be used at any point to sort the current
+cipher list in order of encryption algorithm key length.
+
+The cipher string B<@SECLEVEL=n> can be used at any point to set the security
+level to B<n>.
+
+=head1 CIPHER STRINGS
+
+The following is a list of all permitted cipher strings and their meanings.
+
+=over 4
+
+=item B<DEFAULT>
+
+The default cipher list.
+This is determined at compile time and is normally
+B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>.
+When used, this must be the first cipherstring specified.
+
+=item B<COMPLEMENTOFDEFAULT>
+
+The ciphers included in B<ALL>, but not enabled by default. Currently
+this includes all RC4 and anonymous ciphers. Note that this rule does
+not cover B<eNULL>, which is not included by B<ALL> (use B<COMPLEMENTOFALL> if
+necessary). Note that RC4 based ciphersuites are not built into OpenSSL by
+default (see the enable-weak-ssl-ciphers option to Configure).
+
+=item B<ALL>
+
+All cipher suites except the B<eNULL> ciphers (which must be explicitly enabled
+if needed).
+As of OpenSSL 1.0.0, the B<ALL> cipher suites are sensibly ordered by default.
+
+=item B<COMPLEMENTOFALL>
+
+The cipher suites not enabled by B<ALL>, currently B<eNULL>.
+
+=item B<HIGH>
+
+"high" encryption cipher suites. This currently means those with key lengths
+larger than 128 bits, and some cipher suites with 128-bit keys.
+
+=item B<MEDIUM>
+
+"medium" encryption cipher suites, currently some of those using 128 bit
+encryption.
+
+=item B<LOW>
+
+"low" encryption cipher suites, currently those using 64 or 56 bit
+encryption algorithms but excluding export cipher suites. All these
+ciphersuites have been removed as of OpenSSL 1.1.0.
+
+=item B<eNULL>, B<NULL>
+
+The "NULL" ciphers that is those offering no encryption. Because these offer no
+encryption at all and are a security risk they are not enabled via either the
+B<DEFAULT> or B<ALL> cipher strings.
+Be careful when building cipherlists out of lower-level primitives such as
+B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers. When in
+doubt, include B<!eNULL> in your cipherlist.
+
+=item B<aNULL>
+
+The cipher suites offering no authentication. This is currently the anonymous
+DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable
+to "man in the middle" attacks and so their use is discouraged.
+These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL>
+ciphers.
+Be careful when building cipherlists out of lower-level primitives such as
+B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers.
+When in doubt, include B<!aNULL> in your cipherlist.
+
+=item B<kRSA>, B<aRSA>, B<RSA>
+
+Cipher suites using RSA key exchange, authentication or either respectively.
+
+=item B<kDHr>, B<kDHd>, B<kDH>
+
+Cipher suites using static DH key agreement and DH certificates signed by CAs
+with RSA and DSS keys or either respectively.
+All these cipher suites have been removed in OpenSSL 1.1.0.
+
+=item B<kDHE>, B<kEDH>, B<DH>
+
+Cipher suites using ephemeral DH key agreement, including anonymous cipher
+suites.
+
+=item B<DHE>, B<EDH>
+
+Cipher suites using authenticated ephemeral DH key agreement.
+
+=item B<ADH>
+
+Anonymous DH cipher suites, note that this does not include anonymous Elliptic
+Curve DH (ECDH) cipher suites.
+
+=item B<kEECDH>, B<kECDHE>, B<ECDH>
+
+Cipher suites using ephemeral ECDH key agreement, including anonymous
+cipher suites.
+
+=item B<ECDHE>, B<EECDH>
+
+Cipher suites using authenticated ephemeral ECDH key agreement.
+
+=item B<AECDH>
+
+Anonymous Elliptic Curve Diffie-Hellman cipher suites.
+
+=item B<aDSS>, B<DSS>
+
+Cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
+
+=item B<aDH>
+
+Cipher suites effectively using DH authentication, i.e. the certificates carry
+DH keys.
+All these cipher suites have been removed in OpenSSL 1.1.0.
+
+=item B<aECDSA>, B<ECDSA>
+
+Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
+keys.
+
+=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3>
+
+Lists ciphersuites which are only supported in at least TLS v1.2, TLS v1.0 or
+SSL v3.0 respectively.
+Note: there are no ciphersuites specific to TLS v1.1.
+Since this is only the minimum version, if, for example, TLSv1.0 is negotiated
+then both TLSv1.0 and SSLv3.0 ciphersuites are available.
+
+Note: these cipher strings B<do not> change the negotiated version of SSL or
+TLS, they only affect the list of available cipher suites.
+
+=item B<AES128>, B<AES256>, B<AES>
+
+cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
+
+=item B<AESGCM>
+
+AES in Galois Counter Mode (GCM): these ciphersuites are only supported
+in TLS v1.2.
+
+=item B<AESCCM>, B<AESCCM8>
+
+AES in Cipher Block Chaining - Message Authentication Mode (CCM): these
+ciphersuites are only supported in TLS v1.2. B<AESCCM> references CCM
+cipher suites using both 16 and 8 octet Integrity Check Value (ICV)
+while B<AESCCM8> only references 8 octet ICV.
+
+=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
+
+cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
+CAMELLIA.
+
+=item B<CHACHA20>
+
+cipher suites using ChaCha20.
+
+=item B<3DES>
+
+cipher suites using triple DES.
+
+=item B<DES>
+
+Cipher suites using DES (not triple DES).
+All these cipher suites have been removed in OpenSSL 1.1.0.
+
+=item B<RC4>
+
+Cipher suites using RC4.
+
+=item B<RC2>
+
+Cipher suites using RC2.
+
+=item B<IDEA>
+
+Cipher suites using IDEA.
+
+=item B<SEED>
+
+Cipher suites using SEED.
+
+=item B<MD5>
+
+Cipher suites using MD5.
+
+=item B<SHA1>, B<SHA>
+
+Cipher suites using SHA1.
+
+=item B<SHA256>, B<SHA384>
+
+Ciphersuites using SHA256 or SHA384.
+
+=item B<aGOST>
+
+Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication
+(needs an engine supporting GOST algorithms).
+
+=item B<aGOST01>
+
+Cipher suites using GOST R 34.10-2001 authentication.
+
+=item B<kGOST>
+
+Cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
+
+=item B<GOST94>
+
+Cipher suites, using HMAC based on GOST R 34.11-94.
+
+=item B<GOST89MAC>
+
+Cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
+
+=item B<PSK>
+
+All cipher suites using pre-shared keys (PSK).
+
+=item B<kPSK>, B<kECDHEPSK>, B<kDHEPSK>, B<kRSAPSK>
+
+Cipher suites using PSK key exchange, ECDHE_PSK, DHE_PSK or RSA_PSK.
+
+=item B<aPSK>
+
+Cipher suites using PSK authentication (currently all PSK modes apart from
+RSA_PSK).
+
+=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
+
+Enables suite B mode of operation using 128 (permitting 192 bit mode by peer)
+128 bit (not permitting 192 bit by peer) or 192 bit level of security
+respectively.
+If used these cipherstrings should appear first in the cipher
+list and anything after them is ignored.
+Setting Suite B mode has additional consequences required to comply with
+RFC6460.
+In particular the supported signature algorithms is reduced to support only
+ECDSA and SHA256 or SHA384, only the elliptic curves P-256 and P-384 can be
+used and only the two suite B compliant ciphersuites
+(ECDHE-ECDSA-AES128-GCM-SHA256 and ECDHE-ECDSA-AES256-GCM-SHA384) are
+permissible.
+
+=back
+
+=head1 CIPHER SUITE NAMES
+
+The following lists give the SSL or TLS cipher suites names from the
+relevant specification and their OpenSSL equivalents. It should be noted,
+that several cipher suite names do not include the authentication used,
+e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
+
+=head2 SSL v3.0 cipher suites
+
+ SSL_RSA_WITH_NULL_MD5 NULL-MD5
+ SSL_RSA_WITH_NULL_SHA NULL-SHA
+ SSL_RSA_WITH_RC4_128_MD5 RC4-MD5
+ SSL_RSA_WITH_RC4_128_SHA RC4-SHA
+ SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
+ SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
+
+ SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA
+ SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA
+ SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
+ SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
+
+ SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
+ SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
+
+ SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented.
+ SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented.
+ SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented.
+
+=head2 TLS v1.0 cipher suites
+
+ TLS_RSA_WITH_NULL_MD5 NULL-MD5
+ TLS_RSA_WITH_NULL_SHA NULL-SHA
+ TLS_RSA_WITH_RC4_128_MD5 RC4-MD5
+ TLS_RSA_WITH_RC4_128_SHA RC4-SHA
+ TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
+ TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
+
+ TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
+ TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
+ TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
+ TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
+
+ TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
+ TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
+
+=head2 AES ciphersuites from RFC3268, extending TLS v1.0
+
+ TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA
+ TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA
+
+ TLS_DH_DSS_WITH_AES_128_CBC_SHA DH-DSS-AES128-SHA
+ TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA
+ TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA
+ TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA
+
+ TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA
+ TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA
+ TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE-RSA-AES128-SHA
+ TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA
+
+ TLS_DH_anon_WITH_AES_128_CBC_SHA ADH-AES128-SHA
+ TLS_DH_anon_WITH_AES_256_CBC_SHA ADH-AES256-SHA
+
+=head2 Camellia ciphersuites from RFC4132, extending TLS v1.0
+
+ TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA
+ TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA
+
+ TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA DH-DSS-CAMELLIA128-SHA
+ TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA DH-DSS-CAMELLIA256-SHA
+ TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA DH-RSA-CAMELLIA128-SHA
+ TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA DH-RSA-CAMELLIA256-SHA
+
+ TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA
+ TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA
+ TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA DHE-RSA-CAMELLIA128-SHA
+ TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA DHE-RSA-CAMELLIA256-SHA
+
+ TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA ADH-CAMELLIA128-SHA
+ TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA ADH-CAMELLIA256-SHA
+
+=head2 SEED ciphersuites from RFC4162, extending TLS v1.0
+
+ TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA
+
+ TLS_DH_DSS_WITH_SEED_CBC_SHA DH-DSS-SEED-SHA
+ TLS_DH_RSA_WITH_SEED_CBC_SHA DH-RSA-SEED-SHA
+
+ TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA
+ TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA
+
+ TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA
+
+=head2 GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0
+
+Note: these ciphers require an engine which including GOST cryptographic
+algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
+
+ TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89
+ TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89
+ TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94
+ TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94
+
+=head2 Additional Export 1024 and other cipher suites
+
+Note: these ciphers can also be used in SSL v3.
+
+ TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA
+
+=head2 Elliptic curve cipher suites.
+
+ TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA
+ TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA
+ TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA
+ TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA
+ TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA
+
+ TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA
+ TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA
+ TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA
+ TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA
+ TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA
+
+ TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA
+ TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA
+ TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA
+ TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA
+ TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA
+
+=head2 TLS v1.2 cipher suites
+
+ TLS_RSA_WITH_NULL_SHA256 NULL-SHA256
+
+ TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256
+ TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256
+ TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256
+ TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384
+
+ TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH-RSA-AES128-SHA256
+ TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH-RSA-AES256-SHA256
+ TLS_DH_RSA_WITH_AES_128_GCM_SHA256 DH-RSA-AES128-GCM-SHA256
+ TLS_DH_RSA_WITH_AES_256_GCM_SHA384 DH-RSA-AES256-GCM-SHA384
+
+ TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH-DSS-AES128-SHA256
+ TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH-DSS-AES256-SHA256
+ TLS_DH_DSS_WITH_AES_128_GCM_SHA256 DH-DSS-AES128-GCM-SHA256
+ TLS_DH_DSS_WITH_AES_256_GCM_SHA384 DH-DSS-AES256-GCM-SHA384
+
+ TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE-RSA-AES128-SHA256
+ TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE-RSA-AES256-SHA256
+ TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE-RSA-AES128-GCM-SHA256
+ TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE-RSA-AES256-GCM-SHA384
+
+ TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE-DSS-AES128-SHA256
+ TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE-DSS-AES256-SHA256
+ TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256
+ TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384
+
+ TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256
+ TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384
+ TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256
+ TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384
+
+ TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256
+ TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384
+ TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256
+ TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384
+
+ TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256
+ TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256
+ TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256
+ TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384
+
+ RSA_WITH_AES_128_CCM AES128-CCM
+ RSA_WITH_AES_256_CCM AES256-CCM
+ DHE_RSA_WITH_AES_128_CCM DHE-RSA-AES128-CCM
+ DHE_RSA_WITH_AES_256_CCM DHE-RSA-AES256-CCM
+ RSA_WITH_AES_128_CCM_8 AES128-CCM8
+ RSA_WITH_AES_256_CCM_8 AES256-CCM8
+ DHE_RSA_WITH_AES_128_CCM_8 DHE-RSA-AES128-CCM8
+ DHE_RSA_WITH_AES_256_CCM_8 DHE-RSA-AES256-CCM8
+ ECDHE_ECDSA_WITH_AES_128_CCM ECDHE-ECDSA-AES128-CCM
+ ECDHE_ECDSA_WITH_AES_256_CCM ECDHE-ECDSA-AES256-CCM
+ ECDHE_ECDSA_WITH_AES_128_CCM_8 ECDHE-ECDSA-AES128-CCM8
+ ECDHE_ECDSA_WITH_AES_256_CCM_8 ECDHE-ECDSA-AES256-CCM8
+
+=head2 Camellia HMAC-Based ciphersuites from RFC6367, extending TLS v1.2
+
+ TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256
+ TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384
+ TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-RSA-CAMELLIA128-SHA256
+ TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-RSA-CAMELLIA256-SHA384
+
+=head2 Pre-shared keying (PSK) ciphersuites
+
+ PSK_WITH_NULL_SHA PSK-NULL-SHA
+ DHE_PSK_WITH_NULL_SHA DHE-PSK-NULL-SHA
+ RSA_PSK_WITH_NULL_SHA RSA-PSK-NULL-SHA
+
+ PSK_WITH_RC4_128_SHA PSK-RC4-SHA
+ PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
+ PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
+ PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
+
+ DHE_PSK_WITH_RC4_128_SHA DHE-PSK-RC4-SHA
+ DHE_PSK_WITH_3DES_EDE_CBC_SHA DHE-PSK-3DES-EDE-CBC-SHA
+ DHE_PSK_WITH_AES_128_CBC_SHA DHE-PSK-AES128-CBC-SHA
+ DHE_PSK_WITH_AES_256_CBC_SHA DHE-PSK-AES256-CBC-SHA
+
+ RSA_PSK_WITH_RC4_128_SHA RSA-PSK-RC4-SHA
+ RSA_PSK_WITH_3DES_EDE_CBC_SHA RSA-PSK-3DES-EDE-CBC-SHA
+ RSA_PSK_WITH_AES_128_CBC_SHA RSA-PSK-AES128-CBC-SHA
+ RSA_PSK_WITH_AES_256_CBC_SHA RSA-PSK-AES256-CBC-SHA
+
+ PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
+ PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
+ DHE_PSK_WITH_AES_128_GCM_SHA256 DHE-PSK-AES128-GCM-SHA256
+ DHE_PSK_WITH_AES_256_GCM_SHA384 DHE-PSK-AES256-GCM-SHA384
+ RSA_PSK_WITH_AES_128_GCM_SHA256 RSA-PSK-AES128-GCM-SHA256
+ RSA_PSK_WITH_AES_256_GCM_SHA384 RSA-PSK-AES256-GCM-SHA384
+
+ PSK_WITH_AES_128_CBC_SHA256 PSK-AES128-CBC-SHA256
+ PSK_WITH_AES_256_CBC_SHA384 PSK-AES256-CBC-SHA384
+ PSK_WITH_NULL_SHA256 PSK-NULL-SHA256
+ PSK_WITH_NULL_SHA384 PSK-NULL-SHA384
+ DHE_PSK_WITH_AES_128_CBC_SHA256 DHE-PSK-AES128-CBC-SHA256
+ DHE_PSK_WITH_AES_256_CBC_SHA384 DHE-PSK-AES256-CBC-SHA384
+ DHE_PSK_WITH_NULL_SHA256 DHE-PSK-NULL-SHA256
+ DHE_PSK_WITH_NULL_SHA384 DHE-PSK-NULL-SHA384
+ RSA_PSK_WITH_AES_128_CBC_SHA256 RSA-PSK-AES128-CBC-SHA256
+ RSA_PSK_WITH_AES_256_CBC_SHA384 RSA-PSK-AES256-CBC-SHA384
+ RSA_PSK_WITH_NULL_SHA256 RSA-PSK-NULL-SHA256
+ RSA_PSK_WITH_NULL_SHA384 RSA-PSK-NULL-SHA384
+ PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
+ PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
+
+ ECDHE_PSK_WITH_RC4_128_SHA ECDHE-PSK-RC4-SHA
+ ECDHE_PSK_WITH_3DES_EDE_CBC_SHA ECDHE-PSK-3DES-EDE-CBC-SHA
+ ECDHE_PSK_WITH_AES_128_CBC_SHA ECDHE-PSK-AES128-CBC-SHA
+ ECDHE_PSK_WITH_AES_256_CBC_SHA ECDHE-PSK-AES256-CBC-SHA
+ ECDHE_PSK_WITH_AES_128_CBC_SHA256 ECDHE-PSK-AES128-CBC-SHA256
+ ECDHE_PSK_WITH_AES_256_CBC_SHA384 ECDHE-PSK-AES256-CBC-SHA384
+ ECDHE_PSK_WITH_NULL_SHA ECDHE-PSK-NULL-SHA
+ ECDHE_PSK_WITH_NULL_SHA256 ECDHE-PSK-NULL-SHA256
+ ECDHE_PSK_WITH_NULL_SHA384 ECDHE-PSK-NULL-SHA384
+
+ PSK_WITH_CAMELLIA_128_CBC_SHA256 PSK-CAMELLIA128-SHA256
+ PSK_WITH_CAMELLIA_256_CBC_SHA384 PSK-CAMELLIA256-SHA384
+
+ DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 DHE-PSK-CAMELLIA128-SHA256
+ DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 DHE-PSK-CAMELLIA256-SHA384
+
+ RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 RSA-PSK-CAMELLIA128-SHA256
+ RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 RSA-PSK-CAMELLIA256-SHA384
+
+ ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-PSK-CAMELLIA128-SHA256
+ ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-PSK-CAMELLIA256-SHA384
+
+ PSK_WITH_AES_128_CCM PSK-AES128-CCM
+ PSK_WITH_AES_256_CCM PSK-AES256-CCM
+ DHE_PSK_WITH_AES_128_CCM DHE-PSK-AES128-CCM
+ DHE_PSK_WITH_AES_256_CCM DHE-PSK-AES256-CCM
+ PSK_WITH_AES_128_CCM_8 PSK-AES128-CCM8
+ PSK_WITH_AES_256_CCM_8 PSK-AES256-CCM8
+ DHE_PSK_WITH_AES_128_CCM_8 DHE-PSK-AES128-CCM8
+ DHE_PSK_WITH_AES_256_CCM_8 DHE-PSK-AES256-CCM8
+
+=head2 ChaCha20-Poly1305 cipher suites, extending TLS v1.2
+
+ TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-RSA-CHACHA20-POLY1305
+ TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-ECDSA-CHACHA20-POLY1305
+ TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 DHE-RSA-CHACHA20-POLY1305
+ TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 PSK-CHACHA20-POLY1305
+ TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 ECDHE-PSK-CHACHA20-POLY1305
+ TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 DHE-PSK-CHACHA20-POLY1305
+ TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 RSA-PSK-CHACHA20-POLY1305
+
+=head2 Older names used by OpenSSL
+
+The following names are accepted by older releases:
+
+ SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA)
+ SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA)
+
+=head1 NOTES
+
+Some compiled versions of OpenSSL may not include all the ciphers
+listed here because some ciphers were excluded at compile time.
+
+=head1 EXAMPLES
+
+Verbose listing of all OpenSSL ciphers including NULL ciphers:
+
+ openssl ciphers -v 'ALL:eNULL'
+
+Include all ciphers except NULL and anonymous DH then sort by
+strength:
+
+ openssl ciphers -v 'ALL:!ADH:@STRENGTH'
+
+Include all ciphers except ones with no encryption (eNULL) or no
+authentication (aNULL):
+
+ openssl ciphers -v 'ALL:!aNULL'
+
+Include only 3DES ciphers and then place RSA ciphers last:
+
+ openssl ciphers -v '3DES:+RSA'
+
+Include all RC4 ciphers but leave out those without authentication:
+
+ openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
+
+Include all ciphers with RSA authentication but leave out ciphers without
+encryption.
+
+ openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
+
+Set security level to 2 and display all ciphers consistent with level 2:
+
+ openssl ciphers -s -v 'ALL:@SECLEVEL=2'
+
+=head1 SEE ALSO
+
+L<s_client(1)>, L<s_server(1)>, L<ssl(3)>
+
+=head1 HISTORY
+
+The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+cms - CMS utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<cms>
+[B<-help>]
+[B<-encrypt>]
+[B<-decrypt>]
+[B<-sign>]
+[B<-verify>]
+[B<-cmsout>]
+[B<-resign>]
+[B<-data_create>]
+[B<-data_out>]
+[B<-digest_create>]
+[B<-digest_verify>]
+[B<-compress>]
+[B<-uncompress>]
+[B<-EncryptedData_encrypt>]
+[B<-sign_receipt>]
+[B<-verify_receipt receipt>]
+[B<-in filename>]
+[B<-inform SMIME|PEM|DER>]
+[B<-rctform SMIME|PEM|DER>]
+[B<-out filename>]
+[B<-outform SMIME|PEM|DER>]
+[B<-stream -indef -noindef>]
+[B<-noindef>]
+[B<-content filename>]
+[B<-text>]
+[B<-noout>]
+[B<-print>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-no_check_time>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-use_deltas>]
+[B<-auth_level num>]
+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
+[B<-md digest>]
+[B<-[cipher]>]
+[B<-nointern>]
+[B<-no_signer_cert_verify>]
+[B<-nocerts>]
+[B<-noattr>]
+[B<-nosmimecap>]
+[B<-binary>]
+[B<-crlfeol>]
+[B<-asciicrlf>]
+[B<-nodetach>]
+[B<-certfile file>]
+[B<-certsout file>]
+[B<-signer file>]
+[B<-recip file>]
+[B<-keyid>]
+[B<-receipt_request_all -receipt_request_first>]
+[B<-receipt_request_from emailaddress>]
+[B<-receipt_request_to emailaddress>]
+[B<-receipt_request_print>]
+[B<-secretkey key>]
+[B<-secretkeyid id>]
+[B<-econtent_type type>]
+[B<-inkey file>]
+[B<-keyopt name:parameter>]
+[B<-passin arg>]
+[B<-rand file(s)>]
+[B<cert.pem...>]
+[B<-to addr>]
+[B<-from addr>]
+[B<-subject subj>]
+[cert.pem]...
+
+=head1 DESCRIPTION
+
+The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
+verify, compress and uncompress S/MIME messages.
+
+=head1 COMMAND OPTIONS
+
+There are fourteen operation options that set the type of operation to be
+performed. The meaning of the other options varies according to the operation
+type.
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-encrypt>
+
+encrypt mail for the given recipient certificates. Input file is the message
+to be encrypted. The output file is the encrypted mail in MIME format. The
+actual CMS type is <B>EnvelopedData<B>.
+
+Note that no revocation check is done for the recipient cert, so if that
+key has been compromised, others may be able to decrypt the text.
+
+=item B<-decrypt>
+
+decrypt mail using the supplied certificate and private key. Expects an
+encrypted mail message in MIME format for the input file. The decrypted mail
+is written to the output file.
+
+=item B<-debug_decrypt>
+
+this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used
+with caution: see the notes section below.
+
+=item B<-sign>
+
+sign mail using the supplied certificate and private key. Input file is
+the message to be signed. The signed message in MIME format is written
+to the output file.
+
+=item B<-verify>
+
+verify signed mail. Expects a signed mail message on input and outputs
+the signed data. Both clear text and opaque signing is supported.
+
+=item B<-cmsout>
+
+takes an input message and writes out a PEM encoded CMS structure.
+
+=item B<-resign>
+
+resign a message: take an existing message and one or more new signers.
+
+=item B<-data_create>
+
+Create a CMS B<Data> type.
+
+=item B<-data_out>
+
+B<Data> type and output the content.
+
+=item B<-digest_create>
+
+Create a CMS B<DigestedData> type.
+
+=item B<-digest_verify>
+
+Verify a CMS B<DigestedData> type and output the content.
+
+=item B<-compress>
+
+Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib>
+support for this option to work, otherwise it will output an error.
+
+=item B<-uncompress>
+
+Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be
+compiled with B<zlib> support for this option to work, otherwise it will
+output an error.
+
+=item B<-EncryptedData_encrypt>
+
+Encrypt content using supplied symmetric key and algorithm using a CMS
+B<EncrytedData> type and output the content.
+
+=item B<-sign_receipt>
+
+Generate and output a signed receipt for the supplied message. The input
+message B<must> contain a signed receipt request. Functionality is otherwise
+similar to the B<-sign> operation.
+
+=item B<-verify_receipt receipt>
+
+Verify a signed receipt in filename B<receipt>. The input message B<must>
+contain the original receipt request. Functionality is otherwise similar
+to the B<-verify> operation.
+
+=item B<-in filename>
+
+the input message to be encrypted or signed or the message to be decrypted
+or verified.
+
+=item B<-inform SMIME|PEM|DER>
+
+this specifies the input format for the CMS structure. The default
+is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
+format change this to expect PEM and DER format CMS structures
+instead. This currently only affects the input format of the CMS
+structure, if no CMS structure is being input (for example with
+B<-encrypt> or B<-sign>) this option has no effect.
+
+=item B<-rctform SMIME|PEM|DER>
+
+specify the format for a signed receipt for use with the B<-receipt_verify>
+operation.
+
+=item B<-out filename>
+
+the message text that has been decrypted or verified or the output MIME
+format message that has been signed or verified.
+
+=item B<-outform SMIME|PEM|DER>
+
+this specifies the output format for the CMS structure. The default
+is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER>
+format change this to write PEM and DER format CMS structures
+instead. This currently only affects the output format of the CMS
+structure, if no CMS structure is being output (for example with
+B<-verify> or B<-decrypt>) this option has no effect.
+
+=item B<-stream -indef -noindef>
+
+the B<-stream> and B<-indef> options are equivalent and enable streaming I/O
+for encoding operations. This permits single pass processing of data without
+the need to hold the entire contents in memory, potentially supporting very
+large files. Streaming is automatically set for S/MIME signing with detached
+data if the output format is B<SMIME> it is currently off by default for all
+other operations.
+
+=item B<-noindef>
+
+disable streaming I/O where it would produce and indefinite length constructed
+encoding. This option currently has no effect. In future streaming will be
+enabled by default on all relevant operations and this option will disable it.
+
+=item B<-content filename>
+
+This specifies a file containing the detached content, this is only
+useful with the B<-verify> command. This is only usable if the CMS
+structure is using the detached signature form where the content is
+not included. This option will override any content if the input format
+is S/MIME and it uses the multipart/signed MIME content type.
+
+=item B<-text>
+
+this option adds plain text (text/plain) MIME headers to the supplied
+message if encrypting or signing. If decrypting or verifying it strips
+off text headers: if the decrypted or verified message is not of MIME
+type text/plain then an error occurs.
+
+=item B<-noout>
+
+for the B<-cmsout> operation do not output the parsed CMS structure. This
+is useful when combined with the B<-print> option or if the syntax of the CMS
+structure is being checked.
+
+=item B<-print>
+
+for the B<-cmsout> operation print out all fields of the CMS structure. This
+is mainly useful for testing purposes.
+
+=item B<-CAfile file>
+
+a file containing trusted CA certificates, only used with B<-verify>.
+
+=item B<-CApath dir>
+
+a directory containing trusted CA certificates, only used with
+B<-verify>. This directory must be a standard certificate directory: that
+is a hash of each subject name (using B<x509 -hash>) should be linked
+to each certificate.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-md digest>
+
+digest algorithm to use when signing or resigning. If not present then the
+default digest algorithm for the signing key will be used (usually SHA1).
+
+=item B<-[cipher]>
+
+the encryption algorithm to use. For example triple DES (168 bits) - B<-des3>
+or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
+EVP_get_cipherbyname() function) can also be used preceded by a dash, for
+example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for a list of ciphers
+supported by your version of OpenSSL.
+
+If not specified triple DES is used. Only used with B<-encrypt> and
+B<-EncryptedData_create> commands.
+
+=item B<-nointern>
+
+when verifying a message normally certificates (if any) included in
+the message are searched for the signing certificate. With this option
+only the certificates specified in the B<-certfile> option are used.
+The supplied certificates can still be used as untrusted CAs however.
+
+=item B<-no_signer_cert_verify>
+
+do not verify the signers certificate of a signed message.
+
+=item B<-nocerts>
+
+when signing a message the signer's certificate is normally included
+with this option it is excluded. This will reduce the size of the
+signed message but the verifier must have a copy of the signers certificate
+available locally (passed using the B<-certfile> option for example).
+
+=item B<-noattr>
+
+normally when a message is signed a set of attributes are included which
+include the signing time and supported symmetric algorithms. With this
+option they are not included.
+
+=item B<-nosmimecap>
+
+exclude the list of supported algorithms from signed attributes, other options
+such as signing time and content type are still included.
+
+=item B<-binary>
+
+normally the input message is converted to "canonical" format which is
+effectively using CR and LF as end of line: as required by the S/MIME
+specification. When this option is present no translation occurs. This
+is useful when handling binary data which may not be in MIME format.
+
+=item B<-crlfeol>
+
+normally the output file uses a single B<LF> as end of line. When this
+option is present B<CRLF> is used instead.
+
+=item B<-asciicrlf>
+
+when signing use ASCII CRLF format canonicalisation. This strips trailing
+whitespace from all lines, deletes trailing blank lines at EOF and sets
+the encapsulated content type. This option is normally used with detached
+content and an output signature format of DER. This option is not normally
+needed when verifying as it is enabled automatically if the encapsulated
+content format is detected.
+
+=item B<-nodetach>
+
+when signing a message use opaque signing: this form is more resistant
+to translation by mail relays but it cannot be read by mail agents that
+do not support S/MIME. Without this option cleartext signing with
+the MIME type multipart/signed is used.
+
+=item B<-certfile file>
+
+allows additional certificates to be specified. When signing these will
+be included with the message. When verifying these will be searched for
+the signers certificates. The certificates should be in PEM format.
+
+=item B<-certsout file>
+
+any certificates contained in the message are written to B<file>.
+
+=item B<-signer file>
+
+a signing certificate when signing or resigning a message, this option can be
+used multiple times if more than one signer is required. If a message is being
+verified then the signers certificates will be written to this file if the
+verification was successful.
+
+=item B<-recip file>
+
+when decrypting a message this specifies the recipients certificate. The
+certificate must match one of the recipients of the message or an error
+occurs.
+
+When encrypting a message this option may be used multiple times to specify
+each recipient. This form B<must> be used if customised parameters are
+required (for example to specify RSA-OAEP).
+
+=item B<-keyid>
+
+use subject key identifier to identify certificates instead of issuer name and
+serial number. The supplied certificate B<must> include a subject key
+identifier extension. Supported by B<-sign> and B<-encrypt> options.
+
+=item B<-receipt_request_all -receipt_request_first>
+
+for B<-sign> option include a signed receipt request. Indicate requests should
+be provided by all recipient or first tier recipients (those mailed directly
+and not from a mailing list). Ignored it B<-receipt_request_from> is included.
+
+=item B<-receipt_request_from emailaddress>
+
+for B<-sign> option include a signed receipt request. Add an explicit email
+address where receipts should be supplied.
+
+=item B<-receipt_request_to emailaddress>
+
+Add an explicit email address where signed receipts should be sent to. This
+option B<must> but supplied if a signed receipt it requested.
+
+=item B<-receipt_request_print>
+
+For the B<-verify> operation print out the contents of any signed receipt
+requests.
+
+=item B<-secretkey key>
+
+specify symmetric key to use. The key must be supplied in hex format and be
+consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
+B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
+with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
+content encryption key using an AES key in the B<KEKRecipientInfo> type.
+
+=item B<-secretkeyid id>
+
+the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type.
+This option B<must> be present if the B<-secretkey> option is used with
+B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the
+relevant key if it is not supplied then an attempt is used to decrypt any
+B<KEKRecipientInfo> structures.
+
+=item B<-econtent_type type>
+
+set the encapsulated content type to B<type> if not supplied the B<Data> type
+is used. The B<type> argument can be any valid OID name in either text or
+numerical format.
+
+=item B<-inkey file>
+
+the private key to use when signing or decrypting. This must match the
+corresponding certificate. If this option is not specified then the
+private key must be included in the certificate file specified with
+the B<-recip> or B<-signer> file. When signing this option can be used
+multiple times to specify successive keys.
+
+=item B<-keyopt name:opt>
+
+for signing and encryption this option can be used multiple times to
+set customised parameters for the preceding key or certificate. It can
+currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
+or to modify default parameters for ECDH.
+
+=item B<-passin arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<cert.pem...>
+
+one or more certificates of message recipients: used when encrypting
+a message.
+
+=item B<-to, -from, -subject>
+
+the relevant mail headers. These are included outside the signed
+portion of a message so they may be included manually. If signing
+then many S/MIME mail clients check the signers certificate's email
+address matches that specified in the From: address.
+
+=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
+B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
+B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
+B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
+B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
+B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
+B<-verify_ip>, B<-verify_name>, B<-x509_strict>
+
+Set various certificate chain validation options. See the
+L<verify(1)> manual page for details.
+
+=back
+
+=head1 NOTES
+
+The MIME message must be sent without any blank lines between the
+headers and the output. Some mail programs will automatically add
+a blank line. Piping the mail directly to sendmail is one way to
+achieve the correct format.
+
+The supplied message to be signed or encrypted must include the
+necessary MIME headers or many S/MIME clients won't display it
+properly (if at all). You can use the B<-text> option to automatically
+add plain text headers.
+
+A "signed and encrypted" message is one where a signed message is
+then encrypted. This can be produced by encrypting an already signed
+message: see the examples section.
+
+This version of the program only allows one signer per message but it
+will verify multiple signers on received messages. Some S/MIME clients
+choke if a message contains multiple signers. It is possible to sign
+messages "in parallel" by signing an already signed message.
+
+The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
+clients. Strictly speaking these process CMS enveloped data: CMS
+encrypted data is used for other purposes.
+
+The B<-resign> option uses an existing message digest when adding a new
+signer. This means that attributes must be present in at least one existing
+signer using the same message digest or this operation will fail.
+
+The B<-stream> and B<-indef> options enable streaming I/O support.
+As a result the encoding is BER using indefinite length constructed encoding
+and no longer DER. Streaming is supported for the B<-encrypt> operation and the
+B<-sign> operation if the content is not detached.
+
+Streaming is always used for the B<-sign> operation with detached data but
+since the content is no longer part of the CMS structure the encoding
+remains DER.
+
+If the B<-decrypt> option is used without a recipient certificate then an
+attempt is made to locate the recipient by trying each potential recipient
+in turn using the supplied private key. To thwart the MMA attack
+(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
+tried whether they succeed or not and if no recipients match the message
+is "decrypted" using a random key which will typically output garbage.
+The B<-debug_decrypt> option can be used to disable the MMA attack protection
+and return an error if no recipient can be found: this option should be used
+with caution. For a fuller description see L<CMS_decrypt(3)>).
+
+=head1 EXIT CODES
+
+=over 4
+
+=item Z<>0
+
+the operation was completely successfully.
+
+=item Z<>1
+
+an error occurred parsing the command options.
+
+=item Z<>2
+
+one of the input files could not be read.
+
+=item Z<>3
+
+an error occurred creating the CMS file or when reading the MIME
+message.
+
+=item Z<>4
+
+an error occurred decrypting or verifying the message.
+
+=item Z<>5
+
+the message was verified correctly but an error occurred writing out
+the signers certificates.
+
+=back
+
+=head1 COMPATIBILITY WITH PKCS#7 format.
+
+The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
+utility supports Cryptographic Message Syntax format. Use of some features
+will result in messages which cannot be processed by applications which only
+support the older format. These are detailed below.
+
+The use of the B<-keyid> option with B<-sign> or B<-encrypt>.
+
+The B<-outform PEM> option uses different headers.
+
+The B<-compress> option.
+
+The B<-secretkey> option when used with B<-encrypt>.
+
+The use of PSS with B<-sign>.
+
+The use of OAEP or non-RSA keys with B<-encrypt>.
+
+Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
+be processed by the older B<smime> command.
+
+=head1 EXAMPLES
+
+Create a cleartext signed message:
+
+ openssl cms -sign -in message.txt -text -out mail.msg \
+ -signer mycert.pem
+
+Create an opaque signed message
+
+ openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
+ -signer mycert.pem
+
+Create a signed message, include some additional certificates and
+read the private key from another file:
+
+ openssl cms -sign -in in.txt -text -out mail.msg \
+ -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
+
+Create a signed message with two signers, use key identifier:
+
+ openssl cms -sign -in message.txt -text -out mail.msg \
+ -signer mycert.pem -signer othercert.pem -keyid
+
+Send a signed message under Unix directly to sendmail, including headers:
+
+ openssl cms -sign -in in.txt -text -signer mycert.pem \
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed message" | sendmail someone@somewhere
+
+Verify a message and extract the signer's certificate if successful:
+
+ openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
+
+Send encrypted mail using triple DES:
+
+ openssl cms -encrypt -in in.txt -from steve@openssl.org \
+ -to someone@somewhere -subject "Encrypted message" \
+ -des3 user.pem -out mail.msg
+
+Sign and encrypt mail:
+
+ openssl cms -sign -in ml.txt -signer my.pem -text \
+ | openssl cms -encrypt -out mail.msg \
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed and Encrypted message" -des3 user.pem
+
+Note: the encryption command does not include the B<-text> option because the
+message being encrypted already has MIME headers.
+
+Decrypt mail:
+
+ openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
+
+The output from Netscape form signing is a PKCS#7 structure with the
+detached signature format. You can use this program to verify the
+signature by line wrapping the base64 encoded structure and surrounding
+it with:
+
+ -----BEGIN PKCS7-----
+ -----END PKCS7-----
+
+and using the command,
+
+ openssl cms -verify -inform PEM -in signature.pem -content content.txt
+
+alternatively you can base64 decode the signature and use
+
+ openssl cms -verify -inform DER -in signature.der -content content.txt
+
+Create an encrypted message using 128 bit Camellia:
+
+ openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
+
+Add a signer to an existing message:
+
+ openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
+
+Sign mail using RSA-PSS:
+
+ openssl cms -sign -in message.txt -text -out mail.msg \
+ -signer mycert.pem -keyopt rsa_padding_mode:pss
+
+Create encrypted mail using RSA-OAEP:
+
+ openssl cms -encrypt -in plain.txt -out mail.msg \
+ -recip cert.pem -keyopt rsa_padding_mode:oaep
+
+Use SHA256 KDF with an ECDH certificate:
+
+ openssl cms -encrypt -in plain.txt -out mail.msg \
+ -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
+
+=head1 BUGS
+
+The MIME parser isn't very clever: it seems to handle most messages that I've
+thrown at it but it may choke on others.
+
+The code currently will only write out the signer's certificate to a file: if
+the signer has a separate encryption certificate this must be manually
+extracted. There should be some heuristic that determines the correct
+encryption certificate.
+
+Ideally a database should be maintained of a certificates for each email
+address.
+
+The code doesn't currently take note of the permitted symmetric encryption
+algorithms as supplied in the SMIMECapabilities signed attribute. this means the
+user has to manually include the correct encryption algorithm. It should store
+the list of permitted ciphers in a database and only use those.
+
+No revocation checking is done on the signer's certificate.
+
+=head1 HISTORY
+
+The use of multiple B<-signer> options and the B<-resign> command were first
+added in OpenSSL 1.0.0
+
+The B<keyopt> option was first added in OpenSSL 1.1.0
+
+The use of B<-recip> to specify the recipient when encrypting mail was first
+added to OpenSSL 1.1.0
+
+Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
+
+The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
+to OpenSSL 1.1.0.
+
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+crl - CRL utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<crl>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-text>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-nameopt option>]
+[B<-noout>]
+[B<-hash>]
+[B<-issuer>]
+[B<-lastupdate>]
+[B<-nextupdate>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+
+=head1 DESCRIPTION
+
+The B<crl> command processes CRL files in DER or PEM format.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. B<DER> format is DER encoded CRL
+structure. B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-text>
+
+print out the CRL in text form.
+
+=item B<-nameopt option>
+
+option which determines how the subject or issuer names are displayed. See
+the description of B<-nameopt> in L<x509(1)>.
+
+=item B<-noout>
+
+don't output the encoded version of the CRL.
+
+=item B<-hash>
+
+output a hash of the issuer name. This can be use to lookup CRLs in
+a directory by issuer name.
+
+=item B<-hash_old>
+
+outputs the "hash" of the CRL issuer name using the older algorithm
+as used by OpenSSL versions before 1.0.0.
+
+=item B<-issuer>
+
+output the issuer name.
+
+=item B<-lastupdate>
+
+output the lastUpdate field.
+
+=item B<-nextupdate>
+
+output the nextUpdate field.
+
+=item B<-CAfile file>
+
+verify the signature on a CRL by looking up the issuing certificate in
+B<file>
+
+=item B<-CApath dir>
+
+verify the signature on a CRL by looking up the issuing certificate in
+B<dir>. This directory must be a standard certificate directory: that
+is a hash of each subject name (using B<x509 -hash>) should be linked
+to each certificate.
+
+=back
+
+=head1 NOTES
+
+The PEM CRL format uses the header and footer lines:
+
+ -----BEGIN X509 CRL-----
+ -----END X509 CRL-----
+
+=head1 EXAMPLES
+
+Convert a CRL file from PEM to DER:
+
+ openssl crl -in crl.pem -outform DER -out crl.der
+
+Output the text form of a DER encoded certificate:
+
+ openssl crl -in crl.der -text -noout
+
+=head1 BUGS
+
+Ideally it should be possible to create a CRL using appropriate options
+and files too.
+
+=head1 SEE ALSO
+
+L<crl2pkcs7(1)>, L<ca(1)>, L<x509(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates
+
+=head1 SYNOPSIS
+
+B<openssl> B<crl2pkcs7>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-certfile filename>]
+[B<-nocrl>]
+
+=head1 DESCRIPTION
+
+The B<crl2pkcs7> command takes an optional CRL and one or more
+certificates and converts them into a PKCS#7 degenerate "certificates
+only" structure.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the CRL input format. B<DER> format is DER encoded CRL
+structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the PKCS#7 structure output format. B<DER> format is DER
+encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-in filename>
+
+This specifies the input filename to read a CRL from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write the PKCS#7 structure to or standard
+output by default.
+
+=item B<-certfile filename>
+
+specifies a filename containing one or more certificates in B<PEM> format.
+All certificates in the file will be added to the PKCS#7 structure. This
+option can be used more than once to read certificates form multiple
+files.
+
+=item B<-nocrl>
+
+normally a CRL is included in the output file. With this option no CRL is
+included in the output file and a CRL is not read from the input file.
+
+=back
+
+=head1 EXAMPLES
+
+Create a PKCS#7 structure from a certificate and CRL:
+
+ openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem
+
+Creates a PKCS#7 structure in DER format with no CRL from several
+different certificates:
+
+ openssl crl2pkcs7 -nocrl -certfile newcert.pem
+ -certfile demoCA/cacert.pem -outform DER -out p7.der
+
+=head1 NOTES
+
+The output file is a PKCS#7 signed data structure containing no signers and
+just certificates and an optional CRL.
+
+This utility can be used to send certificates and CAs to Netscape as part of
+the certificate enrollment process. This involves sending the DER encoded output
+as MIME type application/x-x509-user-cert.
+
+The B<PEM> encoded form with the header and footer lines removed can be used to
+install user certificates and CAs in MSIE using the Xenroll control.
+
+=head1 SEE ALSO
+
+L<pkcs7(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5, blake2b, blake2s - message digests
+
+=head1 SYNOPSIS
+
+B<openssl> B<dgst>
+[B<-help>]
+[B<-I<digest>>]
+[B<-c>]
+[B<-d>]
+[B<-hex>]
+[B<-binary>]
+[B<-r>]
+[B<-out filename>]
+[B<-sign filename>]
+[B<-keyform arg>]
+[B<-passin arg>]
+[B<-verify filename>]
+[B<-prverify filename>]
+[B<-signature filename>]
+[B<-hmac key>]
+[B<-fips-fingerprint>]
+[B<-engine id>]
+[B<-engine_impl>]
+[B<file...>]
+
+B<openssl>
+[I<digest>]
+[B<...>]
+
+=head1 DESCRIPTION
+
+The digest functions output the message digest of a supplied file or files
+in hexadecimal. The digest functions also generate and verify digital
+signatures using message digests.
+
+The generic name, B<dgst>, may be used with an option specifying the
+algorithm to be used.
+The default digest is I<sha256>.
+A supported I<digest> name may also be used as the command name.
+To see the list of supported algorithms, use the I<list --digest-commands>
+command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-I<digest>>
+
+Specifies name of a supported digest to be used. To see the list of
+supported digests, use the command I<list --digest-commands>.
+
+=item B<-c>
+
+print out the digest in two digit groups separated by colons, only relevant if
+B<hex> format output is used.
+
+=item B<-d>
+
+print out BIO debugging information.
+
+=item B<-hex>
+
+digest is to be output as a hex dump. This is the default case for a "normal"
+digest as opposed to a digital signature. See NOTES below for digital
+signatures using B<-hex>.
+
+=item B<-binary>
+
+output the digest or signature in binary form.
+
+=item B<-r>
+
+output the digest in the "coreutils" format used by programs like B<sha1sum>.
+
+=item B<-out filename>
+
+filename to output to, or standard output by default.
+
+=item B<-sign filename>
+
+digitally sign the digest using the private key in "filename".
+
+=item B<-keyform arg>
+
+Specifies the key format to sign digest with. The DER, PEM, P12,
+and ENGINE formats are supported.
+
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
+
+=item B<-passin arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-verify filename>
+
+verify the signature using the public key in "filename".
+The output is either "Verification OK" or "Verification Failure".
+
+=item B<-prverify filename>
+
+verify the signature using the private key in "filename".
+
+=item B<-signature filename>
+
+the actual signature to verify.
+
+=item B<-hmac key>
+
+create a hashed MAC using "key".
+
+=item B<-mac alg>
+
+create MAC (keyed Message Authentication Code). The most popular MAC
+algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
+which are not based on hash, for instance B<gost-mac> algorithm,
+supported by B<ccgost> engine. MAC keys and other options should be set
+via B<-macopt> parameter.
+
+=item B<-macopt nm:v>
+
+Passes options to MAC algorithm, specified by B<-mac> key.
+Following options are supported by both by B<HMAC> and B<gost-mac>:
+
+=over 8
+
+=item B<key:string>
+
+Specifies MAC key as alphanumeric string (use if key contain printable
+characters only). String length must conform to any restrictions of
+the MAC algorithm for example exactly 32 chars for gost-mac.
+
+=item B<hexkey:string>
+
+Specifies MAC key in hexadecimal form (two hex digits per byte).
+Key length must conform to any restrictions of the MAC algorithm
+for example exactly 32 chars for gost-mac.
+
+=back
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-fips-fingerprint>
+
+compute HMAC using a specific key
+for certain OpenSSL-FIPS operations.
+
+=item B<-engine id>
+
+Use engine B<id> for operations (including private key storage).
+This engine is not used as source for digest algorithms, unless it is
+also specified in the configuration file or B<-engine_impl> is also
+specified.
+
+=item B<-engine_impl>
+
+When used with the B<-engine> option, it specifies to also use
+engine B<id> for digest operations.
+
+=item B<file...>
+
+file or files to digest. If no files are specified then standard input is
+used.
+
+=back
+
+
+=head1 EXAMPLES
+
+To create a hex-encoded message digest of a file:
+ openssl dgst -md5 -hex file.txt
+
+To sign a file using SHA-256 with binary file output:
+ openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt
+
+To verify a signature:
+ openssl dgst -sha256 -verify publickey.pem \
+ -signature signature.sign \
+ file.txt
+
+
+=head1 NOTES
+
+The digest mechanisms that are available will depend on the options
+used when building OpenSSL.
+The B<list digest-commands> command can be used to list them.
+
+New or agile applications should use probably use SHA-256. Other digests,
+particularly SHA-1 and MD5, are still widely used for interoperating
+with existing formats and protocols.
+
+When signing a file, B<dgst> will automatically determine the algorithm
+(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
+When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
+itself, not the related data to identify the signer and algorithm used in
+formats such as x.509, CMS, and S/MIME.
+
+A source of random numbers is required for certain signing algorithms, in
+particular ECDSA and DSA.
+
+The signing and verify options should only be used if a single file is
+being signed or verified.
+
+Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r"
+or similar program to transform the hex signature into a binary signature
+prior to verification.
+
+=head1 HISTORY
+
+The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0
+The FIPS-related options were removed in OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+dhparam - DH parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl dhparam>
+[B<-help>]
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in> I<filename>]
+[B<-out> I<filename>]
+[B<-dsaparam>]
+[B<-check>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+[B<-2>]
+[B<-5>]
+[B<-rand> I<file(s)>]
+[B<-engine id>]
+[I<numbits>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate DH parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#3 DHparameter structure. The PEM form is the
+default format: it consists of the B<DER> format base64 encoded with
+additional header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in> I<filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified.
+
+=item B<-out> I<filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-dsaparam>
+
+If this option is used, DSA rather than DH parameters are read or created;
+they are converted to DH format. Otherwise, "strong" primes (such
+that (p-1)/2 is also prime) will be used for DH parameter generation.
+
+DH parameter generation with the B<-dsaparam> option is much faster,
+and the recommended exponent length is shorter, which makes DH key
+exchange more efficient. Beware that with such DSA-style DH
+parameters, a fresh DH key should be created for each use to
+avoid small-subgroup attacks that may be possible otherwise.
+
+=item B<-check>
+
+Performs numerous checks to see if the supplied parameters are valid and
+displays a warning if not.
+
+=item B<-2>, B<-5>
+
+The generator to use, either 2 or 5. If present then the
+input file is ignored and parameters are generated instead. If not
+present but B<numbits> is present, parameters are generated with the
+default generator 2.
+
+=item B<-rand> I<file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item I<numbits>
+
+this option specifies that a parameter set should be generated of size
+I<numbits>. It must be the last option. If this option is present then
+the input file is ignored and parameters are generated instead. If
+this option is not present but a generator (B<-2> or B<-5>) is
+present, parameters are generated with a default length of 2048 bits.
+
+=item B<-noout>
+
+this option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+this option prints out the DH parameters in human readable form.
+
+=item B<-C>
+
+this option converts the parameters into C code. The parameters can then
+be loaded by calling the get_dhNNNN() function.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<dhparam>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 WARNINGS
+
+The program B<dhparam> combines the functionality of the programs B<dh> and
+B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh>
+programs are retained for now but may have different purposes in future
+versions of OpenSSL.
+
+=head1 NOTES
+
+PEM format DH parameters use the header and footer lines:
+
+ -----BEGIN DH PARAMETERS-----
+ -----END DH PARAMETERS-----
+
+OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42
+DH.
+
+This program manipulates DH parameters not keys.
+
+=head1 BUGS
+
+There should be a way to generate and manipulate DH keys.
+
+=head1 SEE ALSO
+
+L<dsaparam(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+dsa - DSA key processing
+
+=head1 SYNOPSIS
+
+B<openssl> B<dsa>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-aes128>]
+[B<-aes192>]
+[B<-aes256>]
+[B<-camellia128>]
+[B<-camellia192>]
+[B<-camellia256>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-modulus>]
+[B<-pubin>]
+[B<-pubout>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<dsa> command processes DSA keys. They can be converted between various
+forms and their components printed out. B<Note> This command uses the
+traditional SSLeay compatible format for private key encryption: newer
+applications should use the more secure PKCS#8 format using the B<pkcs8>
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option with a private key uses
+an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of
+version (currently zero), p, q, g, the public and private key components
+respectively as ASN.1 INTEGERs. When used with a public key it uses a
+SubjectPublicKeyInfo structure: it is an error if the key is not DSA.
+
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. In the case of a private key
+PKCS#8 format is also accepted.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+is not specified. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
+
+These options encrypt the private key with the specified
+cipher before outputting it. A pass phrase is prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<dsa> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the public, private key components and parameters.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the public key component of the key.
+
+=item B<-pubin>
+
+by default a private key is read from the input file: with this option a
+public key is read instead.
+
+=item B<-pubout>
+
+by default a private key is output. With this option a public
+key will be output instead. This option is automatically set if the input is
+a public key.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<dsa>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN DSA PRIVATE KEY-----
+ -----END DSA PRIVATE KEY-----
+
+The PEM public key format uses the header and footer lines:
+
+ -----BEGIN PUBLIC KEY-----
+ -----END PUBLIC KEY-----
+
+=head1 EXAMPLES
+
+To remove the pass phrase on a DSA private key:
+
+ openssl dsa -in key.pem -out keyout.pem
+
+To encrypt a private key using triple DES:
+
+ openssl dsa -in key.pem -des3 -out keyout.pem
+
+To convert a private key from PEM to DER format:
+
+ openssl dsa -in key.pem -outform DER -out keyout.der
+
+To print out the components of a private key to standard output:
+
+ openssl dsa -in key.pem -text -noout
+
+To just output the public part of a private key:
+
+ openssl dsa -in key.pem -pubout -out pubkey.pem
+
+=head1 SEE ALSO
+
+L<dsaparam(1)>, L<gendsa(1)>, L<rsa(1)>,
+L<genrsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+dsaparam - DSA parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl dsaparam>
+[B<-help>]
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+[B<-rand file(s)>]
+[B<-genkey>]
+[B<-engine id>]
+[B<numbits>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate or generate DSA parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting
+of p, q and g respectively. The PEM form is the default format: it consists
+of the B<DER> format base64 encoded with additional header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified. If the B<numbits> parameter is included then
+this option will be ignored.
+
+=item B<-out filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-noout>
+
+this option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+this option prints out the DSA parameters in human readable form.
+
+=item B<-C>
+
+this option converts the parameters into C code. The parameters can then
+be loaded by calling the get_dsaXXX() function.
+
+=item B<-genkey>
+
+this option will generate a DSA either using the specified or generated
+parameters.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<numbits>
+
+this option specifies that a parameter set should be generated of size
+B<numbits>. It must be the last option. If this option is included then
+the input file (if any) is ignored.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<dsaparam>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+PEM format DSA parameters use the header and footer lines:
+
+ -----BEGIN DSA PARAMETERS-----
+ -----END DSA PARAMETERS-----
+
+DSA parameter generation is a slow process and as a result the same set of
+DSA parameters is often used to generate several distinct keys.
+
+=head1 SEE ALSO
+
+L<gendsa(1)>, L<dsa(1)>, L<genrsa(1)>,
+L<rsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ec - EC key processing
+
+=head1 SYNOPSIS
+
+B<openssl> B<ec>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-param_out>]
+[B<-pubin>]
+[B<-pubout>]
+[B<-conv_form arg>]
+[B<-param_enc arg>]
+[B<-no_public>]
+[B<-check>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<ec> command processes EC keys. They can be converted between various
+forms and their components printed out. B<Note> OpenSSL uses the
+private key format specified in 'SEC 1: Elliptic Curve Cryptography'
+(http://www.secg.org/). To convert an OpenSSL EC private key into the
+PKCS#8 private key format use the B<pkcs8> command.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option with a private key uses
+an ASN.1 DER encoded SEC1 private key. When used with a public key it
+uses the SubjectPublicKeyInfo structure as specified in RFC 3280.
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. In the case of a private key
+PKCS#8 format is also accepted.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+is not specified. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, IDEA or
+any other cipher supported by OpenSSL before outputting it. A pass phrase is
+prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<ec> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the public, private key components and parameters.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the public key component of the key.
+
+=item B<-pubin>
+
+by default a private key is read from the input file: with this option a
+public key is read instead.
+
+=item B<-pubout>
+
+by default a private key is output. With this option a public
+key will be output instead. This option is automatically set if the input is
+a public key.
+
+=item B<-conv_form>
+
+This specifies how the points on the elliptic curve are converted
+into octet strings. Possible values are: B<compressed> (the default
+value), B<uncompressed> and B<hybrid>. For more information regarding
+the point conversion forms please read the X9.62 standard.
+B<Note> Due to patent issues the B<compressed> option is disabled
+by default for binary curves and can be enabled by defining
+the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
+
+=item B<-param_enc arg>
+
+This specifies how the elliptic curve parameters are encoded.
+Possible value are: B<named_curve>, i.e. the ec parameters are
+specified by an OID, or B<explicit> where the ec parameters are
+explicitly given (see RFC 3279 for the definition of the
+EC parameters structures). The default value is B<named_curve>.
+B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
+is currently not implemented in OpenSSL.
+
+=item B<-no_public>
+
+This option omits the public key components from the private key output.
+
+=item B<-check>
+
+this option checks the consistency of an EC private or public key.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<ec>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN EC PRIVATE KEY-----
+ -----END EC PRIVATE KEY-----
+
+The PEM public key format uses the header and footer lines:
+
+ -----BEGIN PUBLIC KEY-----
+ -----END PUBLIC KEY-----
+
+=head1 EXAMPLES
+
+To encrypt a private key using triple DES:
+
+ openssl ec -in key.pem -des3 -out keyout.pem
+
+To convert a private key from PEM to DER format:
+
+ openssl ec -in key.pem -outform DER -out keyout.der
+
+To print out the components of a private key to standard output:
+
+ openssl ec -in key.pem -text -noout
+
+To just output the public part of a private key:
+
+ openssl ec -in key.pem -pubout -out pubkey.pem
+
+To change the parameters encoding to B<explicit>:
+
+ openssl ec -in key.pem -param_enc explicit -out keyout.pem
+
+To change the point conversion form to B<compressed>:
+
+ openssl ec -in key.pem -conv_form compressed -out keyout.pem
+
+=head1 SEE ALSO
+
+L<ecparam(1)>, L<dsa(1)>, L<rsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ecparam - EC parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl ecparam>
+[B<-help>]
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+[B<-check>]
+[B<-name arg>]
+[B<-list_curves>]
+[B<-conv_form arg>]
+[B<-param_enc arg>]
+[B<-no_seed>]
+[B<-rand file(s)>]
+[B<-genkey>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate or generate EC parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN.1 DER encoded
+form compatible with RFC 3279 EcpkParameters. The PEM form is the default
+format: it consists of the B<DER> format base64 encoded with additional
+header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified.
+
+=item B<-out filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-noout>
+
+This option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+This option prints out the EC parameters in human readable form.
+
+=item B<-C>
+
+This option converts the EC parameters into C code. The parameters can then
+be loaded by calling the get_ec_group_XXX() function.
+
+=item B<-check>
+
+Validate the elliptic curve parameters.
+
+=item B<-name arg>
+
+Use the EC parameters with the specified 'short' name. Use B<-list_curves>
+to get a list of all currently implemented EC parameters.
+
+=item B<-list_curves>
+
+If this options is specified B<ecparam> will print out a list of all
+currently implemented EC parameters names and exit.
+
+=item B<-conv_form>
+
+This specifies how the points on the elliptic curve are converted
+into octet strings. Possible values are: B<compressed> (the default
+value), B<uncompressed> and B<hybrid>. For more information regarding
+the point conversion forms please read the X9.62 standard.
+B<Note> Due to patent issues the B<compressed> option is disabled
+by default for binary curves and can be enabled by defining
+the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
+
+=item B<-param_enc arg>
+
+This specifies how the elliptic curve parameters are encoded.
+Possible value are: B<named_curve>, i.e. the ec parameters are
+specified by an OID, or B<explicit> where the ec parameters are
+explicitly given (see RFC 3279 for the definition of the
+EC parameters structures). The default value is B<named_curve>.
+B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
+is currently not implemented in OpenSSL.
+
+=item B<-no_seed>
+
+This option inhibits that the 'seed' for the parameter generation
+is included in the ECParameters structure (see RFC 3279).
+
+=item B<-genkey>
+
+This option will generate an EC private key using the specified parameters.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<ecparam>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+PEM format EC parameters use the header and footer lines:
+
+ -----BEGIN EC PARAMETERS-----
+ -----END EC PARAMETERS-----
+
+OpenSSL is currently not able to generate new groups and therefore
+B<ecparam> can only create EC parameters from known (named) curves.
+
+=head1 EXAMPLES
+
+To create EC parameters with the group 'prime192v1':
+
+ openssl ecparam -out ec_param.pem -name prime192v1
+
+To create EC parameters with explicit parameters:
+
+ openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit
+
+To validate given EC parameters:
+
+ openssl ecparam -in ec_param.pem -check
+
+To create EC parameters and a private key:
+
+ openssl ecparam -out ec_key.pem -name prime192v1 -genkey
+
+To change the point encoding to 'compressed':
+
+ openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed
+
+To print out the EC parameters to standard output:
+
+ openssl ecparam -in ec_param.pem -noout -text
+
+=head1 SEE ALSO
+
+L<ec(1)>, L<dsaparam(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+enc - symmetric cipher routines
+
+=head1 SYNOPSIS
+
+B<openssl enc -ciphername>
+[B<-help>]
+[B<-ciphers>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-pass arg>]
+[B<-e>]
+[B<-d>]
+[B<-a/-base64>]
+[B<-A>]
+[B<-k password>]
+[B<-kfile filename>]
+[B<-K key>]
+[B<-iv IV>]
+[B<-S salt>]
+[B<-salt>]
+[B<-nosalt>]
+[B<-z>]
+[B<-md digest>]
+[B<-p>]
+[B<-P>]
+[B<-bufsize number>]
+[B<-nopad>]
+[B<-debug>]
+[B<-none>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The symmetric cipher commands allow data to be encrypted or decrypted
+using various block and stream ciphers using keys based on passwords
+or explicitly provided. Base64 encoding or decoding can also be performed
+either by itself or in addition to the encryption or decryption.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-ciphers>
+
+List all supported ciphers.
+
+=item B<-in filename>
+
+the input filename, standard input by default.
+
+=item B<-out filename>
+
+the output filename, standard output by default.
+
+=item B<-pass arg>
+
+the password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-e>
+
+encrypt the input data: this is the default.
+
+=item B<-d>
+
+decrypt the input data.
+
+=item B<-a>
+
+base64 process the data. This means that if encryption is taking place
+the data is base64 encoded after encryption. If decryption is set then
+the input data is base64 decoded before being decrypted.
+
+=item B<-base64>
+
+same as B<-a>
+
+=item B<-A>
+
+if the B<-a> option is set then base64 process the data on one line.
+
+=item B<-k password>
+
+the password to derive the key from. This is for compatibility with previous
+versions of OpenSSL. Superseded by the B<-pass> argument.
+
+=item B<-kfile filename>
+
+read the password to derive the key from the first line of B<filename>.
+This is for compatibility with previous versions of OpenSSL. Superseded by
+the B<-pass> argument.
+
+=item B<-md digest>
+
+Use the specified digest to create the key from the passphrase.
+The default algorithm is sha-256.
+
+=item B<-nosalt>
+
+don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
+used except for test purposes or compatibility with ancient versions of
+OpenSSL.
+
+=item B<-salt>
+
+use salt (randomly generated or provide with B<-S> option) when
+encrypting (this is the default).
+
+=item B<-S salt>
+
+the actual salt to use: this must be represented as a string of hex digits.
+
+=item B<-K key>
+
+the actual key to use: this must be represented as a string comprised only
+of hex digits. If only the key is specified, the IV must additionally specified
+using the B<-iv> option. When both a key and a password are specified, the
+key given with the B<-K> option will be used and the IV generated from the
+password will be taken. It probably does not make much sense to specify
+both key and password.
+
+=item B<-iv IV>
+
+the actual IV to use: this must be represented as a string comprised only
+of hex digits. When only the key is specified using the B<-K> option, the
+IV must explicitly be defined. When a password is being specified using
+one of the other options, the IV is generated from this password.
+
+=item B<-p>
+
+print out the key and IV used.
+
+=item B<-P>
+
+print out the key and IV used then immediately exit: don't do any encryption
+or decryption.
+
+=item B<-bufsize number>
+
+set the buffer size for I/O
+
+=item B<-nopad>
+
+disable standard block padding
+
+=item B<-debug>
+
+debug the BIOs used for I/O.
+
+=item B<-z>
+
+Compress or decompress clear text using zlib before encryption or after
+decryption. This option exists only if OpenSSL with compiled with zlib
+or zlib-dynamic option.
+
+=item B<-none>
+
+Use NULL cipher (no encryption or decryption of input).
+
+=back
+
+=head1 NOTES
+
+The program can be called either as B<openssl ciphername> or
+B<openssl enc -ciphername>. But the first form doesn't work with
+engine-provided ciphers, because this form is processed before the
+configuration file is read and any ENGINEs loaded.
+
+Engines which provide entirely new encryption algorithms (such as ccgost
+engine which provides gost89 algorithm) should be configured in the
+configuration file. Engines, specified in the command line using -engine
+options can only be used for hardware-assisted implementations of
+ciphers, which are supported by OpenSSL core or other engine, specified
+in the configuration file.
+
+When enc command lists supported ciphers, ciphers provided by engines,
+specified in the configuration files are listed too.
+
+A password will be prompted for to derive the key and IV if necessary.
+
+The B<-salt> option should B<ALWAYS> be used if the key is being derived
+from a password unless you want compatibility with previous versions of
+OpenSSL.
+
+Without the B<-salt> option it is possible to perform efficient dictionary
+attacks on the password and to attack stream cipher encrypted data. The reason
+for this is that without the salt the same password always generates the same
+encryption key. When the salt is being used the first eight bytes of the
+encrypted data are reserved for the salt: it is generated at random when
+encrypting a file and read from the encrypted file when it is decrypted.
+
+Some of the ciphers do not have large keys and others have security
+implications if not used correctly. A beginner is advised to just use
+a strong block cipher in CBC mode such as bf or des3.
+
+All the block ciphers normally use PKCS#5 padding also known as standard block
+padding: this allows a rudimentary integrity or password check to be
+performed. However since the chance of random data passing the test is
+better than 1 in 256 it isn't a very good test.
+
+If padding is disabled then the input data must be a multiple of the cipher
+block length.
+
+All RC2 ciphers have the same key and effective key length.
+
+Blowfish and RC5 algorithms use a 128 bit key.
+
+=head1 SUPPORTED CIPHERS
+
+Note that some of these ciphers can be disabled at compile time
+and some are available only if an appropriate engine is configured
+in the configuration file. The output of the B<enc> command run with
+unsupported options (for example B<openssl enc -help>) includes a
+list of ciphers, supported by your version of OpenSSL, including
+ones provided by configured engines.
+
+The B<enc> program does not support authenticated encryption modes
+like CCM and GCM. The utility does not store or retrieve the
+authentication tag.
+
+
+ base64 Base 64
+
+ bf-cbc Blowfish in CBC mode
+ bf Alias for bf-cbc
+ bf-cfb Blowfish in CFB mode
+ bf-ecb Blowfish in ECB mode
+ bf-ofb Blowfish in OFB mode
+
+ cast-cbc CAST in CBC mode
+ cast Alias for cast-cbc
+ cast5-cbc CAST5 in CBC mode
+ cast5-cfb CAST5 in CFB mode
+ cast5-ecb CAST5 in ECB mode
+ cast5-ofb CAST5 in OFB mode
+
+ des-cbc DES in CBC mode
+ des Alias for des-cbc
+ des-cfb DES in CBC mode
+ des-ofb DES in OFB mode
+ des-ecb DES in ECB mode
+
+ des-ede-cbc Two key triple DES EDE in CBC mode
+ des-ede Two key triple DES EDE in ECB mode
+ des-ede-cfb Two key triple DES EDE in CFB mode
+ des-ede-ofb Two key triple DES EDE in OFB mode
+
+ des-ede3-cbc Three key triple DES EDE in CBC mode
+ des-ede3 Three key triple DES EDE in ECB mode
+ des3 Alias for des-ede3-cbc
+ des-ede3-cfb Three key triple DES EDE CFB mode
+ des-ede3-ofb Three key triple DES EDE in OFB mode
+
+ desx DESX algorithm.
+
+ gost89 GOST 28147-89 in CFB mode (provided by ccgost engine)
+ gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
+
+ idea-cbc IDEA algorithm in CBC mode
+ idea same as idea-cbc
+ idea-cfb IDEA in CFB mode
+ idea-ecb IDEA in ECB mode
+ idea-ofb IDEA in OFB mode
+
+ rc2-cbc 128 bit RC2 in CBC mode
+ rc2 Alias for rc2-cbc
+ rc2-cfb 128 bit RC2 in CFB mode
+ rc2-ecb 128 bit RC2 in ECB mode
+ rc2-ofb 128 bit RC2 in OFB mode
+ rc2-64-cbc 64 bit RC2 in CBC mode
+ rc2-40-cbc 40 bit RC2 in CBC mode
+
+ rc4 128 bit RC4
+ rc4-64 64 bit RC4
+ rc4-40 40 bit RC4
+
+ rc5-cbc RC5 cipher in CBC mode
+ rc5 Alias for rc5-cbc
+ rc5-cfb RC5 cipher in CFB mode
+ rc5-ecb RC5 cipher in ECB mode
+ rc5-ofb RC5 cipher in OFB mode
+
+ aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode
+ aes[128|192|256] Alias for aes-[128|192|256]-cbc
+ aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode
+ aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode
+ aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode
+ aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode
+ aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode
+
+=head1 EXAMPLES
+
+Just base64 encode a binary file:
+
+ openssl base64 -in file.bin -out file.b64
+
+Decode the same file
+
+ openssl base64 -d -in file.b64 -out file.bin
+
+Encrypt a file using triple DES in CBC mode using a prompted password:
+
+ openssl des3 -salt -in file.txt -out file.des3
+
+Decrypt a file using a supplied password:
+
+ openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
+
+Encrypt a file then base64 encode it (so it can be sent via mail for example)
+using Blowfish in CBC mode:
+
+ openssl bf -a -salt -in file.txt -out file.bf
+
+Base64 decode a file then decrypt it:
+
+ openssl bf -d -salt -a -in file.bf -out file.txt
+
+Decrypt some data using a supplied 40 bit RC4 key:
+
+ openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
+
+=head1 BUGS
+
+The B<-A> option when used with large files doesn't work properly.
+
+There should be an option to allow an iteration count to be included.
+
+The B<enc> program only supports a fixed number of algorithms with
+certain parameters. So if, for example, you want to use RC2 with a
+76 bit key or RC4 with an 84 bit key you can't use this program.
+
+=head1 HISTORY
+
+The default digest was changed from MD5 to SHA256 in Openssl 1.1.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+engine - load and query engines
+
+=head1 SYNOPSIS
+
+B<openssl engine>
+[ I<engine...> ]
+[B<-v>]
+[B<-vv>]
+[B<-vvv>]
+[B<-vvv>]
+[B<-vvv>]
+[B<-c>]
+[B<-t>]
+[B<-tt>]
+[B<-pre> I<command>]
+[B<-post> I<command>]
+[ I<engine...> ]
+
+=head1 DESCRIPTION
+
+The B<engine> command is used to query the status and capabilities
+of the specified B<engine>'s.
+Engines may be specified before and after all other command-line flags.
+Only those specified are queried.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-v> B<-vv> B<-vvv> B<-vvvv>
+
+Provides information about each specified engine. The first flag lists
+all the possible run-time control commands; the second adds a
+description of each command; the third adds the input flags, and the
+final option adds the internal input flags.
+
+=item B<-c>
+
+Lists the capabilities of each engine.
+
+=item B<-t>
+
+Tests if each specified engine is available, and displays the answer.
+
+=item B<-tt>
+
+Displays an error trace for any unavailable engine.
+
+=item B<-pre> I<command>
+
+=item B<-post> I<command>
+
+Command-line configuration of engines.
+The B<-pre> command is given to the engine before it is loaded and
+the B<-post> command is given after the engine is loaded.
+The I<command> is of the form I<cmd:val> where I<cmd> is the command,
+and I<val> is the value for the command.
+See the example below.
+
+=back
+
+=head1 EXAMPLE
+
+To list all the commands available to a dynamic engine:
+
+ % openssl engine -t -tt -vvvv dynamic
+ (dynamic) Dynamic engine loading support
+ [ unavailable ]
+ SO_PATH: Specifies the path to the new ENGINE shared library
+ (input flags): STRING
+ NO_VCHECK: Specifies to continue even if version checking fails (boolean)
+ (input flags): NUMERIC
+ ID: Specifies an ENGINE id name for loading
+ (input flags): STRING
+ LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory)
+ (input flags): NUMERIC
+ DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory)
+ (input flags): NUMERIC
+ DIR_ADD: Adds a directory from which ENGINEs can be loaded
+ (input flags): STRING
+ LOAD: Load up the ENGINE specified by other settings
+ (input flags): NO_INPUT
+
+To list the capabilities of the I<rsax> engine:
+
+ % openssl engine -c
+ (rsax) RSAX engine support
+ [RSA]
+ (dynamic) Dynamic engine loading support
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+errstr - lookup error codes
+
+=head1 SYNOPSIS
+
+B<openssl errstr error_code>
+
+=head1 DESCRIPTION
+
+Sometimes an application will not load error message and only
+numerical forms will be available. The B<errstr> utility can be used to
+display the meaning of the hex code. The hex code is the hex digits after the
+second colon.
+
+=head1 COMMAND OPTIONS
+
+None.
+
+=head1 EXAMPLE
+
+The error code:
+
+ 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
+
+can be displayed with:
+
+ openssl errstr 2006D080
+
+to produce the error message:
+
+ error:2006D080:BIO routines:BIO_new_file:no such file
+
+=head1 SEE ALSO
+
+L<err(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+gendsa - generate a DSA private key from a set of parameters
+
+=head1 SYNOPSIS
+
+B<openssl> B<gendsa>
+[B<-help>]
+[B<-out filename>]
+[B<-aes128>]
+[B<-aes192>]
+[B<-aes256>]
+[B<-camellia128>]
+[B<-camellia192>]
+[B<-camellia256>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-rand file(s)>]
+[B<-engine id>]
+[B<paramfile>]
+
+=head1 DESCRIPTION
+
+The B<gendsa> command generates a DSA private key from a DSA parameter file
+(which will be typically generated by the B<openssl dsaparam> command).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-out filename>
+
+Output the key to the specified file. If this argument is not specified then
+standard output is used.
+
+=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
+
+These options encrypt the private key with specified
+cipher before outputting it. A pass phrase is prompted for.
+If none of these options is specified no encryption is used.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<gendsa>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<paramfile>
+
+This option specifies the DSA parameter file to use. The parameters in this
+file determine the size of the private key. DSA parameters can be generated
+and examined using the B<openssl dsaparam> command.
+
+=back
+
+=head1 NOTES
+
+DSA key generation is little more than random number generation so it is
+much quicker that RSA key generation for example.
+
+=head1 SEE ALSO
+
+L<dsaparam(1)>, L<dsa(1)>, L<genrsa(1)>,
+L<rsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+genpkey - generate a private key
+
+=head1 SYNOPSIS
+
+B<openssl> B<genpkey>
+[B<-help>]
+[B<-out filename>]
+[B<-outform PEM|DER>]
+[B<-pass arg>]
+[B<-cipher>]
+[B<-engine id>]
+[B<-paramfile file>]
+[B<-algorithm alg>]
+[B<-pkeyopt opt:value>]
+[B<-genparam>]
+[B<-text>]
+
+=head1 DESCRIPTION
+
+The B<genpkey> command generates a private key.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-out filename>
+
+Output the key to the specified file. If this argument is not specified then
+standard output is used.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format DER or PEM.
+
+=item B<-pass arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-cipher>
+
+This option encrypts the private key with the supplied cipher. Any algorithm
+name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<genpkey>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms. If used this option should precede all other
+options.
+
+=item B<-algorithm alg>
+
+public key algorithm to use such as RSA, DSA or DH. If used this option must
+precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
+are mutually exclusive.
+
+=item B<-pkeyopt opt:value>
+
+set the public key algorithm option B<opt> to B<value>. The precise set of
+options supported depends on the public key algorithm used and its
+implementation. See B<KEY GENERATION OPTIONS> below for more details.
+
+=item B<-genparam>
+
+generate a set of parameters instead of a private key. If used this option must
+precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
+
+=item B<-paramfile filename>
+
+Some public key algorithms generate a private key based on a set of parameters.
+They can be supplied using this option. If this option is used the public key
+algorithm used is determined by the parameters. If used this option must
+precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
+are mutually exclusive.
+
+=item B<-text>
+
+Print an (unencrypted) text representation of private and public keys and
+parameters along with the PEM or DER structure.
+
+=back
+
+=head1 KEY GENERATION OPTIONS
+
+The options supported by each algorithm and indeed each implementation of an
+algorithm can vary. The options for the OpenSSL implementations are detailed
+below.
+
+=head1 RSA KEY GENERATION OPTIONS
+
+=over 4
+
+=item B<rsa_keygen_bits:numbits>
+
+The number of bits in the generated key. If not specified 1024 is used.
+
+=item B<rsa_keygen_pubexp:value>
+
+The RSA public exponent value. This can be a large decimal or
+hexadecimal value if preceded by B<0x>. Default value is 65537.
+
+=back
+
+=head1 DSA PARAMETER GENERATION OPTIONS
+
+=over 4
+
+=item B<dsa_paramgen_bits:numbits>
+
+The number of bits in the generated parameters. If not specified 1024 is used.
+
+=back
+
+=head1 DH PARAMETER GENERATION OPTIONS
+
+=over 4
+
+=item B<dh_paramgen_prime_len:numbits>
+
+The number of bits in the prime parameter B<p>.
+
+=item B<dh_paramgen_generator:value>
+
+The value to use for the generator B<g>.
+
+=item B<dh_rfc5114:num>
+
+If this option is set then the appropriate RFC5114 parameters are used
+instead of generating new parameters. The value B<num> can take the
+values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of
+1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup
+and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
+2.1, 2.2 and 2.3 respectively.
+
+=back
+
+=head1 EC PARAMETER GENERATION OPTIONS
+
+The EC parameter generation options below can also
+be supplied as EC key generation options. This can (for example) generate a
+key from a named curve without the need to use an explicit parameter file.
+
+=over 4
+
+=item B<ec_paramgen_curve:curve>
+
+the EC curve to use. OpenSSL supports NIST curve names such as "P-256".
+
+=item B<ec_param_enc:encoding>
+
+the encoding to use for parameters. The "encoding" parameter must be either
+"named_curve" or "explicit".
+
+=back
+
+=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS
+
+Gost 2001 support is not enabled by default. To enable this algorithm,
+one should load the ccgost engine in the OpenSSL configuration file.
+See README.gost file in the engines/ccgost directory of the source
+distribution for more details.
+
+Use of a parameter file for the GOST R 34.10 algorithm is optional.
+Parameters can be specified during key generation directly as well as
+during generation of parameter file.
+
+=over 4
+
+=item B<paramset:name>
+
+Specifies GOST R 34.10-2001 parameter set according to RFC 4357.
+Parameter set can be specified using abbreviated name, object short name or
+numeric OID. Following parameter sets are supported:
+
+ paramset OID Usage
+ A 1.2.643.2.2.35.1 Signature
+ B 1.2.643.2.2.35.2 Signature
+ C 1.2.643.2.2.35.3 Signature
+ XA 1.2.643.2.2.36.0 Key exchange
+ XB 1.2.643.2.2.36.1 Key exchange
+ test 1.2.643.2.2.35.0 Test purposes
+
+=back
+
+=head1 X25519 KEY GENERATION OPTIONS
+
+The X25519 algorithm does not currently support any key generation options.
+
+
+=head1 NOTES
+
+The use of the genpkey program is encouraged over the algorithm specific
+utilities because additional algorithm options and ENGINE provided algorithms
+can be used.
+
+=head1 EXAMPLES
+
+Generate an RSA private key using default parameters:
+
+ openssl genpkey -algorithm RSA -out key.pem
+
+Encrypt output private key using 128 bit AES and the passphrase "hello":
+
+ openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
+
+Generate a 2048 bit RSA key using 3 as the public exponent:
+
+ openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \
+ -pkeyopt rsa_keygen_pubexp:3
+
+Generate 1024 bit DSA parameters:
+
+ openssl genpkey -genparam -algorithm DSA -out dsap.pem \
+ -pkeyopt dsa_paramgen_bits:1024
+
+Generate DSA key from parameters:
+
+ openssl genpkey -paramfile dsap.pem -out dsakey.pem
+
+Generate 1024 bit DH parameters:
+
+ openssl genpkey -genparam -algorithm DH -out dhp.pem \
+ -pkeyopt dh_paramgen_prime_len:1024
+
+Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
+
+ openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
+
+Generate DH key from parameters:
+
+ openssl genpkey -paramfile dhp.pem -out dhkey.pem
+
+Generate EC parameters:
+
+ openssl genpkey -genparam -algorithm EC -out ecp.pem \
+ -pkeyopt ec_paramgen_curve:secp384r1 \
+ -pkeyopt ec_param_enc:named_curve
+
+Generate EC key from parameters:
+
+ openssl genpkey -paramfile ecp.pem -out eckey.pem
+
+Generate EC key directly:
+
+ openssl genpkey -algorithm EC -out eckey.pem \
+ -pkeyopt ec_paramgen_curve:P-384 \
+ -pkeyopt ec_param_enc:named_curve
+
+Generate an X25519 private key:
+
+ openssl genpkey -algorithm X25519 -out xkey.pem
+
+=head1 HISTORY
+
+The ability to use NIST curve names, and to generate an EC key directly,
+were added in OpenSSL 1.0.2.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+genrsa - generate an RSA private key
+
+=head1 SYNOPSIS
+
+B<openssl> B<genrsa>
+[B<-help>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-aes128>]
+[B<-aes192>]
+[B<-aes256>]
+[B<-camellia128>]
+[B<-camellia192>]
+[B<-camellia256>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-f4>]
+[B<-3>]
+[B<-rand file(s)>]
+[B<-engine id>]
+[B<numbits>]
+
+=head1 DESCRIPTION
+
+The B<genrsa> command generates an RSA private key.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-out filename>
+
+Output the key to the specified file. If this argument is not specified then
+standard output is used.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
+
+These options encrypt the private key with specified
+cipher before outputting it. If none of these options is
+specified no encryption is used. If encryption is used a pass phrase is prompted
+for if it is not supplied via the B<-passout> argument.
+
+=item B<-F4|-3>
+
+the public exponent to use, either 65537 or 3. The default is 65537.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<genrsa>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<numbits>
+
+the size of the private key to generate in bits. This must be the last option
+specified. The default is 512.
+
+=back
+
+=head1 NOTES
+
+RSA private key generation essentially involves the generation of two prime
+numbers. When generating a private key various symbols will be output to
+indicate the progress of the generation. A B<.> represents each number which
+has passed an initial sieve test, B<+> means a number has passed a single
+round of the Miller-Rabin primality test. A newline means that the number has
+passed all the prime tests (the actual number depends on the key size).
+
+Because key generation is a random process the time taken to generate a key
+may vary somewhat.
+
+=head1 BUGS
+
+A quirk of the prime generation algorithm is that it cannot generate small
+primes. Therefore the number of bits should not be less that 64. For typical
+private keys this will not matter because for security reasons they will
+be much larger (typically 1024 bits).
+
+=head1 SEE ALSO
+
+L<gendsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+list - list algorithms and features
+
+=head1 SYNOPSIS
+
+B<openssl list>
+[B<-help>]
+[B<-commands>]
+[B<-digest-commands>]
+[B<-digest-algorithms>]
+[B<-cipher-commands>]
+[B<-cipher-algorithms>]
+[B<-public-key-algorithms>]
+[B<-disabled>]
+
+=head1 DESCRIPTION
+
+This command is used to generate list of algorithms or disabled
+features.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Display out a usage message.
+
+=item B<-commands>
+
+Display a list of standard commands.
+
+=item B<-digest-commands>
+
+Display a list of message digest commands, which are typically used
+as input to the L<dgst(1)> or L<speed(1)> commands.
+
+=item B<-digest-algorithms>
+
+Display a list of message digest algorithms.
+If a line is of the form
+ foo => bar
+then B<foo> is an alias for the official algorithm name, B<bar>.
+
+=item B<-cipher-commands>
+
+Display a list of cipher commands, which are typically used as input
+to the L<dgst(1)> or L<speed(1)> commands.
+
+=item B<-cipher-algorithms>
+
+Display a list of cipher algorithms.
+If a line is of the form
+ foo => bar
+then B<foo> is an alias for the official algorithm name, B<bar>.
+
+=item B<-public-key-algorithms>
+
+Display a list of public key algorithms, with each algorithm as
+a block of multiple lines, all but the first are indented.
+
+=item B<-disabled>
+
+Display a list of disabled features, those that were compiled out
+of the installation.
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+nseq - create or examine a Netscape certificate sequence
+
+=head1 SYNOPSIS
+
+B<openssl> B<nseq>
+[B<-help>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-toseq>]
+
+=head1 DESCRIPTION
+
+The B<nseq> command takes a file containing a Netscape certificate
+sequence and prints out the certificates contained in it or takes a
+file of certificates and converts it into a Netscape certificate
+sequence.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-in filename>
+
+This specifies the input filename to read or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename or standard output by default.
+
+=item B<-toseq>
+
+normally a Netscape certificate sequence will be input and the output
+is the certificates contained in it. With the B<-toseq> option the
+situation is reversed: a Netscape certificate sequence is created from
+a file of certificates.
+
+=back
+
+=head1 EXAMPLES
+
+Output the certificates in a Netscape certificate sequence
+
+ openssl nseq -in nseq.pem -out certs.pem
+
+Create a Netscape certificate sequence
+
+ openssl nseq -in certs.pem -toseq -out nseq.pem
+
+=head1 NOTES
+
+The B<PEM> encoded form uses the same headers and footers as a certificate:
+
+ -----BEGIN CERTIFICATE-----
+ -----END CERTIFICATE-----
+
+A Netscape certificate sequence is a Netscape specific form that can be sent
+to browsers as an alternative to the standard PKCS#7 format when several
+certificates are sent to the browser: for example during certificate enrollment.
+It is used by Netscape certificate server for example.
+
+=head1 BUGS
+
+This program needs a few more options: like allowing DER or PEM input and
+output files and allowing multiple certificate files to be used.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ocsp - Online Certificate Status Protocol utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<ocsp>
+[B<-help>]
+[B<-out file>]
+[B<-issuer file>]
+[B<-cert file>]
+[B<-serial n>]
+[B<-signer file>]
+[B<-signkey file>]
+[B<-sign_other file>]
+[B<-no_certs>]
+[B<-req_text>]
+[B<-resp_text>]
+[B<-text>]
+[B<-reqout file>]
+[B<-respout file>]
+[B<-reqin file>]
+[B<-respin file>]
+[B<-nonce>]
+[B<-no_nonce>]
+[B<-url URL>]
+[B<-host host:port>]
+[B<-header>]
+[B<-path>]
+[B<-CApath dir>]
+[B<-CAfile file>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-no_check_time>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-use_deltas>]
+[B<-auth_level num>]
+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
+[B<-VAfile file>]
+[B<-validity_period n>]
+[B<-status_age n>]
+[B<-noverify>]
+[B<-verify_other file>]
+[B<-trust_other>]
+[B<-no_intern>]
+[B<-no_signature_verify>]
+[B<-no_cert_verify>]
+[B<-no_chain>]
+[B<-no_cert_checks>]
+[B<-no_explicit>]
+[B<-port num>]
+[B<-index file>]
+[B<-CA file>]
+[B<-rsigner file>]
+[B<-rkey file>]
+[B<-rother file>]
+[B<-resp_no_certs>]
+[B<-nmin n>]
+[B<-ndays n>]
+[B<-resp_key_id>]
+[B<-nrequest n>]
+[B<-md5|-sha1|...>]
+
+=head1 DESCRIPTION
+
+The Online Certificate Status Protocol (OCSP) enables applications to
+determine the (revocation) state of an identified certificate (RFC 2560).
+
+The B<ocsp> command performs many common OCSP tasks. It can be used
+to print out requests and responses, create requests and send queries
+to an OCSP responder and behave like a mini OCSP server itself.
+
+=head1 COMMAND OPTIONS
+
+This command operates as either a client or a server.
+The options are described below, divided into those two modes.
+
+=head2 OCSP Client Options
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-out filename>
+
+specify output filename, default is standard output.
+
+=item B<-issuer filename>
+
+This specifies the current issuer certificate. This option can be used
+multiple times. The certificate specified in B<filename> must be in
+PEM format. This option B<MUST> come before any B<-cert> options.
+
+=item B<-cert filename>
+
+Add the certificate B<filename> to the request. The issuer certificate
+is taken from the previous B<issuer> option, or an error occurs if no
+issuer certificate is specified.
+
+=item B<-serial num>
+
+Same as the B<cert> option except the certificate with serial number
+B<num> is added to the request. The serial number is interpreted as a
+decimal integer unless preceded by B<0x>. Negative integers can also
+be specified by preceding the value by a B<-> sign.
+
+=item B<-signer filename>, B<-signkey filename>
+
+Sign the OCSP request using the certificate specified in the B<signer>
+option and the private key specified by the B<signkey> option. If
+the B<signkey> option is not present then the private key is read
+from the same file as the certificate. If neither option is specified then
+the OCSP request is not signed.
+
+=item B<-sign_other filename>
+
+Additional certificates to include in the signed request.
+
+=item B<-nonce>, B<-no_nonce>
+
+Add an OCSP nonce extension to a request or disable OCSP nonce addition.
+Normally if an OCSP request is input using the B<reqin> option no
+nonce is added: using the B<nonce> option will force addition of a nonce.
+If an OCSP request is being created (using B<cert> and B<serial> options)
+a nonce is automatically added specifying B<no_nonce> overrides this.
+
+=item B<-req_text>, B<-resp_text>, B<-text>
+
+print out the text form of the OCSP request, response or both respectively.
+
+=item B<-reqout file>, B<-respout file>
+
+write out the DER encoded certificate request or response to B<file>.
+
+=item B<-reqin file>, B<-respin file>
+
+read OCSP request or response file from B<file>. These option are ignored
+if OCSP request or response creation is implied by other options (for example
+with B<serial>, B<cert> and B<host> options).
+
+=item B<-url responder_url>
+
+specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
+
+=item B<-host hostname:port>, B<-path pathname>
+
+if the B<host> option is present then the OCSP request is sent to the host
+B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
+or "/" by default. This is equivalent to specifying B<-url> with scheme
+http:// and the given hostname, port, and pathname.
+
+=item B<-header name=value>
+
+Adds the header B<name> with the specified B<value> to the OCSP request
+that is sent to the responder.
+This may be repeated.
+
+=item B<-timeout seconds>
+
+connection timeout to the OCSP responder in seconds
+
+=item B<-CAfile file>, B<-CApath pathname>
+
+file or pathname containing trusted CA certificates. These are used to verify
+the signature on the OCSP response.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
+B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
+B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
+B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
+B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
+B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
+B<-verify_ip>, B<-verify_name>, B<-x509_strict>
+
+Set different certificate verification options.
+See L<verify(1)> manual page for details.
+
+=item B<-verify_other file>
+
+file containing additional certificates to search when attempting to locate
+the OCSP response signing certificate. Some responders omit the actual signer's
+certificate from the response: this option can be used to supply the necessary
+certificate in such cases.
+
+=item B<-trust_other>
+
+the certificates specified by the B<-verify_other> option should be explicitly
+trusted and no additional checks will be performed on them. This is useful
+when the complete responder certificate chain is not available or trusting a
+root CA is not appropriate.
+
+=item B<-VAfile file>
+
+file containing explicitly trusted responder certificates. Equivalent to the
+B<-verify_other> and B<-trust_other> options.
+
+=item B<-noverify>
+
+don't attempt to verify the OCSP response signature or the nonce values. This
+option will normally only be used for debugging since it disables all verification
+of the responders certificate.
+
+=item B<-no_intern>
+
+ignore certificates contained in the OCSP response when searching for the
+signers certificate. With this option the signers certificate must be specified
+with either the B<-verify_other> or B<-VAfile> options.
+
+=item B<-no_signature_verify>
+
+don't check the signature on the OCSP response. Since this option tolerates invalid
+signatures on OCSP responses it will normally only be used for testing purposes.
+
+=item B<-no_cert_verify>
+
+don't verify the OCSP response signers certificate at all. Since this option allows
+the OCSP response to be signed by any certificate it should only be used for
+testing purposes.
+
+=item B<-no_chain>
+
+do not use certificates in the response as additional untrusted CA
+certificates.
+
+=item B<-no_explicit>
+
+do not explicitly trust the root CA if it is set to be trusted for OCSP signing.
+
+=item B<-no_cert_checks>
+
+don't perform any additional checks on the OCSP response signers certificate.
+That is do not make any checks to see if the signers certificate is authorised
+to provide the necessary status information: as a result this option should
+only be used for testing purposes.
+
+=item B<-validity_period nsec>, B<-status_age age>
+
+these options specify the range of times, in seconds, which will be tolerated
+in an OCSP response. Each certificate status response includes a B<notBefore>
+time and an optional B<notAfter> time. The current time should fall between
+these two values, but the interval between the two times may be only a few
+seconds. In practice the OCSP responder and clients clocks may not be precisely
+synchronised and so such a check may fail. To avoid this the
+B<-validity_period> option can be used to specify an acceptable error range in
+seconds, the default value is 5 minutes.
+
+If the B<notAfter> time is omitted from a response then this means that new
+status information is immediately available. In this case the age of the
+B<notBefore> field is checked to see it is not older than B<age> seconds old.
+By default this additional check is not performed.
+
+=item B<-[digest]>
+
+this option sets digest algorithm to use for certificate identification in the
+OCSP request. Any digest supported by the OpenSSL B<dgst> command can be used.
+The default is SHA-1. This option may be used multiple times to specify the
+digest used by subsequent certificate identifiers.
+
+=back
+
+=head2 OCSP Server Options
+
+=over 4
+
+=item B<-index indexfile>
+
+B<indexfile> is a text index file in B<ca> format containing certificate revocation
+information.
+
+If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise
+it is in client mode. The request(s) the responder processes can be either specified on
+the command line (using B<issuer> and B<serial> options), supplied in a file (using the
+B<reqin> option) or via external OCSP clients (if B<port> or B<url> is specified).
+
+If the B<index> option is present then the B<CA> and B<rsigner> options must also be
+present.
+
+=item B<-CA file>
+
+CA certificate corresponding to the revocation information in B<indexfile>.
+
+=item B<-rsigner file>
+
+The certificate to sign OCSP responses with.
+
+=item B<-rother file>
+
+Additional certificates to include in the OCSP response.
+
+=item B<-resp_no_certs>
+
+Don't include any certificates in the OCSP response.
+
+=item B<-resp_key_id>
+
+Identify the signer certificate using the key ID, default is to use the subject name.
+
+=item B<-rkey file>
+
+The private key to sign OCSP responses with: if not present the file specified in the
+B<rsigner> option is used.
+
+=item B<-port portnum>
+
+Port to listen for OCSP requests on. The port may also be specified using the B<url>
+option.
+
+=item B<-nrequest number>
+
+The OCSP server will exit after receiving B<number> requests, default unlimited.
+
+=item B<-nmin minutes>, B<-ndays days>
+
+Number of minutes or days when fresh revocation information is available: used in the
+B<nextUpdate> field. If neither option is present then the B<nextUpdate> field
+is omitted meaning fresh revocation information is immediately available.
+
+=back
+
+=head1 OCSP Response verification.
+
+OCSP Response follows the rules specified in RFC2560.
+
+Initially the OCSP responder certificate is located and the signature on
+the OCSP request checked using the responder certificate's public key.
+
+Then a normal certificate verify is performed on the OCSP responder certificate
+building up a certificate chain in the process. The locations of the trusted
+certificates used to build the chain can be specified by the B<CAfile>
+and B<CApath> options or they will be looked for in the standard OpenSSL
+certificates directory.
+
+If the initial verify fails then the OCSP verify process halts with an
+error.
+
+Otherwise the issuing CA certificate in the request is compared to the OCSP
+responder certificate: if there is a match then the OCSP verify succeeds.
+
+Otherwise the OCSP responder certificate's CA is checked against the issuing
+CA certificate in the request. If there is a match and the OCSPSigning
+extended key usage is present in the OCSP responder certificate then the
+OCSP verify succeeds.
+
+Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders
+CA is checked to see if it is trusted for OCSP signing. If it is the OCSP
+verify succeeds.
+
+If none of these checks is successful then the OCSP verify fails.
+
+What this effectively means if that if the OCSP responder certificate is
+authorised directly by the CA it is issuing revocation information about
+(and it is correctly configured) then verification will succeed.
+
+If the OCSP responder is a "global responder" which can give details about
+multiple CAs and has its own separate certificate chain then its root
+CA can be trusted for OCSP signing. For example:
+
+ openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
+
+Alternatively the responder certificate itself can be explicitly trusted
+with the B<-VAfile> option.
+
+=head1 NOTES
+
+As noted, most of the verify options are for testing or debugging purposes.
+Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global
+VA') B<-VAfile> options need to be used.
+
+The OCSP server is only useful for test and demonstration purposes: it is
+not really usable as a full OCSP responder. It contains only a very
+simple HTTP request handling and can only handle the POST form of OCSP
+queries. It also handles requests serially meaning it cannot respond to
+new requests until it has processed the current one. The text index file
+format of revocation is also inefficient for large quantities of revocation
+data.
+
+It is possible to run the B<ocsp> application in responder mode via a CGI
+script using the B<reqin> and B<respout> options.
+
+=head1 EXAMPLES
+
+Create an OCSP request and write it to a file:
+
+ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
+
+Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
+response to a file, print it out in text form, and verify the response:
+
+ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
+ -url http://ocsp.myhost.com/ -resp_text -respout resp.der
+
+Read in an OCSP response and print out text form:
+
+ openssl ocsp -respin resp.der -text -noverify
+
+OCSP server on port 8888 using a standard B<ca> configuration, and a separate
+responder certificate. All requests and responses are printed to a file.
+
+ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
+ -text -out log.txt
+
+As above but exit after processing one request:
+
+ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
+ -nrequest 1
+
+Query status information using an internally generated request:
+
+ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
+ -issuer demoCA/cacert.pem -serial 1
+
+Query status information using request read from a file, and write the response
+to a second file.
+
+ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
+ -reqin req.der -respout resp.der
+
+=head1 HISTORY
+
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+openssl - OpenSSL command line tool
+
+=head1 SYNOPSIS
+
+B<openssl>
+I<command>
+[ I<command_opts> ]
+[ I<command_args> ]
+
+B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<public-key-algorithms>]
+
+B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
+
+=head1 DESCRIPTION
+
+OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL
+v2/v3) and Transport Layer Security (TLS v1) network protocols and related
+cryptography standards required by them.
+
+The B<openssl> program is a command line tool for using the various
+cryptography functions of OpenSSL's B<crypto> library from the shell.
+It can be used for
+
+ o Creation and management of private keys, public keys and parameters
+ o Public key cryptographic operations
+ o Creation of X.509 certificates, CSRs and CRLs
+ o Calculation of Message Digests
+ o Encryption and Decryption with Ciphers
+ o SSL/TLS Client and Server Tests
+ o Handling of S/MIME signed or encrypted mail
+ o Time Stamp requests, generation and verification
+
+=head1 COMMAND SUMMARY
+
+The B<openssl> program provides a rich variety of commands (I<command> in the
+SYNOPSIS above), each of which often has a wealth of options and arguments
+(I<command_opts> and I<command_args> in the SYNOPSIS).
+
+The list parameters B<standard-commands>, B<digest-commands>,
+and B<cipher-commands> output a list (one entry per line) of the names
+of all standard commands, message digest commands, or cipher commands,
+respectively, that are available in the present B<openssl> utility.
+
+The list parameters B<cipher-algorithms> and
+B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
+
+ from => to
+
+The list parameter B<public-key-algorithms> lists all supported public
+key algorithms.
+
+The command B<no->I<XXX> tests whether a command of the
+specified name is available. If no command named I<XXX> exists, it
+returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1
+and prints I<XXX>. In both cases, the output goes to B<stdout> and
+nothing is printed to B<stderr>. Additional command line arguments
+are always ignored. Since for each cipher there is a command of the
+same name, this provides an easy way for shell scripts to test for the
+availability of ciphers in the B<openssl> program. (B<no->I<XXX> is
+not able to detect pseudo-commands such as B<quit>,
+B<list>, or B<no->I<XXX> itself.)
+
+=head2 Standard Commands
+
+=over 10
+
+=item L<B<asn1parse>|asn1parse(1)>
+
+Parse an ASN.1 sequence.
+
+=item L<B<ca>|ca(1)>
+
+Certificate Authority (CA) Management.
+
+=item L<B<ciphers>|ciphers(1)>
+
+Cipher Suite Description Determination.
+
+=item L<B<cms>|cms(1)>
+
+CMS (Cryptographic Message Syntax) utility
+
+=item L<B<crl>|crl(1)>
+
+Certificate Revocation List (CRL) Management.
+
+=item L<B<crl2pkcs7>|crl2pkcs7(1)>
+
+CRL to PKCS#7 Conversion.
+
+=item L<B<dgst>|dgst(1)>
+
+Message Digest Calculation.
+
+=item B<dh>
+
+Diffie-Hellman Parameter Management.
+Obsoleted by L<B<dhparam>|dhparam(1)>.
+
+=item L<B<dhparam>|dhparam(1)>
+
+Generation and Management of Diffie-Hellman Parameters. Superseded by
+L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
+
+
+=item L<B<dsa>|dsa(1)>
+
+DSA Data Management.
+
+=item L<B<dsaparam>|dsaparam(1)>
+
+DSA Parameter Generation and Management. Superseded by
+L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
+
+=item L<B<ec>|ec(1)>
+
+EC (Elliptic curve) key processing
+
+=item L<B<ecparam>|ecparam(1)>
+
+EC parameter manipulation and generation
+
+=item L<B<enc>|enc(1)>
+
+Encoding with Ciphers.
+
+=item L<B<engine>|engine(1)>
+
+Engine (loadable module) information and manipulation.
+
+=item L<B<errstr>|errstr(1)>
+
+Error Number to Error String Conversion.
+
+=item B<gendh>
+
+Generation of Diffie-Hellman Parameters.
+Obsoleted by L<B<dhparam>|dhparam(1)>.
+
+=item L<B<gendsa>|gendsa(1)>
+
+Generation of DSA Private Key from Parameters. Superseded by
+L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>
+
+=item L<B<genpkey>|genpkey(1)>
+
+Generation of Private Key or Parameters.
+
+=item L<B<genrsa>|genrsa(1)>
+
+Generation of RSA Private Key. Superseded by L<B<genpkey>|genpkey(1)>.
+
+=item L<B<nseq>|nseq(1)>
+
+Create or examine a Netscape certificate sequence
+
+=item L<B<ocsp>|ocsp(1)>
+
+Online Certificate Status Protocol utility.
+
+=item L<B<passwd>|passwd(1)>
+
+Generation of hashed passwords.
+
+=item L<B<pkcs12>|pkcs12(1)>
+
+PKCS#12 Data Management.
+
+=item L<B<pkcs7>|pkcs7(1)>
+
+PKCS#7 Data Management.
+
+=item L<B<pkey>|pkey(1)>
+
+Public and private key management.
+
+=item L<B<pkeyparam>|pkeyparam(1)>
+
+Public key algorithm parameter management.
+
+=item L<B<pkeyutl>|pkeyutl(1)>
+
+Public key algorithm cryptographic operation utility.
+
+=item L<B<rand>|rand(1)>
+
+Generate pseudo-random bytes.
+
+=item L<B<req>|req(1)>
+
+PKCS#10 X.509 Certificate Signing Request (CSR) Management.
+
+=item L<B<rsa>|rsa(1)>
+
+RSA key management.
+
+
+=item L<B<rsautl>|rsautl(1)>
+
+RSA utility for signing, verification, encryption, and decryption. Superseded
+by L<B<pkeyutl>|pkeyutl(1)>
+
+=item L<B<s_client>|s_client(1)>
+
+This implements a generic SSL/TLS client which can establish a transparent
+connection to a remote server speaking SSL/TLS. It's intended for testing
+purposes only and provides only rudimentary interface functionality but
+internally uses mostly all functionality of the OpenSSL B<ssl> library.
+
+=item L<B<s_server>|s_server(1)>
+
+This implements a generic SSL/TLS server which accepts connections from remote
+clients speaking SSL/TLS. It's intended for testing purposes only and provides
+only rudimentary interface functionality but internally uses mostly all
+functionality of the OpenSSL B<ssl> library. It provides both an own command
+line oriented protocol for testing SSL functions and a simple HTTP response
+facility to emulate an SSL/TLS-aware webserver.
+
+=item L<B<s_time>|s_time(1)>
+
+SSL Connection Timer.
+
+=item L<B<sess_id>|sess_id(1)>
+
+SSL Session Data Management.
+
+=item L<B<smime>|smime(1)>
+
+S/MIME mail processing.
+
+=item L<B<speed>|speed(1)>
+
+Algorithm Speed Measurement.
+
+=item L<B<spkac>|spkac(1)>
+
+SPKAC printing and generating utility
+
+=item L<B<ts>|ts(1)>
+
+Time Stamping Authority tool (client/server)
+
+=item L<B<verify>|verify(1)>
+
+X.509 Certificate Verification.
+
+=item L<B<version>|version(1)>
+
+OpenSSL Version Information.
+
+=item L<B<x509>|x509(1)>
+
+X.509 Certificate Data Management.
+
+=back
+
+=head2 Message Digest Commands
+
+=over 10
+
+=item B<md2>
+
+MD2 Digest
+
+=item B<md5>
+
+MD5 Digest
+
+=item B<mdc2>
+
+MDC2 Digest
+
+=item B<rmd160>
+
+RMD-160 Digest
+
+=item B<sha>
+
+SHA Digest
+
+=item B<sha1>
+
+SHA-1 Digest
+
+=item B<sha224>
+
+SHA-224 Digest
+
+=item B<sha256>
+
+SHA-256 Digest
+
+=item B<sha384>
+
+SHA-384 Digest
+
+=item B<sha512>
+
+SHA-512 Digest
+
+=back
+
+=head2 Encoding and Cipher Commands
+
+=over 10
+
+=item B<base64>
+
+Base64 Encoding
+
+=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb>
+
+Blowfish Cipher
+
+=item B<cast cast-cbc>
+
+CAST Cipher
+
+=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb>
+
+CAST5 Cipher
+
+=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb>
+
+DES Cipher
+
+=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb>
+
+Triple-DES Cipher
+
+=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb>
+
+IDEA Cipher
+
+=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb>
+
+RC2 Cipher
+
+=item B<rc4>
+
+RC4 Cipher
+
+=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb>
+
+RC5 Cipher
+
+=back
+
+=head1 COMMAND OPTIONS
+
+Details of which options are available depend on the specific command.
+This section describes some common options with common behavior.
+
+=head2 Common Options
+
+=over 10
+
+=item B<-help>
+
+Provides a terse summary of all options.
+
+=back
+
+=head2 Pass Phrase Options
+
+Several commands accept password arguments, typically using B<-passin>
+and B<-passout> for input and output passwords respectively. These allow
+the password to be obtained from a variety of sources. Both of these
+options take a single argument whose format is described below. If no
+password argument is given and a password is required then the user is
+prompted to enter one: this will typically be read from the current
+terminal with echoing turned off.
+
+=over 10
+
+=item B<pass:password>
+
+the actual password is B<password>. Since the password is visible
+to utilities (like 'ps' under Unix) this form should only be used
+where security is not important.
+
+=item B<env:var>
+
+obtain the password from the environment variable B<var>. Since
+the environment of other processes is visible on certain platforms
+(e.g. ps under certain Unix OSes) this option should be used with caution.
+
+=item B<file:pathname>
+
+the first line of B<pathname> is the password. If the same B<pathname>
+argument is supplied to B<-passin> and B<-passout> arguments then the first
+line will be used for the input password and the next line for the output
+password. B<pathname> need not refer to a regular file: it could for example
+refer to a device or named pipe.
+
+=item B<fd:number>
+
+read the password from the file descriptor B<number>. This can be used to
+send the data via a pipe for example.
+
+=item B<stdin>
+
+read the password from standard input.
+
+=back
+
+=head1 SEE ALSO
+
+L<asn1parse(1)>, L<ca(1)>, L<config(5)>,
+L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
+L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
+L<enc(1)>, L<engine(1)>, L<gendsa(1)>, L<genpkey(1)>,
+L<genrsa(1)>, L<nseq(1)>, L<openssl(1)>,
+L<passwd(1)>,
+L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,
+L<rand(1)>, L<req(1)>, L<rsa(1)>,
+L<rsautl(1)>, L<s_client(1)>,
+L<s_server(1)>, L<s_time(1)>,
+L<smime(1)>, L<spkac(1)>,
+L<verify(1)>, L<version(1)>, L<x509(1)>,
+L<crypto(3)>, L<ssl(3)>, L<x509v3_config(5)>
+
+=head1 HISTORY
+
+The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0;
+For notes on the availability of other commands, see their individual
+manual pages.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+passwd - compute password hashes
+
+=head1 SYNOPSIS
+
+B<openssl passwd>
+[B<-help>]
+[B<-crypt>]
+[B<-1>]
+[B<-apr1>]
+[B<-5>]
+[B<-6>]
+[B<-salt> I<string>]
+[B<-in> I<file>]
+[B<-stdin>]
+[B<-noverify>]
+[B<-quiet>]
+[B<-table>]
+{I<password>}
+
+=head1 DESCRIPTION
+
+The B<passwd> command computes the hash of a password typed at
+run-time or the hash of each password in a list. The password list is
+taken from the named file for option B<-in file>, from stdin for
+option B<-stdin>, or from the command line, or from the terminal otherwise.
+The Unix standard algorithm B<crypt> and the MD5-based BSD password
+algorithm B<1> and its Apache variant B<apr1> are available.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-crypt>
+
+Use the B<crypt> algorithm (default).
+
+=item B<-1>
+
+Use the MD5 based BSD password algorithm B<1>.
+
+=item B<-apr1>
+
+Use the B<apr1> algorithm (Apache variant of the BSD algorithm).
+
+=item B<-5>
+
+=item B<-6>
+
+Use the B<SHA256> / B<SHA512> based algorithms defined by Ulrich Drepper.
+See L<https://www.akkadia.org/drepper/SHA-crypt.txt>.
+
+=item B<-salt> I<string>
+
+Use the specified salt.
+When reading a password from the terminal, this implies B<-noverify>.
+
+=item B<-in> I<file>
+
+Read passwords from I<file>.
+
+=item B<-stdin>
+
+Read passwords from B<stdin>.
+
+=item B<-noverify>
+
+Don't verify when reading a password from the terminal.
+
+=item B<-quiet>
+
+Don't output warnings when passwords given at the command line are truncated.
+
+=item B<-table>
+
+In the output list, prepend the cleartext password and a TAB character
+to each password hash.
+
+=back
+
+=head1 EXAMPLES
+
+B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>.
+
+B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>.
+
+B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+pkcs12 - PKCS#12 file utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs12>
+[B<-help>]
+[B<-export>]
+[B<-chain>]
+[B<-inkey filename>]
+[B<-certfile filename>]
+[B<-name name>]
+[B<-caname name>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-nomacver>]
+[B<-nocerts>]
+[B<-clcerts>]
+[B<-cacerts>]
+[B<-nokeys>]
+[B<-info>]
+[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>]
+[B<-noiter>]
+[B<-maciter | -nomaciter | -nomac>]
+[B<-twopass>]
+[B<-descert>]
+[B<-certpbe cipher>]
+[B<-keypbe cipher>]
+[B<-macalg digest>]
+[B<-keyex>]
+[B<-keysig>]
+[B<-password arg>]
+[B<-passin arg>]
+[B<-passout arg>]
+[B<-rand file(s)>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-CSP name>]
+
+=head1 DESCRIPTION
+
+The B<pkcs12> command allows PKCS#12 files (sometimes referred to as
+PFX files) to be created and parsed. PKCS#12 files are used by several
+programs including Netscape, MSIE and MS Outlook.
+
+=head1 COMMAND OPTIONS
+
+There are a lot of options the meaning of some depends of whether a PKCS#12 file
+is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12
+file can be created by using the B<-export> option (see below).
+
+=head1 PARSING OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-in filename>
+
+This specifies filename of the PKCS#12 file to be parsed. Standard input is used
+by default.
+
+=item B<-out filename>
+
+The filename to write certificates and private keys to, standard output by
+default. They are all written in PEM format.
+
+=item B<-passin arg>
+
+the PKCS#12 file (i.e. input file) password source. For more information about
+the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)>.
+
+=item B<-passout arg>
+
+pass phrase source to encrypt any outputted private keys with. For more
+information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section
+in L<openssl(1)>.
+
+=item B<-password arg>
+
+With -export, -password is equivalent to -passout.
+Otherwise, -password is equivalent to -passin.
+
+=item B<-noout>
+
+this option inhibits output of the keys and certificates to the output file
+version of the PKCS#12 file.
+
+=item B<-clcerts>
+
+only output client certificates (not CA certificates).
+
+=item B<-cacerts>
+
+only output CA certificates (not client certificates).
+
+=item B<-nocerts>
+
+no certificates at all will be output.
+
+=item B<-nokeys>
+
+no private keys will be output.
+
+=item B<-info>
+
+output additional information about the PKCS#12 file structure, algorithms used and
+iteration counts.
+
+=item B<-des>
+
+use DES to encrypt private keys before outputting.
+
+=item B<-des3>
+
+use triple DES to encrypt private keys before outputting, this is the default.
+
+=item B<-idea>
+
+use IDEA to encrypt private keys before outputting.
+
+=item B<-aes128>, B<-aes192>, B<-aes256>
+
+use AES to encrypt private keys before outputting.
+
+=item B<-camellia128>, B<-camellia192>, B<-camellia256>
+
+use Camellia to encrypt private keys before outputting.
+
+=item B<-nodes>
+
+don't encrypt the private keys at all.
+
+=item B<-nomacver>
+
+don't attempt to verify the integrity MAC before reading the file.
+
+=item B<-twopass>
+
+prompt for separate integrity and encryption passwords: most software
+always assumes these are the same so this option will render such
+PKCS#12 files unreadable.
+
+=back
+
+=head1 FILE CREATION OPTIONS
+
+=over 4
+
+=item B<-export>
+
+This option specifies that a PKCS#12 file will be created rather than
+parsed.
+
+=item B<-out filename>
+
+This specifies filename to write the PKCS#12 file to. Standard output is used
+by default.
+
+=item B<-in filename>
+
+The filename to read certificates and private keys from, standard input by
+default. They must all be in PEM format. The order doesn't matter but one
+private key and its corresponding certificate should be present. If additional
+certificates are present they will also be included in the PKCS#12 file.
+
+=item B<-inkey filename>
+
+file to read private key from. If not present then a private key must be present
+in the input file.
+
+=item B<-name friendlyname>
+
+This specifies the "friendly name" for the certificate and private key. This
+name is typically displayed in list boxes by software importing the file.
+
+=item B<-certfile filename>
+
+A filename to read additional certificates from.
+
+=item B<-caname friendlyname>
+
+This specifies the "friendly name" for other certificates. This option may be
+used multiple times to specify names for all certificates in the order they
+appear. Netscape ignores friendly names on other certificates whereas MSIE
+displays them.
+
+=item B<-pass arg>, B<-passout arg>
+
+the PKCS#12 file (i.e. output file) password source. For more information about
+the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)>.
+
+=item B<-passin password>
+
+pass phrase source to decrypt any input private keys with. For more information
+about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)>.
+
+=item B<-chain>
+
+if this option is present then an attempt is made to include the entire
+certificate chain of the user certificate. The standard CA store is used
+for this search. If the search fails it is considered a fatal error.
+
+=item B<-descert>
+
+encrypt the certificate using triple DES, this may render the PKCS#12
+file unreadable by some "export grade" software. By default the private
+key is encrypted using triple DES and the certificate using 40 bit RC2.
+
+=item B<-keypbe alg>, B<-certpbe alg>
+
+these options allow the algorithm used to encrypt the private key and
+certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name
+can be used (see B<NOTES> section for more information). If a cipher name
+(as output by the B<list-cipher-algorithms> command is specified then it
+is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only
+use PKCS#12 algorithms.
+
+=item B<-keyex|-keysig>
+
+specifies that the private key is to be used for key exchange or just signing.
+This option is only interpreted by MSIE and similar MS software. Normally
+"export grade" software will only allow 512 bit RSA keys to be used for
+encryption purposes but arbitrary length keys for signing. The B<-keysig>
+option marks the key for signing only. Signing only keys can be used for
+S/MIME signing, authenticode (ActiveX control signing) and SSL client
+authentication, however due to a bug only MSIE 5.0 and later support
+the use of signing only keys for SSL client authentication.
+
+=item B<-macalg digest>
+
+specify the MAC digest algorithm. If not included them SHA1 will be used.
+
+=item B<-nomaciter>, B<-noiter>
+
+these options affect the iteration counts on the MAC and key algorithms.
+Unless you wish to produce files compatible with MSIE 4.0 you should leave
+these options alone.
+
+To discourage attacks by using large dictionaries of common passwords the
+algorithm that derives keys from passwords can have an iteration count applied
+to it: this causes a certain part of the algorithm to be repeated and slows it
+down. The MAC is used to check the file integrity but since it will normally
+have the same password as the keys and certificates it could also be attacked.
+By default both MAC and encryption iteration counts are set to 2048, using
+these options the MAC and encryption iteration counts can be set to 1, since
+this reduces the file security you should not use these options unless you
+really have to. Most software supports both MAC and key iteration counts.
+MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter>
+option.
+
+=item B<-maciter>
+
+This option is included for compatibility with previous versions, it used
+to be needed to use MAC iterations counts but they are now used by default.
+
+=item B<-nomac>
+
+don't attempt to provide the MAC integrity.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-CAfile file>
+
+CA storage as a file.
+
+=item B<-CApath dir>
+
+CA storage as a directory. This directory must be a standard certificate
+directory: that is a hash of each subject name (using B<x509 -hash>) should be
+linked to each certificate.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-CSP name>
+
+write B<name> as a Microsoft CSP name.
+
+=back
+
+=head1 NOTES
+
+Although there are a large number of options most of them are very rarely
+used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
+for PKCS#12 file creation B<-export> and B<-name> are also used.
+
+If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present
+then all certificates will be output in the order they appear in the input
+PKCS#12 files. There is no guarantee that the first certificate present is
+the one corresponding to the private key. Certain software which requires
+a private key and certificate and assumes the first certificate in the
+file is the one corresponding to the private key: this may not always
+be the case. Using the B<-clcerts> option will solve this problem by only
+outputting the certificate corresponding to the private key. If the CA
+certificates are required then they can be output to a separate file using
+the B<-nokeys -cacerts> options to just output CA certificates.
+
+The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption
+algorithms for private keys and certificates to be specified. Normally
+the defaults are fine but occasionally software can't handle triple DES
+encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can
+be used to reduce the private key encryption to 40 bit RC2. A complete
+description of all algorithms is contained in the B<pkcs8> manual page.
+
+Prior 1.1 release passwords containing non-ASCII characters were encoded
+in non-compliant manner, which limited interoperability, in first hand
+with Windows. But switching to standard-compliant password encoding
+poses problem accessing old data protected with broken encoding. For
+this reason even legacy encodings is attempted when reading the
+data. If you use PKCS#12 files in production application you are advised
+to convert the data, because implemented heuristic approach is not
+MT-safe, its sole goal is to facilitate the data upgrade with this
+utility.
+
+=head1 EXAMPLES
+
+Parse a PKCS#12 file and output it to a file:
+
+ openssl pkcs12 -in file.p12 -out file.pem
+
+Output only client certificates to a file:
+
+ openssl pkcs12 -in file.p12 -clcerts -out file.pem
+
+Don't encrypt the private key:
+
+ openssl pkcs12 -in file.p12 -out file.pem -nodes
+
+Print some info about a PKCS#12 file:
+
+ openssl pkcs12 -in file.p12 -info -noout
+
+Create a PKCS#12 file:
+
+ openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
+
+Include some extra certificates:
+
+ openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
+ -certfile othercerts.pem
+
+=head1 SEE ALSO
+
+L<pkcs8(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+pkcs7 - PKCS#7 utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs7>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-print_certs>]
+[B<-text>]
+[B<-noout>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. B<DER> format is DER encoded PKCS#7
+v1.5 structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-print_certs>
+
+prints out any certificates or CRLs contained in the file. They are
+preceded by their subject and issuer names in one line format.
+
+=item B<-text>
+
+prints out certificates details in full rather than just subject and
+issuer names.
+
+=item B<-noout>
+
+don't output the encoded version of the PKCS#7 structure (or certificates
+is B<-print_certs> is set).
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<pkcs7>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 EXAMPLES
+
+Convert a PKCS#7 file from PEM to DER:
+
+ openssl pkcs7 -in file.pem -outform DER -out file.der
+
+Output all certificates in a file:
+
+ openssl pkcs7 -in file.pem -print_certs -out certs.pem
+
+=head1 NOTES
+
+The PEM PKCS#7 format uses the header and footer lines:
+
+ -----BEGIN PKCS7-----
+ -----END PKCS7-----
+
+For compatibility with some CAs it will also accept:
+
+ -----BEGIN CERTIFICATE-----
+ -----END CERTIFICATE-----
+
+=head1 RESTRICTIONS
+
+There is no option to print out all the fields of a PKCS#7 file.
+
+This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
+cannot currently parse, for example, the new CMS as described in RFC2630.
+
+=head1 SEE ALSO
+
+L<crl2pkcs7(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+pkcs8 - PKCS#8 format private key conversion tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs8>
+[B<-help>]
+[B<-topk8>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-iter count>]
+[B<-noiter>]
+[B<-nocrypt>]
+[B<-traditional>]
+[B<-v2 alg>]
+[B<-v2prf alg>]
+[B<-v1 alg>]
+[B<-engine id>]
+[B<-scrypt>]
+[B<-scrypt_N N>]
+[B<-scrypt_r r>]
+[B<-scrypt_p p>]
+
+=head1 DESCRIPTION
+
+The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
+both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
+format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-topk8>
+
+Normally a PKCS#8 private key is expected on input and a private key will be
+written to the output file. With the B<-topk8> option the situation is
+reversed: it reads a private key and writes a PKCS#8 format key.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format: see L<KEY FORMATS> for more details.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format: see L<KEY FORMATS> for more details.
+
+=item B<-traditional>
+
+When this option is present and B<-topk8> is not a traditional format private
+key is written.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+default. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-iter count>
+
+When creating new PKCS#8 containers, use a given number of iterations on
+the password in deriving the encryption key for the PKCS#8 output.
+High values increase the time required to brute-force a PKCS#8 container.
+
+=item B<-nocrypt>
+
+PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
+structures using an appropriate password based encryption algorithm. With
+this option an unencrypted PrivateKeyInfo structure is expected or output.
+This option does not encrypt private keys at all and should only be used
+when absolutely necessary. Certain software such as some versions of Java
+code signing software used unencrypted private keys.
+
+=item B<-v2 alg>
+
+This option sets the PKCS#5 v2.0 algorithm.
+
+The B<alg> argument is the encryption algorithm to use, valid values include
+B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256>
+is used.
+
+=item B<-v2prf alg>
+
+This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
+value would be B<hmacWithSHA256>. If this option isn't set then the default
+for the cipher is used or B<hmacWithSHA256> if there is no default.
+
+Some implementations may not support custom PRF algorithms and may require
+the B<hmacWithSHA1> option to work.
+
+=item B<-v1 alg>
+
+This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some
+older implementations may not support PKCS#5 v2.0 and may require this option.
+If not specified PKCS#5 v2.0 form is used.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<pkcs8>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-scrypt>
+
+uses the B<scrypt> algorithm for private key encryption using default
+parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
+key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>,
+B<-scrypt_p> and B<-v2> options.
+
+B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p>
+
+sets the scrypt B<N>, B<r> or B<p> parameters.
+
+=back
+
+=head1 KEY FORMATS
+
+Various different formats are used by the pkcs8 utility. These are detailed
+below.
+
+If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is
+not used) then the input file must be in PKCS#8 format. An encrypted
+key is expected unless B<-nocrypt> is included.
+
+If B<-topk8> is not used and B<PEM> mode is set the output file will be an
+unencrypted private key in PKCS#8 format. If the B<-traditional> option is
+used then a traditional format private key is written instead.
+
+If B<-topk8> is not used and B<DER> mode is set the output file will be an
+unencrypted private key in traditional DER format.
+
+If B<-topk8> is used then any supported private key can be used for the input
+file in a format specified by B<-inform>. The output file will be encrypted
+PKCS#8 format using the specified encryption parameters unless B<-nocrypt>
+is included.
+
+=head1 NOTES
+
+By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
+AES with HMAC and SHA256 is used.
+
+Some older implementations do not support PKCS#5 v2.0 format and require
+the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
+encryption algorithms such as 56 bit DES.
+
+The encrypted form of a PEM encode PKCS#8 files uses the following
+headers and footers:
+
+ -----BEGIN ENCRYPTED PRIVATE KEY-----
+ -----END ENCRYPTED PRIVATE KEY-----
+
+The unencrypted form uses:
+
+ -----BEGIN PRIVATE KEY-----
+ -----END PRIVATE KEY-----
+
+Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
+counts are more secure that those encrypted using the traditional
+SSLeay compatible formats. So if additional security is considered
+important the keys should be converted.
+
+It is possible to write out DER encoded encrypted private keys in
+PKCS#8 format because the encryption details are included at an ASN1
+level whereas the traditional format includes them at a PEM level.
+
+=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
+
+Various algorithms can be used with the B<-v1> command line option,
+including PKCS#5 v1.5 and PKCS#12. These are described in more detail
+below.
+
+=over 4
+
+=item B<PBE-MD2-DES PBE-MD5-DES>
+
+These algorithms were included in the original PKCS#5 v1.5 specification.
+They only offer 56 bits of protection since they both use DES.
+
+=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES>
+
+These algorithms are not mentioned in the original PKCS#5 v1.5 specification
+but they use the same key derivation algorithm and are supported by some
+software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
+56 bit DES.
+
+=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40>
+
+These algorithms use the PKCS#12 password based encryption algorithm and
+allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
+
+=back
+
+=head1 EXAMPLES
+
+Convert a private key to PKCS#8 format using default parameters (AES with
+256 bit key and B<hmacWithSHA256>):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem
+
+Convert a private key to PKCS#8 unencrypted format:
+
+ openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
+
+Convert a private key to PKCS#5 v2.0 format using triple DES:
+
+ openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
+
+Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
+mode and B<hmacWithSHA512> PRF:
+
+ openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem
+
+Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
+(DES):
+
+ openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem
+
+Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
+(3DES):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
+
+Read a DER unencrypted PKCS#8 format private key:
+
+ openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
+
+Convert a private key from any PKCS#8 encrypted format to traditional format:
+
+ openssl pkcs8 -in pk8.pem -traditional -out key.pem
+
+Convert a private key to PKCS#8 format, encrypting with AES-256 and with
+one million iterations of the password:
+
+ openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
+
+=head1 STANDARDS
+
+Test vectors from this PKCS#5 v2.0 implementation were posted to the
+pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
+counts, several people confirmed that they could decrypt the private
+keys produced and Therefore it can be assumed that the PKCS#5 v2.0
+implementation is reasonably accurate at least as far as these
+algorithms are concerned.
+
+The format of PKCS#8 DSA (and other) private keys is not well documented:
+it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
+PKCS#8 private key format complies with this standard.
+
+=head1 BUGS
+
+There should be an option that prints out the encryption algorithm
+in use and other details such as the iteration count.
+
+=head1 SEE ALSO
+
+L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
+L<gendsa(1)>
+
+=head1 HISTORY
+
+The B<-iter> option was added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+pkey - public or private key processing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkey>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-traditional>]
+[B<-cipher>]
+[B<-text>]
+[B<-text_pub>]
+[B<-noout>]
+[B<-pubin>]
+[B<-pubout>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<pkey> command processes public or private keys. They can be converted
+between various forms and their components printed out.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format DER or PEM.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output if this
+option is not specified. If any encryption options are set then a pass phrase
+will be prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout password>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-traditional>
+
+normally a private key is written using standard format: this is PKCS#8 form
+with the appropriate encryption algorithm (if any). If the B<-traditional>
+option is specified then the older "traditional" format is used instead.
+
+=item B<-cipher>
+
+These options encrypt the private key with the supplied cipher. Any algorithm
+name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
+
+=item B<-text>
+
+prints out the various public or private key components in
+plain text in addition to the encoded version.
+
+=item B<-text_pub>
+
+print out only public key components even if a private key is being processed.
+
+=item B<-noout>
+
+do not output the encoded version of the key.
+
+=item B<-pubin>
+
+by default a private key is read from the input file: with this
+option a public key is read instead.
+
+=item B<-pubout>
+
+by default a private key is output: with this option a public
+key will be output instead. This option is automatically set if
+the input is a public key.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<pkey>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 EXAMPLES
+
+To remove the pass phrase on an RSA private key:
+
+ openssl pkey -in key.pem -out keyout.pem
+
+To encrypt a private key using triple DES:
+
+ openssl pkey -in key.pem -des3 -out keyout.pem
+
+To convert a private key from PEM to DER format:
+
+ openssl pkey -in key.pem -outform DER -out keyout.der
+
+To print out the components of a private key to standard output:
+
+ openssl pkey -in key.pem -text -noout
+
+To print out the public components of a private key to standard output:
+
+ openssl pkey -in key.pem -text_pub -noout
+
+To just output the public part of a private key:
+
+ openssl pkey -in key.pem -pubout -out pubkey.pem
+
+=head1 SEE ALSO
+
+L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
+L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+pkeyparam - public key algorithm parameter processing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkeyparam>
+[B<-help>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-text>]
+[B<-noout>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<pkey> command processes public or private keys. They can be converted
+between various forms and their components printed out.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-in filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified.
+
+=item B<-out filename>
+
+This specifies the output filename to write parameters to or standard output if
+this option is not specified.
+
+=item B<-text>
+
+prints out the parameters in plain text in addition to the encoded version.
+
+=item B<-noout>
+
+do not output the encoded version of the parameters.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<pkeyparam>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 EXAMPLE
+
+Print out text version of parameters:
+
+ openssl pkeyparam -in param.pem -text
+
+=head1 NOTES
+
+There are no B<-inform> or B<-outform> options for this command because only
+PEM format is supported because the key type is determined by the PEM headers.
+
+=head1 SEE ALSO
+
+L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
+L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+pkeyutl - public key algorithm utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkeyutl>
+[B<-help>]
+[B<-in file>]
+[B<-out file>]
+[B<-sigfile file>]
+[B<-inkey file>]
+[B<-keyform PEM|DER|ENGINE>]
+[B<-passin arg>]
+[B<-peerkey file>]
+[B<-peerform PEM|DER|ENGINE>]
+[B<-pubin>]
+[B<-certin>]
+[B<-rev>]
+[B<-sign>]
+[B<-verify>]
+[B<-verifyrecover>]
+[B<-encrypt>]
+[B<-decrypt>]
+[B<-derive>]
+[B<-kdf algorithm>]
+[B<-kdflen length>]
+[B<-pkeyopt opt:value>]
+[B<-hexdump>]
+[B<-asn1parse>]
+[B<-engine id>]
+[B<-engine_impl>]
+
+=head1 DESCRIPTION
+
+The B<pkeyutl> command can be used to perform public key operations using
+any supported algorithm.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-in filename>
+
+This specifies the input filename to read data from or standard input
+if this option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-sigfile file>
+
+Signature file, required for B<verify> operations only
+
+=item B<-inkey file>
+
+the input key file, by default it should be a private key.
+
+=item B<-keyform PEM|DER|ENGINE>
+
+the key format PEM, DER or ENGINE. Default is PEM.
+
+=item B<-passin arg>
+
+the input key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+
+=item B<-peerkey file>
+
+the peer key file, used by key derivation (agreement) operations.
+
+=item B<-peerform PEM|DER|ENGINE>
+
+the peer key format PEM, DER or ENGINE. Default is PEM.
+
+=item B<-pubin>
+
+the input file is a public key.
+
+=item B<-certin>
+
+the input is a certificate containing a public key.
+
+=item B<-rev>
+
+reverse the order of the input buffer. This is useful for some libraries
+(such as CryptoAPI) which represent the buffer in little endian format.
+
+=item B<-sign>
+
+sign the input data and output the signed result. This requires
+a private key.
+
+=item B<-verify>
+
+verify the input data against the signature file and indicate if the
+verification succeeded or failed.
+
+=item B<-verifyrecover>
+
+verify the input data and output the recovered data.
+
+=item B<-encrypt>
+
+encrypt the input data using a public key.
+
+=item B<-decrypt>
+
+decrypt the input data using a private key.
+
+=item B<-derive>
+
+derive a shared secret using the peer key.
+
+=item B<-kdf algorithm>
+
+Use key derivation function B<algorithm>. The supported algorithms are
+at present B<TLS1-PRF> and B<HKDF>.
+Note: additional parameters and the KDF output length will normally have to be
+set for this to work. See L<EVP_PKEY_HKDF(3)> and L<EVP_PKEY_TLS1_PRF(3)>
+for the supported string parameters of each algorithm.
+
+=item B<-kdflen length>
+
+Set the output length for KDF.
+
+=item B<-pkeyopt opt:value>
+
+Public key options specified as opt:value. See NOTES below for more details.
+
+=item B<-hexdump>
+
+hex dump the output data.
+
+=item B<-asn1parse>
+
+asn1parse the output data, this is useful when combined with the
+B<-verifyrecover> option when an ASN1 structure is signed.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-engine_impl>
+
+When used with the B<-engine> option, it specifies to also use
+engine B<id> for crypto operations.
+
+=back
+
+=head1 NOTES
+
+The operations and options supported vary according to the key algorithm
+and its implementation. The OpenSSL operations and options are indicated below.
+
+Unless otherwise mentioned all algorithms support the B<digest:alg> option
+which specifies the digest in use for sign, verify and verifyrecover operations.
+The value B<alg> should represent a digest name as used in the
+EVP_get_digestbyname() function for example B<sha1>.
+This value is used only for sanity-checking the lengths of data passed in to
+the B<pkeyutl> and for creating the structures that make up the signature
+(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
+In case of RSA, ECDSA and DSA signatures, this utility
+will not perform hashing on input data but rather use the data directly as
+input of signature algorithm. Depending on key type, signature type and mode
+of padding, the maximum acceptable lengths of input data differ. In general,
+with RSA the signed data can't be longer than the key modulus, in case of ECDSA
+and DSA the data shouldn't be longer than field size, otherwise it will be
+silently truncated to field size.
+
+In other words, if the value of digest is B<sha1> the input should be 20 bytes
+long binary encoding of SHA-1 hash function output.
+
+=head1 RSA ALGORITHM
+
+The RSA algorithm generally supports the encrypt, decrypt, sign,
+verify and verifyrecover operations. However, some padding modes
+support only a subset of these operations. The following additional
+B<pkeyopt> values are supported:
+
+=over 4
+
+=item B<rsa_padding_mode:mode>
+
+This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for
+PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep>
+for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
+
+In PKCS#1 padding if the message digest is not set then the supplied data is
+signed or verified directly instead of using a B<DigestInfo> structure. If a
+digest is set then the a B<DigestInfo> structure is used and its the length
+must correspond to the digest type.
+
+For B<oaep> mode only encryption and decryption is supported.
+
+For B<x931> if the digest type is set it is used to format the block data
+otherwise the first byte is used to specify the X9.31 digest ID. Sign,
+verify and verifyrecover are can be performed in this mode.
+
+For B<pss> mode only sign and verify are supported and the digest type must be
+specified.
+
+=item B<rsa_pss_saltlen:len>
+
+For B<pss> mode only this option specifies the salt length. Two special values
+are supported: -1 sets the salt length to the digest length. When signing -2
+sets the salt length to the maximum permissible value. When verifying -2 causes
+the salt length to be automatically determined based on the B<PSS> block
+structure.
+
+=back
+
+=head1 DSA ALGORITHM
+
+The DSA algorithm supports signing and verification operations only. Currently
+there are no additional options other than B<digest>. Only the SHA1
+digest can be used and this digest is assumed by default.
+
+=head1 DH ALGORITHM
+
+The DH algorithm only supports the derivation operation and no additional
+options.
+
+=head1 EC ALGORITHM
+
+The EC algorithm supports sign, verify and derive operations. The sign and
+verify operations use ECDSA and derive uses ECDH. Currently there are no
+additional options other than B<digest>. Only the SHA1 digest can be used and
+this digest is assumed by default.
+
+=head1 X25519 ALGORITHM
+
+The X25519 algorithm supports key derivation only. Currently there are no
+additional options.
+
+=head1 EXAMPLES
+
+Sign some data using a private key:
+
+ openssl pkeyutl -sign -in file -inkey key.pem -out sig
+
+Recover the signed data (e.g. if an RSA key is used):
+
+ openssl pkeyutl -verifyrecover -in sig -inkey key.pem
+
+Verify the signature (e.g. a DSA key):
+
+ openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
+
+Sign data using a message digest value (this is currently only valid for RSA):
+
+ openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
+
+Derive a shared secret value:
+
+ openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
+
+Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and
+seed consisting of the single byte 0xFF:
+
+ openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
+ -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
+
+=head1 SEE ALSO
+
+L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
+L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
+L<EVP_PKEY_HKDF(3)>, L<EVP_PKEY_TLS1_PRF(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+rand - generate pseudo-random bytes
+
+=head1 SYNOPSIS
+
+B<openssl rand>
+[B<-help>]
+[B<-out> I<file>]
+[B<-rand> I<file(s)>]
+[B<-base64>]
+[B<-hex>]
+I<num>
+
+=head1 DESCRIPTION
+
+The B<rand> command outputs I<num> pseudo-random bytes after seeding
+the random number generator once. As in other B<openssl> command
+line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd>
+in addition to the files given in the B<-rand> option. A new
+I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough
+seeding was obtained from these sources.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-out> I<file>
+
+Write to I<file> instead of standard output.
+
+=item B<-rand> I<file(s)>
+
+Use specified file or files or EGD socket (see L<RAND_egd(3)>)
+for seeding the random number generator.
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-base64>
+
+Perform base64 encoding on the output.
+
+=item B<-hex>
+
+Show the output as a hex string.
+
+=back
+
+=head1 SEE ALSO
+
+L<RAND_bytes(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=for comment
+Original text by James Westby, contributed under the OpenSSL license.
+
+=head1 NAME
+
+c_rehash, rehash - Create symbolic links to files named by the hash values
+
+=head1 SYNOPSIS
+
+B<openssl>
+B<rehash>
+B<[-h]>
+B<[-help]>
+B<[-old]>
+B<[-n]>
+B<[-v]>
+[ I<directory>...]
+
+B<c_rehash>
+I<flags...>
+
+=head1 DESCRIPTION
+
+On some platforms, the OpenSSL B<rehash> command is available as
+an external script called B<c_rehash>. They are functionally equivalent,
+except for minor differences noted below.
+
+B<rehash> scans directories and calculates a hash value of each
+C<.pem>, C<.crt>, C<.cer>, or C<.crl>
+file in the specified directory list and creates symbolic links
+for each file, where the name of the link is the hash value.
+(If the platform does not support symbolic links, a copy is made.)
+This utility is useful as many programs that use OpenSSL require
+directories to be set up like this in order to find certificates.
+
+If any directories are named on the command line, then those are
+processed in turn. If not, then the B<SSL_CERT_DIR> environment variable
+is consulted; this should be a colon-separated list of directories,
+like the Unix B<PATH> variable.
+If that is not set then the default directory (installation-specific
+but often B</usr/local/ssl/certs>) is processed.
+
+In order for a directory to be processed, the user must have write
+permissions on that directory, otherwise an error will be generated.
+
+The links created are of the form C<HHHHHHHH.D>, where each B<H>
+is a hexadecimal character and B<D> is a single decimal digit.
+When processing a directory, B<rehash> will first remove all links
+that have a name in that syntax, even if they are being used for some
+other purpose.
+To skip the removal step, use the B<-n> flag.
+Hashes for CRL's look similar except the letter B<r> appears after
+the period, like this: C<HHHHHHHH.rD>.
+
+Multiple objects may have the same hash; they will be indicated by
+incrementing the B<D> value. Duplicates are found by comparing the
+full SHA-1 fingerprint. A warning will be displayed if a duplicate
+is found.
+
+A warning will also be displayed if there are files that
+cannot be parsed as either a certificate or a CRL or if
+more than one such object appears in the file.
+
+=head2 Script Configuration
+
+The B<c_rehash> script
+uses the B<openssl> program to compute the hashes and
+fingerprints. If not found in the user's B<PATH>, then set the
+B<OPENSSL> environment variable to the full pathname.
+Any program can be used, it will be invoked as follows for either
+a certificate or CRL:
+
+ $OPENSSL x509 -hash -fingerprint -noout -in FILENAME
+ $OPENSSL crl -hash -fingerprint -noout -in FILENAME
+
+where B<FILENAME> is the filename. It must output the hash of the
+file on the first line, and the fingerprint on the second,
+optionally prefixed with some text and an equals sign.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help> B<-h>
+
+Display a brief usage message.
+
+=item B<-old>
+
+Use old-style hashing (MD5, as opposed to SHA-1) for generating
+links to be used for releases before 1.0.0.
+Note that current versions will not use the old style.
+
+=item B<-n>
+
+Do not remove existing links.
+This is needed when keeping new and old-style links in the same directory.
+
+=item B<-v>
+
+Print messages about old links removed and new links created.
+By default, B<rehash> only lists each directory as it is processed.
+
+=back
+
+=head1 ENVIRONMENT
+
+=over
+
+=item B<OPENSSL>
+
+The path to an executable to use to generate hashes and
+fingerprints (see above).
+
+=item B<SSL_CERT_DIR>
+
+Colon separated list of directories to operate on.
+Ignored if directories are listed on the command line.
+
+=back
+
+=head1 SEE ALSO
+
+L<openssl(1)>,
+L<crl(1)>.
+L<x509(1)>.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+req - PKCS#10 certificate request and certificate generating utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<req>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-text>]
+[B<-pubkey>]
+[B<-noout>]
+[B<-verify>]
+[B<-modulus>]
+[B<-new>]
+[B<-rand file(s)>]
+[B<-newkey rsa:bits>]
+[B<-newkey alg:file>]
+[B<-nodes>]
+[B<-key filename>]
+[B<-keyform PEM|DER>]
+[B<-keyout filename>]
+[B<-keygen_engine id>]
+[B<-[digest]>]
+[B<-config filename>]
+[B<-multivalue-rdn>]
+[B<-x509>]
+[B<-days n>]
+[B<-set_serial n>]
+[B<-newhdr>]
+[B<-extensions section>]
+[B<-reqexts section>]
+[B<-utf8>]
+[B<-nameopt>]
+[B<-reqopt>]
+[B<-subject>]
+[B<-subj arg>]
+[B<-batch>]
+[B<-verbose>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<req> command primarily creates and processes certificate requests
+in PKCS#10 format. It can additionally create self signed certificates
+for use as root CAs for example.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#10. The B<PEM> form is the default format: it
+consists of the B<DER> format base64 encoded with additional header and
+footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a request from or standard input
+if this option is not specified. A request is only read if the creation
+options (B<-new> and B<-newkey>) are not specified.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write to or standard output by
+default.
+
+=item B<-passout arg>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-text>
+
+prints out the certificate request in text form.
+
+=item B<-subject>
+
+prints out the request subject (or certificate subject if B<-x509> is
+specified)
+
+=item B<-pubkey>
+
+outputs the public key.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the request.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the public key
+contained in the request.
+
+=item B<-verify>
+
+verifies the signature on the request.
+
+=item B<-new>
+
+this option generates a new certificate request. It will prompt
+the user for the relevant field values. The actual fields
+prompted for and their maximum and minimum sizes are specified
+in the configuration file and any requested extensions.
+
+If the B<-key> option is not used it will generate a new RSA private
+key using information specified in the configuration file.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-newkey arg>
+
+this option creates a new certificate request and a new private
+key. The argument takes one of several forms. B<rsa:nbits>, where
+B<nbits> is the number of bits, generates an RSA key B<nbits>
+in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified,
+the default key size, specified in the configuration file is used.
+
+All other algorithms support the B<-newkey alg:file> form, where file may be
+an algorithm parameter file, created by the B<genpkey -genparam> command
+or and X.509 certificate for a key with appropriate algorithm.
+
+B<param:file> generates a key using the parameter file or certificate B<file>,
+the algorithm is determined by the parameters. B<algname:file> use algorithm
+B<algname> and parameter file B<file>: the two algorithms must match or an
+error occurs. B<algname> just uses algorithm B<algname>, and parameters,
+if necessary should be specified via B<-pkeyopt> parameter.
+
+B<dsa:filename> generates a DSA key using the parameters
+in the file B<filename>. B<ec:filename> generates EC key (usable both with
+ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R
+34.10-2001 key (requires B<ccgost> engine configured in the configuration
+file). If just B<gost2001> is specified a parameter set should be
+specified by B<-pkeyopt paramset:X>
+
+
+=item B<-pkeyopt opt:value>
+
+set the public key algorithm option B<opt> to B<value>. The precise set of
+options supported depends on the public key algorithm used and its
+implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page
+for more details.
+
+=item B<-key filename>
+
+This specifies the file to read the private key from. It also
+accepts PKCS#8 format private keys for PEM format files.
+
+=item B<-keyform PEM|DER>
+
+the format of the private key file specified in the B<-key>
+argument. PEM is the default.
+
+=item B<-keyout filename>
+
+this gives the filename to write the newly created private key to.
+If this option is not specified then the filename present in the
+configuration file is used.
+
+=item B<-nodes>
+
+if this option is specified then if a private key is created it
+will not be encrypted.
+
+=item B<-[digest]>
+
+this specifies the message digest to sign the request.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+This overrides the digest algorithm specified in
+the configuration file.
+
+Some public key algorithms may override this choice. For instance, DSA
+signatures always use SHA1, GOST R 34.10 signatures always use
+GOST R 34.11-94 (B<-md_gost94>).
+
+=item B<-config filename>
+
+this allows an alternative configuration file to be specified,
+this overrides the compile time filename or any specified in
+the B<OPENSSL_CONF> environment variable.
+
+=item B<-subj arg>
+
+sets subject name for new request or supersedes the subject name
+when processing a request.
+The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
+characters may be escaped by \ (backslash), no spaces are skipped.
+
+=item B<-multivalue-rdn>
+
+this option causes the -subj argument to be interpreted with full
+support for multivalued RDNs. Example:
+
+I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
+
+If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
+
+=item B<-x509>
+
+this option outputs a self signed certificate instead of a certificate
+request. This is typically used to generate a test certificate or
+a self signed root CA. The extensions added to the certificate
+(if any) are specified in the configuration file. Unless specified
+using the B<set_serial> option, a large random number will be used for
+the serial number.
+
+=item B<-days n>
+
+when the B<-x509> option is being used this specifies the number of
+days to certify the certificate for. The default is 30 days.
+
+=item B<-set_serial n>
+
+serial number to use when outputting a self signed certificate. This
+may be specified as a decimal value or a hex value if preceded by B<0x>.
+It is possible to use negative serial numbers but this is not recommended.
+
+=item B<-extensions section>
+
+=item B<-reqexts section>
+
+these options specify alternative sections to include certificate
+extensions (if the B<-x509> option is present) or certificate
+request extensions. This allows several different sections to
+be used in the same configuration file to specify requests for
+a variety of purposes.
+
+=item B<-utf8>
+
+this option causes field values to be interpreted as UTF8 strings, by
+default they are interpreted as ASCII. This means that the field
+values, whether prompted from a terminal or obtained from a
+configuration file, must be valid UTF8 strings.
+
+=item B<-nameopt option>
+
+option which determines how the subject or issuer names are displayed. The
+B<option> argument can be a single option or multiple options separated by
+commas. Alternatively the B<-nameopt> switch may be used more than once to
+set multiple options. See the L<x509(1)> manual page for details.
+
+=item B<-reqopt>
+
+customise the output format used with B<-text>. The B<option> argument can be
+a single option or multiple options separated by commas.
+
+See discussion of the B<-certopt> parameter in the L<x509(1)>
+command.
+
+=item B<-newhdr>
+
+Adds the word B<NEW> to the PEM file header and footer lines on the outputted
+request. Some software (Netscape certificate server) and some CAs need this.
+
+=item B<-batch>
+
+non-interactive mode.
+
+=item B<-verbose>
+
+print extra details about the operations being performed.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<req>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-keygen_engine id>
+
+specifies an engine (by its unique B<id> string) which would be used
+for key generation operations.
+
+=back
+
+=head1 CONFIGURATION FILE FORMAT
+
+The configuration options are specified in the B<req> section of
+the configuration file. As with all configuration files if no
+value is specified in the specific section (i.e. B<req>) then
+the initial unnamed or B<default> section is searched too.
+
+The options available are described in detail below.
+
+=over 4
+
+=item B<input_password output_password>
+
+The passwords for the input private key file (if present) and
+the output private key file (if one will be created). The
+command line options B<passin> and B<passout> override the
+configuration file values.
+
+=item B<default_bits>
+
+Specifies the default key size in bits.
+
+This option is used in conjunction with the B<-new> option to generate
+a new key. It can be overridden by specifying an explicit key size in
+the B<-newkey> option. The smallest accepted key size is 512 bits. If
+no key size is specified then 2048 bits is used.
+
+=item B<default_keyfile>
+
+This is the default filename to write a private key to. If not
+specified the key is written to standard output. This can be
+overridden by the B<-keyout> option.
+
+=item B<oid_file>
+
+This specifies a file containing additional B<OBJECT IDENTIFIERS>.
+Each line of the file should consist of the numerical form of the
+object identifier followed by white space then the short name followed
+by white space and finally the long name.
+
+=item B<oid_section>
+
+This specifies a section in the configuration file containing extra
+object identifiers. Each line should consist of the short name of the
+object identifier followed by B<=> and the numerical form. The short
+and long names are the same when this option is used.
+
+=item B<RANDFILE>
+
+This specifies a filename in which random number seed information is
+placed and read from, or an EGD socket (see L<RAND_egd(3)>).
+It is used for private key generation.
+
+=item B<encrypt_key>
+
+If this is set to B<no> then if a private key is generated it is
+B<not> encrypted. This is equivalent to the B<-nodes> command line
+option. For compatibility B<encrypt_rsa_key> is an equivalent option.
+
+=item B<default_md>
+
+This option specifies the digest algorithm to use.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+If not present then MD5 is used.
+This option can be overridden on the command line.
+
+=item B<string_mask>
+
+This option masks out the use of certain string types in certain
+fields. Most users will not need to change this option.
+
+It can be set to several values B<default> which is also the default
+option uses PrintableStrings, T61Strings and BMPStrings if the
+B<pkix> value is used then only PrintableStrings and BMPStrings will
+be used. This follows the PKIX recommendation in RFC2459. If the
+B<utf8only> option is used then only UTF8Strings will be used: this
+is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
+option just uses PrintableStrings and T61Strings: certain software has
+problems with BMPStrings and UTF8Strings: in particular Netscape.
+
+=item B<req_extensions>
+
+this specifies the configuration file section containing a list of
+extensions to add to the certificate request. It can be overridden
+by the B<-reqexts> command line switch. See the
+L<x509v3_config(5)> manual page for details of the
+extension section format.
+
+=item B<x509_extensions>
+
+this specifies the configuration file section containing a list of
+extensions to add to certificate generated when the B<-x509> switch
+is used. It can be overridden by the B<-extensions> command line switch.
+
+=item B<prompt>
+
+if set to the value B<no> this disables prompting of certificate fields
+and just takes values from the config file directly. It also changes the
+expected format of the B<distinguished_name> and B<attributes> sections.
+
+=item B<utf8>
+
+if set to the value B<yes> then field values to be interpreted as UTF8
+strings, by default they are interpreted as ASCII. This means that
+the field values, whether prompted from a terminal or obtained from a
+configuration file, must be valid UTF8 strings.
+
+=item B<attributes>
+
+this specifies the section containing any request attributes: its format
+is the same as B<distinguished_name>. Typically these may contain the
+challengePassword or unstructuredName types. They are currently ignored
+by OpenSSL's request signing utilities but some CAs might want them.
+
+=item B<distinguished_name>
+
+This specifies the section containing the distinguished name fields to
+prompt for when generating a certificate or certificate request. The format
+is described in the next section.
+
+=back
+
+=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
+
+There are two separate formats for the distinguished name and attribute
+sections. If the B<prompt> option is set to B<no> then these sections
+just consist of field names and values: for example,
+
+ CN=My Name
+ OU=My Organization
+ emailAddress=someone@somewhere.org
+
+This allows external programs (e.g. GUI based) to generate a template file
+with all the field names and values and just pass it to B<req>. An example
+of this kind of configuration file is contained in the B<EXAMPLES> section.
+
+Alternatively if the B<prompt> option is absent or not set to B<no> then the
+file contains field prompting information. It consists of lines of the form:
+
+ fieldName="prompt"
+ fieldName_default="default field value"
+ fieldName_min= 2
+ fieldName_max= 4
+
+"fieldName" is the field name being used, for example commonName (or CN).
+The "prompt" string is used to ask the user to enter the relevant
+details. If the user enters nothing then the default value is used if no
+default value is present then the field is omitted. A field can
+still be omitted if a default value is present if the user just
+enters the '.' character.
+
+The number of characters entered must be between the fieldName_min and
+fieldName_max limits: there may be additional restrictions based
+on the field being used (for example countryName can only ever be
+two characters long and must fit in a PrintableString).
+
+Some fields (such as organizationName) can be used more than once
+in a DN. This presents a problem because configuration files will
+not recognize the same name occurring twice. To avoid this problem
+if the fieldName contains some characters followed by a full stop
+they will be ignored. So for example a second organizationName can
+be input by calling it "1.organizationName".
+
+The actual permitted field names are any object identifier short or
+long names. These are compiled into OpenSSL and include the usual
+values such as commonName, countryName, localityName, organizationName,
+organizationalUnitName, stateOrProvinceName. Additionally emailAddress
+is include as well as name, surname, givenName initials and dnQualifier.
+
+Additional object identifiers can be defined with the B<oid_file> or
+B<oid_section> options in the configuration file. Any additional fields
+will be treated as though they were a DirectoryString.
+
+
+=head1 EXAMPLES
+
+Examine and verify certificate request:
+
+ openssl req -in req.pem -text -verify -noout
+
+Create a private key and then generate a certificate request from it:
+
+ openssl genrsa -out key.pem 2048
+ openssl req -new -key key.pem -out req.pem
+
+The same but just using req:
+
+ openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
+
+Generate a self signed root certificate:
+
+ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
+
+Example of a file pointed to by the B<oid_file> option:
+
+ 1.2.3.4 shortName A longer Name
+ 1.2.3.6 otherName Other longer Name
+
+Example of a section pointed to by B<oid_section> making use of variable
+expansion:
+
+ testoid1=1.2.3.5
+ testoid2=${testoid1}.6
+
+Sample configuration file prompting for field values:
+
+ [ req ]
+ default_bits = 2048
+ default_keyfile = privkey.pem
+ distinguished_name = req_distinguished_name
+ attributes = req_attributes
+ req_extensions = v3_ca
+
+ dirstring_type = nobmp
+
+ [ req_distinguished_name ]
+ countryName = Country Name (2 letter code)
+ countryName_default = AU
+ countryName_min = 2
+ countryName_max = 2
+
+ localityName = Locality Name (eg, city)
+
+ organizationalUnitName = Organizational Unit Name (eg, section)
+
+ commonName = Common Name (eg, YOUR name)
+ commonName_max = 64
+
+ emailAddress = Email Address
+ emailAddress_max = 40
+
+ [ req_attributes ]
+ challengePassword = A challenge password
+ challengePassword_min = 4
+ challengePassword_max = 20
+
+ [ v3_ca ]
+
+ subjectKeyIdentifier=hash
+ authorityKeyIdentifier=keyid:always,issuer:always
+ basicConstraints = critical, CA:true
+
+Sample configuration containing all field values:
+
+
+ RANDFILE = $ENV::HOME/.rnd
+
+ [ req ]
+ default_bits = 2048
+ default_keyfile = keyfile.pem
+ distinguished_name = req_distinguished_name
+ attributes = req_attributes
+ prompt = no
+ output_password = mypass
+
+ [ req_distinguished_name ]
+ C = GB
+ ST = Test State or Province
+ L = Test Locality
+ O = Organization Name
+ OU = Organizational Unit Name
+ CN = Common Name
+ emailAddress = test@email.address
+
+ [ req_attributes ]
+ challengePassword = A challenge password
+
+
+=head1 NOTES
+
+The header and footer lines in the B<PEM> format are normally:
+
+ -----BEGIN CERTIFICATE REQUEST-----
+ -----END CERTIFICATE REQUEST-----
+
+some software (some versions of Netscape certificate server) instead needs:
+
+ -----BEGIN NEW CERTIFICATE REQUEST-----
+ -----END NEW CERTIFICATE REQUEST-----
+
+which is produced with the B<-newhdr> option but is otherwise compatible.
+Either form is accepted transparently on input.
+
+The certificate requests generated by B<Xenroll> with MSIE have extensions
+added. It includes the B<keyUsage> extension which determines the type of
+key (signature only or general purpose) and any additional OIDs entered
+by the script in an extendedKeyUsage extension.
+
+=head1 DIAGNOSTICS
+
+The following messages are frequently asked about:
+
+ Using configuration from /some/path/openssl.cnf
+ Unable to load config info
+
+This is followed some time later by...
+
+ unable to find 'distinguished_name' in config
+ problems making Certificate Request
+
+The first error message is the clue: it can't find the configuration
+file! Certain operations (like examining a certificate request) don't
+need a configuration file so its use isn't enforced. Generation of
+certificates or requests however does need a configuration file. This
+could be regarded as a bug.
+
+Another puzzling message is this:
+
+ Attributes:
+ a0:00
+
+this is displayed when no attributes are present and the request includes
+the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
+0x00). If you just see:
+
+ Attributes:
+
+then the B<SET OF> is missing and the encoding is technically invalid (but
+it is tolerated). See the description of the command line option B<-asn1-kludge>
+for more information.
+
+=head1 ENVIRONMENT VARIABLES
+
+The variable B<OPENSSL_CONF> if defined allows an alternative configuration
+file location to be specified, it will be overridden by the B<-config> command
+line switch if it is present.
+
+=head1 BUGS
+
+OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
+treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
+This can cause problems if you need characters that aren't available in
+PrintableStrings and you don't want to or can't use BMPStrings.
+
+As a consequence of the T61String handling the only correct way to represent
+accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
+currently chokes on these. If you have to use accented characters with Netscape
+and MSIE then you currently need to use the invalid T61String form.
+
+The current prompting is not very friendly. It doesn't allow you to confirm what
+you've just entered. Other things like extensions in certificate requests are
+statically defined in the configuration file. Some of these: like an email
+address in subjectAltName should be input by the user.
+
+=head1 SEE ALSO
+
+L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
+L<gendsa(1)>, L<config(5)>,
+L<x509v3_config(5)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+rsa - RSA key processing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<rsa>
+[B<-help>]
+[B<-inform PEM|NET|DER>]
+[B<-outform PEM|NET|DER>]
+[B<-in filename>]
+[B<-passin arg>]
+[B<-out filename>]
+[B<-passout arg>]
+[B<-aes128>]
+[B<-aes192>]
+[B<-aes256>]
+[B<-camellia128>]
+[B<-camellia192>]
+[B<-camellia256>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-modulus>]
+[B<-check>]
+[B<-pubin>]
+[B<-pubout>]
+[B<-RSAPublicKey_in>]
+[B<-RSAPublicKey_out>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<rsa> command processes RSA keys. They can be converted between various
+forms and their components printed out. B<Note> this command uses the
+traditional SSLeay compatible format for private key encryption: newer
+applications should use the more secure PKCS#8 format using the B<pkcs8>
+utility.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|NET|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format.
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. On input PKCS#8 format private
+keys are also accepted. The B<NET> form is a format is described in the B<NOTES>
+section.
+
+=item B<-outform DER|NET|PEM>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin arg>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output if this
+option is not specified. If any encryption options are set then a pass phrase
+will be prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout password>
+
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
+
+These options encrypt the private key with the specified
+cipher before outputting it. A pass phrase is prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<rsa> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the various public or private key components in
+plain text in addition to the encoded version.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the key.
+
+=item B<-check>
+
+this option checks the consistency of an RSA private key.
+
+=item B<-pubin>
+
+by default a private key is read from the input file: with this
+option a public key is read instead.
+
+=item B<-pubout>
+
+by default a private key is output: with this option a public
+key will be output instead. This option is automatically set if
+the input is a public key.
+
+=item B<-RSAPublicKey_in>, B<-RSAPublicKey_out>
+
+like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<rsa>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN RSA PRIVATE KEY-----
+ -----END RSA PRIVATE KEY-----
+
+The PEM public key format uses the header and footer lines:
+
+ -----BEGIN PUBLIC KEY-----
+ -----END PUBLIC KEY-----
+
+The PEM B<RSAPublicKey> format uses the header and footer lines:
+
+ -----BEGIN RSA PUBLIC KEY-----
+ -----END RSA PUBLIC KEY-----
+
+The B<NET> form is a format compatible with older Netscape servers
+and Microsoft IIS .key files, this uses unsalted RC4 for its encryption.
+It is not very secure and so should only be used when necessary.
+
+Some newer version of IIS have additional data in the exported .key
+files. To use these with the utility, view the file with a binary editor
+and look for the string "private-key", then trace back to the byte
+sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data
+from this point onwards to another file and use that as the input
+to the B<rsa> utility with the B<-inform NET> option.
+
+=head1 EXAMPLES
+
+To remove the pass phrase on an RSA private key:
+
+ openssl rsa -in key.pem -out keyout.pem
+
+To encrypt a private key using triple DES:
+
+ openssl rsa -in key.pem -des3 -out keyout.pem
+
+To convert a private key from PEM to DER format:
+
+ openssl rsa -in key.pem -outform DER -out keyout.der
+
+To print out the components of a private key to standard output:
+
+ openssl rsa -in key.pem -text -noout
+
+To just output the public part of a private key:
+
+ openssl rsa -in key.pem -pubout -out pubkey.pem
+
+Output the public part of a private key in B<RSAPublicKey> format:
+
+ openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem
+
+=head1 BUGS
+
+The command line password arguments don't currently work with
+B<NET> format.
+
+There should be an option that automatically handles .key files,
+without having to manually edit them.
+
+=head1 SEE ALSO
+
+L<pkcs8(1)>, L<dsa(1)>, L<genrsa(1)>,
+L<gendsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+rsautl - RSA utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<rsautl>
+[B<-help>]
+[B<-in file>]
+[B<-out file>]
+[B<-inkey file>]
+[B<-keyform PEM|DER|ENGINE>]
+[B<-pubin>]
+[B<-certin>]
+[B<-sign>]
+[B<-verify>]
+[B<-encrypt>]
+[B<-decrypt>]
+[B<-pkcs>]
+[B<-ssl>]
+[B<-raw>]
+[B<-hexdump>]
+[B<-asn1parse>]
+
+=head1 DESCRIPTION
+
+The B<rsautl> command can be used to sign, verify, encrypt and decrypt
+data using the RSA algorithm.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-in filename>
+
+This specifies the input filename to read data from or standard input
+if this option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-inkey file>
+
+the input key file, by default it should be an RSA private key.
+
+=item B<-keyform PEM|DER|ENGINE>
+
+the key format PEM, DER or ENGINE.
+
+=item B<-pubin>
+
+the input file is an RSA public key.
+
+=item B<-certin>
+
+the input is a certificate containing an RSA public key.
+
+=item B<-sign>
+
+sign the input data and output the signed result. This requires
+an RSA private key.
+
+=item B<-verify>
+
+verify the input data and output the recovered data.
+
+=item B<-encrypt>
+
+encrypt the input data using an RSA public key.
+
+=item B<-decrypt>
+
+decrypt the input data using an RSA private key.
+
+=item B<-pkcs, -oaep, -ssl, -raw>
+
+the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
+special padding used in SSL v2 backwards compatible handshakes,
+or no padding, respectively.
+For signatures, only B<-pkcs> and B<-raw> can be used.
+
+=item B<-hexdump>
+
+hex dump the output data.
+
+=item B<-asn1parse>
+
+asn1parse the output data, this is useful when combined with the
+B<-verify> option.
+
+=back
+
+=head1 NOTES
+
+B<rsautl> because it uses the RSA algorithm directly can only be
+used to sign or verify small pieces of data.
+
+=head1 EXAMPLES
+
+Sign some data using a private key:
+
+ openssl rsautl -sign -in file -inkey key.pem -out sig
+
+Recover the signed data
+
+ openssl rsautl -verify -in sig -inkey key.pem
+
+Examine the raw signed data:
+
+ openssl rsautl -verify -in file -inkey key.pem -raw -hexdump
+
+ 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
+ 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world
+
+The PKCS#1 block formatting is evident from this. If this was done using
+encrypt and decrypt the block would have been of type 2 (the second byte)
+and random padding data visible instead of the 0xff bytes.
+
+It is possible to analyse the signature of certificates using this
+utility in conjunction with B<asn1parse>. Consider the self signed
+example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
+
+ openssl asn1parse -in pca-cert.pem
+
+ 0:d=0 hl=4 l= 742 cons: SEQUENCE
+ 4:d=1 hl=4 l= 591 cons: SEQUENCE
+ 8:d=2 hl=2 l= 3 cons: cont [ 0 ]
+ 10:d=3 hl=2 l= 1 prim: INTEGER :02
+ 13:d=2 hl=2 l= 1 prim: INTEGER :00
+ 16:d=2 hl=2 l= 13 cons: SEQUENCE
+ 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
+ 29:d=3 hl=2 l= 0 prim: NULL
+ 31:d=2 hl=2 l= 92 cons: SEQUENCE
+ 33:d=3 hl=2 l= 11 cons: SET
+ 35:d=4 hl=2 l= 9 cons: SEQUENCE
+ 37:d=5 hl=2 l= 3 prim: OBJECT :countryName
+ 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU
+ ....
+ 599:d=1 hl=2 l= 13 cons: SEQUENCE
+ 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
+ 612:d=2 hl=2 l= 0 prim: NULL
+ 614:d=1 hl=3 l= 129 prim: BIT STRING
+
+
+The final BIT STRING contains the actual signature. It can be extracted with:
+
+ openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
+
+The certificate public key can be extracted with:
+
+ openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
+
+The signature can be analysed with:
+
+ openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
+
+ 0:d=0 hl=2 l= 32 cons: SEQUENCE
+ 2:d=1 hl=2 l= 12 cons: SEQUENCE
+ 4:d=2 hl=2 l= 8 prim: OBJECT :md5
+ 14:d=2 hl=2 l= 0 prim: NULL
+ 16:d=1 hl=2 l= 16 prim: OCTET STRING
+ 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%..
+
+This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
+the digest used was md5. The actual part of the certificate that was signed can
+be extracted with:
+
+ openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
+
+and its digest computed with:
+
+ openssl md5 -c tbs
+ MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
+
+which it can be seen agrees with the recovered value above.
+
+=head1 SEE ALSO
+
+L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+s_client - SSL/TLS client program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_client>
+[B<-help>]
+[B<-connect host:port>]
+[B<-proxy host:port>]
+[B<-servername name>]
+[B<-verify depth>]
+[B<-verify_return_error>]
+[B<-cert filename>]
+[B<-certform DER|PEM>]
+[B<-key filename>]
+[B<-keyform DER|PEM>]
+[B<-pass arg>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-dane_tlsa_domain domain>]
+[B<-dane_tlsa_rrdata rrdata>]
+[B<-dane_ee_no_namechecks>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-no_check_time>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-use_deltas>]
+[B<-auth_level num>]
+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
+[B<-reconnect>]
+[B<-showcerts>]
+[B<-debug>]
+[B<-msg>]
+[B<-nbio_test>]
+[B<-state>]
+[B<-nbio>]
+[B<-crlf>]
+[B<-ign_eof>]
+[B<-no_ign_eof>]
+[B<-quiet>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<-tls1_1>]
+[B<-tls1_2>]
+[B<-no_ssl3>]
+[B<-no_tls1>]
+[B<-no_tls1_1>]
+[B<-no_tls1_2>]
+[B<-dtls>]
+[B<-dtls1>]
+[B<-dtls1_2>]
+[B<-fallback_scsv>]
+[B<-async>]
+[B<-split_send_frag>]
+[B<-max_pipelines>]
+[B<-read_buf>]
+[B<-bugs>]
+[B<-comp>]
+[B<-no_comp>]
+[B<-cipher cipherlist>]
+[B<-serverpref>]
+[B<-starttls protocol>]
+[B<-xmpphost hostname>]
+[B<-engine id>]
+[B<-tlsextdebug>]
+[B<-no_ticket>]
+[B<-sess_out filename>]
+[B<-sess_in filename>]
+[B<-rand file(s)>]
+[B<-serverinfo types>]
+[B<-status>]
+[B<-alpn protocols>]
+[B<-nextprotoneg protocols>]
+[B<-ct|noct>]
+[B<-ctlogfile>]
+
+=head1 DESCRIPTION
+
+The B<s_client> command implements a generic SSL/TLS client which connects
+to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for
+SSL servers.
+
+=head1 OPTIONS
+
+In addition to the options below the B<s_client> utility also supports the
+common and client only options documented in the
+in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
+manual page.
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-connect host:port>
+
+This specifies the host and optional port to connect to. If not specified
+then an attempt is made to connect to the local host on port 4433.
+
+=item B<-proxy host:port>
+
+When used with the B<-connect> flag, the program uses the host and port
+specified with this flag and issues an HTTP CONNECT command to connect
+to the desired server.
+
+=item B<-servername name>
+
+Set the TLS SNI (Server Name Indication) extension in the ClientHello message.
+
+=item B<-cert certname>
+
+The certificate to use, if one is requested by the server. The default is
+not to use a certificate.
+
+=item B<-certform format>
+
+The certificate format to use: DER or PEM. PEM is the default.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used.
+
+=item B<-keyform format>
+
+The private format to use: DER or PEM. PEM is the default.
+
+=item B<-pass arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+server certificate chain and turns on server certificate verification.
+Currently the verify operation continues after errors so all the problems
+with a certificate chain can be seen. As a side effect the connection
+will never fail due to a server certificate verify failure.
+
+=item B<-verify_return_error>
+
+Return verification errors instead of continuing. This will typically
+abort the handshake with a fatal error.
+
+=item B<-CApath directory>
+
+The directory to use for server certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the client certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during server authentication
+and to use when attempting to build the client certificate chain.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-dane_tlsa_domain domain>
+
+Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
+TLSA base domain which becomes the default SNI hint and the primary
+reference identifier for hostname checks. This must be used in
+combination with at least one instance of the B<-dane_tlsa_rrdata>
+option below.
+
+When DANE authentication succeeds, the diagnostic output will include
+the lowest (closest to 0) depth at which a TLSA record authenticated
+a chain certificate. When that TLSA record is a "2 1 0" trust
+anchor public key that signed (rather than matched) the top-most
+certificate of the chain, the result is reported as "TA public key
+verified". Otherwise, either the TLSA record "matched TA certificate"
+at a positive depth or else "matched EE certificate" at depth 0.
+
+=item B<-dane_tlsa_rrdata rrdata>
+
+Use one or more times to specify the RRDATA fields of the DANE TLSA
+RRset associated with the target service. The B<rrdata> value is
+specied in "presentation form", that is four whitespace separated
+fields that specify the usage, selector, matching type and associated
+data, with the last of these encoded in hexadecimal. Optional
+whitespace is ignored in the associated data field. For example:
+
+ $ openssl s_client -brief -starttls smtp \
+ -connect smtp.example.com:25 \
+ -dane_tlsa_domain smtp.example.com \
+ -dane_tlsa_rrdata "2 1 1
+ B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \
+ -dane_tlsa_rrdata "2 1 1
+ 60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18"
+ ...
+ Verification: OK
+ Verified peername: smtp.example.com
+ DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1
+ ...
+
+=item B<-dane_ee_no_namechecks>
+
+This disables server name checks when authenticating via DANE-EE(3) TLSA
+records.
+For some applications, primarily web browsers, it is not safe to disable name
+checks due to "unknown key share" attacks, in which a malicious server can
+convince a client that a connection to a victim server is instead a secure
+connection to the malicious server.
+The malicious server may then be able to violate cross-origin scripting
+restrictions.
+Thus, despite the text of RFC7671, name checks are by default enabled for
+DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
+to do so.
+In particular, SMTP and XMPP clients should set this option as SRV and MX
+records already make it possible for a remote domain to redirect client
+connections to any server of its choice, and in any case SMTP and XMPP clients
+do not execute scripts downloaded from remote servers.
+
+=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
+B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
+B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
+B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
+B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
+B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
+B<-verify_ip>, B<-verify_name>, B<-x509_strict>
+
+Set various certificate chain validation options. See the
+L<verify(1)> manual page for details.
+
+=item B<-reconnect>
+
+reconnects to the same server 5 times using the same session ID, this can
+be used as a test that session caching is working.
+
+=item B<-showcerts>
+
+display the whole server certificate chain: normally only the server
+certificate itself is displayed.
+
+=item B<-prexit>
+
+print session information when the program exits. This will always attempt
+to print out information even if the connection fails. Normally information
+will only be printed out once if the connection succeeds. This option is useful
+because the cipher in use may be renegotiated or the connection may fail
+because a client certificate is required or is requested only after an
+attempt is made to access a certain URL. Note: the output produced by this
+option is not always accurate because a connection might never have been
+established.
+
+=item B<-state>
+
+prints out the SSL session states.
+
+=item B<-debug>
+
+print extensive debugging information including a hex dump of all traffic.
+
+=item B<-msg>
+
+show all protocol messages with hex dump.
+
+=item B<-trace>
+
+show verbose trace output of protocol messages. OpenSSL needs to be compiled
+with B<enable-ssl-trace> for this option to work.
+
+=item B<-msgfile>
+
+file to send output of B<-msg> or B<-trace> to, default standard output.
+
+=item B<-nbio_test>
+
+tests non-blocking I/O
+
+=item B<-nbio>
+
+turns on non-blocking I/O
+
+=item B<-crlf>
+
+this option translated a line feed from the terminal into CR+LF as required
+by some servers.
+
+=item B<-ign_eof>
+
+inhibit shutting down the connection when end of file is reached in the
+input.
+
+=item B<-quiet>
+
+inhibit printing of session and certificate information. This implicitly
+turns on B<-ign_eof> as well.
+
+=item B<-no_ign_eof>
+
+shut down the connection when end of file is reached in the input.
+Can be used to override the implicit B<-ign_eof> after B<-quiet>.
+
+=item B<-psk_identity identity>
+
+Use the PSK identity B<identity> when using a PSK cipher suite.
+
+=item B<-psk key>
+
+Use the PSK key B<key> when using a PSK cipher suite. The key is
+given as a hexadecimal number without leading 0x, for example -psk
+1a2b3c4d.
+
+=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
+
+These options require or disable the use of the specified SSL or TLS protocols.
+By default B<s_client> will negotiate the highest mutually supported protocol
+version.
+When a specific TLS version is required, only that version will be offered to
+and accepted from the server.
+
+=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
+
+These options make B<s_client> use DTLS protocols instead of TLS.
+With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version,
+whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2
+respectively.
+
+=item B<-fallback_scsv>
+
+Send TLS_FALLBACK_SCSV in the ClientHello.
+
+=item B<-async>
+
+switch on asynchronous mode. Cryptographic operations will be performed
+asynchronously. This will only have an effect if an asynchronous capable engine
+is also used via the B<-engine> option. For test purposes the dummy async engine
+(dasync) can be used (if available).
+
+=item B<-split_send_frag int>
+
+The size used to split data for encrypt pipelines. If more data is written in
+one go than this value then it will be split into multiple pipelines, up to the
+maximum number of pipelines defined by max_pipelines. This only has an effect if
+a suitable ciphersuite has been negotiated, an engine that supports pipelining
+has been loaded, and max_pipelines is greater than 1. See
+L<SSL_CTX_set_split_send_fragment(3)> for further information.
+
+=item B<-max_pipelines int>
+
+The maximum number of encrypt/decrypt pipelines to be used. This will only have
+an effect if an engine has been loaded that supports pipelining (e.g. the dasync
+engine) and a suitable ciphersuite has been negotiated. The default value is 1.
+See L<SSL_CTX_set_max_pipelines(3)> for further information.
+
+=item B<-read_buf int>
+
+The default read buffer size to be used for connections. This will only have an
+effect if the buffer size is larger than the size that would otherwise be used
+and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
+further information).
+
+=item B<-bugs>
+
+there are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-comp>
+
+Enables support for SSL/TLS compression.
+This option was introduced in OpenSSL 1.1.0.
+TLS compression is not recommended and is off by default as of
+OpenSSL 1.1.0.
+
+=item B<-no_comp>
+
+Disables support for SSL/TLS compression.
+TLS compression is not recommended and is off by default as of
+OpenSSL 1.1.0.
+
+=item B<-brief>
+
+only provide a brief summary of connection parameters instead of the
+normal verbose output.
+
+=item B<-cipher cipherlist>
+
+this allows the cipher list sent by the client to be modified. Although
+the server determines which cipher suite is used it should take the first
+supported cipher in the list sent by the client. See the B<ciphers>
+command for more information.
+
+=item B<-starttls protocol>
+
+send the protocol-specific message(s) to switch to TLS for communication.
+B<protocol> is a keyword for the intended protocol. Currently, the only
+supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server",
+"irc" and "postgres."
+
+=item B<-xmpphost hostname>
+
+This option, when used with "-starttls xmpp" or "-starttls xmpp-server",
+specifies the host for the "to" attribute of the stream element.
+If this option is not specified, then the host specified with "-connect"
+will be used.
+
+=item B<-tlsextdebug>
+
+print out a hex dump of any TLS extensions received from the server.
+
+=item B<-no_ticket>
+
+disable RFC4507bis session ticket support.
+
+=item B<-sess_out filename>
+
+output SSL session to B<filename>
+
+=item B<-sess_in sess.pem>
+
+load SSL session from B<filename>. The client will attempt to resume a
+connection from this session.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<s_client>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-serverinfo types>
+
+a list of comma-separated TLS Extension Types (numbers between 0 and
+65535). Each type will be sent as an empty ClientHello TLS Extension.
+The server's response (if any) will be encoded and displayed as a PEM
+file.
+
+=item B<-status>
+
+sends a certificate status request to the server (OCSP stapling). The server
+response (if any) is printed out.
+
+=item B<-alpn protocols>, B<-nextprotoneg protocols>
+
+these flags enable the
+Enable the Application-Layer Protocol Negotiation or Next Protocol
+Negotiation extension, respectively. ALPN is the IETF standard and
+replaces NPN.
+The B<protocols> list is a
+comma-separated protocol names that the client should advertise
+support for. The list should contain most wanted protocols first.
+Protocol names are printable ASCII strings, for example "http/1.1" or
+"spdy/3".
+Empty list of protocols is treated specially and will cause the client to
+advertise support for the TLS extension but disconnect just after
+receiving ServerHello with a list of server supported protocols.
+
+=item B<-ct|noct>
+
+Use one of these two options to control whether Certificate Transparency (CT)
+is enabled (B<-ct>) or disabled (B<-noct>).
+If CT is enabled, signed certificate timestamps (SCTs) will be requested from
+the server and reported at handshake completion.
+
+Enabling CT also enables OCSP stapling, as this is one possible delivery method
+for SCTs.
+
+=item B<-ctlogfile>
+
+A file containing a list of known Certificate Transparency logs. See
+L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format.
+
+=back
+
+=head1 CONNECTED COMMANDS
+
+If a connection is established with an SSL server then any data received
+from the server is displayed and any key presses will be sent to the
+server. When used interactively (which means neither B<-quiet> nor B<-ign_eof>
+have been given), the session will be renegotiated if the line begins with an
+B<R>, and if the line begins with a B<Q> or if end of file is reached, the
+connection will be closed down.
+
+=head1 NOTES
+
+B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP
+server the command:
+
+ openssl s_client -connect servername:443
+
+would typically be used (https uses port 443). If the connection succeeds
+then an HTTP command can be given such as "GET /" to retrieve a web page.
+
+If the handshake fails then there are several possible causes, if it is
+nothing obvious like no client certificate then the B<-bugs>,
+B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1> options can be tried
+in case it is a buggy server. In particular you should play with these
+options B<before> submitting a bug report to an OpenSSL mailing list.
+
+A frequent problem when attempting to get client certificates working
+is that a web client complains it has no certificates or gives an empty
+list to choose from. This is normally because the server is not sending
+the clients certificate authority in its "acceptable CA list" when it
+requests a certificate. By using B<s_client> the CA list can be viewed
+and checked. However some servers only request client authentication
+after a specific URL is requested. To obtain the list in this case it
+is necessary to use the B<-prexit> option and send an HTTP request
+for an appropriate page.
+
+If a certificate is specified on the command line using the B<-cert>
+option it will not be used unless the server specifically requests
+a client certificate. Therefor merely including a client certificate
+on the command line is no guarantee that the certificate works.
+
+If there are problems verifying a server certificate then the
+B<-showcerts> option can be used to show the whole chain.
+
+The B<s_client> utility is a test tool and is designed to continue the
+handshake after any certificate verification errors. As a result it will
+accept any certificate chain (trusted or not) sent by the peer. None test
+applications should B<not> do this as it makes them vulnerable to a MITM
+attack. This behaviour can be changed by with the B<-verify_return_error>
+option: any verify errors are then returned aborting the handshake.
+
+=head1 BUGS
+
+Because this program has a lot of options and also because some of the
+techniques used are rather old, the C source of B<s_client> is rather hard to
+read and not a model of how things should be done.
+A typical SSL client program would be much simpler.
+
+The B<-prexit> option is a bit of a hack. We should really report
+information whenever a session is renegotiated.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_cmd(3)>,
+L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>
+
+=head1 HISTORY
+
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+s_server - SSL/TLS server program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_server>
+[B<-help>]
+[B<-accept port>]
+[B<-naccept count>]
+[B<-context id>]
+[B<-verify depth>]
+[B<-Verify depth>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-cert filename>]
+[B<-certform DER|PEM>]
+[B<-key keyfile>]
+[B<-keyform DER|PEM>]
+[B<-pass arg>]
+[B<-dcert filename>]
+[B<-dcertform DER|PEM>]
+[B<-dkey keyfile>]
+[B<-dkeyform DER|PEM>]
+[B<-dpass arg>]
+[B<-dhparam filename>]
+[B<-nbio>]
+[B<-nbio_test>]
+[B<-crlf>]
+[B<-debug>]
+[B<-msg>]
+[B<-state>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-no_check_time>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-use_deltas>]
+[B<-auth_level num>]
+[B<-verify_depth num>]
+[B<-verify_return_error>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
+[B<-nocert>]
+[B<-cipher cipherlist>]
+[B<-serverpref>]
+[B<-quiet>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<-dtls>]
+[B<-dtls1>]
+[B<-dtls1_2>]
+[B<-listen>]
+[B<-async>]
+[B<-split_send_frag>]
+[B<-max_pipelines>]
+[B<-read_buf>]
+[B<-no_ssl3>]
+[B<-no_tls1>]
+[B<-no_tls1_1>]
+[B<-no_tls1_2>]
+[B<-no_dhe>]
+[B<-bugs>]
+[B<-comp>]
+[B<-no_comp>]
+[B<-brief>]
+[B<-www>]
+[B<-WWW>]
+[B<-HTTP>]
+[B<-engine id>]
+[B<-tlsextdebug>]
+[B<-no_ticket>]
+[B<-id_prefix arg>]
+[B<-rand file(s)>]
+[B<-serverinfo file>]
+[B<-no_resumption_on_reneg>]
+[B<-status>]
+[B<-status_verbose>]
+[B<-status_timeout nsec>]
+[B<-status_url url>]
+[B<-alpn protocols>]
+[B<-nextprotoneg protocols>]
+
+=head1 DESCRIPTION
+
+The B<s_server> command implements a generic SSL/TLS server which listens
+for connections on a given port using SSL/TLS.
+
+=head1 OPTIONS
+
+In addition to the options below the B<s_server> utility also supports the
+common and server only options documented in the
+in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
+manual page.
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-accept port>
+
+The TCP port to listen on for connections. If not specified 4433 is used.
+
+=item B<-naccept count>
+
+The server will exit after receiving B<number> connections, default unlimited.
+
+=item B<-context id>
+
+Sets the SSL context id. It can be given any string value. If this option
+is not present a default value will be used.
+
+=item B<-cert certname>
+
+The certificate to use, most servers cipher suites require the use of a
+certificate and some require a certificate with a certain public key type:
+for example the DSS cipher suites require a certificate containing a DSS
+(DSA) key. If not specified then the filename "server.pem" will be used.
+
+=item B<-certform format>
+
+The certificate format to use: DER or PEM. PEM is the default.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used.
+
+=item B<-keyform format>
+
+The private format to use: DER or PEM. PEM is the default.
+
+=item B<-pass arg>
+
+The private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-dcert filename>, B<-dkey keyname>
+
+Specify an additional certificate and private key, these behave in the
+same manner as the B<-cert> and B<-key> options except there is no default
+if they are not specified (no additional certificate and key is used). As
+noted above some cipher suites require a certificate containing a key of
+a certain type. Some cipher suites need a certificate carrying an RSA key
+and some a DSS (DSA) key. By using RSA and DSS certificates and keys
+a server can support clients which only support RSA or DSS cipher suites
+by using an appropriate certificate.
+
+=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
+
+Additional certificate and private key format and passphrase respectively.
+
+=item B<-nocert>
+
+If this option is set then no certificate is used. This restricts the
+cipher suites available to the anonymous ones (currently just anonymous
+DH).
+
+=item B<-dhparam filename>
+
+The DH parameter file to use. The ephemeral DH cipher suites generate keys
+using a set of DH parameters. If not specified then an attempt is made to
+load the parameters from the server certificate file.
+If this fails then a static set of parameters hard coded into the B<s_server>
+program will be used.
+
+=item B<-no_dhe>
+
+If this option is set then no DH parameters will be loaded effectively
+disabling the ephemeral DH cipher suites.
+
+=item B<-crl_check>, B<-crl_check_all>
+
+Check the peer certificate has not been revoked by its CA.
+The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
+option all CRLs of all CAs in the chain are checked.
+
+=item B<-CApath directory>
+
+The directory to use for client certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the server certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during client authentication
+and to use when attempting to build the server certificate chain. The list
+is also used in the list of acceptable client CAs passed to the client when
+a certificate is requested.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-verify depth>, B<-Verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+client certificate chain and makes the server request a certificate from
+the client. With the B<-verify> option a certificate is requested but the
+client does not have to send one, with the B<-Verify> option the client
+must supply a certificate or an error occurs.
+
+If the ciphersuite cannot request a client certificate (for example an
+anonymous ciphersuite or PSK) this option has no effect.
+
+=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
+B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
+B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
+B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
+B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
+B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
+B<-verify_ip>, B<-verify_name>, B<-x509_strict>
+
+Set different peer certificate verification options.
+See the L<verify(1)> manual page for details.
+
+=item B<-verify_return_error>
+
+Verification errors normally just print a message but allow the
+connection to continue, for debugging purposes.
+If this option is used, then verification errors close the connection.
+
+=item B<-state>
+
+Prints the SSL session states.
+
+=item B<-debug>
+
+Print extensive debugging information including a hex dump of all traffic.
+
+=item B<-msg>
+
+Show all protocol messages with hex dump.
+
+=item B<-trace>
+
+Show verbose trace output of protocol messages. OpenSSL needs to be compiled
+with B<enable-ssl-trace> for this option to work.
+
+=item B<-msgfile>
+
+File to send output of B<-msg> or B<-trace> to, default standard output.
+
+=item B<-nbio_test>
+
+Tests non blocking I/O
+
+=item B<-nbio>
+
+Turns on non blocking I/O
+
+=item B<-crlf>
+
+This option translated a line feed from the terminal into CR+LF.
+
+=item B<-quiet>
+
+Inhibit printing of session and certificate information.
+
+=item B<-psk_hint hint>
+
+Use the PSK identity hint B<hint> when using a PSK cipher suite.
+
+=item B<-psk key>
+
+Use the PSK key B<key> when using a PSK cipher suite. The key is
+given as a hexadecimal number without leading 0x, for example -psk
+1a2b3c4d.
+
+=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
+
+These options require or disable the use of the specified SSL or TLS protocols.
+By default B<s_server> will negotiate the highest mutually supported protocol
+version.
+When a specific TLS version is required, only that version will be accepted
+from the client.
+
+=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
+
+These options make B<s_server> use DTLS protocols instead of TLS.
+With B<-dtls>, B<s_server> will negotiate any supported DTLS protocol version,
+whilst B<-dtls1> and B<-dtls1_2> will only support DTLSv1.0 and DTLSv1.2
+respectively.
+
+=item B<-listen>
+
+This option can only be used in conjunction with one of the DTLS options above.
+With this option B<s_server> will listen on a UDP port for incoming connections.
+Any ClientHellos that arrive will be checked to see if they have a cookie in
+them or not.
+Any without a cookie will be responded to with a HelloVerifyRequest.
+If a ClientHello with a cookie is received then B<s_server> will connect to
+that peer and complete the handshake.
+
+=item B<-async>
+
+Switch on asynchronous mode. Cryptographic operations will be performed
+asynchronously. This will only have an effect if an asynchronous capable engine
+is also used via the B<-engine> option. For test purposes the dummy async engine
+(dasync) can be used (if available).
+
+=item B<-split_send_frag int>
+
+The size used to split data for encrypt pipelines. If more data is written in
+one go than this value then it will be split into multiple pipelines, up to the
+maximum number of pipelines defined by max_pipelines. This only has an effect if
+a suitable ciphersuite has been negotiated, an engine that supports pipelining
+has been loaded, and max_pipelines is greater than 1. See
+L<SSL_CTX_set_split_send_fragment(3)> for further information.
+
+=item B<-max_pipelines int>
+
+The maximum number of encrypt/decrypt pipelines to be used. This will only have
+an effect if an engine has been loaded that supports pipelining (e.g. the dasync
+engine) and a suitable ciphersuite has been negotiated. The default value is 1.
+See L<SSL_CTX_set_max_pipelines(3)> for further information.
+
+=item B<-read_buf int>
+
+The default read buffer size to be used for connections. This will only have an
+effect if the buffer size is larger than the size that would otherwise be used
+and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
+further information).
+
+=item B<-bugs>
+
+There are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-comp>
+
+Enable negotiation of TLS compression.
+This option was introduced in OpenSSL 1.1.0.
+TLS compression is not recommended and is off by default as of
+OpenSSL 1.1.0.
+
+=item B<-no_comp>
+
+Disable negotiation of TLS compression.
+TLS compression is not recommended and is off by default as of
+OpenSSL 1.1.0.
+
+=item B<-brief>
+
+Provide a brief summary of connection parameters instead of the normal verbose
+output.
+
+=item B<-cipher cipherlist>
+
+This allows the cipher list used by the server to be modified. When
+the client sends a list of supported ciphers the first client cipher
+also included in the server list is used. Because the client specifies
+the preference order, the order of the server cipherlist irrelevant. See
+the B<ciphers> command for more information.
+
+=item B<-serverpref>
+
+Use the server's cipher preferences, rather than the client's preferences.
+
+=item B<-tlsextdebug>
+
+Print a hex dump of any TLS extensions received from the server.
+
+=item B<-no_ticket>
+
+Disable RFC4507bis session ticket support.
+
+=item B<-www>
+
+Sends a status message back to the client when it connects. This includes
+information about the ciphers used and various session parameters.
+The output is in HTML format so this option will normally be used with a
+web browser.
+
+=item B<-WWW>
+
+Emulates a simple web server. Pages will be resolved relative to the
+current directory, for example if the URL https://myhost/page.html is
+requested the file ./page.html will be loaded.
+
+=item B<-HTTP>
+
+Emulates a simple web server. Pages will be resolved relative to the
+current directory, for example if the URL https://myhost/page.html is
+requested the file ./page.html will be loaded. The files loaded are
+assumed to contain a complete and correct HTTP response (lines that
+are part of the HTTP response line and headers must end with CRLF).
+
+=item B<-rev>
+
+Simple test server which just reverses the text received from the client
+and sends it back to the server. Also sets B<-brief>.
+
+=item B<-engine id>
+
+Specifying an engine (by its unique B<id> string) will cause B<s_server>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-id_prefix arg>
+
+Generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
+for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
+servers, when each of which might be generating a unique range of session
+IDs (eg. with a certain prefix).
+
+=item B<-rand file(s)>
+
+A file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<-serverinfo file>
+
+A file containing one or more blocks of PEM data. Each PEM block
+must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
+followed by "length" bytes of extension data). If the client sends
+an empty TLS ClientHello extension matching the type, the corresponding
+ServerHello extension will be returned.
+
+=item B<-no_resumption_on_reneg>
+
+Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option.
+
+=item B<-status>
+
+Enables certificate status request support (aka OCSP stapling).
+
+=item B<-status_verbose>
+
+Enables certificate status request support (aka OCSP stapling) and gives
+a verbose printout of the OCSP response.
+
+=item B<-status_timeout nsec>
+
+Sets the timeout for OCSP response to B<nsec> seconds.
+
+=item B<-status_url url>
+
+Sets a fallback responder URL to use if no responder URL is present in the
+server certificate. Without this option an error is returned if the server
+certificate does not contain a responder address.
+
+=item B<-alpn protocols>, B<-nextprotoneg protocols>
+
+these flags enable the
+Enable the Application-Layer Protocol Negotiation or Next Protocol
+Negotiation extension, respectively. ALPN is the IETF standard and
+replaces NPN.
+The B<protocols> list is a
+comma-separated list of supported protocol names.
+The list should contain most wanted protocols first.
+Protocol names are printable ASCII strings, for example "http/1.1" or
+"spdy/3".
+
+=back
+
+=head1 CONNECTED COMMANDS
+
+If a connection request is established with an SSL client and neither the
+B<-www> nor the B<-WWW> option has been used then normally any data received
+from the client is displayed and any key presses will be sent to the client.
+
+Certain single letter commands are also recognized which perform special
+operations: these are listed below.
+
+=over 4
+
+=item B<q>
+
+end the current SSL connection but still accept new connections.
+
+=item B<Q>
+
+end the current SSL connection and exit.
+
+=item B<r>
+
+renegotiate the SSL session.
+
+=item B<R>
+
+renegotiate the SSL session and request a client certificate.
+
+=item B<P>
+
+send some plain text down the underlying TCP connection: this should
+cause the client to disconnect due to a protocol violation.
+
+=item B<S>
+
+print out some session cache status information.
+
+=back
+
+=head1 NOTES
+
+B<s_server> can be used to debug SSL clients. To accept connections from
+a web browser the command:
+
+ openssl s_server -accept 443 -www
+
+can be used for example.
+
+Most web browsers (in particular Netscape and MSIE) only support RSA cipher
+suites, so they cannot connect to servers which don't use a certificate
+carrying an RSA key or a version of OpenSSL with RSA disabled.
+
+Although specifying an empty list of CAs when requesting a client certificate
+is strictly speaking a protocol violation, some SSL clients interpret this to
+mean any CA is acceptable. This is useful for debugging purposes.
+
+The session parameters can printed out using the B<sess_id> program.
+
+=head1 BUGS
+
+Because this program has a lot of options and also because some of the
+techniques used are rather old, the C source of B<s_server> is rather hard to
+read and not a model of how things should be done.
+A typical SSL server program would be much simpler.
+
+The output of common ciphers is wrong: it just gives the list of ciphers that
+OpenSSL recognizes and the client supports.
+
+There should be a way for the B<s_server> program to print out details of any
+unknown cipher suites a client says it supports.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_cmd(3)>,
+L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)>
+
+=head1 HISTORY
+
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+s_time - SSL/TLS performance timing program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_time>
+[B<-help>]
+[B<-connect host:port>]
+[B<-www page>]
+[B<-cert filename>]
+[B<-key filename>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-reuse>]
+[B<-new>]
+[B<-verify depth>]
+[B<-nbio>]
+[B<-time seconds>]
+[B<-ssl3>]
+[B<-bugs>]
+[B<-cipher cipherlist>]
+
+=head1 DESCRIPTION
+
+The B<s_time> command implements a generic SSL/TLS client which connects to a
+remote host using SSL/TLS. It can request a page from the server and includes
+the time to transfer the payload data in its timing measurements. It measures
+the number of connections within a given timeframe, the amount of data
+transferred (if any), and calculates the average time spent for one connection.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-connect host:port>
+
+This specifies the host and optional port to connect to.
+
+=item B<-www page>
+
+This specifies the page to GET from the server. A value of '/' gets the
+index.htm[l] page. If this parameter is not specified, then B<s_time> will only
+perform the handshake to establish SSL connections but not transfer any
+payload data.
+
+=item B<-cert certname>
+
+The certificate to use, if one is requested by the server. The default is
+not to use a certificate. The file is in PEM format.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used. The file is in PEM format.
+
+=item B<-verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+server certificate chain and turns on server certificate verification.
+Currently the verify operation continues after errors so all the problems
+with a certificate chain can be seen. As a side effect the connection
+will never fail due to a server certificate verify failure.
+
+=item B<-CApath directory>
+
+The directory to use for server certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the client certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during server authentication
+and to use when attempting to build the client certificate chain.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-new>
+
+performs the timing test using a new session ID for each connection.
+If neither B<-new> nor B<-reuse> are specified, they are both on by default
+and executed in sequence.
+
+=item B<-reuse>
+
+performs the timing test using the same session ID; this can be used as a test
+that session caching is working. If neither B<-new> nor B<-reuse> are
+specified, they are both on by default and executed in sequence.
+
+=item B<-nbio>
+
+turns on non-blocking I/O.
+
+=item B<-ssl3>
+
+these options disable the use of certain SSL or TLS protocols. By default
+the initial handshake uses a method which should be compatible with all
+servers and permit them to use SSL v3 or TLS as appropriate.
+The timing program is not as rich in options to turn protocols on and off as
+the L<s_client(1)> program and may not connect to all servers.
+
+Unfortunately there are a lot of ancient and broken servers in use which
+cannot handle this technique and will fail to connect. Some servers only
+work if TLS is turned off with the B<-ssl3> option.
+
+=item B<-bugs>
+
+there are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-cipher cipherlist>
+
+this allows the cipher list sent by the client to be modified. Although
+the server determines which cipher suite is used it should take the first
+supported cipher in the list sent by the client.
+See the L<ciphers(1)> command for more information.
+
+=item B<-time length>
+
+specifies how long (in seconds) B<s_time> should establish connections and
+optionally transfer payload data from a server. Server and client performance
+and the link speed determine how many connections B<s_time> can establish.
+
+=back
+
+=head1 NOTES
+
+B<s_time> can be used to measure the performance of an SSL connection.
+To connect to an SSL HTTP server and get the default page the command
+
+ openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
+
+would typically be used (https uses port 443). 'commoncipher' is a cipher to
+which both client and server can agree, see the L<ciphers(1)> command
+for details.
+
+If the handshake fails then there are several possible causes, if it is
+nothing obvious like no client certificate then the B<-bugs> and
+B<-ssl3> options can be tried
+in case it is a buggy server. In particular you should play with these
+options B<before> submitting a bug report to an OpenSSL mailing list.
+
+A frequent problem when attempting to get client certificates working
+is that a web client complains it has no certificates or gives an empty
+list to choose from. This is normally because the server is not sending
+the clients certificate authority in its "acceptable CA list" when it
+requests a certificate. By using L<s_client(1)> the CA list can be
+viewed and checked. However some servers only request client authentication
+after a specific URL is requested. To obtain the list in this case it
+is necessary to use the B<-prexit> option of L<s_client(1)> and
+send an HTTP request for an appropriate page.
+
+If a certificate is specified on the command line using the B<-cert>
+option it will not be used unless the server specifically requests
+a client certificate. Therefor merely including a client certificate
+on the command line is no guarantee that the certificate works.
+
+=head1 BUGS
+
+Because this program does not have all the options of the
+L<s_client(1)> program to turn protocols on and off, you may not be
+able to measure the performance of all protocols with all servers.
+
+The B<-verify> option should really exit if the server verification
+fails.
+
+=head1 SEE ALSO
+
+L<s_client(1)>, L<s_server(1)>, L<ciphers(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+sess_id - SSL/TLS session handling utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<sess_id>
+[B<-help>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER|NSS>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-text>]
+[B<-noout>]
+[B<-context ID>]
+
+=head1 DESCRIPTION
+
+The B<sess_id> process the encoded version of the SSL session structure
+and optionally prints out SSL session details (for example the SSL session
+master key) in human readable format. Since this is a diagnostic tool that
+needs some knowledge of the SSL protocol to use properly, most users will
+not need to use it.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+format containing session details. The precise format can vary from one version
+to the next. The B<PEM> form is the default format: it consists of the B<DER>
+format base64 encoded with additional header and footer lines.
+
+=item B<-outform DER|PEM|NSS>
+
+This specifies the output format. The B<PEM> and B<DER> options have the same meaning
+as the B<-inform> option. The B<NSS> option outputs the session id and the master key
+in NSS keylog format.
+
+=item B<-in filename>
+
+This specifies the input filename to read session information from or standard
+input by default.
+
+=item B<-out filename>
+
+This specifies the output filename to write session information to or standard
+output if this option is not specified.
+
+=item B<-text>
+
+prints out the various public or private key components in
+plain text in addition to the encoded version.
+
+=item B<-cert>
+
+if a certificate is present in the session it will be output using this option,
+if the B<-text> option is also present then it will be printed out in text form.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the session.
+
+=item B<-context ID>
+
+this option can set the session id so the output session information uses the
+supplied ID. The ID can be any string of characters. This option won't normally
+be used.
+
+=back
+
+=head1 OUTPUT
+
+Typical output:
+
+ SSL-Session:
+ Protocol : TLSv1
+ Cipher : 0016
+ Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED
+ Session-ID-ctx: 01000000
+ Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD
+ Key-Arg : None
+ Start Time: 948459261
+ Timeout : 300 (sec)
+ Verify return code 0 (ok)
+
+Theses are described below in more detail.
+
+=over 4
+
+=item B<Protocol>
+
+this is the protocol in use TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
+
+=item B<Cipher>
+
+the cipher used this is the actual raw SSL or TLS cipher code, see the SSL
+or TLS specifications for more information.
+
+=item B<Session-ID>
+
+the SSL session ID in hex format.
+
+=item B<Session-ID-ctx>
+
+the session ID context in hex format.
+
+=item B<Master-Key>
+
+this is the SSL session master key.
+
+=item B<Start Time>
+
+this is the session start time represented as an integer in standard Unix format.
+
+=item B<Timeout>
+
+the timeout in seconds.
+
+=item B<Verify return code>
+
+this is the return code when an SSL client certificate is verified.
+
+=back
+
+=head1 NOTES
+
+The PEM encoded session format uses the header and footer lines:
+
+ -----BEGIN SSL SESSION PARAMETERS-----
+ -----END SSL SESSION PARAMETERS-----
+
+Since the SSL session output contains the master key it is possible to read the contents
+of an encrypted session using this information. Therefore appropriate security precautions
+should be taken if the information is being output by a "real" application. This is
+however strongly discouraged and should only be used for debugging purposes.
+
+=head1 BUGS
+
+The cipher and start time should be printed out in human readable form.
+
+=head1 SEE ALSO
+
+L<ciphers(1)>, L<s_server(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+smime - S/MIME utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<smime>
+[B<-help>]
+[B<-encrypt>]
+[B<-decrypt>]
+[B<-sign>]
+[B<-resign>]
+[B<-verify>]
+[B<-pk7out>]
+[B<-binary>]
+[B<-crlfeol>]
+[B<-[cipher]>]
+[B<-in file>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-use_deltas>]
+[B<-auth_level num>]
+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
+[B<-certfile file>]
+[B<-signer file>]
+[B<-recip file>]
+[B<-inform SMIME|PEM|DER>]
+[B<-passin arg>]
+[B<-inkey file>]
+[B<-out file>]
+[B<-outform SMIME|PEM|DER>]
+[B<-content file>]
+[B<-to addr>]
+[B<-from ad>]
+[B<-subject s>]
+[B<-text>]
+[B<-indef>]
+[B<-noindef>]
+[B<-stream>]
+[B<-rand file(s)>]
+[B<-md digest>]
+[cert.pem]...
+
+=head1 DESCRIPTION
+
+The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
+verify S/MIME messages.
+
+=head1 COMMAND OPTIONS
+
+There are six operation options that set the type of operation to be performed.
+The meaning of the other options varies according to the operation type.
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-encrypt>
+
+encrypt mail for the given recipient certificates. Input file is the message
+to be encrypted. The output file is the encrypted mail in MIME format.
+
+Note that no revocation check is done for the recipient cert, so if that
+key has been compromised, others may be able to decrypt the text.
+
+=item B<-decrypt>
+
+decrypt mail using the supplied certificate and private key. Expects an
+encrypted mail message in MIME format for the input file. The decrypted mail
+is written to the output file.
+
+=item B<-sign>
+
+sign mail using the supplied certificate and private key. Input file is
+the message to be signed. The signed message in MIME format is written
+to the output file.
+
+=item B<-verify>
+
+verify signed mail. Expects a signed mail message on input and outputs
+the signed data. Both clear text and opaque signing is supported.
+
+=item B<-pk7out>
+
+takes an input message and writes out a PEM encoded PKCS#7 structure.
+
+=item B<-resign>
+
+resign a message: take an existing message and one or more new signers.
+
+=item B<-in filename>
+
+the input message to be encrypted or signed or the MIME message to
+be decrypted or verified.
+
+=item B<-inform SMIME|PEM|DER>
+
+this specifies the input format for the PKCS#7 structure. The default
+is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
+format change this to expect PEM and DER format PKCS#7 structures
+instead. This currently only affects the input format of the PKCS#7
+structure, if no PKCS#7 structure is being input (for example with
+B<-encrypt> or B<-sign>) this option has no effect.
+
+=item B<-out filename>
+
+the message text that has been decrypted or verified or the output MIME
+format message that has been signed or verified.
+
+=item B<-outform SMIME|PEM|DER>
+
+this specifies the output format for the PKCS#7 structure. The default
+is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
+format change this to write PEM and DER format PKCS#7 structures
+instead. This currently only affects the output format of the PKCS#7
+structure, if no PKCS#7 structure is being output (for example with
+B<-verify> or B<-decrypt>) this option has no effect.
+
+=item B<-stream -indef -noindef>
+
+the B<-stream> and B<-indef> options are equivalent and enable streaming I/O
+for encoding operations. This permits single pass processing of data without
+the need to hold the entire contents in memory, potentially supporting very
+large files. Streaming is automatically set for S/MIME signing with detached
+data if the output format is B<SMIME> it is currently off by default for all
+other operations.
+
+=item B<-noindef>
+
+disable streaming I/O where it would produce and indefinite length constructed
+encoding. This option currently has no effect. In future streaming will be
+enabled by default on all relevant operations and this option will disable it.
+
+=item B<-content filename>
+
+This specifies a file containing the detached content, this is only
+useful with the B<-verify> command. This is only usable if the PKCS#7
+structure is using the detached signature form where the content is
+not included. This option will override any content if the input format
+is S/MIME and it uses the multipart/signed MIME content type.
+
+=item B<-text>
+
+this option adds plain text (text/plain) MIME headers to the supplied
+message if encrypting or signing. If decrypting or verifying it strips
+off text headers: if the decrypted or verified message is not of MIME
+type text/plain then an error occurs.
+
+=item B<-CAfile file>
+
+a file containing trusted CA certificates, only used with B<-verify>.
+
+=item B<-CApath dir>
+
+a directory containing trusted CA certificates, only used with
+B<-verify>. This directory must be a standard certificate directory: that
+is a hash of each subject name (using B<x509 -hash>) should be linked
+to each certificate.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-md digest>
+
+digest algorithm to use when signing or resigning. If not present then the
+default digest algorithm for the signing key will be used (usually SHA1).
+
+=item B<-[cipher]>
+
+the encryption algorithm to use. For example DES (56 bits) - B<-des>,
+triple DES (168 bits) - B<-des3>,
+EVP_get_cipherbyname() function) can also be used preceded by a dash, for
+example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers
+supported by your version of OpenSSL.
+
+If not specified triple DES is used. Only used with B<-encrypt>.
+
+=item B<-nointern>
+
+when verifying a message normally certificates (if any) included in
+the message are searched for the signing certificate. With this option
+only the certificates specified in the B<-certfile> option are used.
+The supplied certificates can still be used as untrusted CAs however.
+
+=item B<-noverify>
+
+do not verify the signers certificate of a signed message.
+
+=item B<-nochain>
+
+do not do chain verification of signers certificates: that is don't
+use the certificates in the signed message as untrusted CAs.
+
+=item B<-nosigs>
+
+don't try to verify the signatures on the message.
+
+=item B<-nocerts>
+
+when signing a message the signer's certificate is normally included
+with this option it is excluded. This will reduce the size of the
+signed message but the verifier must have a copy of the signers certificate
+available locally (passed using the B<-certfile> option for example).
+
+=item B<-noattr>
+
+normally when a message is signed a set of attributes are included which
+include the signing time and supported symmetric algorithms. With this
+option they are not included.
+
+=item B<-binary>
+
+normally the input message is converted to "canonical" format which is
+effectively using CR and LF as end of line: as required by the S/MIME
+specification. When this option is present no translation occurs. This
+is useful when handling binary data which may not be in MIME format.
+
+=item B<-crlfeol>
+
+normally the output file uses a single B<LF> as end of line. When this
+option is present B<CRLF> is used instead.
+
+=item B<-nodetach>
+
+when signing a message use opaque signing: this form is more resistant
+to translation by mail relays but it cannot be read by mail agents that
+do not support S/MIME. Without this option cleartext signing with
+the MIME type multipart/signed is used.
+
+=item B<-certfile file>
+
+allows additional certificates to be specified. When signing these will
+be included with the message. When verifying these will be searched for
+the signers certificates. The certificates should be in PEM format.
+
+=item B<-signer file>
+
+a signing certificate when signing or resigning a message, this option can be
+used multiple times if more than one signer is required. If a message is being
+verified then the signers certificates will be written to this file if the
+verification was successful.
+
+=item B<-recip file>
+
+the recipients certificate when decrypting a message. This certificate
+must match one of the recipients of the message or an error occurs.
+
+=item B<-inkey file>
+
+the private key to use when signing or decrypting. This must match the
+corresponding certificate. If this option is not specified then the
+private key must be included in the certificate file specified with
+the B<-recip> or B<-signer> file. When signing this option can be used
+multiple times to specify successive keys.
+
+=item B<-passin arg>
+
+the private key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
+
+=item B<cert.pem...>
+
+one or more certificates of message recipients: used when encrypting
+a message.
+
+=item B<-to, -from, -subject>
+
+the relevant mail headers. These are included outside the signed
+portion of a message so they may be included manually. If signing
+then many S/MIME mail clients check the signers certificate's email
+address matches that specified in the From: address.
+
+=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
+B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
+B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
+B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
+B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
+B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
+B<-verify_ip>, B<-verify_name>, B<-x509_strict>
+
+Set various options of certificate chain verification. See
+L<verify(1)> manual page for details.
+
+=back
+
+=head1 NOTES
+
+The MIME message must be sent without any blank lines between the
+headers and the output. Some mail programs will automatically add
+a blank line. Piping the mail directly to sendmail is one way to
+achieve the correct format.
+
+The supplied message to be signed or encrypted must include the
+necessary MIME headers or many S/MIME clients won't display it
+properly (if at all). You can use the B<-text> option to automatically
+add plain text headers.
+
+A "signed and encrypted" message is one where a signed message is
+then encrypted. This can be produced by encrypting an already signed
+message: see the examples section.
+
+This version of the program only allows one signer per message but it
+will verify multiple signers on received messages. Some S/MIME clients
+choke if a message contains multiple signers. It is possible to sign
+messages "in parallel" by signing an already signed message.
+
+The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
+clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
+encrypted data is used for other purposes.
+
+The B<-resign> option uses an existing message digest when adding a new
+signer. This means that attributes must be present in at least one existing
+signer using the same message digest or this operation will fail.
+
+The B<-stream> and B<-indef> options enable streaming I/O support.
+As a result the encoding is BER using indefinite length constructed encoding
+and no longer DER. Streaming is supported for the B<-encrypt> operation and the
+B<-sign> operation if the content is not detached.
+
+Streaming is always used for the B<-sign> operation with detached data but
+since the content is no longer part of the PKCS#7 structure the encoding
+remains DER.
+
+=head1 EXIT CODES
+
+=over 4
+
+=item Z<>0
+
+the operation was completely successfully.
+
+=item Z<>1
+
+an error occurred parsing the command options.
+
+=item Z<>2
+
+one of the input files could not be read.
+
+=item Z<>3
+
+an error occurred creating the PKCS#7 file or when reading the MIME
+message.
+
+=item Z<>4
+
+an error occurred decrypting or verifying the message.
+
+=item Z<>5
+
+the message was verified correctly but an error occurred writing out
+the signers certificates.
+
+=back
+
+=head1 EXAMPLES
+
+Create a cleartext signed message:
+
+ openssl smime -sign -in message.txt -text -out mail.msg \
+ -signer mycert.pem
+
+Create an opaque signed message:
+
+ openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
+ -signer mycert.pem
+
+Create a signed message, include some additional certificates and
+read the private key from another file:
+
+ openssl smime -sign -in in.txt -text -out mail.msg \
+ -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
+
+Create a signed message with two signers:
+
+ openssl smime -sign -in message.txt -text -out mail.msg \
+ -signer mycert.pem -signer othercert.pem
+
+Send a signed message under Unix directly to sendmail, including headers:
+
+ openssl smime -sign -in in.txt -text -signer mycert.pem \
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed message" | sendmail someone@somewhere
+
+Verify a message and extract the signer's certificate if successful:
+
+ openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
+
+Send encrypted mail using triple DES:
+
+ openssl smime -encrypt -in in.txt -from steve@openssl.org \
+ -to someone@somewhere -subject "Encrypted message" \
+ -des3 user.pem -out mail.msg
+
+Sign and encrypt mail:
+
+ openssl smime -sign -in ml.txt -signer my.pem -text \
+ | openssl smime -encrypt -out mail.msg \
+ -from steve@openssl.org -to someone@somewhere \
+ -subject "Signed and Encrypted message" -des3 user.pem
+
+Note: the encryption command does not include the B<-text> option because the
+message being encrypted already has MIME headers.
+
+Decrypt mail:
+
+ openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
+
+The output from Netscape form signing is a PKCS#7 structure with the
+detached signature format. You can use this program to verify the
+signature by line wrapping the base64 encoded structure and surrounding
+it with:
+
+ -----BEGIN PKCS7-----
+ -----END PKCS7-----
+
+and using the command:
+
+ openssl smime -verify -inform PEM -in signature.pem -content content.txt
+
+Alternatively you can base64 decode the signature and use:
+
+ openssl smime -verify -inform DER -in signature.der -content content.txt
+
+Create an encrypted message using 128 bit Camellia:
+
+ openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
+
+Add a signer to an existing message:
+
+ openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg
+
+=head1 BUGS
+
+The MIME parser isn't very clever: it seems to handle most messages that I've
+thrown at it but it may choke on others.
+
+The code currently will only write out the signer's certificate to a file: if
+the signer has a separate encryption certificate this must be manually
+extracted. There should be some heuristic that determines the correct
+encryption certificate.
+
+Ideally a database should be maintained of a certificates for each email
+address.
+
+The code doesn't currently take note of the permitted symmetric encryption
+algorithms as supplied in the SMIMECapabilities signed attribute. This means the
+user has to manually include the correct encryption algorithm. It should store
+the list of permitted ciphers in a database and only use those.
+
+No revocation checking is done on the signer's certificate.
+
+The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
+structures may cause parsing errors.
+
+=head1 HISTORY
+
+The use of multiple B<-signer> options and the B<-resign> command were first
+added in OpenSSL 1.0.0
+
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+speed - test library performance
+
+=head1 SYNOPSIS
+
+B<openssl speed>
+[B<-help>]
+[B<-engine id>]
+[B<-elapsed>]
+[B<-evp algo>]
+[B<-decrypt>]
+[B<algorithm...>]
+
+=head1 DESCRIPTION
+
+This command is used to test the performance of cryptographic algorithms.
+To see the list of supported algorithms, use the I<list --digest-commands>
+or I<list --cipher-commands> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<speed>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-elapsed>
+
+Measure time in real time instead of CPU time. It can be useful when testing
+speed of hardware engines.
+
+=item B<-evp algo>
+
+Use the specified cipher or message digest algorithm via the EVP interface.
+
+=item B<-decrypt>
+
+Time the decryption instead of encryption. Affects only the EVP testing.
+
+=item B<[zero or more test algorithms]>
+
+If any options are given, B<speed> tests those algorithms, otherwise all of
+the above are tested.
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+spkac - SPKAC printing and generating utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<spkac>
+[B<-help>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-key keyfile>]
+[B<-passin arg>]
+[B<-challenge string>]
+[B<-pubkey>]
+[B<-spkac spkacname>]
+[B<-spksect section>]
+[B<-noout>]
+[B<-verify>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<spkac> command processes Netscape signed public key and challenge
+(SPKAC) files. It can print out their contents, verify the signature and
+produce its own SPKACs from a supplied private key.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified. Ignored if the B<-key> option is used.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-key keyfile>
+
+create an SPKAC file using the private key in B<keyfile>. The
+B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
+present.
+
+=item B<-passin password>
+
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-challenge string>
+
+specifies the challenge string if an SPKAC is being created.
+
+=item B<-spkac spkacname>
+
+allows an alternative name form the variable containing the
+SPKAC. The default is "SPKAC". This option affects both
+generated and input SPKAC files.
+
+=item B<-spksect section>
+
+allows an alternative name form the section containing the
+SPKAC. The default is the default section.
+
+=item B<-noout>
+
+don't output the text version of the SPKAC (not used if an
+SPKAC is being created).
+
+=item B<-pubkey>
+
+output the public key of an SPKAC (not used if an SPKAC is
+being created).
+
+=item B<-verify>
+
+verifies the digital signature on the supplied SPKAC.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<spkac>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head1 EXAMPLES
+
+Print out the contents of an SPKAC:
+
+ openssl spkac -in spkac.cnf
+
+Verify the signature of an SPKAC:
+
+ openssl spkac -in spkac.cnf -noout -verify
+
+Create an SPKAC using the challenge string "hello":
+
+ openssl spkac -key key.pem -challenge hello -out spkac.cnf
+
+Example of an SPKAC, (long lines split up for clarity):
+
+ SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\
+ PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\
+ PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\
+ 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\
+ 4=
+
+=head1 NOTES
+
+A created SPKAC with suitable DN components appended can be fed into
+the B<ca> utility.
+
+SPKACs are typically generated by Netscape when a form is submitted
+containing the B<KEYGEN> tag as part of the certificate enrollment
+process.
+
+The challenge string permits a primitive form of proof of possession
+of private key. By checking the SPKAC signature and a random challenge
+string some guarantee is given that the user knows the private key
+corresponding to the public key being certified. This is important in
+some applications. Without this it is possible for a previous SPKAC
+to be used in a "replay attack".
+
+=head1 SEE ALSO
+
+L<ca(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ts - Time Stamping Authority tool (client/server)
+
+=head1 SYNOPSIS
+
+B<openssl> B<ts>
+B<-query>
+[B<-rand> file:file...]
+[B<-config> configfile]
+[B<-data> file_to_hash]
+[B<-digest> digest_bytes]
+[B<-[digest]>]
+[B<-tspolicy> object_id]
+[B<-no_nonce>]
+[B<-cert>]
+[B<-in> request.tsq]
+[B<-out> request.tsq]
+[B<-text>]
+
+B<openssl> B<ts>
+B<-reply>
+[B<-config> configfile]
+[B<-section> tsa_section]
+[B<-queryfile> request.tsq]
+[B<-passin> password_src]
+[B<-signer> tsa_cert.pem]
+[B<-inkey> private.pem]
+[B<-sha1|-sha224|-sha256|-sha384|-sha512>]
+[B<-chain> certs_file.pem]
+[B<-tspolicy> object_id]
+[B<-in> response.tsr]
+[B<-token_in>]
+[B<-out> response.tsr]
+[B<-token_out>]
+[B<-text>]
+[B<-engine> id]
+
+B<openssl> B<ts>
+B<-verify>
+[B<-data> file_to_hash]
+[B<-digest> digest_bytes]
+[B<-queryfile> request.tsq]
+[B<-in> response.tsr]
+[B<-token_in>]
+[B<-CApath> trusted_cert_path]
+[B<-CAfile> trusted_certs.pem]
+[B<-untrusted> cert_file.pem]
+[I<verify options>]
+
+I<verify options:>
+[-attime timestamp]
+[-check_ss_sig]
+[-crl_check]
+[-crl_check_all]
+[-explicit_policy]
+[-extended_crl]
+[-ignore_critical]
+[-inhibit_any]
+[-inhibit_map]
+[-issuer_checks]
+[-no_alt_chains]
+[-no_check_time]
+[-partial_chain]
+[-policy arg]
+[-policy_check]
+[-policy_print]
+[-purpose purpose]
+[-suiteB_128]
+[-suiteB_128_only]
+[-suiteB_192]
+[-trusted_first]
+[-use_deltas]
+[-auth_level num]
+[-verify_depth num]
+[-verify_email email]
+[-verify_hostname hostname]
+[-verify_ip ip]
+[-verify_name name]
+[-x509_strict]
+
+=head1 DESCRIPTION
+
+The B<ts> command is a basic Time Stamping Authority (TSA) client and server
+application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A
+TSA can be part of a PKI deployment and its role is to provide long
+term proof of the existence of a certain datum before a particular
+time. Here is a brief description of the protocol:
+
+=over 4
+
+=item 1.
+
+The TSA client computes a one-way hash value for a data file and sends
+the hash to the TSA.
+
+=item 2.
+
+The TSA attaches the current date and time to the received hash value,
+signs them and sends the time stamp token back to the client. By
+creating this token the TSA certifies the existence of the original
+data file at the time of response generation.
+
+=item 3.
+
+The TSA client receives the time stamp token and verifies the
+signature on it. It also checks if the token contains the same hash
+value that it had sent to the TSA.
+
+=back
+
+There is one DER encoded protocol data unit defined for transporting a time
+stamp request to the TSA and one for sending the time stamp response
+back to the client. The B<ts> command has three main functions:
+creating a time stamp request based on a data file,
+creating a time stamp response based on a request, verifying if a
+response corresponds to a particular request or a data file.
+
+There is no support for sending the requests/responses automatically
+over HTTP or TCP yet as suggested in RFC 3161. The users must send the
+requests either by ftp or e-mail.
+
+=head1 OPTIONS
+
+=head2 Time Stamp Request generation
+
+The B<-query> switch can be used for creating and printing a time stamp
+request with the following options:
+
+=over 4
+
+=item B<-rand> file:file...
+
+The files containing random data for seeding the random number
+generator. Multiple files can be specified, the separator is B<;> for
+MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
+
+=item B<-config> configfile
+
+The configuration file to use, this option overrides the
+B<OPENSSL_CONF> environment variable. Only the OID section
+of the config file is used with the B<-query> command. (Optional)
+
+=item B<-data> file_to_hash
+
+The data file for which the time stamp request needs to be
+created. stdin is the default if neither the B<-data> nor the B<-digest>
+parameter is specified. (Optional)
+
+=item B<-digest> digest_bytes
+
+It is possible to specify the message imprint explicitly without the data
+file. The imprint must be specified in a hexadecimal format, two characters
+per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
+1AF601...). The number of bytes must match the message digest algorithm
+in use. (Optional)
+
+=item B<-[digest]>
+
+The message digest to apply to the data file.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+The default is SHA-1. (Optional)
+
+=item B<-tspolicy> object_id
+
+The policy that the client expects the TSA to use for creating the
+time stamp token. Either the dotted OID notation or OID names defined
+in the config file can be used. If no policy is requested the TSA will
+use its own default policy. (Optional)
+
+=item B<-no_nonce>
+
+No nonce is specified in the request if this option is
+given. Otherwise a 64 bit long pseudo-random none is
+included in the request. It is recommended to use nonce to
+protect against replay-attacks. (Optional)
+
+=item B<-cert>
+
+The TSA is expected to include its signing certificate in the
+response. (Optional)
+
+=item B<-in> request.tsq
+
+This option specifies a previously created time stamp request in DER
+format that will be printed into the output file. Useful when you need
+to examine the content of a request in human-readable
+
+format. (Optional)
+
+=item B<-out> request.tsq
+
+Name of the output file to which the request will be written. Default
+is stdout. (Optional)
+
+=item B<-text>
+
+If this option is specified the output is human-readable text format
+instead of DER. (Optional)
+
+=back
+
+=head2 Time Stamp Response generation
+
+A time stamp response (TimeStampResp) consists of a response status
+and the time stamp token itself (ContentInfo), if the token generation was
+successful. The B<-reply> command is for creating a time stamp
+response or time stamp token based on a request and printing the
+response/token in human-readable format. If B<-token_out> is not
+specified the output is always a time stamp response (TimeStampResp),
+otherwise it is a time stamp token (ContentInfo).
+
+=over 4
+
+=item B<-config> configfile
+
+The configuration file to use, this option overrides the
+B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE
+OPTIONS> for configurable variables. (Optional)
+
+=item B<-section> tsa_section
+
+The name of the config file section containing the settings for the
+response generation. If not specified the default TSA section is
+used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional)
+
+=item B<-queryfile> request.tsq
+
+The name of the file containing a DER encoded time stamp request. (Optional)
+
+=item B<-passin> password_src
+
+Specifies the password source for the private key of the TSA. See
+B<PASS PHRASE ARGUMENTS> in L<openssl(1)>. (Optional)
+
+=item B<-signer> tsa_cert.pem
+
+The signer certificate of the TSA in PEM format. The TSA signing
+certificate must have exactly one extended key usage assigned to it:
+timeStamping. The extended key usage must also be critical, otherwise
+the certificate is going to be refused. Overrides the B<signer_cert>
+variable of the config file. (Optional)
+
+=item B<-inkey> private.pem
+
+The signer private key of the TSA in PEM format. Overrides the
+B<signer_key> config file option. (Optional)
+
+=item B<-sha1|-sha224|-sha256|-sha384|-sha512>
+
+Signing digest to use. Overrides the B<signer_digest> config file
+option. (Optional)
+
+=item B<-chain> certs_file.pem
+
+The collection of certificates in PEM format that will all
+be included in the response in addition to the signer certificate if
+the B<-cert> option was used for the request. This file is supposed to
+contain the certificate chain for the signer certificate from its
+issuer upwards. The B<-reply> command does not build a certificate
+chain automatically. (Optional)
+
+=item B<-tspolicy> object_id
+
+The default policy to use for the response unless the client
+explicitly requires a particular TSA policy. The OID can be specified
+either in dotted notation or with its name. Overrides the
+B<default_policy> config file option. (Optional)
+
+=item B<-in> response.tsr
+
+Specifies a previously created time stamp response or time stamp token
+(if B<-token_in> is also specified) in DER format that will be written
+to the output file. This option does not require a request, it is
+useful e.g. when you need to examine the content of a response or
+token or you want to extract the time stamp token from a response. If
+the input is a token and the output is a time stamp response a default
+'granted' status info is added to the token. (Optional)
+
+=item B<-token_in>
+
+This flag can be used together with the B<-in> option and indicates
+that the input is a DER encoded time stamp token (ContentInfo) instead
+of a time stamp response (TimeStampResp). (Optional)
+
+=item B<-out> response.tsr
+
+The response is written to this file. The format and content of the
+file depends on other options (see B<-text>, B<-token_out>). The default is
+stdout. (Optional)
+
+=item B<-token_out>
+
+The output is a time stamp token (ContentInfo) instead of time stamp
+response (TimeStampResp). (Optional)
+
+=item B<-text>
+
+If this option is specified the output is human-readable text format
+instead of DER. (Optional)
+
+=item B<-engine> id
+
+Specifying an engine (by its unique B<id> string) will cause B<ts>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms. Default is builtin. (Optional)
+
+=back
+
+=head2 Time Stamp Response verification
+
+The B<-verify> command is for verifying if a time stamp response or time
+stamp token is valid and matches a particular time stamp request or
+data file. The B<-verify> command does not use the configuration file.
+
+=over 4
+
+=item B<-data> file_to_hash
+
+The response or token must be verified against file_to_hash. The file
+is hashed with the message digest algorithm specified in the token.
+The B<-digest> and B<-queryfile> options must not be specified with this one.
+(Optional)
+
+=item B<-digest> digest_bytes
+
+The response or token must be verified against the message digest specified
+with this option. The number of bytes must match the message digest algorithm
+specified in the token. The B<-data> and B<-queryfile> options must not be
+specified with this one. (Optional)
+
+=item B<-queryfile> request.tsq
+
+The original time stamp request in DER format. The B<-data> and B<-digest>
+options must not be specified with this one. (Optional)
+
+=item B<-in> response.tsr
+
+The time stamp response that needs to be verified in DER format. (Mandatory)
+
+=item B<-token_in>
+
+This flag can be used together with the B<-in> option and indicates
+that the input is a DER encoded time stamp token (ContentInfo) instead
+of a time stamp response (TimeStampResp). (Optional)
+
+=item B<-CApath> trusted_cert_path
+
+The name of the directory containing the trusted CA certificates of the
+client. See the similar option of L<verify(1)> for additional
+details. Either this option or B<-CAfile> must be specified. (Optional)
+
+
+=item B<-CAfile> trusted_certs.pem
+
+The name of the file containing a set of trusted self-signed CA
+certificates in PEM format. See the similar option of
+L<verify(1)> for additional details. Either this option
+or B<-CApath> must be specified.
+(Optional)
+
+=item B<-untrusted> cert_file.pem
+
+Set of additional untrusted certificates in PEM format which may be
+needed when building the certificate chain for the TSA's signing
+certificate. This file must contain the TSA signing certificate and
+all intermediate CA certificates unless the response includes them.
+(Optional)
+
+=item I<verify options>
+
+The options B<-attime timestamp>, B<-check_ss_sig>, B<-crl_check>,
+B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>,
+B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>,
+B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>,
+B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>,
+B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>,
+B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>,
+B<-verify_name>, and B<-x509_strict> can be used to control timestamp
+verification. See L<verify(1)>.
+
+=back
+
+=head1 CONFIGURATION FILE OPTIONS
+
+The B<-query> and B<-reply> commands make use of a configuration file
+defined by the B<OPENSSL_CONF> environment variable. See L<config(5)>
+for a general description of the syntax of the config file. The
+B<-query> command uses only the symbolic OID names section
+and it can work without it. However, the B<-reply> command needs the
+config file for its operation.
+
+When there is a command line switch equivalent of a variable the
+switch always overrides the settings in the config file.
+
+=over 4
+
+=item B<tsa> section, B<default_tsa>
+
+This is the main section and it specifies the name of another section
+that contains all the options for the B<-reply> command. This default
+section can be overridden with the B<-section> command line switch. (Optional)
+
+=item B<oid_file>
+
+See L<ca(1)> for description. (Optional)
+
+=item B<oid_section>
+
+See L<ca(1)> for description. (Optional)
+
+=item B<RANDFILE>
+
+See L<ca(1)> for description. (Optional)
+
+=item B<serial>
+
+The name of the file containing the hexadecimal serial number of the
+last time stamp response created. This number is incremented by 1 for
+each response. If the file does not exist at the time of response
+generation a new file is created with serial number 1. (Mandatory)
+
+=item B<crypto_device>
+
+Specifies the OpenSSL engine that will be set as the default for
+all available algorithms. The default value is builtin, you can specify
+any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM).
+(Optional)
+
+=item B<signer_cert>
+
+TSA signing certificate in PEM format. The same as the B<-signer>
+command line option. (Optional)
+
+=item B<certs>
+
+A file containing a set of PEM encoded certificates that need to be
+included in the response. The same as the B<-chain> command line
+option. (Optional)
+
+=item B<signer_key>
+
+The private key of the TSA in PEM format. The same as the B<-inkey>
+command line option. (Optional)
+
+=item B<signer_digest>
+
+Signing digest to use. The same as the
+B<-sha1|-sha224|-sha256|-sha384|-sha512> command line option. (Optional)
+
+=item B<default_policy>
+
+The default policy to use when the request does not mandate any
+policy. The same as the B<-tspolicy> command line option. (Optional)
+
+=item B<other_policies>
+
+Comma separated list of policies that are also acceptable by the TSA
+and used only if the request explicitly specifies one of them. (Optional)
+
+=item B<digests>
+
+The list of message digest algorithms that the TSA accepts. At least
+one algorithm must be specified. (Mandatory)
+
+=item B<accuracy>
+
+The accuracy of the time source of the TSA in seconds, milliseconds
+and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
+the components is missing zero is assumed for that field. (Optional)
+
+=item B<clock_precision_digits>
+
+Specifies the maximum number of digits, which represent the fraction of
+seconds, that need to be included in the time field. The trailing zeroes
+must be removed from the time, so there might actually be fewer digits,
+or no fraction of seconds at all. Supported only on UNIX platforms.
+The maximum value is 6, default is 0.
+(Optional)
+
+=item B<ordering>
+
+If this option is yes the responses generated by this TSA can always
+be ordered, even if the time difference between two responses is less
+than the sum of their accuracies. Default is no. (Optional)
+
+=item B<tsa_name>
+
+Set this option to yes if the subject name of the TSA must be included in
+the TSA name field of the response. Default is no. (Optional)
+
+=item B<ess_cert_id_chain>
+
+The SignedData objects created by the TSA always contain the
+certificate identifier of the signing certificate in a signed
+attribute (see RFC 2634, Enhanced Security Services). If this option
+is set to yes and either the B<certs> variable or the B<-chain> option
+is specified then the certificate identifiers of the chain will also
+be included in the SigningCertificate signed attribute. If this
+variable is set to no, only the signing certificate identifier is
+included. Default is no. (Optional)
+
+=back
+
+=head1 ENVIRONMENT VARIABLES
+
+B<OPENSSL_CONF> contains the path of the configuration file and can be
+overridden by the B<-config> command line option.
+
+=head1 EXAMPLES
+
+All the examples below presume that B<OPENSSL_CONF> is set to a proper
+configuration file, e.g. the example configuration file
+openssl/apps/openssl.cnf will do.
+
+=head2 Time Stamp Request
+
+To create a time stamp request for design1.txt with SHA-1
+without nonce and policy and no certificate is required in the response:
+
+ openssl ts -query -data design1.txt -no_nonce \
+ -out design1.tsq
+
+To create a similar time stamp request with specifying the message imprint
+explicitly:
+
+ openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
+ -no_nonce -out design1.tsq
+
+To print the content of the previous request in human readable format:
+
+ openssl ts -query -in design1.tsq -text
+
+To create a time stamp request which includes the MD-5 digest
+of design2.txt, requests the signer certificate and nonce,
+specifies a policy id (assuming the tsa_policy1 name is defined in the
+OID section of the config file):
+
+ openssl ts -query -data design2.txt -md5 \
+ -tspolicy tsa_policy1 -cert -out design2.tsq
+
+=head2 Time Stamp Response
+
+Before generating a response a signing certificate must be created for
+the TSA that contains the B<timeStamping> critical extended key usage extension
+without any other key usage extensions. You can add the
+'extendedKeyUsage = critical,timeStamping' line to the user certificate section
+of the config file to generate a proper certificate. See L<req(1)>,
+L<ca(1)>, L<x509(1)> for instructions. The examples
+below assume that cacert.pem contains the certificate of the CA,
+tsacert.pem is the signing certificate issued by cacert.pem and
+tsakey.pem is the private key of the TSA.
+
+To create a time stamp response for a request:
+
+ openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
+ -signer tsacert.pem -out design1.tsr
+
+If you want to use the settings in the config file you could just write:
+
+ openssl ts -reply -queryfile design1.tsq -out design1.tsr
+
+To print a time stamp reply to stdout in human readable format:
+
+ openssl ts -reply -in design1.tsr -text
+
+To create a time stamp token instead of time stamp response:
+
+ openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
+
+To print a time stamp token to stdout in human readable format:
+
+ openssl ts -reply -in design1_token.der -token_in -text -token_out
+
+To extract the time stamp token from a response:
+
+ openssl ts -reply -in design1.tsr -out design1_token.der -token_out
+
+To add 'granted' status info to a time stamp token thereby creating a
+valid response:
+
+ openssl ts -reply -in design1_token.der -token_in -out design1.tsr
+
+=head2 Time Stamp Verification
+
+To verify a time stamp reply against a request:
+
+ openssl ts -verify -queryfile design1.tsq -in design1.tsr \
+ -CAfile cacert.pem -untrusted tsacert.pem
+
+To verify a time stamp reply that includes the certificate chain:
+
+ openssl ts -verify -queryfile design2.tsq -in design2.tsr \
+ -CAfile cacert.pem
+
+To verify a time stamp token against the original data file:
+ openssl ts -verify -data design2.txt -in design2.tsr \
+ -CAfile cacert.pem
+
+To verify a time stamp token against a message imprint:
+ openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
+ -in design2.tsr -CAfile cacert.pem
+
+You could also look at the 'test' directory for more examples.
+
+=head1 BUGS
+
+If you find any bugs or you have suggestions please write to
+Zoltan Glozik <zglozik@opentsa.org>. Known issues:
+
+=over 4
+
+=item * No support for time stamps over SMTP, though it is quite easy
+to implement an automatic e-mail based TSA with L<procmail(1)>
+and L<perl(1)>. HTTP server support is provided in the form of
+a separate apache module. HTTP client support is provided by
+L<tsget(1)>. Pure TCP/IP protocol is not supported.
+
+=item * The file containing the last serial number of the TSA is not
+locked when being read or written. This is a problem if more than one
+instance of L<openssl(1)> is trying to create a time stamp
+response at the same time. This is not an issue when using the apache
+server module, it does proper locking.
+
+=item * Look for the FIXME word in the source files.
+
+=item * The source code should really be reviewed by somebody else, too.
+
+=item * More testing is needed, I have done only some basic tests (see
+test/testtsa).
+
+=back
+
+=head1 SEE ALSO
+
+L<tsget(1)>, L<openssl(1)>, L<req(1)>,
+L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
+L<config(5)>
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+tsget - Time Stamping HTTP/HTTPS client
+
+=head1 SYNOPSIS
+
+B<tsget>
+B<-h> server_url
+[B<-e> extension]
+[B<-o> output]
+[B<-v>]
+[B<-d>]
+[B<-k> private_key.pem]
+[B<-p> key_password]
+[B<-c> client_cert.pem]
+[B<-C> CA_certs.pem]
+[B<-P> CA_path]
+[B<-r> file:file...]
+[B<-g> EGD_socket]
+[request]...
+
+=head1 DESCRIPTION
+
+The B<tsget> command can be used for sending a time stamp request, as
+specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing
+the time stamp response in a file. This tool cannot be used for creating the
+requests and verifying responses, you can use the OpenSSL B<ts(1)> command to
+do that. B<tsget> can send several requests to the server without closing
+the TCP connection if more than one requests are specified on the command
+line.
+
+The tool sends the following HTTP request for each time stamp request:
+
+ POST url HTTP/1.1
+ User-Agent: OpenTSA tsget.pl/<version>
+ Host: <host>:<port>
+ Pragma: no-cache
+ Content-Type: application/timestamp-query
+ Accept: application/timestamp-reply
+ Content-Length: length of body
+
+ ...binary request specified by the user...
+
+B<tsget> expects a response of type application/timestamp-reply, which is
+written to a file without any interpretation.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h> server_url
+
+The URL of the HTTP/HTTPS server listening for time stamp requests.
+
+=item B<-e> extension
+
+If the B<-o> option is not given this argument specifies the extension of the
+output files. The base name of the output file will be the same as those of
+the input files. Default extension is '.tsr'. (Optional)
+
+=item B<-o> output
+
+This option can be specified only when just one request is sent to the
+server. The time stamp response will be written to the given output file. '-'
+means standard output. In case of multiple time stamp requests or the absence
+of this argument the names of the output files will be derived from the names
+of the input files and the default or specified extension argument. (Optional)
+
+=item B<-v>
+
+The name of the currently processed request is printed on standard
+error. (Optional)
+
+=item B<-d>
+
+Switches on verbose mode for the underlying B<curl> library. You can see
+detailed debug messages for the connection. (Optional)
+
+=item B<-k> private_key.pem
+
+(HTTPS) In case of certificate-based client authentication over HTTPS
+<private_key.pem> must contain the private key of the user. The private key
+file can optionally be protected by a passphrase. The B<-c> option must also
+be specified. (Optional)
+
+=item B<-p> key_password
+
+(HTTPS) Specifies the passphrase for the private key specified by the B<-k>
+argument. If this option is omitted and the key is passphrase protected B<tsget>
+will ask for it. (Optional)
+
+=item B<-c> client_cert.pem
+
+(HTTPS) In case of certificate-based client authentication over HTTPS
+<client_cert.pem> must contain the X.509 certificate of the user. The B<-k>
+option must also be specified. If this option is not specified no
+certificate-based client authentication will take place. (Optional)
+
+=item B<-C> CA_certs.pem
+
+(HTTPS) The trusted CA certificate store. The certificate chain of the peer's
+certificate must include one of the CA certificates specified in this file.
+Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional)
+
+=item B<-P> CA_path
+
+(HTTPS) The path containing the trusted CA certificates to verify the peer's
+certificate. The directory must be prepared with the B<c_rehash>
+OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of
+HTTPS. (Optional)
+
+=item B<-rand> file:file...
+
+The files containing random data for seeding the random number
+generator. Multiple files can be specified, the separator is B<;> for
+MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
+
+=item B<-g> EGD_socket
+
+The name of an EGD socket to get random data from. (Optional)
+
+=item [request]...
+
+List of files containing B<RFC 3161> DER-encoded time stamp requests. If no
+requests are specified only one request will be sent to the server and it will be
+read from the standard input. (Optional)
+
+=back
+
+=head1 ENVIRONMENT VARIABLES
+
+The B<TSGET> environment variable can optionally contain default
+arguments. The content of this variable is added to the list of command line
+arguments.
+
+=head1 EXAMPLES
+
+The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid
+time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
+and at port 8443 for HTTPS requests, the TSA service is available at the /tsa
+absolute path.
+
+Get a time stamp response for file1.tsq over HTTP, output is written to
+file1.tsr:
+
+ tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq
+
+Get a time stamp response for file1.tsq and file2.tsq over HTTP showing
+progress, output is written to file1.reply and file2.reply respectively:
+
+ tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \
+ file1.tsq file2.tsq
+
+Create a time stamp request, write it to file3.tsq, send it to the server and
+write the response to file3.tsr:
+
+ openssl ts -query -data file3.txt -cert | tee file3.tsq \
+ | tsget -h http://tsa.opentsa.org:8080/tsa \
+ -o file3.tsr
+
+Get a time stamp response for file1.tsq over HTTPS without client
+authentication:
+
+ tsget -h https://tsa.opentsa.org:8443/tsa \
+ -C cacerts.pem file1.tsq
+
+Get a time stamp response for file1.tsq over HTTPS with certificate-based
+client authentication (it will ask for the passphrase if client_key.pem is
+protected):
+
+ tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
+ -k client_key.pem -c client_cert.pem file1.tsq
+
+You can shorten the previous command line if you make use of the B<TSGET>
+environment variable. The following commands do the same as the previous
+example:
+
+ TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
+ -k client_key.pem -c client_cert.pem'
+ export TSGET
+ tsget file1.tsq
+
+=head1 SEE ALSO
+
+L<openssl(1)>, L<ts(1)>, L<curl(1)>,
+B<RFC 3161>
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+verify - Utility to verify certificates
+
+=head1 SYNOPSIS
+
+B<openssl> B<verify>
+[B<-help>]
+[B<-CAfile file>]
+[B<-CApath directory>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-allow_proxy_certs>]
+[B<-attime timestamp>]
+[B<-check_ss_sig>]
+[B<-CRLfile file>]
+[B<-crl_download>]
+[B<-crl_check>]
+[B<-crl_check_all>]
+[B<-engine id>]
+[B<-explicit_policy>]
+[B<-extended_crl>]
+[B<-ignore_critical>]
+[B<-inhibit_any>]
+[B<-inhibit_map>]
+[B<-no_check_time>]
+[B<-partial_chain>]
+[B<-policy arg>]
+[B<-policy_check>]
+[B<-policy_print>]
+[B<-purpose purpose>]
+[B<-suiteB_128>]
+[B<-suiteB_128_only>]
+[B<-suiteB_192>]
+[B<-trusted_first>]
+[B<-no_alt_chains>]
+[B<-untrusted file>]
+[B<-trusted file>]
+[B<-use_deltas>]
+[B<-verbose>]
+[B<-auth_level level>]
+[B<-verify_depth num>]
+[B<-verify_email email>]
+[B<-verify_hostname hostname>]
+[B<-verify_ip ip>]
+[B<-verify_name name>]
+[B<-x509_strict>]
+[B<-show_chain>]
+[B<->]
+[certificates]
+
+=head1 DESCRIPTION
+
+The B<verify> command verifies certificate chains.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-CAfile file>
+
+A B<file> of trusted certificates.
+The file should contain one or more certificates in PEM format.
+
+=item B<-CApath directory>
+
+A directory of trusted certificates. The certificates should have names
+of the form: hash.0 or have symbolic links to them of this
+form ("hash" is the hashed certificate subject name: see the B<-hash> option
+of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
+create symbolic links to a directory of certificates.
+
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-allow_proxy_certs>
+
+Allow the verification of proxy certificates
+
+=item B<-attime timestamp>
+
+Perform validation checks using time specified by B<timestamp> and not
+current system time. B<timestamp> is the number of seconds since
+01.01.1970 (UNIX time).
+
+=item B<-check_ss_sig>
+
+Verify the signature on the self-signed root CA. This is disabled by default
+because it doesn't add any security.
+
+=item B<-CRLfile file>
+
+The B<file> should contain one or more CRLs in PEM format.
+This option can be specified more than once to include CRLs from multiple
+B<files>.
+
+=item B<-crl_download>
+
+Attempt to download CRL information for this certificate.
+
+=item B<-crl_check>
+
+Checks end entity certificate validity by attempting to look up a valid CRL.
+If a valid CRL cannot be found an error occurs.
+
+=item B<-crl_check_all>
+
+Checks the validity of B<all> certificates in the chain by attempting
+to look up valid CRLs.
+
+=item B<-engine id>
+
+Specifying an engine B<id> will cause L<verify(1)> to attempt to load the
+specified engine.
+The engine will then be set as the default for all its supported algorithms.
+If you want to load certificates or CRLs that require engine support via any of
+the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
+must be specified before those options.
+
+=item B<-explicit_policy>
+
+Set policy variable require-explicit-policy (see RFC5280).
+
+=item B<-extended_crl>
+
+Enable extended CRL features such as indirect CRLs and alternate CRL
+signing keys.
+
+=item B<-ignore_critical>
+
+Normally if an unhandled critical extension is present which is not
+supported by OpenSSL the certificate is rejected (as required by RFC5280).
+If this option is set critical extensions are ignored.
+
+=item B<-inhibit_any>
+
+Set policy variable inhibit-any-policy (see RFC5280).
+
+=item B<-inhibit_map>
+
+Set policy variable inhibit-policy-mapping (see RFC5280).
+
+=item B<-no_check_time>
+
+This option suppresses checking the validity period of certificates and CRLs
+against the current time. If option B<-attime timestamp> is used to specify
+a verification time, the check is not suppressed.
+
+=item B<-partial_chain>
+
+Allow verification to succeed even if a I<complete> chain cannot be built to a
+self-signed trust-anchor, provided it is possible to construct a chain to a
+trusted certificate that might not be self-signed.
+
+=item B<-policy arg>
+
+Enable policy processing and add B<arg> to the user-initial-policy-set (see
+RFC5280). The policy B<arg> can be an object name an OID in numeric form.
+This argument can appear more than once.
+
+=item B<-policy_check>
+
+Enables certificate policy processing.
+
+=item B<-policy_print>
+
+Print out diagnostics related to policy processing.
+
+=item B<-purpose purpose>
+
+The intended use for the certificate. If this option is not specified,
+B<verify> will not consider certificate purpose during chain verification.
+Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
+B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more
+information.
+
+=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
+
+enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
+192 bit, or only 192 bit Level of Security respectively.
+See RFC6460 for details. In particular the supported signature algorithms are
+reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
+P-256 and P-384.
+
+=item B<-trusted_first>
+
+When constructing the certificate chain, use the trusted certificates specified
+via B<-CAfile>, B<-CApath> or B<-trusted> before any certificates specified via
+B<-untrusted>.
+This can be useful in environments with Bridge or Cross-Certified CAs.
+As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
+
+=item B<-no_alt_chains>
+
+By default, unless B<-trusted_first> is specified, when building a certificate
+chain, if the first certificate chain found is not trusted, then OpenSSL will
+attempt to replace untrusted issuer certificates with certificates from the
+trust store to see if an alternative chain can be found that is trusted.
+As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
+effect.
+
+=item B<-untrusted file>
+
+A B<file> of additional untrusted certificates (intermediate issuer CAs) used
+to construct a certificate chain from the subject certificate to a trust-anchor.
+The B<file> should contain one or more certificates in PEM format.
+This option can be specified more than once to include untrusted certificates
+from multiple B<files>.
+
+=item B<-trusted file>
+
+A B<file> of trusted certificates, which must be self-signed, unless the
+B<-partial_chain> option is specified.
+The B<file> contains one or more certificates in PEM format.
+With this option, no additional (e.g., default) certificate lists are
+consulted.
+That is, the only trust-anchors are those listed in B<file>.
+This option can be specified more than once to include trusted certificates
+from multiple B<files>.
+This option implies the B<-no-CAfile> and B<-no-CApath> options.
+This option cannot be used in combination with either of the B<-CAfile> or
+B<-CApath> options.
+
+=item B<-use_deltas>
+
+Enable support for delta CRLs.
+
+=item B<-verbose>
+
+Print extra information about the operations being performed.
+
+=item B<-auth_level level>
+
+Set the certificate chain authentication security level to B<level>.
+The authentication security level determines the acceptable signature and
+public key strength when verifying certificate chains.
+For a certificate chain to validate, the public keys of all the certificates
+must meet the specified security B<level>.
+The signature algorithm security level is enforced for all the certificates in
+the chain except for the chain's I<trust anchor>, which is either directly
+trusted or validated by means other than its signature.
+See L<SSL_CTX_set_security_level(3)> for the definitions of the available
+levels.
+The default security level is -1, or "not set".
+At security level 0 or lower all algorithms are acceptable.
+Security level 1 requires at least 80-bit-equivalent security and is broadly
+interoperable, though it will, for example, reject MD5 signatures or RSA keys
+shorter than 1024 bits.
+
+=item B<-verify_depth num>
+
+Limit the certificate chain to B<num> intermediate CA certificates.
+A maximal depth chain can have up to B<num+2> certificates, since neither the
+end-entity certificate nor the trust-anchor certificate count against the
+B<-verify_depth> limit.
+
+=item B<-verify_email email>
+
+Verify if the B<email> matches the email address in Subject Alternative Name or
+the email in the subject Distinguished Name.
+
+=item B<-verify_hostname hostname>
+
+Verify if the B<hostname> matches DNS name in Subject Alternative Name or
+Common Name in the subject certificate.
+
+=item B<-verify_ip ip>
+
+Verify if the B<ip> matches the IP address in Subject Alternative Name of
+the subject certificate.
+
+=item B<-verify_name name>
+
+Use default verification policies like trust model and required certificate
+policies identified by B<name>.
+The trust model determines which auxiliary trust or reject OIDs are applicable
+to verifying the given certificate chain.
+See the B<-addtrust> and B<-addreject> options of the L<x509(1)> command-line
+utility.
+Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
+B<ssl_client>, B<ssl_server>.
+These mimics the combinations of purpose and trust settings used in SSL, CMS
+and S/MIME.
+As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
+specified, so the B<-verify_name> options are functionally equivalent to the
+corresponding B<-purpose> settings.
+
+=item B<-x509_strict>
+
+For strict X.509 compliance, disable non-compliant workarounds for broken
+certificates.
+
+=item B<-show_chain>
+
+Display information about the certificate chain that has been built (if
+successful). Certificates in the chain that came from the untrusted list will be
+flagged as "untrusted".
+
+=item B<->
+
+Indicates the last option. All arguments following this are assumed to be
+certificate files. This is useful if the first certificate filename begins
+with a B<->.
+
+=item B<certificates>
+
+One or more certificates to verify. If no certificates are given, B<verify>
+will attempt to read a certificate from standard input. Certificates must be
+in PEM format.
+
+=back
+
+=head1 VERIFY OPERATION
+
+The B<verify> program uses the same functions as the internal SSL and S/MIME
+verification, therefore this description applies to these verify operations
+too.
+
+There is one crucial difference between the verify operations performed
+by the B<verify> program: wherever possible an attempt is made to continue
+after an error whereas normally the verify operation would halt on the
+first error. This allows all the problems with a certificate chain to be
+determined.
+
+The verify operation consists of a number of separate steps.
+
+Firstly a certificate chain is built up starting from the supplied certificate
+and ending in the root CA.
+It is an error if the whole chain cannot be built up.
+The chain is built up by looking up the issuers certificate of the current
+certificate.
+If a certificate is found which is its own issuer it is assumed to be the root
+CA.
+
+The process of 'looking up the issuers certificate' itself involves a number of
+steps.
+After all certificates whose subject name matches the issuer name of the current
+certificate are subject to further tests.
+The relevant authority key identifier components of the current certificate (if
+present) must match the subject key identifier (if present) and issuer and
+serial number of the candidate issuer, in addition the keyUsage extension of
+the candidate issuer (if present) must permit certificate signing.
+
+The lookup first looks in the list of untrusted certificates and if no match
+is found the remaining lookups are from the trusted certificates. The root CA
+is always looked up in the trusted certificate list: if the certificate to
+verify is a root certificate then an exact match must be found in the trusted
+list.
+
+The second operation is to check every untrusted certificate's extensions for
+consistency with the supplied purpose. If the B<-purpose> option is not included
+then no checks are done. The supplied or "leaf" certificate must have extensions
+compatible with the supplied purpose and all other certificates must also be valid
+CA certificates. The precise extensions required are described in more detail in
+the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
+
+The third operation is to check the trust settings on the root CA. The root CA
+should be trusted for the supplied purpose.
+For compatibility with previous versions of OpenSSL, a certificate with no
+trust settings is considered to be valid for all purposes.
+
+The final operation is to check the validity of the certificate chain. The validity
+period is checked against the current system time and the notBefore and notAfter
+dates in the certificate. The certificate signatures are also checked at this
+point.
+
+If all operations complete successfully then certificate is considered valid. If
+any operation fails then the certificate is not valid.
+
+=head1 DIAGNOSTICS
+
+When a verify operation fails the output messages can be somewhat cryptic. The
+general form of the error message is:
+
+ server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
+ error 24 at 1 depth lookup:invalid CA certificate
+
+The first line contains the name of the certificate being verified followed by
+the subject name of the certificate. The second line contains the error number
+and the depth. The depth is number of the certificate being verified when a
+problem was detected starting with zero for the certificate being verified itself
+then 1 for the CA that signed the certificate and so on. Finally a text version
+of the error number is presented.
+
+A partial list of the error codes and messages is shown below, this also
+includes the name of the error code as defined in the header file x509_vfy.h
+Some of the error codes are defined but never returned: these are described
+as "unused".
+
+=over 4
+
+=item B<X509_V_OK>
+
+The operation was successful.
+
+=item B<X509_V_ERR_UNSPECIFIED>
+
+Unspecified error; should not happen.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT>
+
+The issuer certificate of a looked up certificate could not be found. This
+normally means the list of trusted certificates is not complete.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_CRL>
+
+The CRL of a certificate could not be found.
+
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
+
+The certificate signature could not be decrypted. This means that the actual signature value
+could not be determined rather than it not matching the expected value, this is only
+meaningful for RSA keys.
+
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
+
+The CRL signature could not be decrypted: this means that the actual signature value
+could not be determined rather than it not matching the expected value. Unused.
+
+=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
+
+The public key in the certificate SubjectPublicKeyInfo could not be read.
+
+=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
+
+The signature of the certificate is invalid.
+
+=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
+
+The signature of the certificate is invalid.
+
+=item B<X509_V_ERR_CERT_NOT_YET_VALID>
+
+The certificate is not yet valid: the notBefore date is after the current time.
+
+=item B<X509_V_ERR_CERT_HAS_EXPIRED>
+
+The certificate has expired: that is the notAfter date is before the current time.
+
+=item B<X509_V_ERR_CRL_NOT_YET_VALID>
+
+The CRL is not yet valid.
+
+=item B<X509_V_ERR_CRL_HAS_EXPIRED>
+
+The CRL has expired.
+
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
+
+The certificate notBefore field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
+
+The certificate notAfter field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
+
+The CRL lastUpdate field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
+
+The CRL nextUpdate field contains an invalid time.
+
+=item B<X509_V_ERR_OUT_OF_MEM>
+
+An error occurred trying to allocate memory. This should never happen.
+
+=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT>
+
+The passed certificate is self-signed and the same certificate cannot be found in the list of
+trusted certificates.
+
+=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN>
+
+The certificate chain could be built up using the untrusted certificates but the root could not
+be found locally.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
+
+The issuer certificate could not be found: this occurs if the issuer
+certificate of an untrusted certificate cannot be found.
+
+=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE>
+
+No signatures could be verified because the chain contains only one certificate and it is not
+self signed.
+
+=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
+
+The certificate chain length is greater than the supplied maximum depth. Unused.
+
+=item B<X509_V_ERR_CERT_REVOKED>
+
+The certificate has been revoked.
+
+=item B<X509_V_ERR_INVALID_CA>
+
+A CA certificate is invalid. Either it is not a CA or its extensions are not consistent
+with the supplied purpose.
+
+=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
+
+The basicConstraints pathlength parameter has been exceeded.
+
+=item B<X509_V_ERR_INVALID_PURPOSE>
+
+The supplied certificate cannot be used for the specified purpose.
+
+=item B<X509_V_ERR_CERT_UNTRUSTED>
+
+the root CA is not marked as trusted for the specified purpose.
+
+=item B<X509_V_ERR_CERT_REJECTED>
+
+The root CA is marked to reject the specified purpose.
+
+=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH>
+
+not used as of OpenSSL 1.1.0 as a result of the deprecation of the
+B<-issuer_checks> option.
+
+=item B<X509_V_ERR_AKID_SKID_MISMATCH>
+
+Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
+B<-issuer_checks> option.
+
+=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH>
+
+Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
+B<-issuer_checks> option.
+
+=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
+
+Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
+B<-issuer_checks> option.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
+
+Unable to get CRL issuer certificate.
+
+=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION>
+
+Unhandled critical extension.
+
+=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN>
+
+Key usage does not include CRL signing.
+
+=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION>
+
+Unhandled critical CRL extension.
+
+=item B<X509_V_ERR_INVALID_NON_CA>
+
+Invalid non-CA certificate has CA markings.
+
+=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED>
+
+Proxy path length constraint exceeded.
+
+=item B<X509_V_ERR_PROXY_SUBJECT_INVALID>
+
+Proxy certificate subject is invalid. It MUST be the same as the issuer
+with a single CN component added.
+
+=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE>
+
+Key usage does not include digital signature.
+
+=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED>
+
+Proxy certificates not allowed, please use B<-allow_proxy_certs>.
+
+=item B<X509_V_ERR_INVALID_EXTENSION>
+
+Invalid or inconsistent certificate extension.
+
+=item B<X509_V_ERR_INVALID_POLICY_EXTENSION>
+
+Invalid or inconsistent certificate policy extension.
+
+=item B<X509_V_ERR_NO_EXPLICIT_POLICY>
+
+No explicit policy.
+
+=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE>
+
+Different CRL scope.
+
+=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE>
+
+Unsupported extension feature.
+
+=item B<X509_V_ERR_UNNESTED_RESOURCE>
+
+RFC 3779 resource not subset of parent's resources.
+
+=item B<X509_V_ERR_PERMITTED_VIOLATION>
+
+Permitted subtree violation.
+
+=item B<X509_V_ERR_EXCLUDED_VIOLATION>
+
+Excluded subtree violation.
+
+=item B<X509_V_ERR_SUBTREE_MINMAX>
+
+Name constraints minimum and maximum not supported.
+
+=item B<X509_V_ERR_APPLICATION_VERIFICATION>
+
+Application verification failure. Unused.
+
+=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>
+
+Unsupported name constraint type.
+
+=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX>
+
+Unsupported or invalid name constraint syntax.
+
+=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>
+
+Unsupported or invalid name syntax.
+
+=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR>
+
+CRL path validation error.
+
+=item B<X509_V_ERR_PATH_LOOP>
+
+Path loop.
+
+=item B<X509_V_ERR_SUITE_B_INVALID_VERSION>
+
+Suite B: certificate version invalid.
+
+=item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM>
+
+Suite B: invalid public key algorithm.
+
+=item B<X509_V_ERR_SUITE_B_INVALID_CURVE>
+
+Suite B: invalid ECC curve.
+
+=item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM>
+
+Suite B: invalid signature algorithm.
+
+=item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED>
+
+Suite B: curve not allowed for this LOS.
+
+=item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256>
+
+Suite B: cannot sign P-384 with P-256.
+
+=item B<X509_V_ERR_HOSTNAME_MISMATCH>
+
+Hostname mismatch.
+
+=item B<X509_V_ERR_EMAIL_MISMATCH>
+
+Email address mismatch.
+
+=item B<X509_V_ERR_IP_ADDRESS_MISMATCH>
+
+IP address mismatch.
+
+=item B<X509_V_ERR_DANE_NO_MATCH>
+
+DANE TLSA authentication is enabled, but no TLSA records matched the
+certificate chain.
+This error is only possible in L<s_client(1)>.
+
+=back
+
+=head1 BUGS
+
+Although the issuer checks are a considerable improvement over the old technique they still
+suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
+trusted certificates with matching subject name must either appear in a file (as specified by the
+B<-CAfile> option) or a directory (as specified by B<-CApath>). If they occur in both then only
+the certificates in the file will be recognised.
+
+Previous versions of OpenSSL assume certificates with matching subject name are identical and
+mishandled them.
+
+Previous versions of this documentation swapped the meaning of the
+B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
+B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
+
+=head1 SEE ALSO
+
+L<x509(1)>
+
+=head1 HISTORY
+
+The B<-show_chain> option was first added to OpenSSL 1.1.0.
+
+The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
+is silently ignored.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+version - print OpenSSL version information
+
+=head1 SYNOPSIS
+
+B<openssl version>
+[B<-help>]
+[B<-a>]
+[B<-v>]
+[B<-b>]
+[B<-o>]
+[B<-f>]
+[B<-p>]
+[B<-d>]
+[B<-e>]
+
+=head1 DESCRIPTION
+
+This command is used to print out version information about OpenSSL.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-a>
+
+all information, this is the same as setting all the other flags.
+
+=item B<-v>
+
+the current OpenSSL version.
+
+=item B<-b>
+
+the date the current version of OpenSSL was built.
+
+=item B<-o>
+
+option information: various options set when the library was built.
+
+=item B<-f>
+
+compilation flags.
+
+=item B<-p>
+
+platform setting.
+
+=item B<-d>
+
+OPENSSLDIR setting.
+
+=item B<-e>
+
+ENGINESDIR setting.
+
+=back
+
+=head1 NOTES
+
+The output of B<openssl version -a> would typically be used when sending
+in a bug report.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+x509 - Certificate display and signing utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<x509>
+[B<-help>]
+[B<-inform DER|PEM|NET>]
+[B<-outform DER|PEM|NET>]
+[B<-keyform DER|PEM>]
+[B<-CAform DER|PEM>]
+[B<-CAkeyform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-serial>]
+[B<-hash>]
+[B<-subject_hash>]
+[B<-issuer_hash>]
+[B<-ocspid>]
+[B<-subject>]
+[B<-issuer>]
+[B<-nameopt option>]
+[B<-email>]
+[B<-ocsp_uri>]
+[B<-startdate>]
+[B<-enddate>]
+[B<-purpose>]
+[B<-dates>]
+[B<-checkend num>]
+[B<-modulus>]
+[B<-pubkey>]
+[B<-fingerprint>]
+[B<-alias>]
+[B<-noout>]
+[B<-trustout>]
+[B<-clrtrust>]
+[B<-clrreject>]
+[B<-addtrust arg>]
+[B<-addreject arg>]
+[B<-setalias arg>]
+[B<-days arg>]
+[B<-set_serial n>]
+[B<-signkey filename>]
+[B<-passin arg>]
+[B<-x509toreq>]
+[B<-req>]
+[B<-CA filename>]
+[B<-CAkey filename>]
+[B<-CAcreateserial>]
+[B<-CAserial filename>]
+[B<-force_pubkey key>]
+[B<-text>]
+[B<-certopt option>]
+[B<-C>]
+[B<-[digest]>]
+[B<-clrext>]
+[B<-extfile filename>]
+[B<-extensions section>]
+[B<-engine id>]
+
+=head1 DESCRIPTION
+
+The B<x509> command is a multi purpose certificate utility. It can be
+used to display certificate information, convert certificates to
+various forms, sign certificate requests like a "mini CA" or edit
+certificate trust settings.
+
+Since there are a large number of options they will split up into
+various sections.
+
+=head1 OPTIONS
+
+=head2 Input, Output, and General Purpose Options
+
+=over 4
+
+=item B<-help>
+
+Print out a usage message.
+
+=item B<-inform DER|PEM|NET>
+
+This specifies the input format normally the command will expect an X509
+certificate but this can change if other options such as B<-req> are
+present. The DER format is the DER encoding of the certificate and PEM
+is the base64 encoding of the DER encoding with header and footer lines
+added. The NET option is an obscure Netscape server format that is now
+obsolete.
+
+=item B<-outform DER|PEM|NET>
+
+This specifies the output format, the options have the same meaning as the
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a certificate from or standard input
+if this option is not specified.
+
+=item B<-out filename>
+
+This specifies the output filename to write to or standard output by
+default.
+
+=item B<-[digest]>
+
+the digest to use.
+This affects any signing or display option that uses a message
+digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+If not specified then SHA1 is used with B<-fingerprint> or
+the default digest for the signing algorithm is used, typically SHA256.
+
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<x509>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=back
+
+=head2 Display Options
+
+Note: the B<-alias> and B<-purpose> options are also display options
+but are described in the B<TRUST SETTINGS> section.
+
+=over 4
+
+=item B<-text>
+
+prints out the certificate in text form. Full details are output including the
+public key, signature algorithms, issuer and subject names, serial number
+any extensions present and any trust settings.
+
+=item B<-certopt option>
+
+customise the output format used with B<-text>. The B<option> argument can be
+a single option or multiple options separated by commas. The B<-certopt> switch
+may be also be used more than once to set multiple options. See the B<TEXT OPTIONS>
+section for more information.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the request.
+
+=item B<-pubkey>
+
+outputs the certificate's SubjectPublicKeyInfo block in PEM format.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the public key
+contained in the certificate.
+
+=item B<-serial>
+
+outputs the certificate serial number.
+
+=item B<-subject_hash>
+
+outputs the "hash" of the certificate subject name. This is used in OpenSSL to
+form an index to allow certificates in a directory to be looked up by subject
+name.
+
+=item B<-issuer_hash>
+
+outputs the "hash" of the certificate issuer name.
+
+=item B<-ocspid>
+
+outputs the OCSP hash values for the subject name and public key.
+
+=item B<-hash>
+
+synonym for "-subject_hash" for backward compatibility reasons.
+
+=item B<-subject_hash_old>
+
+outputs the "hash" of the certificate subject name using the older algorithm
+as used by OpenSSL versions before 1.0.0.
+
+=item B<-issuer_hash_old>
+
+outputs the "hash" of the certificate issuer name using the older algorithm
+as used by OpenSSL versions before 1.0.0.
+
+=item B<-subject>
+
+outputs the subject name.
+
+=item B<-issuer>
+
+outputs the issuer name.
+
+=item B<-nameopt option>
+
+option which determines how the subject or issuer names are displayed. The
+B<option> argument can be a single option or multiple options separated by
+commas. Alternatively the B<-nameopt> switch may be used more than once to
+set multiple options. See the B<NAME OPTIONS> section for more information.
+
+=item B<-email>
+
+outputs the email address(es) if any.
+
+=item B<-ocsp_uri>
+
+outputs the OCSP responder address(es) if any.
+
+=item B<-startdate>
+
+prints out the start date of the certificate, that is the notBefore date.
+
+=item B<-enddate>
+
+prints out the expiry date of the certificate, that is the notAfter date.
+
+=item B<-dates>
+
+prints out the start and expiry dates of a certificate.
+
+=item B<-checkend arg>
+
+checks if the certificate expires within the next B<arg> seconds and exits
+non-zero if yes it will expire or zero if not.
+
+=item B<-fingerprint>
+
+prints out the digest of the DER encoded version of the whole certificate
+(see digest options).
+
+=item B<-C>
+
+this outputs the certificate in the form of a C source file.
+
+=back
+
+=head2 Trust Settings
+
+A B<trusted certificate> is an ordinary certificate which has several
+additional pieces of information attached to it such as the permitted
+and prohibited uses of the certificate and an "alias".
+
+Normally when a certificate is being verified at least one certificate
+must be "trusted". By default a trusted certificate must be stored
+locally and must be a root CA: any certificate chain ending in this CA
+is then usable for any purpose.
+
+Trust settings currently are only used with a root CA. They allow a finer
+control over the purposes the root CA can be used for. For example a CA
+may be trusted for SSL client but not SSL server use.
+
+See the description of the B<verify> utility for more information on the
+meaning of trust settings.
+
+Future versions of OpenSSL will recognize trust settings on any
+certificate: not just root CAs.
+
+
+=over 4
+
+=item B<-trustout>
+
+this causes B<x509> to output a B<trusted> certificate. An ordinary
+or trusted certificate can be input but by default an ordinary
+certificate is output and any trust settings are discarded. With the
+B<-trustout> option a trusted certificate is output. A trusted
+certificate is automatically output if any trust settings are modified.
+
+=item B<-setalias arg>
+
+sets the alias of the certificate. This will allow the certificate
+to be referred to using a nickname for example "Steve's Certificate".
+
+=item B<-alias>
+
+outputs the certificate alias, if any.
+
+=item B<-clrtrust>
+
+clears all the permitted or trusted uses of the certificate.
+
+=item B<-clrreject>
+
+clears all the prohibited or rejected uses of the certificate.
+
+=item B<-addtrust arg>
+
+adds a trusted certificate use.
+Any object name can be used here but currently only B<clientAuth> (SSL client
+use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and
+B<anyExtendedKeyUsage> are used.
+As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
+enables all purposes when trusted.
+Other OpenSSL applications may define additional uses.
+
+=item B<-addreject arg>
+
+adds a prohibited use. It accepts the same values as the B<-addtrust>
+option.
+
+=item B<-purpose>
+
+this option performs tests on the certificate extensions and outputs
+the results. For a more complete description see the B<CERTIFICATE
+EXTENSIONS> section.
+
+=back
+
+=head2 Signing Options
+
+The B<x509> utility can be used to sign certificates and requests: it
+can thus behave like a "mini CA".
+
+=over 4
+
+=item B<-signkey filename>
+
+this option causes the input file to be self signed using the supplied
+private key.
+
+If the input file is a certificate it sets the issuer name to the
+subject name (i.e. makes it self signed) changes the public key to the
+supplied value and changes the start and end dates. The start date is
+set to the current time and the end date is set to a value determined
+by the B<-days> option. Any certificate extensions are retained unless
+the B<-clrext> option is supplied; this includes, for example, any existing
+key identifier extensions.
+
+If the input is a certificate request then a self signed certificate
+is created using the supplied private key using the subject name in
+the request.
+
+=item B<-passin arg>
+
+the key password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
+=item B<-clrext>
+
+delete any extensions from a certificate. This option is used when a
+certificate is being created from another certificate (for example with
+the B<-signkey> or the B<-CA> options). Normally all extensions are
+retained.
+
+=item B<-keyform PEM|DER>
+
+specifies the format (DER or PEM) of the private key file used in the
+B<-signkey> option.
+
+=item B<-days arg>
+
+specifies the number of days to make a certificate valid for. The default
+is 30 days.
+
+=item B<-x509toreq>
+
+converts a certificate into a certificate request. The B<-signkey> option
+is used to pass the required private key.
+
+=item B<-req>
+
+by default a certificate is expected on input. With this option a
+certificate request is expected instead.
+
+=item B<-set_serial n>
+
+specifies the serial number to use. This option can be used with either
+the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
+option the serial number file (as specified by the B<-CAserial> or
+B<-CAcreateserial> options) is not used.
+
+The serial number can be decimal or hex (if preceded by B<0x>).
+
+=item B<-CA filename>
+
+specifies the CA certificate to be used for signing. When this option is
+present B<x509> behaves like a "mini CA". The input file is signed by this
+CA using this option: that is its issuer name is set to the subject name
+of the CA and it is digitally signed using the CAs private key.
+
+This option is normally combined with the B<-req> option. Without the
+B<-req> option the input is a certificate which must be self signed.
+
+=item B<-CAkey filename>
+
+sets the CA private key to sign a certificate with. If this option is
+not specified then it is assumed that the CA private key is present in
+the CA certificate file.
+
+=item B<-CAserial filename>
+
+sets the CA serial number file to use.
+
+When the B<-CA> option is used to sign a certificate it uses a serial
+number specified in a file. This file consist of one line containing
+an even number of hex digits with the serial number to use. After each
+use the serial number is incremented and written out to the file again.
+
+The default filename consists of the CA certificate file base name with
+".srl" appended. For example if the CA certificate file is called
+"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
+
+=item B<-CAcreateserial>
+
+with this option the CA serial number file is created if it does not exist:
+it will contain the serial number "02" and the certificate being signed will
+have the 1 as its serial number. If the B<-CA> option is specified
+and the serial number file does not exist a random number is generated;
+this is the recommended practice.
+
+=item B<-extfile filename>
+
+file containing certificate extensions to use. If not specified then
+no extensions are added to the certificate.
+
+=item B<-extensions section>
+
+the section to add certificate extensions from. If this option is not
+specified then the extensions should either be contained in the unnamed
+(default) section or the default section should contain a variable called
+"extensions" which contains the section to use. See the
+L<x509v3_config(5)> manual page for details of the
+extension section format.
+
+=item B<-force_pubkey key>
+
+when a certificate is created set its public key to B<key> instead of the
+key in the certificate or certificate request. This option is useful for
+creating certificates where the algorithm can't normally sign requests, for
+example DH.
+
+The format or B<key> can be specified using the B<-keyform> option.
+
+=back
+
+=head2 Name Options
+
+The B<nameopt> command line switch determines how the subject and issuer
+names are displayed. If no B<nameopt> switch is present the default "oneline"
+format is used which is compatible with previous versions of OpenSSL.
+Each option is described in detail below, all options can be preceded by
+a B<-> to turn the option off. Only the first four will normally be used.
+
+=over 4
+
+=item B<compat>
+
+use the old format.
+
+=item B<RFC2253>
+
+displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
+B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
+B<sep_comma_plus>, B<dn_rev> and B<sname>.
+
+=item B<oneline>
+
+a oneline format which is more readable than RFC2253. It is equivalent to
+specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
+B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
+options. This is the I<default> of no name options are given explicitly.
+
+=item B<multiline>
+
+a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
+B<space_eq>, B<lname> and B<align>.
+
+=item B<esc_2253>
+
+escape the "special" characters required by RFC2253 in a field. That is
+B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
+and a space character at the beginning or end of a string.
+
+=item B<esc_2254>
+
+escape the "special" characters required by RFC2254 in a field. That is
+the B<NUL> character as well as and B<()*>.
+
+=item B<esc_ctrl>
+
+escape control characters. That is those with ASCII values less than
+0x20 (space) and the delete (0x7f) character. They are escaped using the
+RFC2253 \XX notation (where XX are two hex digits representing the
+character value).
+
+=item B<esc_msb>
+
+escape characters with the MSB set, that is with ASCII values larger than
+127.
+
+=item B<use_quote>
+
+escapes some characters by surrounding the whole string with B<"> characters,
+without the option all escaping is done with the B<\> character.
+
+=item B<utf8>
+
+convert all strings to UTF8 format first. This is required by RFC2253. If
+you are lucky enough to have a UTF8 compatible terminal then the use
+of this option (and B<not> setting B<esc_msb>) may result in the correct
+display of multibyte (international) characters. Is this option is not
+present then multibyte characters larger than 0xff will be represented
+using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
+Also if this option is off any UTF8Strings will be converted to their
+character form first.
+
+=item B<ignore_type>
+
+this option does not attempt to interpret multibyte characters in any
+way. That is their content octets are merely dumped as though one octet
+represents each character. This is useful for diagnostic purposes but
+will result in rather odd looking output.
+
+=item B<show_type>
+
+show the type of the ASN1 character string. The type precedes the
+field contents. For example "BMPSTRING: Hello World".
+
+=item B<dump_der>
+
+when this option is set any fields that need to be hexdumped will
+be dumped using the DER encoding of the field. Otherwise just the
+content octets will be displayed. Both options use the RFC2253
+B<#XXXX...> format.
+
+=item B<dump_nostr>
+
+dump non character string types (for example OCTET STRING) if this
+option is not set then non character string types will be displayed
+as though each content octet represents a single character.
+
+=item B<dump_all>
+
+dump all fields. This option when used with B<dump_der> allows the
+DER encoding of the structure to be unambiguously determined.
+
+=item B<dump_unknown>
+
+dump any field whose OID is not recognised by OpenSSL.
+
+=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
+B<sep_multiline>
+
+these options determine the field separators. The first character is
+between RDNs and the second between multiple AVAs (multiple AVAs are
+very rare and their use is discouraged). The options ending in
+"space" additionally place a space after the separator to make it
+more readable. The B<sep_multiline> uses a linefeed character for
+the RDN separator and a spaced B<+> for the AVA separator. It also
+indents the fields by four characters. If no field separator is specified
+then B<sep_comma_plus_space> is used by default.
+
+=item B<dn_rev>
+
+reverse the fields of the DN. This is required by RFC2253. As a side
+effect this also reverses the order of multiple AVAs but this is
+permissible.
+
+=item B<nofname>, B<sname>, B<lname>, B<oid>
+
+these options alter how the field name is displayed. B<nofname> does
+not display the field at all. B<sname> uses the "short name" form
+(CN for commonName for example). B<lname> uses the long form.
+B<oid> represents the OID in numerical form and is useful for
+diagnostic purpose.
+
+=item B<align>
+
+align field values for a more readable output. Only usable with
+B<sep_multiline>.
+
+=item B<space_eq>
+
+places spaces round the B<=> character which follows the field
+name.
+
+=back
+
+=head2 Text Options
+
+As well as customising the name output format, it is also possible to
+customise the actual fields printed using the B<certopt> options when
+the B<text> option is present. The default behaviour is to print all fields.
+
+=over 4
+
+=item B<compatible>
+
+use the old format. This is equivalent to specifying no output options at all.
+
+=item B<no_header>
+
+don't print header information: that is the lines saying "Certificate" and "Data".
+
+=item B<no_version>
+
+don't print out the version number.
+
+=item B<no_serial>
+
+don't print out the serial number.
+
+=item B<no_signame>
+
+don't print out the signature algorithm used.
+
+=item B<no_validity>
+
+don't print the validity, that is the B<notBefore> and B<notAfter> fields.
+
+=item B<no_subject>
+
+don't print out the subject name.
+
+=item B<no_issuer>
+
+don't print out the issuer name.
+
+=item B<no_pubkey>
+
+don't print out the public key.
+
+=item B<no_sigdump>
+
+don't give a hexadecimal dump of the certificate signature.
+
+=item B<no_aux>
+
+don't print out certificate trust information.
+
+=item B<no_extensions>
+
+don't print out any X509V3 extensions.
+
+=item B<ext_default>
+
+retain default extension behaviour: attempt to print out unsupported certificate extensions.
+
+=item B<ext_error>
+
+print an error message for unsupported certificate extensions.
+
+=item B<ext_parse>
+
+ASN1 parse unsupported extensions.
+
+=item B<ext_dump>
+
+hex dump unsupported extensions.
+
+=item B<ca_default>
+
+the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>,
+B<no_header>, and B<no_version>.
+
+=back
+
+=head1 EXAMPLES
+
+Note: in these examples the '\' means the example should be all on one
+line.
+
+Display the contents of a certificate:
+
+ openssl x509 -in cert.pem -noout -text
+
+Display the certificate serial number:
+
+ openssl x509 -in cert.pem -noout -serial
+
+Display the certificate subject name:
+
+ openssl x509 -in cert.pem -noout -subject
+
+Display the certificate subject name in RFC2253 form:
+
+ openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
+
+Display the certificate subject name in oneline form on a terminal
+supporting UTF8:
+
+ openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
+
+Display the certificate MD5 fingerprint:
+
+ openssl x509 -in cert.pem -noout -fingerprint
+
+Display the certificate SHA1 fingerprint:
+
+ openssl x509 -sha1 -in cert.pem -noout -fingerprint
+
+Convert a certificate from PEM to DER format:
+
+ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
+
+Convert a certificate to a certificate request:
+
+ openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
+
+Convert a certificate request into a self signed certificate using
+extensions for a CA:
+
+ openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
+ -signkey key.pem -out cacert.pem
+
+Sign a certificate request using the CA certificate above and add user
+certificate extensions:
+
+ openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
+ -CA cacert.pem -CAkey key.pem -CAcreateserial
+
+
+Set a certificate to be trusted for SSL client use and change set its alias to
+"Steve's Class 1 CA"
+
+ openssl x509 -in cert.pem -addtrust clientAuth \
+ -setalias "Steve's Class 1 CA" -out trust.pem
+
+=head1 NOTES
+
+The PEM format uses the header and footer lines:
+
+ -----BEGIN CERTIFICATE-----
+ -----END CERTIFICATE-----
+
+it will also handle files containing:
+
+ -----BEGIN X509 CERTIFICATE-----
+ -----END X509 CERTIFICATE-----
+
+Trusted certificates have the lines
+
+ -----BEGIN TRUSTED CERTIFICATE-----
+ -----END TRUSTED CERTIFICATE-----
+
+The conversion to UTF8 format used with the name options assumes that
+T61Strings use the ISO8859-1 character set. This is wrong but Netscape
+and MSIE do this as do many certificates. So although this is incorrect
+it is more likely to display the majority of certificates correctly.
+
+The B<-fingerprint> option takes the digest of the DER encoded certificate.
+This is commonly called a "fingerprint". Because of the nature of message
+digests the fingerprint of a certificate is unique to that certificate and
+two certificates with the same fingerprint can be considered to be the same.
+
+The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
+
+The B<-email> option searches the subject name and the subject alternative
+name extension. Only unique email addresses will be printed out: it will
+not print the same address more than once.
+
+=head1 CERTIFICATE EXTENSIONS
+
+The B<-purpose> option checks the certificate extensions and determines
+what the certificate can be used for. The actual checks done are rather
+complex and include various hacks and workarounds to handle broken
+certificates and software.
+
+The same code is used when verifying untrusted certificates in chains
+so this section is useful if a chain is rejected by the verify code.
+
+The basicConstraints extension CA flag is used to determine whether the
+certificate can be used as a CA. If the CA flag is true then it is a CA,
+if the CA flag is false then it is not a CA. B<All> CAs should have the
+CA flag set to true.
+
+If the basicConstraints extension is absent then the certificate is
+considered to be a "possible CA" other extensions are checked according
+to the intended use of the certificate. A warning is given in this case
+because the certificate should really not be regarded as a CA: however
+it is allowed to be a CA to work around some broken software.
+
+If the certificate is a V1 certificate (and thus has no extensions) and
+it is self signed it is also assumed to be a CA but a warning is again
+given: this is to work around the problem of Verisign roots which are V1
+self signed certificates.
+
+If the keyUsage extension is present then additional restraints are
+made on the uses of the certificate. A CA certificate B<must> have the
+keyCertSign bit set if the keyUsage extension is present.
+
+The extended key usage extension places additional restrictions on the
+certificate uses. If this extension is present (whether critical or not)
+the key can only be used for the purposes specified.
+
+A complete description of each test is given below. The comments about
+basicConstraints and keyUsage and V1 certificates above apply to B<all>
+CA certificates.
+
+
+=over 4
+
+=item B<SSL Client>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID. keyUsage must be absent or it must have the
+digitalSignature bit set. Netscape certificate type must be absent or it must
+have the SSL client bit set.
+
+=item B<SSL Client CA>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID. Netscape certificate type must be absent or it must have
+the SSL CA bit set: this is used as a work around if the basicConstraints
+extension is absent.
+
+=item B<SSL Server>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs. keyUsage must be absent or it
+must have the digitalSignature, the keyEncipherment set or both bits set.
+Netscape certificate type must be absent or have the SSL server bit set.
+
+=item B<SSL Server CA>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs. Netscape certificate type must
+be absent or the SSL CA bit must be set: this is used as a work around if the
+basicConstraints extension is absent.
+
+=item B<Netscape SSL Server>
+
+For Netscape SSL clients to connect to an SSL server it must have the
+keyEncipherment bit set if the keyUsage extension is present. This isn't
+always valid because some cipher suites use the key for digital signing.
+Otherwise it is the same as a normal SSL server.
+
+=item B<Common S/MIME Client Tests>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or should have the
+S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type
+then the SSL client bit is tolerated as an alternative but a warning is shown:
+this is because some Verisign certificates don't set the S/MIME bit.
+
+=item B<S/MIME Signing>
+
+In addition to the common S/MIME client tests the digitalSignature bit must
+be set if the keyUsage extension is present.
+
+=item B<S/MIME Encryption>
+
+In addition to the common S/MIME tests the keyEncipherment bit must be set
+if the keyUsage extension is present.
+
+=item B<S/MIME CA>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or must have the
+S/MIME CA bit set: this is used as a work around if the basicConstraints
+extension is absent.
+
+=item B<CRL Signing>
+
+The keyUsage extension must be absent or it must have the CRL signing bit
+set.
+
+=item B<CRL Signing CA>
+
+The normal CA tests apply. Except in this case the basicConstraints extension
+must be present.
+
+=back
+
+=head1 BUGS
+
+Extensions in certificates are not transferred to certificate requests and
+vice versa.
+
+It is possible to produce invalid certificates or requests by specifying the
+wrong private key or using inconsistent options in some cases: these should
+be checked.
+
+There should be options to explicitly set such things as start and end
+dates rather than an offset from the current time.
+
+=head1 SEE ALSO
+
+L<req(1)>, L<ca(1)>, L<genrsa(1)>,
+L<gendsa(1)>, L<verify(1)>,
+L<x509v3_config(5)>
+
+=head1 HISTORY
+
+The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
+before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
+of the distinguished name. In OpenSSL 1.0.0 and later it is based on a
+canonical version of the DN using SHA1. This means that any directories using
+the old form must have their links rebuilt using B<c_rehash> or similar.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64,
+ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN, - ASN.1 INTEGER and ENUMERATED utilities
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
+ int ASN1_INTEGER_get(const ASN1_INTEGER *a, long v);
+
+ int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
+ long ASN1_INTEGER_set(const ASN1_INTEGER *a);
+
+ int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);
+ int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);
+
+ ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
+ BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
+
+ int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
+ long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
+
+ int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
+ int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
+
+ ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
+ BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn);
+
+=head1 DESCRIPTION
+
+These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED>
+structures.
+
+ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type
+If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails
+(due to invalid type or the value being too big to fit into an B<int64_t> type)
+it returns 0.
+
+ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it
+converts to a B<uint64_t> type and an error is returned if the passed integer
+is negative.
+
+ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is
+NULL and -1 on error (which is ambiguous because -1 is a legitimate value for
+an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64()
+instead.
+
+ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the
+B<int64_t> value B<r>.
+
+ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the
+B<uint64_t> value B<r>.
+
+ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
+B<v>.
+
+BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai>
+is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then
+the existing structure will be used instead.
+
+ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is
+NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the
+existing structure will be used instead.
+
+ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
+ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN()
+behave in an identical way to their ASN1_INTEGER counterparts except they
+operate on an B<ASN1_ENUMERATED> value.
+
+ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to
+ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not
+fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
+instead.
+
+=head1 NOTES
+
+In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an
+integer of almost arbitrary size and so cannot always be represented by a C
+B<int64_t> type. However in many cases (for example version numbers) they
+represent small integers which can be more easily manipulated if converted to
+an appropriate C integer type.
+
+=head1 BUGS
+
+The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get()
+mean these functions should be avoided if possible. They are retained for
+compatibility. Normally the ambiguous return values are not legitimate
+values for the fields they represent.
+
+=head1 RETURN VALUES
+
+ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and
+ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only
+fail if a memory allocation error occurs.
+
+ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success
+and 0 for failure. They will fail if the passed type is incorrect (this will
+only happen if there is a programming error) or if the value exceeds the range
+of an B<int64_t> type.
+
+BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or
+B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will
+only fail due to a memory allocation error.
+
+ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure
+of NULL if an error occurs. They can fail if the passed type is incorrect
+(due to programming error) or due to a memory allocation failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+
+=head1 HISTORY
+
+ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(),
+ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64()
+were added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ const ASN1_ITEM *ASN1_ITEM_lookup(const char *name);
+ const ASN1_ITEM *ASN1_ITEM_get(size_t i);
+
+=head1 DESCRIPTION
+
+ASN1_ITEM_lookup() returns the B<ASN1_ITEM name>.
+
+ASN1_ITEM_get() returns the B<ASN1_ITEM> with index B<i>. This function
+returns B<NULL> if the index B<i> is out of range.
+
+=head1 RETURN VALUES
+
+ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid B<ASN1_ITEM> structure
+or B<NULL> if an error occurred.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ ASN1_OBJECT *ASN1_OBJECT_new(void);
+ void ASN1_OBJECT_free(ASN1_OBJECT *a);
+
+=head1 DESCRIPTION
+
+The ASN1_OBJECT allocation routines, allocate and free an
+ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
+
+ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.
+
+ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
+If B<a> is NULL, nothing is done.
+
+=head1 NOTES
+
+Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
+is almost never used in applications. The ASN1 object utility functions
+such as OBJ_nid2obj() are used instead.
+
+=head1 RETURN VALUES
+
+If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
+code that can be obtained by L<ERR_get_error(3)>.
+Otherwise it returns a pointer to the newly allocated structure.
+
+ASN1_OBJECT_free() returns no value.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
+ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
+ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ int ASN1_STRING_length(ASN1_STRING *x);
+ const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
+ unsigned char * ASN1_STRING_data(ASN1_STRING *x);
+
+ ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
+
+ int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
+
+ int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
+
+ int ASN1_STRING_type(const ASN1_STRING *x);
+
+ int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
+
+=head1 DESCRIPTION
+
+These functions allow an B<ASN1_STRING> structure to be manipulated.
+
+ASN1_STRING_length() returns the length of the content of B<x>.
+
+ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
+Since this is an internal pointer it should B<not> be freed or
+modified in any way.
+
+ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the
+returned value is not constant. This function is deprecated:
+applications should use ASN1_STRING_get0_data() instead.
+
+ASN1_STRING_dup() returns a copy of the structure B<a>.
+
+ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
+are identical. The string types and content are compared.
+
+ASN1_STRING_set() sets the data of string B<str> to the buffer
+B<data> or length B<len>. The supplied data is copied. If B<len>
+is -1 then the length is determined by strlen(data).
+
+ASN1_STRING_type() returns the type of B<x>, using standard constants
+such as B<V_ASN1_OCTET_STRING>.
+
+ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
+converted data is allocated in a buffer in B<*out>. The length of
+B<out> is returned or a negative error code. The buffer B<*out>
+should be freed using OPENSSL_free().
+
+=head1 NOTES
+
+Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
+structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed
+to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.
+B<ASN1_STRING> is also used for some B<CHOICE> types which consist
+entirely of primitive string types such as B<DirectoryString> and
+B<Time>.
+
+These functions should B<not> be used to examine or modify B<ASN1_INTEGER>
+or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED>
+utility functions should be used instead.
+
+In general it cannot be assumed that the data returned by ASN1_STRING_data()
+is null terminated or does not contain embedded nulls. The actual format
+of the data will depend on the actual string type itself: for example
+for 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 SEE ALSO
+
+L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -
+ASN1_STRING allocation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ ASN1_STRING * ASN1_STRING_new(void);
+ ASN1_STRING * ASN1_STRING_type_new(int type);
+ void ASN1_STRING_free(ASN1_STRING *a);
+
+=head1 DESCRIPTION
+
+ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type
+is undefined.
+
+ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
+type B<type>.
+
+ASN1_STRING_free() frees up B<a>.
+If B<a> is NULL nothing is done.
+
+=head1 NOTES
+
+Other string types call the B<ASN1_STRING> functions. For example
+ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
+
+=head1 RETURN VALUES
+
+ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
+ASN1_STRING structure or B<NULL> if an error occurred.
+
+ASN1_STRING_free() does not return a value.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
+ int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
+ int ASN1_STRING_print(BIO *out, const ASN1_STRING *str);
+
+
+=head1 DESCRIPTION
+
+These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
+represent all the ASN1 string types.
+
+ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
+the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
+to B<fp> instead.
+
+ASN1_STRING_print() prints B<str> to B<out> but using a different format to
+ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
+with '.'.
+
+=head1 NOTES
+
+ASN1_STRING_print() is a legacy function which should be avoided in new applications.
+
+Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
+suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
+
+The complete set of supported options for B<flags> is listed below.
+
+Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
+determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
+characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the
+MSB set are escaped: this option should B<not> be used if the terminal correctly
+interprets UTF8 sequences.
+
+Escaping takes several forms.
+
+If the character being escaped is a 16 bit character then the form "\UXXXX" is used
+using exactly four characters for the hex representation. If it is 32 bits then
+"\WXXXXXXXX" is used using eight characters of its hex representation. These forms
+will only be used if UTF8 conversion is not set (see below).
+
+Printable characters are normally escaped using the backslash '\' character. If
+B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by
+double quote characters: this is arguably more readable than the backslash
+notation. Other characters use the "\XX" using exactly two characters of the hex
+representation.
+
+If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8
+format first. If the terminal supports the display of UTF8 sequences then this
+option will correctly display multi byte characters.
+
+If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at
+all: everything is assumed to be one byte per character. This is primarily for
+debugging purposes and can result in confusing output in multi character strings.
+
+If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out
+before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str().
+
+The content of a string instead of being interpreted can be "dumped": this just
+outputs the value of the string using the form #XXXX using hex format for each
+octet.
+
+If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped.
+
+Normally non character string types (such as OCTET STRING) are assumed to be
+one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will
+be dumped instead.
+
+When a type is dumped normally just the content octets are printed, if
+B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
+instead (including tag and length octets).
+
+B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is
+equivalent to:
+ ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
+ ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
+
+=head1 SEE ALSO
+
+L<X509_NAME_print_ex(3)>,
+L<ASN1_tag2str(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string,
+ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions
+
+=head1 SYNOPSIS
+
+ ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
+ ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t,
+ int offset_day, long offset_sec);
+ int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
+ int ASN1_TIME_check(const ASN1_TIME *t);
+ int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
+
+ int ASN1_TIME_diff(int *pday, int *psec,
+ const ASN1_TIME *from, const ASN1_TIME *to);
+
+=head1 DESCRIPTION
+
+The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the
+time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME
+structure is allocated and returned.
+
+ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented
+by the time B<offset_day> and B<offset_sec> after the time_t value B<t>.
+The values of B<offset_day> or B<offset_sec> can be negative to set a
+time before B<t>. The B<offset_sec> value can also exceed the number of
+seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated
+and returned.
+
+ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time
+represented by string B<str> which must be in appropriate ASN.1 time
+format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
+
+ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>.
+
+ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable
+format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
+"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time
+structure has invalid format it prints out "Bad time value" and returns
+an error.
+
+ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
+B<from> and B<to>. If B<to> represents a time later than B<from> then
+one or both (depending on the time difference) of B<*pday> and B<*psec>
+will be positive. If B<to> represents a time earlier than B<from> then
+one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
+represent the same time then B<*pday> and B<*psec> will both be zero.
+If both B<*pday> and B<*psec> are non-zero they will always have the same
+sign. The value of B<*psec> will always be less than the number of seconds
+in a day. If B<from> or B<to> is NULL the current time is used.
+
+=head1 NOTES
+
+The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
+defined in RFC5280 et al. The time setting functions obey the rules outlined
+in RFC5280: if the date can be represented by UTCTime it is used, else
+GeneralizedTime is used.
+
+The ASN1_TIME structure is represented as an ASN1_STRING internally and can
+be freed up using ASN1_STRING_free().
+
+The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
+is made to correct ancient calendar changes (for example from Julian to
+Gregorian calendars).
+
+Some applications add offset times directly to a time_t value and pass the
+results to ASN1_TIME_set() (or equivalent). This can cause problems as the
+time_t value can overflow on some systems resulting in unexpected results.
+New applications should use ASN1_TIME_adj() instead and pass the offset value
+in the B<offset_sec> and B<offset_day> parameters instead of directly
+manipulating a time_t value.
+
+=head1 BUGS
+
+ASN1_TIME_print() currently does not print out the time zone: it either prints
+out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT
+anyway.
+
+=head1 EXAMPLES
+
+Set a time structure to one hour after the current time and print it out:
+
+ #include <time.h>
+ #include <openssl/asn1.h>
+ ASN1_TIME *tm;
+ time_t t;
+ BIO *b;
+ t = time(NULL);
+ tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
+ b = BIO_new_fp(stdout, BIO_NOCLOSE);
+ ASN1_TIME_print(b, tm);
+ ASN1_STRING_free(tm);
+ BIO_free(b);
+
+Determine if one time is later or sooner than the current time:
+
+ int day, sec;
+
+ if (!ASN1_TIME_diff(&day, &sec, NULL, to))
+ /* Invalid time format */
+
+ if (day > 0 || sec > 0)
+ printf("Later\n");
+ else if (day < 0 || sec < 0)
+ printf("Sooner\n");
+ else
+ printf("Same\n");
+
+=head1 RETURN VALUES
+
+ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure
+or NULL if an error occurred.
+
+ASN1_TIME_set_string() returns 1 if the time value is successfully set and
+0 otherwise.
+
+ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0
+otherwise.
+
+ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if
+an error occurred (I/O error or invalid time format).
+
+ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
+pass ASN1_TIME structure has invalid syntax for example.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility
+functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ int ASN1_TYPE_get(const ASN1_TYPE *a);
+ void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);
+ int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);
+ int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);
+
+ void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);
+ ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s,
+ ASN1_TYPE **t);
+
+=head1 DESCRIPTION
+
+These functions allow an ASN1_TYPE structure to be manipulated. The
+ASN1_TYPE structure can contain any ASN.1 type or constructed type
+such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.
+
+ASN1_TYPE_get() returns the type of B<a>.
+
+ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This
+function uses the pointer B<value> internally so it must B<not> be freed
+up after the call.
+
+ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>.
+
+ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if
+they are identical and non-zero otherwise.
+
+ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in
+B<t> using the ASN.1 structure B<it>. If successful it returns a pointer
+to the ASN.1 structure corresponding to B<it> which must be freed by the
+caller. If it fails it return NULL.
+
+ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s>
+corresponding to B<it> into an ASN1_TYPE. If successful the encoded
+ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type
+is written to B<t> overwriting any existing data. If B<t> is not NULL
+but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>.
+
+=head1 NOTES
+
+The type and meaning of the B<value> parameter for ASN1_TYPE_set() and
+ASN1_TYPE_set1() is determined by the B<type> parameter.
+If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN
+then the boolean is set to TRUE if B<value> is not NULL. If B<type> is
+V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type>
+is and ASN1_STRING structure. If B<type> corresponds to a primitive type
+(or a string type) then the contents of the ASN1_STRING contain the content
+octets of the type. If B<type> corresponds to a constructed type or
+a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the
+ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and
+length octets).
+
+ASN1_TYPE_cmp() may not return zero if two types are equivalent but have
+different encodings. For example the single content octet of the boolean TRUE
+value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will
+only return zero if the values are the same.
+
+If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
+return value is non-zero. Technically if both parameters are NULL the two
+types could be absent OPTIONAL fields and so should match, however passing
+NULL values could also indicate a programming error (for example an
+unparseable type which returns NULL) for types which do B<not> match. So
+applications should handle the case of two absent values separately.
+
+=head1 RETURN VALUES
+
+ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.
+
+ASN1_TYPE_set() does not return a value.
+
+ASN1_TYPE_set1() returns 1 for success and 0 for failure.
+
+ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise.
+
+ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or
+NULL on failure.
+
+ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or
+NULL on failure.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1.h>
+
+ ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
+ ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
+
+=head1 DESCRIPTION
+
+These functions generate the ASN1 encoding of a string
+in an B<ASN1_TYPE> structure.
+
+B<str> contains the string to encode B<nconf> or B<cnf> contains
+the optional configuration information where additional strings
+will be read from. B<nconf> will typically come from a config
+file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
+which will typically be used by X509 v3 certificate extension
+functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
+configuration will be used.
+
+=head1 GENERATION STRING FORMAT
+
+The actual data encoded is determined by the string B<str> and
+the configuration information. The general format of the string
+is:
+
+=over 2
+
+=item B<[modifier,]type[:value]>
+
+=back
+
+That is zero or more comma separated modifiers followed by a type
+followed by an optional colon and a value. The formats of B<type>,
+B<value> and B<modifier> are explained below.
+
+=head2 Supported Types
+
+The supported types are listed below. Unless otherwise specified
+only the B<ASCII> format is permissible.
+
+=over 2
+
+=item B<BOOLEAN>, B<BOOL>
+
+This encodes a boolean type. The B<value> string is mandatory and
+should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
+B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
+are acceptable.
+
+=item B<NULL>
+
+Encode the B<NULL> type, the B<value> string must not be present.
+
+=item B<INTEGER>, B<INT>
+
+Encodes an ASN1 B<INTEGER> type. The B<value> string represents
+the value of the integer, it can be prefaced by a minus sign and
+is normally interpreted as a decimal value unless the prefix B<0x>
+is included.
+
+=item B<ENUMERATED>, B<ENUM>
+
+Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
+B<INTEGER>.
+
+=item B<OBJECT>, B<OID>
+
+Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
+a short name, a long name or numerical format.
+
+=item B<UTCTIME>, B<UTC>
+
+Encodes an ASN1 B<UTCTime> structure, the value should be in
+the format B<YYMMDDHHMMSSZ>.
+
+=item B<GENERALIZEDTIME>, B<GENTIME>
+
+Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
+the format B<YYYYMMDDHHMMSSZ>.
+
+=item B<OCTETSTRING>, B<OCT>
+
+Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
+of this structure, the format strings B<ASCII> and B<HEX> can be
+used to specify the format of B<value>.
+
+=item B<BITSTRING>, B<BITSTR>
+
+Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
+of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
+can be used to specify the format of B<value>.
+
+If the format is anything other than B<BITLIST> the number of unused
+bits is set to zero.
+
+=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
+B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
+B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
+B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
+B<NUMERIC>
+
+These encode the corresponding string types. B<value> represents the
+contents of this structure. The format can be B<ASCII> or B<UTF8>.
+
+=item B<SEQUENCE>, B<SEQ>, B<SET>
+
+Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
+should be a section name which will contain the contents. The
+field names in the section are ignored and the values are in the
+generated string format. If B<value> is absent then an empty SEQUENCE
+will be encoded.
+
+=back
+
+=head2 Modifiers
+
+Modifiers affect the following structure, they can be used to
+add EXPLICIT or IMPLICIT tagging, add wrappers or to change
+the string format of the final type and value. The supported
+formats are documented below.
+
+=over 2
+
+=item B<EXPLICIT>, B<EXP>
+
+Add an explicit tag to the following structure. This string
+should be followed by a colon and the tag value to use as a
+decimal value.
+
+By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
+APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
+the default is CONTEXT SPECIFIC.
+
+=item B<IMPLICIT>, B<IMP>
+
+This is the same as B<EXPLICIT> except IMPLICIT tagging is used
+instead.
+
+=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
+
+The following structure is surrounded by an OCTET STRING, a SEQUENCE,
+a SET or a BIT STRING respectively. For a BIT STRING the number of unused
+bits is set to zero.
+
+=item B<FORMAT>
+
+This specifies the format of the ultimate value. It should be followed
+by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
+
+If no format specifier is included then B<ASCII> is used. If B<UTF8> is
+specified then the value string must be a valid B<UTF8> string. For B<HEX> the
+output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT
+STRING) is a comma separated list of the indices of the set bits, all other
+bits are zero.
+
+=back
+
+=head1 EXAMPLES
+
+A simple IA5String:
+
+ IA5STRING:Hello World
+
+An IA5String explicitly tagged:
+
+ EXPLICIT:0,IA5STRING:Hello World
+
+An IA5String explicitly tagged using APPLICATION tagging:
+
+ EXPLICIT:0A,IA5STRING:Hello World
+
+A BITSTRING with bits 1 and 5 set and all others zero:
+
+ FORMAT:BITLIST,BITSTRING:1,5
+
+A more complex example using a config file to produce a
+SEQUENCE consisting of a BOOL an OID and a UTF8String:
+
+ asn1 = SEQUENCE:seq_section
+
+ [seq_section]
+
+ field1 = BOOLEAN:TRUE
+ field2 = OID:commonName
+ field3 = UTF8:Third field
+
+This example produces an RSAPrivateKey structure, this is the
+key contained in the file client.pem in all OpenSSL distributions
+(note: the field names such as 'coeff' are ignored and are present just
+for clarity):
+
+ asn1=SEQUENCE:private_key
+ [private_key]
+ version=INTEGER:0
+
+ n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
+ D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
+
+ e=INTEGER:0x010001
+
+ d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
+ F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
+
+ p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
+ D4BD57
+
+ q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
+ 46EC4F
+
+ exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
+ 9C0A39B9
+
+ exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
+ E7B2458F
+
+ coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
+ 628657053A
+
+This example is the corresponding public key in a SubjectPublicKeyInfo
+structure:
+
+ # Start with a SEQUENCE
+ asn1=SEQUENCE:pubkeyinfo
+
+ # pubkeyinfo contains an algorithm identifier and the public key wrapped
+ # in a BIT STRING
+ [pubkeyinfo]
+ algorithm=SEQUENCE:rsa_alg
+ pubkey=BITWRAP,SEQUENCE:rsapubkey
+
+ # algorithm ID for RSA is just an OID and a NULL
+ [rsa_alg]
+ algorithm=OID:rsaEncryption
+ parameter=NULL
+
+ # Actual public key: modulus and exponent
+ [rsapubkey]
+ n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
+ D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
+
+ e=INTEGER:0x010001
+
+=head1 RETURN VALUES
+
+ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
+data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
+
+The error codes that can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
+ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
+ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage
+waiting for asynchronous jobs to complete
+
+=head1 SYNOPSIS
+
+ #include <openssl/async.h>
+
+ ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
+ void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
+ int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
+ OSSL_ASYNC_FD fd,
+ void *custom_data,
+ void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
+ OSSL_ASYNC_FD, void *));
+ int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
+ OSSL_ASYNC_FD *fd, void **custom_data);
+ int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
+ size_t *numfds);
+ int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
+ size_t *numaddfds, OSSL_ASYNC_FD *delfd,
+ size_t *numdelfds);
+ int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
+
+
+=head1 DESCRIPTION
+
+For an overview of how asynchronous operations are implemented in OpenSSL see
+L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous
+"session", i.e. a related set of crypto operations. For example in SSL terms
+this would have a one-to-one correspondence with an SSL connection.
+
+Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new()
+function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
+the job is started it is associated with the ASYNC_WAIT_CTX for the duration of
+that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one
+time, but can be reused after an ASYNC_JOB has finished for a subsequent
+ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed),
+application code cleans up with ASYNC_WAIT_CTX_free().
+
+ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling
+ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in
+the B<ctx> parameter will return the wait file descriptors associated with that
+job in B<*fd>. The number of file descriptors returned will be stored in
+B<*numfds>. It is the caller's responsibility to ensure that sufficient memory
+has been allocated in B<*fd> to receive all the file descriptors. Calling
+ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file
+descriptors but will still populate B<*numfds>. Therefore application code is
+typically expected to call this function twice: once to get the number of fds,
+and then again when sufficient memory has been allocated. If only one
+asynchronous engine is being used then normally this call will only ever return
+one fd. If multiple asynchronous engines are being used then more could be
+returned.
+
+The function ASYNC_WAIT_CTX_fds_have_changed() can be used to detect if any fds
+have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE
+result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has
+been received). The B<numaddfds> and B<numdelfds> parameters will be populated
+with the number of fds added or deleted respectively. B<*addfd> and B<*delfd>
+will be populated with the list of added and deleted fds respectively. Similarly
+to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
+NULL then the caller is responsible for ensuring sufficient memory is allocated.
+
+Implementors of async aware code (e.g. engines) are encouraged to return a
+stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn"
+of regularly changing fds - although no guarantees of this are provided to
+applications.
+
+Applications can wait for the file descriptor to be ready for "read" using a
+system function call such as select or poll (being ready for "read" indicates
+that the job should be resumed). If no file descriptor is made available then an
+application will have to periodically "poll" the job by attempting to restart it
+to see if it is ready to continue.
+
+Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job
+via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting
+on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an
+engine immediately prior to calling ASYNC_pause_job() and not by end user code.
+An existing association with a file descriptor can be obtained using
+ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
+these functions requires a B<key> value which is unique to the async aware
+code. This could be any unique value but a good candidate might be the
+B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and
+will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
+ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
+routine. This can be NULL but if provided will automatically get called when
+the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the
+fd or any other resources. Note: The "cleanup" routine does not get called if
+the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
+
+An example of typical usage might be an async capable engine. User code would
+initiate cryptographic operations. The engine would initiate those operations
+asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
+ASYNC_pause_job() to return control to the user code. The user code can then
+perform other tasks or wait for the job to be ready by calling "select" or other
+similar function on the wait file descriptor. The engine can signal to the user
+code that the job should be resumed by making the wait file descriptor
+"readable". Once resumed the engine should clear the wake signal on the wait
+file descriptor.
+
+=head1 RETURN VALUES
+
+ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
+NULL on error.
+
+ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
+ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
+success or 0 on error.
+
+=head1 NOTES
+
+On Windows platforms the openssl/async.h header is dependent on some
+of the types customarily made available by including windows.h. The
+application developer is likely to require control over when the latter
+is included, commonly as one of the first included headers. Therefore
+it is defined as an application developer's responsibility to include
+windows.h prior to async.h.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ASYNC_start_job(3)>
+
+=head1 HISTORY
+
+ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
+ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
+ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to
+OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ASYNC_get_wait_ctx,
+ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job,
+ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
+- asynchronous job management functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/async.h>
+
+ int ASYNC_init_thread(size_t max_size, size_t init_size);
+ void ASYNC_cleanup_thread(void);
+
+ int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,
+ int (*func)(void *), void *args, size_t size);
+ int ASYNC_pause_job(void);
+
+ ASYNC_JOB *ASYNC_get_current_job(void);
+ ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);
+ void ASYNC_block_pause(void);
+ void ASYNC_unblock_pause(void);
+
+ int ASYNC_is_capable(void);
+
+=head1 DESCRIPTION
+
+OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This
+represents code that can be started and executes until some event occurs. At
+that point the code can be paused and control returns to user code until some
+subsequent event indicates that the job can be resumed.
+
+The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for
+efficiency reasons, jobs can be created up front and reused many times. They are
+held in a pool until they are needed, at which point they are removed from the
+pool, used, and then returned to the pool when the job completes. If the user
+application is multi-threaded, then ASYNC_init_thread() may be called for each
+thread that will initiate asynchronous jobs. Before
+user code exits per-thread resources need to be cleaned up. This will normally
+occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly
+initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be
+outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to
+ensure this will result in memory leaks.
+
+The B<max_size> argument limits the number of ASYNC_JOBs that will be held in
+the pool. If B<max_size> is set to 0 then no upper limit is set. When an
+ASYNC_JOB is needed but there are none available in the pool already then one
+will be automatically created, as long as the total of ASYNC_JOBs managed by the
+pool does not exceed B<max_size>. When the pool is first initialised
+B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is
+not called before the pool is first used then it will be called automatically
+with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs
+created up front).
+
+An asynchronous job is started by calling the ASYNC_start_job() function.
+Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX
+object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should
+point to a location where the return value of the asynchronous function should
+be stored on completion of the job. B<func> represents the function that should
+be started asynchronously. The data pointed to by B<args> and of size B<size>
+will be copied and then passed as an argument to B<func> when the job starts.
+ASYNC_start_job will return one of the following values:
+
+=over 4
+
+=item B<ASYNC_ERR>
+
+An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
+see L<ERR_print_errors(3)>) for more details.
+
+=item B<ASYNC_NO_JOBS>
+
+There are no jobs currently available in the pool. This call can be retried
+again at a later time.
+
+=item B<ASYNC_PAUSE>
+
+The job was successfully started but was "paused" before it completed (see
+ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work
+can be performed (if desired) and the job restarted at a later time. To restart
+a job call ASYNC_start_job() again passing the job handle in B<*job>. The
+B<func>, B<args> and B<size> parameters will be ignored when restarting a job.
+When restarting a job ASYNC_start_job() B<must> be called from the same thread
+that the job was originally started from.
+
+=item B<ASYNC_FINISH>
+
+The job completed. B<*job> will be NULL and the return value from B<func> will
+be placed in B<*ret>.
+
+=back
+
+At any one time there can be a maximum of one job actively running per thread
+(you can have many that are paused). ASYNC_get_current_job() can be used to get
+a pointer to the currently executing ASYNC_JOB. If no job is currently executing
+then this will return NULL.
+
+If executing within the context of a job (i.e. having been called directly or
+indirectly by the function "func" passed as an argument to ASYNC_start_job())
+then ASYNC_pause_job() will immediately return control to the calling
+application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A
+subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the
+B<*job> parameter will resume execution from the ASYNC_pause_job() call. If
+ASYNC_pause_job() is called whilst not within the context of a job then no
+action is taken and ASYNC_pause_job() returns immediately.
+
+ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX
+for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated
+with them. Applications can wait for the file descriptor to be ready for "read"
+using a system function call such as select or poll (being ready for "read"
+indicates that the job should be resumed). If no file descriptor is made
+available then an application will have to periodically "poll" the job by
+attempting to restart it to see if it is ready to continue.
+
+An example of typical usage might be an async capable engine. User code would
+initiate cryptographic operations. The engine would initiate those operations
+asynchronously and then call L<ASYNC_WAIT_CTX_set_wait_fd(3)> followed by
+ASYNC_pause_job() to return control to the user code. The user code can then
+perform other tasks or wait for the job to be ready by calling "select" or other
+similar function on the wait file descriptor. The engine can signal to the user
+code that the job should be resumed by making the wait file descriptor
+"readable". Once resumed the engine should clear the wake signal on the wait
+file descriptor.
+
+The ASYNC_block_pause() function will prevent the currently active job from
+pausing. The block will remain in place until a subsequent call to
+ASYNC_unblock_pause(). These functions can be nested, e.g. if you call
+ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in
+order to re-enable pausing. If these functions are called while there is no
+currently active job then they have no effect. This functionality can be useful
+to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an
+application acquires a lock. It then calls some cryptographic function which
+invokes ASYNC_pause_job(). This returns control back to the code that created
+the ASYNC_JOB. If that code then attempts to acquire the same lock before
+resuming the original job then a deadlock can occur. By calling
+ASYNC_block_pause() immediately after acquiring the lock and
+ASYNC_unblock_pause() immediately before releasing it then this situation cannot
+occur.
+
+Some platforms cannot support async operations. The ASYNC_is_capable() function
+can be used to detect whether the current platform is async capable or not.
+
+=head1 RETURN VALUES
+
+ASYNC_init_thread returns 1 on success or 0 otherwise.
+
+ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or
+ASYNC_FINISH as described above.
+
+ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
+not within the context of an ASYNC_JOB then this is counted as success so 1 is
+returned.
+
+ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or
+NULL if not within the context of a job.
+
+ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.
+
+ASYNC_is_capable() returns 1 if the current platform is async capable or 0
+otherwise.
+
+=head1 NOTES
+
+On Windows platforms the openssl/async.h header is dependent on some
+of the types customarily made available by including windows.h. The
+application developer is likely to require control over when the latter
+is included, commonly as one of the first included headers. Therefore
+it is defined as an application developer's responsibility to include
+windows.h prior to async.h.
+
+=head1 EXAMPLE
+
+The following example demonstrates how to use most of the core async APIs:
+
+ #ifdef _WIN32
+ # include <windows.h>
+ #endif
+ #include <stdio.h>
+ #include <unistd.h>
+ #include <openssl/async.h>
+ #include <openssl/crypto.h>
+
+ int unique = 0;
+
+ void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
+ {
+ OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;
+ close(r);
+ close(*w);
+ OPENSSL_free(w);
+ }
+
+ int jobfunc(void *arg)
+ {
+ ASYNC_JOB *currjob;
+ unsigned char *msg;
+ int pipefds[2] = {0, 0};
+ OSSL_ASYNC_FD *wptr;
+ char buf = 'X';
+
+ currjob = ASYNC_get_current_job();
+ if (currjob != NULL) {
+ printf("Executing within a job\n");
+ } else {
+ printf("Not executing within a job - should not happen\n");
+ return 0;
+ }
+
+ msg = (unsigned char *)arg;
+ printf("Passed in message is: %s\n", msg);
+
+ if (pipe(pipefds) != 0) {
+ printf("Failed to create pipe\n");
+ return 0;
+ }
+ wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
+ if (wptr == NULL) {
+ printf("Failed to malloc\n");
+ return 0;
+ }
+ *wptr = pipefds[1];
+ ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,
+ pipefds[0], wptr, cleanup);
+
+ /*
+ * Normally some external event would cause this to happen at some
+ * later point - but we do it here for demo purposes, i.e.
+ * immediately signalling that the job is ready to be woken up after
+ * we return to main via ASYNC_pause_job().
+ */
+ write(pipefds[1], &buf, 1);
+
+ /* Return control back to main */
+ ASYNC_pause_job();
+
+ /* Clear the wake signal */
+ read(pipefds[0], &buf, 1);
+
+ printf ("Resumed the job after a pause\n");
+
+ return 1;
+ }
+
+ int main(void)
+ {
+ ASYNC_JOB *job = NULL;
+ ASYNC_WAIT_CTX *ctx = NULL;
+ int ret;
+ OSSL_ASYNC_FD waitfd;
+ fd_set waitfdset;
+ size_t numfds;
+ unsigned char msg[13] = "Hello world!";
+
+ printf("Starting...\n");
+
+ ctx = ASYNC_WAIT_CTX_new();
+ if (ctx == NULL) {
+ printf("Failed to create ASYNC_WAIT_CTX\n");
+ abort();
+ }
+
+ for (;;) {
+ switch(ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
+ case ASYNC_ERR:
+ case ASYNC_NO_JOBS:
+ printf("An error occurred\n");
+ goto end;
+ case ASYNC_PAUSE:
+ printf("Job was paused\n");
+ break;
+ case ASYNC_FINISH:
+ printf("Job finished with return value %d\n", ret);
+ goto end;
+ }
+
+ /* Wait for the job to be woken */
+ printf("Waiting for the job to be woken up\n");
+
+ if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
+ || numfds > 1) {
+ printf("Unexpected number of fds\n");
+ abort();
+ }
+ ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);
+ FD_ZERO(&waitfdset);
+ FD_SET(waitfd, &waitfdset);
+ select(waitfd + 1, &waitfdset, NULL, NULL, NULL);
+ }
+
+ end:
+ ASYNC_WAIT_CTX_free(ctx);
+ printf("Finishing\n");
+
+ return 0;
+ }
+
+The expected output from executing the above example program is:
+
+ Starting...
+ Executing within a job
+ Passed in message is: Hello world!
+ Job was paused
+ Waiting for the job to be woken up
+ Resumed the job after a pause
+ Job finished with return value 1
+ Finishing
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ERR_print_errors(3)>
+
+=head1 HISTORY
+
+ASYNC_init_thread, ASYNC_cleanup_thread,
+ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(),
+ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first
+added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
+BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/blowfish.h>
+
+ void BF_set_key(BF_KEY *key, int len, const unsigned char *data);
+
+ void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
+ BF_KEY *key, int enc);
+ void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
+ long length, BF_KEY *schedule, unsigned char *ivec, int enc);
+ void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, BF_KEY *schedule, unsigned char *ivec, int *num,
+ int enc);
+ void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, BF_KEY *schedule, unsigned char *ivec, int *num);
+ const char *BF_options(void);
+
+ void BF_encrypt(BF_LONG *data, const BF_KEY *key);
+ void BF_decrypt(BF_LONG *data, const BF_KEY *key);
+
+=head1 DESCRIPTION
+
+This library implements the Blowfish cipher, which was invented and described
+by Counterpane (see http://www.counterpane.com/blowfish.html ).
+
+Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
+It uses a variable size key, but typically, 128 bit (16 byte) keys are
+considered good for strong encryption. Blowfish can be used in the same
+modes as DES (see L<des_modes(7)>). Blowfish is currently one
+of the faster block ciphers. It is quite a bit faster than DES, and much
+faster than IDEA or RC2.
+
+Blowfish consists of a key setup phase and the actual encryption or decryption
+phase.
+
+BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key
+at B<data>.
+
+BF_ecb_encrypt() is the basic Blowfish encryption and decryption function.
+It encrypts or decrypts the first 64 bits of B<in> using the key B<key>,
+putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
+or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by
+B<in> and B<out> must be 64 bits in length, no less. If they are larger,
+everything after the first 64 bits is ignored.
+
+The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
+all operate on variable length data. They all take an initialization vector
+B<ivec> which needs to be passed along into the next call of the same function
+for the same message. B<ivec> may be initialized with anything, but the
+recipient needs to know what it was initialized with, or it won't be able
+to decrypt. Some programs and protocols simplify this, like SSH, where
+B<ivec> is simply initialized to zero.
+BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while
+BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable
+number of bytes (the amount does not have to be an exact multiple of 8). The
+purpose of the latter two is to simulate stream ciphers, and therefore, they
+need the parameter B<num>, which is a pointer to an integer where the current
+offset in B<ivec> is stored between calls. This integer must be initialized
+to zero when B<ivec> is initialized.
+
+BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It
+encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>,
+putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or
+decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte
+long initialization vector.
+
+BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback.
+It encrypts or decrypts the bytes in B<in> using the key B<schedule>,
+putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
+or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an
+8 byte long initialization vector. B<num> must point at an integer which must
+be initially zero.
+
+BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback.
+It uses the same parameters as BF_cfb64_encrypt(), which must be initialized
+the same way.
+
+BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish
+encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
+B<data>, using the key B<key>. These functions should not be used unless you
+implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt().
+If you still want to use these functions, you should be aware that they take
+each 32-bit chunk in host-byte order, which is little-endian on little-endian
+platforms and big-endian on big-endian ones.
+
+=head1 RETURN VALUES
+
+None of the functions presented here return any value.
+
+=head1 NOTE
+
+Applications should use the higher level functions
+L<EVP_EncryptInit(3)> etc. instead of calling these
+functions directly.
+
+=head1 SEE ALSO
+
+L<EVP_EncryptInit(3)>,
+L<des_modes(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake,
+BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
+BIO_ADDR_hostname_string, BIO_ADDR_service_string,
+BIO_ADDR_path_string - BIO_ADDR routines
+
+=head1 SYNOPSIS
+
+ #include <sys/types.h>
+ #include <openssl/bio.h>
+
+ typedef union bio_addr_st BIO_ADDR;
+
+ BIO_ADDR *BIO_ADDR_new(void);
+ void BIO_ADDR_free(BIO_ADDR *);
+ void BIO_ADDR_clear(BIO_ADDR *ap);
+ int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
+ const void *where, size_t wherelen, unsigned short port);
+ int BIO_ADDR_family(const BIO_ADDR *ap);
+ int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
+ unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
+ char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
+ char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
+ char *BIO_ADDR_path_string(const BIO_ADDR *ap);
+
+=head1 DESCRIPTION
+
+The B<BIO_ADDR> type is a wrapper around all types of socket
+addresses that OpenSSL deals with, currently transparently
+supporting AF_INET, AF_INET6 and AF_UNIX according to what's
+available on the platform at hand.
+
+BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
+with routines that will fill it with information, such as
+BIO_accept_ex().
+
+BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new().
+
+BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
+it back to an uninitialised state.
+
+BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of
+size B<wherelen> with an address in network byte order pointed at
+by B<where> and a port number in network byte order in B<port> (except
+for the B<AF_UNIX> protocol family, where B<port> is meaningless and
+therefore ignored) and populates the given B<BIO_ADDR> with them.
+In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected
+to be the length of the path string (not including the terminating
+NUL, such as the result of a call to strlen()).
+I<Read on about the addresses in L</RAW ADDRESSES> below>.
+
+BIO_ADDR_family() returns the protocol family of the given
+B<BIO_ADDR>. The possible non-error results are one of the
+constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the
+BIO_ADDR has not been initialised.
+
+BIO_ADDR_rawaddress() will write the raw address of the given
+B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL,
+and will set B<*l> to be the amount of bytes the raw address
+takes up if B<l> is non-NULL.
+A technique to only find out the size of the address is a call
+with B<p> set to B<NULL>. The raw address will be in network byte
+order, most significant byte first.
+In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the
+path string (not including the terminating NUL, such as the result of
+a call to strlen()).
+I<Read on about the addresses in L</RAW ADDRESSES> below>.
+
+BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>.
+The raw port will be in network byte order.
+
+BIO_ADDR_hostname_string() returns a character string with the
+hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string
+will contain the numerical form of the address. This only works for
+B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
+returned string has been allocated on the heap and must be freed
+with OPENSSL_free().
+
+BIO_ADDR_service_string() returns a character string with the
+service name of the port of the given B<BIO_ADDR>. If B<numeric>
+is 1, the string will contain the port number. This only works
+for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
+returned string has been allocated on the heap and must be freed
+with OPENSSL_free().
+
+BIO_ADDR_path_string() returns a character string with the path
+of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the
+protocol family AF_UNIX. The returned string has been allocated
+on the heap and must be freed with OPENSSL_free().
+
+=head1 RAW ADDRESSES
+
+Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a
+network byte order address of a specific site. Internally, those are
+treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct
+in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all
+depending on the protocol family the address is for.
+
+=head1 RETURN VALUES
+
+The string producing functions BIO_ADDR_hostname_string(),
+BIO_ADDR_service_string() and BIO_ADDR_path_string() will
+return B<NULL> on error and leave an error indication on the
+OpenSSL error stack.
+
+All other functions described here return 0 or B<NULL> when the
+information they should return isn't available.
+
+=head1 SEE ALSO
+
+L<BIO_connect(3)>, L<BIO_s_connect(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
+BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
+BIO_ADDRINFO_address,
+BIO_lookup
+- BIO_ADDRINFO type and routines
+
+=head1 SYNOPSIS
+
+ #include <sys/types.h>
+ #include <openssl/bio.h>
+
+ typedef union bio_addrinfo_st BIO_ADDRINFO;
+
+ enum BIO_lookup_type {
+ BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
+ };
+ int BIO_lookup(const char *node, const char *service,
+ enum BIO_lookup_type lookup_type,
+ int family, int socktype, BIO_ADDRINFO **res);
+
+ const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
+ int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
+ int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
+ int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
+ const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
+ void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
+
+=head1 DESCRIPTION
+
+The B<BIO_ADDRINFO> type is a wrapper for address information
+types provided on your platform.
+
+B<BIO_ADDRINFO> normally forms a chain of several that can be
+picked at one by one.
+
+BIO_lookup() looks up a specified B<host> and B<service>, and
+uses B<lookup_type> to determine what the default address should
+be if B<host> is B<NULL>. B<family>, B<socktype> are used to
+determine what protocol family and protocol should be used for
+the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
+AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM.
+B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
+chain.
+For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service>
+parameter and expects the B<node> parameter to hold the path to the
+socket file.
+
+BIO_ADDRINFO_family() returns the family of the given
+B<BIO_ADDRINFO>. The result will be one of the constants
+AF_INET, AF_INET6 and AF_UNIX.
+
+BIO_ADDRINFO_socktype() returns the socket type of the given
+B<BIO_ADDRINFO>. The result will be one of the constants
+SOCK_STREAM and SOCK_DGRAM.
+
+BIO_ADDRINFO_protocol() returns the protocol id of the given
+B<BIO_ADDRINFO>. The result will be one of the constants
+IPPROTO_TCP and IPPROTO_UDP.
+
+BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR>
+of the given B<BIO_ADDRINFO>.
+
+BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain
+from the given one.
+
+BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
+with the given one.
+
+=head1 RETURN VALUES
+
+BIO_lookup() returns 1 on success and 0 when an error occurred, and
+will leave an error indication on the OpenSSL error stack in that case.
+
+All other functions described here return 0 or B<NULL> when the
+information they should return isn't available.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
+socket communication setup routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ int BIO_socket(int domain, int socktype, int protocol, int options);
+ int BIO_connect(int sock, const BIO_ADDR *addr, int options);
+ int BIO_listen(int sock, const BIO_ADDR *addr, int options);
+ int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);
+ int BIO_closesocket(int sock);
+
+=head1 DESCRIPTION
+
+BIO_socket() creates a socket in the domain B<domain>, of type
+B<socktype> and B<protocol>. Socket B<options> are currently unused,
+but is present for future use.
+
+BIO_connect() connects B<sock> to the address and service given by
+B<addr>. Connection B<options> may be zero or any combination of
+B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>.
+The flags are described in L</FLAGS> below.
+
+BIO_listen() has B<sock> start listening on the address and service
+given by B<addr>. Connection B<options> may be zero or any
+combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>,
+B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>.
+The flags are described in L</FLAGS> below.
+
+BIO_accept_ex() waits for an incoming connections on the given
+socket B<accept_sock>. When it gets a connection, the address and
+port of the peer gets stored in B<peer> if that one is non-NULL.
+Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied
+on the accepted socket. The flags are described in L</FLAGS> below.
+
+BIO_closesocket() closes B<sock>.
+
+=head1 FLAGS
+
+=over 4
+
+=item BIO_SOCK_KEEPALIVE
+
+Enables regular sending of keep-alive messages.
+
+=item BIO_SOCK_NONBLOCK
+
+Sets the socket to non-blocking mode.
+
+=item BIO_SOCK_NODELAY
+
+Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With
+this set, any data will be sent as soon as possible instead of being
+buffered until there's enough for the socket to send out in one go.
+
+=item BIO_SOCK_REUSEADDR
+
+Try to reuse the address and port combination for a recently closed
+port.
+
+=item BIO_SOCK_V6_ONLY
+
+When creating an IPv6 socket, make it only listen for IPv6 addresses
+and not IPv4 addresses mapped to IPv6.
+
+=back
+
+These flags are bit flags, so they are to be combined with the
+C<|> operator, for example:
+
+ BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);
+
+=head1 RETURN VALUES
+
+BIO_socket() returns the socket number on success or B<INVALID_SOCKET>
+(-1) on error. When an error has occurred, the OpenSSL error stack
+will hold the error data and errno has the system error.
+
+BIO_connect() and BIO_listen() return 1 on success or 0 on error.
+When an error has occurred, the OpenSSL error stack will hold the error
+data and errno has the system error.
+
+BIO_accept_ex() returns the accepted socket on success or
+B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
+OpenSSL error stack will hold the error data and errno has the system
+error.
+
+=head1 HISTORY
+
+BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
+BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL
+1.1. Use the functions described above instead.
+
+=head1 SEE ALSO
+
+L<BIO_ADDR(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
+BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
+BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
+BIO_get_info_callback, BIO_set_info_callback - BIO control operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
+
+ long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
+ long BIO_callback_ctrl(BIO *b, int cmd, bio_info_cb cb);
+ char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
+ long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
+
+ int BIO_reset(BIO *b);
+ int BIO_seek(BIO *b, int ofs);
+ int BIO_tell(BIO *b);
+ int BIO_flush(BIO *b);
+ int BIO_eof(BIO *b);
+ int BIO_set_close(BIO *b, long flag);
+ int BIO_get_close(BIO *b);
+ int BIO_pending(BIO *b);
+ int BIO_wpending(BIO *b);
+ size_t BIO_ctrl_pending(BIO *b);
+ size_t BIO_ctrl_wpending(BIO *b);
+
+ int BIO_get_info_callback(BIO *b, bio_info_cb **cbp);
+ int BIO_set_info_callback(BIO *b, bio_info_cb *cb);
+
+=head1 DESCRIPTION
+
+BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
+are BIO "control" operations taking arguments of various types.
+These functions are not normally called directly, various macros
+are used instead. The standard macros are described below, macros
+specific to a particular type of BIO are described in the specific
+BIOs manual page as well as any special features of the standard
+calls.
+
+BIO_reset() typically resets a BIO to some initial state, in the case
+of file related BIOs for example it rewinds the file pointer to the
+start of the file.
+
+BIO_seek() resets a file related BIO's (that is file descriptor and
+FILE BIOs) file position pointer to B<ofs> bytes from start of file.
+
+BIO_tell() returns the current file position of a file related BIO.
+
+BIO_flush() normally writes out any internally buffered data, in some
+cases it is used to signal EOF and that no more data will be written.
+
+BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of
+"EOF" varies according to the BIO type.
+
+BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can
+take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
+in a source/sink BIO to indicate that the underlying I/O stream should
+be closed when the BIO is freed.
+
+BIO_get_close() returns the BIOs close flag.
+
+BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
+return the number of pending characters in the BIOs read and write buffers.
+Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending()
+return a size_t type and are functions, BIO_pending() and BIO_wpending() are
+macros which call BIO_ctrl().
+
+=head1 RETURN VALUES
+
+BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
+BIOs are an exception, they return 0 for success and -1 for failure.
+
+BIO_seek() and BIO_tell() both return the current file position on success
+and -1 for failure, except file BIOs which for BIO_seek() always return 0
+for success and -1 for failure.
+
+BIO_flush() returns 1 for success and 0 or -1 for failure.
+
+BIO_eof() returns 1 if EOF has been reached 0 otherwise.
+
+BIO_set_close() always returns 1.
+
+BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
+
+BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
+return the amount of pending data.
+
+=head1 NOTES
+
+BIO_flush(), because it can write data may return 0 or -1 indicating
+that the call should be retried later in a similar manner to BIO_write().
+The BIO_should_retry() call should be used and appropriate action taken
+is the call fails.
+
+The return values of BIO_pending() and BIO_wpending() may not reliably
+determine the amount of pending data in all cases. For example in the
+case of a file BIO some data may be available in the FILE structures
+internal buffers but it is not possible to determine this in a
+portably way. For other types of BIO they may not be supported.
+
+Filter BIOs if they do not internally handle a particular BIO_ctrl()
+operation usually pass the operation to the next BIO in the chain.
+This often means there is no need to locate the required BIO for
+a particular operation, it can be called on a chain and it will
+be automatically passed to the relevant BIO. However this can cause
+unexpected results: for example no current filter BIOs implement
+BIO_seek(), but this may still succeed if the chain ends in a FILE
+or file descriptor BIO.
+
+Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl()
+operation.
+
+=head1 BUGS
+
+Some of the return values are ambiguous and care should be taken. In
+particular a return value of 0 can be returned if an operation is not
+supported, if an error occurred, if EOF has not been reached and in
+the case of BIO_seek() on a file BIO for a successful operation.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_f_base64 - base64 BIO filter
+
+=for comment multiple includes
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/evp.h>
+
+ const BIO_METHOD *BIO_f_base64(void);
+
+=head1 DESCRIPTION
+
+BIO_f_base64() returns the base64 BIO method. This is a filter
+BIO that base64 encodes any data written through it and decodes
+any data read through it.
+
+Base64 BIOs do not support BIO_gets() or BIO_puts().
+
+BIO_flush() on a base64 BIO that is being written through is
+used to signal that no more data is to be encoded: this is used
+to flush the final block through the BIO.
+
+The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
+to encode the data all on one line or expect the data to be all
+on one line.
+
+=head1 NOTES
+
+Because of the format of base64 encoding the end of the encoded
+block cannot always be reliably determined.
+
+=head1 RETURN VALUES
+
+BIO_f_base64() returns the base64 BIO method.
+
+=head1 EXAMPLES
+
+Base64 encode the string "Hello World\n" and write the result
+to standard output:
+
+ BIO *bio, *b64;
+ char message[] = "Hello World \n";
+
+ b64 = BIO_new(BIO_f_base64());
+ bio = BIO_new_fp(stdout, BIO_NOCLOSE);
+ BIO_push(b64, bio);
+ BIO_write(b64, message, strlen(message));
+ BIO_flush(b64);
+
+ BIO_free_all(b64);
+
+Read Base64 encoded data from standard input and write the decoded
+data to standard output:
+
+ BIO *bio, *b64, *bio_out;
+ char inbuf[512];
+ int inlen;
+
+ b64 = BIO_new(BIO_f_base64());
+ bio = BIO_new_fp(stdin, BIO_NOCLOSE);
+ bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ BIO_push(b64, bio);
+ while((inlen = BIO_read(b64, inbuf, 512)) > 0)
+ BIO_write(bio_out, inbuf, inlen);
+
+ BIO_flush(bio_out);
+ BIO_free_all(b64);
+
+=head1 BUGS
+
+The ambiguity of EOF in base64 encoded data can cause additional
+data following the base64 encoded block to be misinterpreted.
+
+There should be some way of specifying a test that the BIO can perform
+to reliably determine EOF (for example a MIME boundary).
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_get_buffer_num_lines,
+BIO_set_read_buffer_size,
+BIO_set_write_buffer_size,
+BIO_set_buffer_size,
+BIO_set_buffer_read_data,
+BIO_f_buffer
+- buffering BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD *BIO_f_buffer(void);
+
+ long BIO_get_buffer_num_lines(BIO *b);
+ long BIO_set_read_buffer_size(BIO *b, long size);
+ long BIO_set_write_buffer_size(BIO *b, long size);
+ long BIO_set_buffer_size(BIO *b, long size);
+ long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
+
+=head1 DESCRIPTION
+
+BIO_f_buffer() returns the buffering BIO method.
+
+Data written to a buffering BIO is buffered and periodically written
+to the next BIO in the chain. Data read from a buffering BIO comes from
+an internal buffer which is filled from the next BIO in the chain.
+Both BIO_gets() and BIO_puts() are supported.
+
+Calling BIO_reset() on a buffering BIO clears any buffered data.
+
+BIO_get_buffer_num_lines() returns the number of lines currently buffered.
+
+BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
+set the read, write or both read and write buffer sizes to B<size>. The initial
+buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the
+buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared
+when the buffer is resized.
+
+BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>
+bytes of B<buf>. If B<num> is larger than the current buffer size the buffer
+is expanded.
+
+=head1 NOTES
+
+These functions, other than BIO_f_buffer(), are implemented as macros.
+
+Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
+next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
+possible to provide BIO_gets() functionality if the following BIOs do not
+support it (for example SSL BIOs).
+
+Data is only written to the next BIO in the chain when the write buffer fills
+or when BIO_flush() is called. It is therefore important to call BIO_flush()
+whenever any pending data should be written such as when removing a buffering
+BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
+source/sink BIO is non blocking.
+
+=head1 RETURN VALUES
+
+BIO_f_buffer() returns the buffering BIO method.
+
+BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
+
+BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
+return 1 if the buffer was successfully resized or 0 for failure.
+
+BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if
+there was an error.
+
+=head1 SEE ALSO
+
+L<BIO(3)>,
+L<BIO_reset(3)>,
+L<BIO_flush(3)>,
+L<BIO_pop(3)>,
+L<BIO_ctrl(3)>.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
+
+=for comment multiple includes
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/evp.h>
+
+ const BIO_METHOD *BIO_f_cipher(void);
+ void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
+ unsigned char *key, unsigned char *iv, int enc);
+ int BIO_get_cipher_status(BIO *b)
+ int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
+
+=head1 DESCRIPTION
+
+BIO_f_cipher() returns the cipher BIO method. This is a filter
+BIO that encrypts any data written through it, and decrypts any data
+read from it. It is a BIO wrapper for the cipher routines
+EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
+
+Cipher BIOs do not support BIO_gets() or BIO_puts().
+
+BIO_flush() on an encryption BIO that is being written through is
+used to signal that no more data is to be encrypted: this is used
+to flush and possibly pad the final block through the BIO.
+
+BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key>
+and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
+decryption.
+
+When reading from an encryption BIO the final block is automatically
+decrypted and checked when EOF is detected. BIO_get_cipher_status()
+is a BIO_ctrl() macro which can be called to determine whether the
+decryption operation was successful.
+
+BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
+BIO cipher context. The retrieved context can be used in conjunction
+with the standard cipher routines to set it up. This is useful when
+BIO_set_cipher() is not flexible enough for the applications needs.
+
+=head1 NOTES
+
+When encrypting BIO_flush() B<must> be called to flush the final block
+through the BIO. If it is not then the final block will fail a subsequent
+decrypt.
+
+When decrypting an error on the final block is signaled by a zero
+return value from the read operation. A successful decrypt followed
+by EOF will also return zero for the final read. BIO_get_cipher_status()
+should be called to determine if the decrypt was successful.
+
+As always, if BIO_gets() or BIO_puts() support is needed then it can
+be achieved by preceding the cipher BIO with a buffering BIO.
+
+=head1 RETURN VALUES
+
+BIO_f_cipher() returns the cipher BIO method.
+
+BIO_set_cipher() does not return a value.
+
+BIO_get_cipher_status() returns 1 for a successful decrypt and 0
+for failure.
+
+BIO_get_cipher_ctx() currently always returns 1.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
+
+=for comment multiple includes
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/evp.h>
+
+ const BIO_METHOD *BIO_f_md(void);
+ int BIO_set_md(BIO *b, EVP_MD *md);
+ int BIO_get_md(BIO *b, EVP_MD **mdp);
+ int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
+
+=head1 DESCRIPTION
+
+BIO_f_md() returns the message digest BIO method. This is a filter
+BIO that digests any data passed through it, it is a BIO wrapper
+for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
+and EVP_DigestFinal().
+
+Any data written or read through a digest BIO using BIO_read() and
+BIO_write() is digested.
+
+BIO_gets(), if its B<size> parameter is large enough finishes the
+digest calculation and returns the digest value. BIO_puts() is
+not supported.
+
+BIO_reset() reinitialises a digest BIO.
+
+BIO_set_md() sets the message digest of BIO B<b> to B<md>: this
+must be called to initialize a digest BIO before any data is
+passed through it. It is a BIO_ctrl() macro.
+
+BIO_get_md() places the a pointer to the digest BIOs digest method
+in B<mdp>, it is a BIO_ctrl() macro.
+
+BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.
+
+=head1 NOTES
+
+The context returned by BIO_get_md_ctx() can be used in calls
+to EVP_DigestFinal() and also the signature routines EVP_SignFinal()
+and EVP_VerifyFinal().
+
+The context returned by BIO_get_md_ctx() is an internal context
+structure. Changes made to this context will affect the digest
+BIO itself and the context pointer will become invalid when the digest
+BIO is freed.
+
+After the digest has been retrieved from a digest BIO it must be
+reinitialized by calling BIO_reset(), or BIO_set_md() before any more
+data is passed through it.
+
+If an application needs to call BIO_gets() or BIO_puts() through
+a chain containing digest BIOs then this can be done by prepending
+a buffering BIO.
+
+Calling BIO_get_md_ctx() will return the context and initialize the BIO
+state. This allows applications to initialize the context externally
+if the standard calls such as BIO_set_md() are not sufficiently flexible.
+
+=head1 RETURN VALUES
+
+BIO_f_md() returns the digest BIO method.
+
+BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and
+0 for failure.
+
+=head1 EXAMPLES
+
+The following example creates a BIO chain containing an SHA1 and MD5
+digest BIO and passes the string "Hello World" through it. Error
+checking has been omitted for clarity.
+
+ BIO *bio, *mdtmp;
+ char message[] = "Hello World";
+ bio = BIO_new(BIO_s_null());
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_sha1());
+ /* For BIO_push() we want to append the sink BIO and keep a note of
+ * the start of the chain.
+ */
+ bio = BIO_push(mdtmp, bio);
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_md5());
+ bio = BIO_push(mdtmp, bio);
+ /* Note: mdtmp can now be discarded */
+ BIO_write(bio, message, strlen(message));
+
+The next example digests data by reading through a chain instead:
+
+ BIO *bio, *mdtmp;
+ char buf[1024];
+ int rdlen;
+ bio = BIO_new_file(file, "rb");
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_sha1());
+ bio = BIO_push(mdtmp, bio);
+ mdtmp = BIO_new(BIO_f_md());
+ BIO_set_md(mdtmp, EVP_md5());
+ bio = BIO_push(mdtmp, bio);
+ do {
+ rdlen = BIO_read(bio, buf, sizeof(buf));
+ /* Might want to do something with the data here */
+ } while (rdlen > 0);
+
+This next example retrieves the message digests from a BIO chain and
+outputs them. This could be used with the examples above.
+
+ BIO *mdtmp;
+ unsigned char mdbuf[EVP_MAX_MD_SIZE];
+ int mdlen;
+ int i;
+ mdtmp = bio; /* Assume bio has previously been set up */
+ do {
+ EVP_MD *md;
+ mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
+ if (!mdtmp) break;
+ BIO_get_md(mdtmp, &md);
+ printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
+ mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
+ for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
+ printf("\n");
+ mdtmp = BIO_next(mdtmp);
+ } while (mdtmp);
+
+ BIO_free_all(bio);
+
+=head1 BUGS
+
+The lack of support for BIO_puts() and the non standard behaviour of
+BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()
+and BIO_puts() should be passed to the next BIO in the chain and digest
+the data passed through and that digests should be retrieved using a
+separate BIO_ctrl() call.
+
+=head1 HISTORY
+
+Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the
+BIO was initialized first.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_f_null - null filter
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD * BIO_f_null(void);
+
+=head1 DESCRIPTION
+
+BIO_f_null() returns the null filter BIO method. This is a filter BIO
+that does nothing.
+
+All requests to a null filter BIO are passed through to the next BIO in
+the chain: this means that a BIO chain containing a null filter BIO
+behaves just as though the BIO was not there.
+
+=head1 NOTES
+
+As may be apparent a null filter BIO is not particularly useful.
+
+=head1 RETURN VALUES
+
+BIO_f_null() returns the null filter BIO method.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_do_handshake,
+BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
+BIO_set_ssl_renegotiate_bytes,
+BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
+BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
+BIO_ssl_shutdown - SSL BIO
+
+=for comment multiple includes
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/ssl.h>
+
+ const BIO_METHOD *BIO_f_ssl(void);
+
+ long BIO_set_ssl(BIO *b, SSL *ssl, long c);
+ long BIO_get_ssl(BIO *b, SSL **sslp);
+ long BIO_set_ssl_mode(BIO *b, long client);
+ long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
+ long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
+ long BIO_get_num_renegotiates(BIO *b);
+
+ BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
+ BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
+ BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
+ int BIO_ssl_copy_session_id(BIO *to, BIO *from);
+ void BIO_ssl_shutdown(BIO *bio);
+
+ long BIO_do_handshake(BIO *b);
+
+=head1 DESCRIPTION
+
+BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
+is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
+SSL I/O.
+
+I/O performed on an SSL BIO communicates using the SSL protocol with
+the SSLs read and write BIOs. If an SSL connection is not established
+then an attempt is made to establish one on the first I/O call.
+
+If a BIO is appended to an SSL BIO using BIO_push() it is automatically
+used as the SSL BIOs read and write BIOs.
+
+Calling BIO_reset() on an SSL BIO closes down any current SSL connection
+by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
+the chain: this will typically disconnect the underlying transport.
+The SSL BIO is then reset to the initial accept or connect state.
+
+If the close flag is set when an SSL BIO is freed then the internal
+SSL structure is also freed using SSL_free().
+
+BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
+the close flag B<c>.
+
+BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
+manipulated using the standard SSL library functions.
+
+BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
+is 1 client mode is set. If B<client> is 0 server mode is set.
+
+BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
+to B<num>. When set after every B<num> bytes of I/O (read and write)
+the SSL session is automatically renegotiated. B<num> must be at
+least 512 bytes.
+
+BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
+B<seconds>. When the renegotiate timeout elapses the session is
+automatically renegotiated.
+
+BIO_get_num_renegotiates() returns the total number of session
+renegotiations due to I/O or timeout.
+
+BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
+client mode if B<client> is non zero.
+
+BIO_new_ssl_connect() creates a new BIO chain consisting of an
+SSL BIO (using B<ctx>) followed by a connect BIO.
+
+BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
+of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
+BIO.
+
+BIO_ssl_copy_session_id() copies an SSL session id between
+BIO chains B<from> and B<to>. It does this by locating the
+SSL BIOs in each chain and calling SSL_copy_session_id() on
+the internal SSL pointer.
+
+BIO_ssl_shutdown() closes down an SSL connection on BIO
+chain B<bio>. It does this by locating the SSL BIO in the
+chain and calling SSL_shutdown() on its internal SSL
+pointer.
+
+BIO_do_handshake() attempts to complete an SSL handshake on the
+supplied BIO and establish the SSL connection. It returns 1
+if the connection was established successfully. A zero or negative
+value is returned if the connection could not be established, the
+call BIO_should_retry() should be used for non blocking connect BIOs
+to determine if the call should be retried. If an SSL connection has
+already been established this call has no effect.
+
+=head1 NOTES
+
+SSL BIOs are exceptional in that if the underlying transport
+is non blocking they can still request a retry in exceptional
+circumstances. Specifically this will happen if a session
+renegotiation takes place during a BIO_read() operation, one
+case where this happens is when step up occurs.
+
+The SSL flag SSL_AUTO_RETRY can be
+set to disable this behaviour. That is when this flag is set
+an SSL BIO using a blocking transport will never request a
+retry.
+
+Since unknown BIO_ctrl() operations are sent through filter
+BIOs the servers name and port can be set using BIO_set_host()
+on the BIO returned by BIO_new_ssl_connect() without having
+to locate the connect BIO first.
+
+Applications do not have to call BIO_do_handshake() but may wish
+to do so to separate the handshake process from other I/O
+processing.
+
+BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
+BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
+BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
+
+=head1 EXAMPLE
+
+This SSL/TLS client example, attempts to retrieve a page from an
+SSL/TLS web server. The I/O routines are identical to those of the
+unencrypted example in L<BIO_s_connect(3)>.
+
+ BIO *sbio, *out;
+ int len;
+ char tmpbuf[1024];
+ SSL_CTX *ctx;
+ SSL *ssl;
+
+ /* XXX Seed the PRNG if needed. */
+
+ ctx = SSL_CTX_new(TLS_client_method());
+
+ /* XXX Set verify paths and mode here. */
+
+ sbio = BIO_new_ssl_connect(ctx);
+ BIO_get_ssl(sbio, &ssl);
+ if (ssl == NULL) {
+ fprintf(stderr, "Can't locate SSL pointer\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ /* Don't want any retries */
+ SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
+
+ /* XXX We might want to do other things with ssl here */
+
+ /* An empty host part means the loopback address */
+ BIO_set_conn_hostname(sbio, ":https");
+
+ out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ if (BIO_do_connect(sbio) <= 0) {
+ fprintf(stderr, "Error connecting to server\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+ if (BIO_do_handshake(sbio) <= 0) {
+ fprintf(stderr, "Error establishing SSL connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ /* XXX Could examine ssl here to get connection info */
+
+ BIO_puts(sbio, "GET / HTTP/1.0\n\n");
+ for ( ; ; ) {
+ len = BIO_read(sbio, tmpbuf, 1024);
+ if (len <= 0)
+ break;
+ BIO_write(out, tmpbuf, len);
+ }
+ BIO_free_all(sbio);
+ BIO_free(out);
+
+Here is a simple server example. It makes use of a buffering
+BIO to allow lines to be read from the SSL BIO using BIO_gets.
+It creates a pseudo web page containing the actual request from
+a client and also echoes the request to standard output.
+
+ BIO *sbio, *bbio, *acpt, *out;
+ int len;
+ char tmpbuf[1024];
+ SSL_CTX *ctx;
+ SSL *ssl;
+
+ /* XXX Seed the PRNG if needed. */
+
+ ctx = SSL_CTX_new(TLS_server_method());
+ if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
+ || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
+ || !SSL_CTX_check_private_key(ctx)) {
+ fprintf(stderr, "Error setting up SSL_CTX\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ /* XXX Other things like set verify locations, EDH temp callbacks. */
+
+ /* New SSL BIO setup as server */
+ sbio = BIO_new_ssl(ctx, 0);
+ BIO_get_ssl(sbio, &ssl);
+ if (ssl == NULL) {
+ fprintf(stderr, "Can't locate SSL pointer\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
+ bbio = BIO_new(BIO_f_buffer());
+ sbio = BIO_push(bbio, sbio);
+ acpt = BIO_new_accept("4433");
+
+ /*
+ * By doing this when a new connection is established
+ * we automatically have sbio inserted into it. The
+ * BIO chain is now 'swallowed' by the accept BIO and
+ * will be freed when the accept BIO is freed.
+ */
+ BIO_set_accept_bios(acpt, sbio);
+ out = BIO_new_fp(stdout, BIO_NOCLOSE);
+
+ /* Setup accept BIO */
+ if (BIO_do_accept(acpt) <= 0) {
+ fprintf(stderr, "Error setting up accept BIO\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ if (BIO_do_accept(acpt) <= 0) {
+ fprintf(stderr, "Error in connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ /* We only want one connection so remove and free accept BIO */
+ sbio = BIO_pop(acpt);
+ BIO_free_all(acpt);
+
+ if (BIO_do_handshake(sbio) <= 0) {
+ fprintf(stderr, "Error in SSL handshake\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
+ BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
+ BIO_puts(sbio, "--------------------------------------------------\r\n");
+
+ for ( ; ; ) {
+ len = BIO_gets(sbio, tmpbuf, 1024);
+ if (len <= 0)
+ break;
+ BIO_write(sbio, tmpbuf, len);
+ BIO_write(out, tmpbuf, len);
+ /* Look for blank line signifying end of headers*/
+ if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
+ break;
+ }
+
+ BIO_puts(sbio, "--------------------------------------------------\r\n");
+ BIO_puts(sbio, "\r\n");
+ BIO_flush(sbio);
+ BIO_free_all(sbio);
+
+=head1 BUGS
+
+In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly,
+the I/O BIO reference count was incorrectly incremented (instead of
+decremented) and dissociated with the SSL BIO even if the SSL BIO was not
+explicitly being popped (e.g. a pop higher up the chain). Applications which
+included workarounds for this bug (e.g. freeing BIOs more than once) should
+be modified to handle this fix or they may free up an already freed BIO.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO *BIO_find_type(BIO *b, int bio_type);
+ BIO *BIO_next(BIO *b);
+ int BIO_method_type(const BIO *b);
+
+=head1 DESCRIPTION
+
+The BIO_find_type() searches for a BIO of a given type in a chain, starting
+at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search
+is made for a BIO of that type. If B<type> is a general type (such as
+B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
+searched for. BIO_find_type() returns the next matching BIO or NULL if none is
+found.
+
+The following general types are defined:
+B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
+
+For a list of the specific types, see the B<openssl/bio.h> header file.
+
+BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
+in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
+certain type.
+
+BIO_method_type() returns the type of a BIO.
+
+=head1 RETURN VALUES
+
+BIO_find_type() returns a matching BIO or NULL for no match.
+
+BIO_next() returns the next BIO in a chain.
+
+BIO_method_type() returns the type of the BIO B<b>.
+
+=head1 EXAMPLE
+
+Traverse a chain looking for digest BIOs:
+
+ BIO *btmp;
+ btmp = in_bio; /* in_bio is chain to search through */
+
+ do {
+ btmp = BIO_find_type(btmp, BIO_TYPE_MD);
+ if (btmp == NULL) break; /* Not found */
+ /* btmp is a digest BIO, do something with it ...*/
+ ...
+
+ btmp = BIO_next(btmp);
+ } while (btmp);
+
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown,
+BIO_get_shutdown - functions for managing BIO state information
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ void BIO_set_data(BIO *a, void *ptr);
+ void *BIO_get_data(BIO *a);
+ void BIO_set_init(BIO *a, int init);
+ int BIO_get_init(BIO *a);
+ void BIO_set_shutdown(BIO *a, int shut);
+ int BIO_get_shutdown(BIO *a);
+
+=head1 DESCRIPTION
+
+These functions are mainly useful when implementing a custom BIO.
+
+The BIO_set_data() function associates the custom data pointed to by B<ptr> with
+the BIO. This data can subsequently be retrieved via a call to BIO_get_data().
+This can be used by custom BIOs for storing implementation specific information.
+
+The BIO_set_init() function sets the value of the BIO's "init" flag to indicate
+whether initialisation has been completed for this BIO or not. A non-zero value
+indicates that initialisation is complete, whilst zero indicates that it is not.
+Often initialisation will complete during initial construction of the BIO. For
+some BIOs however, initialisation may not complete until after additional steps
+have occurred (for example through calling custom ctrls). The BIO_get_init()
+function returns the value of the "init" flag.
+
+The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of
+this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource
+is also closed when the BIO is freed.
+
+=head1 RETURN VALUES
+
+BIO_get_data() returns a pointer to the implementation specific custom data
+associated with this BIO, or NULL if none has been set.
+
+BIO_get_init() returns the state of the BIO's init flag.
+
+BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.
+
+=head1 SEE ALSO
+
+L<bio>, L<BIO_meth_new>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data,
+ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
+UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data,
+X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data,
+X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data,
+X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data,
+DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
+DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
+ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data,
+ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_get_ex_data,
+RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
+- application-specific data
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int TYPE_get_ex_new_index(long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
+
+ void *TYPE_get_ex_data(TYPE *d, int idx);
+
+=head1 DESCRIPTION
+
+In the description here, I<TYPE> is used a placeholder
+for any of the OpenSSL datatypes listed in
+L<CRYPTO_get_ex_new_index(3)>.
+
+These functions handle application-specific data for OpenSSL data
+structures.
+
+TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
+with the correct B<index> value.
+
+TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
+an offset into the opaque exdata part of the TYPE object.
+
+TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an
+an offset into the opaque exdata part of the TYPE object.
+
+=head1 SEE ALSO
+
+L<CRYPTO_get_ex_new_index(3)>.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_get_new_index,
+BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,
+BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,
+BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,
+BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,
+BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
+BIO_meth_set_callback_ctrl - Routines to build up BIO methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ int BIO_get_new_index(void);
+ BIO_METHOD *BIO_meth_new(int type, const char *name);
+ void BIO_meth_free(BIO_METHOD *biom);
+ int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);
+ int BIO_meth_set_write(BIO_METHOD *biom,
+ int (*write) (BIO *, const char *, int));
+ int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);
+ int BIO_meth_set_read(BIO_METHOD *biom,
+ int (*read) (BIO *, char *, int));
+ int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);
+ int BIO_meth_set_puts(BIO_METHOD *biom,
+ int (*puts) (BIO *, const char *));
+ int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int);
+ int BIO_meth_set_gets(BIO_METHOD *biom,
+ int (*gets) (BIO *, char *, int));
+ long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *);
+ int BIO_meth_set_ctrl(BIO_METHOD *biom,
+ long (*ctrl) (BIO *, int, long, void *));
+ int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *);
+ int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *));
+ int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *);
+ int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *));
+ long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom))
+ (BIO *, int, bio_info_cb *);
+ int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
+ long (*callback_ctrl) (BIO *, int,
+ bio_info_cb *));
+
+=head1 DESCRIPTION
+
+The B<BIO_METHOD> type is a structure used for the implementation of new BIO
+types. It provides a set of of functions used by OpenSSL for the implementation
+of the various BIO capabilities. See the L<bio> page for more information.
+
+BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
+unique integer B<type> and a string that represents its B<name>.
+Use BIO_get_new_index() to get the value for B<type>.
+
+The set of
+standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
+include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
+type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
+should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
+based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
+"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
+more information.
+
+BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
+associated with it.
+
+BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for
+writing arbitrary length data to the BIO respectively. This function will be
+called in response to the application calling BIO_write(). The parameters for
+the function have the same meaning as for BIO_write().
+
+BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for
+reading arbitrary length data from the BIO respectively. This function will be
+called in response to the application calling BIO_read(). The parameters for the
+function have the same meaning as for BIO_read().
+
+BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
+writing a NULL terminated string to the BIO respectively. This function will be
+called in response to the application calling BIO_puts(). The parameters for
+the function have the same meaning as for BIO_puts().
+
+BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
+used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
+page for more information). This function will be called in response to the
+application calling BIO_gets(). The parameters for the function have the same
+meaning as for BIO_gets().
+
+BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
+processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
+more information. This function will be called in response to the application
+calling BIO_ctrl(). The parameters for the function have the same meaning as for
+BIO_ctrl().
+
+BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
+for creating a new instance of the BIO respectively. This function will be
+called in response to the application calling BIO_new() and passing
+in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
+memory for the new BIO, and a pointer to this newly allocated structure will
+be passed as a parameter to the function.
+
+BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
+for destroying an instance of a BIO respectively. This function will be
+called in response to the application calling BIO_free(). A pointer to the BIO
+to be destroyed is passed as a parameter. The destroy function should be used
+for BIO specific clean up. The memory for the BIO itself should not be freed by
+this function.
+
+BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
+function used for processing callback ctrl messages in the BIO respectively. See
+the L<BIO_callback_ctrl(3)> page for more information. This function will be called
+in response to the application calling BIO_callback_ctrl(). The parameters for
+the function have the same meaning as for BIO_callback_ctrl().
+
+=head1 SEE ALSO
+
+L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all,
+BIO_set - BIO allocation and freeing functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO * BIO_new(const BIO_METHOD *type);
+ int BIO_set(BIO *a, const BIO_METHOD *type);
+ int BIO_up_ref(BIO *a);
+ int BIO_free(BIO *a);
+ void BIO_vfree(BIO *a);
+ void BIO_free_all(BIO *a);
+
+=head1 DESCRIPTION
+
+The BIO_new() function returns a new BIO using method B<type>.
+
+BIO_up_ref() increments the reference count associated with the BIO object.
+
+BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
+but it does not return a value.
+If B<a> is NULL nothing is done.
+Calling BIO_free() may also have some effect
+on the underlying I/O structure, for example it may close the file being
+referred to under certain circumstances. For more details see the individual
+BIO_METHOD descriptions.
+
+BIO_free_all() frees up an entire BIO chain, it does not halt if an error
+occurs freeing up an individual BIO in the chain.
+If B<a> is NULL nothing is done.
+
+=head1 RETURN VALUES
+
+BIO_new() returns a newly created BIO or NULL if the call fails.
+
+BIO_set(), BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.
+
+BIO_free_all() and BIO_vfree() do not return values.
+
+=head1 NOTES
+
+If BIO_free() is called on a BIO chain it will only free one BIO resulting
+in a memory leak.
+
+Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free()
+on it other than the discarded return value.
+
+=head1 HISTORY
+
+BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
+
+=head1 EXAMPLE
+
+Create a memory BIO:
+
+ BIO *mem = BIO_new(BIO_s_mem());
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_new_CMS - CMS streaming filter BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);
+
+=head1 DESCRIPTION
+
+BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output
+of the filter is written to B<out>. Any data written to the chain is
+automatically translated to a BER format CMS structure of the appropriate type.
+
+=head1 NOTES
+
+The chain returned by this function behaves like a standard filter BIO. It
+supports non blocking I/O. Content is processed and streamed on the fly and not
+all held in memory at once: so it is possible to encode very large structures.
+After all content has been written through the chain BIO_flush() must be called
+to finalise the structure.
+
+The B<CMS_STREAM> flag must be included in the corresponding B<flags>
+parameter of the B<cms> creation function.
+
+If an application wishes to write additional data to B<out> BIOs should be
+removed from the chain using BIO_pop() and freed with BIO_free() until B<out>
+is reached. If no additional data needs to be written BIO_free_all() can be
+called to free up the whole chain.
+
+Any content written through the filter is used verbatim: no canonical
+translation is performed.
+
+It is possible to chain multiple BIOs to, for example, create a triple wrapped
+signed, enveloped, signed structure. In this case it is the applications
+responsibility to set the inner content type of any outer CMS_ContentInfo
+structures.
+
+Large numbers of small writes through the chain should be avoided as this will
+produce an output consisting of lots of OCTET STRING structures. Prepending
+a BIO_f_buffer() buffering BIO will prevent this.
+
+=head1 BUGS
+
+There is currently no corresponding inverse BIO: i.e. one which can decode
+a CMS structure on the fly.
+
+=head1 RETURN VALUES
+
+BIO_new_CMS() returns a BIO chain when successful or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>,
+L<CMS_encrypt(3)>
+
+=head1 HISTORY
+
+BIO_new_CMS() was added to OpenSSL 1.0.0
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_parse_hostserv - utility routines to parse a standard host and service
+string
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ enum BIO_hostserv_priorities {
+ BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
+ };
+ int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
+ enum BIO_hostserv_priorities hostserv_prio);
+
+=head1 DESCRIPTION
+
+BIO_parse_hostserv() will parse the information given in B<hostserv>,
+create strings with the host name and service name and give those
+back via B<host> and B<service>. Those will need to be freed after
+they are used. B<hostserv_prio> helps determine if B<hostserv> shall
+be interpreted primarily as a host name or a service name in ambiguous
+cases.
+
+The syntax the BIO_parse_hostserv() recognises is:
+
+ host + ':' + service
+ host + ':' + '*'
+ host + ':'
+ ':' + service
+ '*' + ':' + service
+ host
+ service
+
+The host part can be a name or an IP address. If it's a IPv6
+address, it MUST be enclosed in brackets, such as '[::1]'.
+
+The service part can be a service name or its port number.
+
+The returned values will depend on the given B<hostserv> string
+and B<hostserv_prio>, as follows:
+
+ host + ':' + service => *host = "host", *service = "service"
+ host + ':' + '*' => *host = "host", *service = NULL
+ host + ':' => *host = "host", *service = NULL
+ ':' + service => *host = NULL, *service = "service"
+ '*' + ':' + service => *host = NULL, *service = "service"
+
+ in case no ':' is present in the string, the result depends on
+ hostserv_prio, as follows:
+
+ when hostserv_prio == BIO_PARSE_PRIO_HOST
+ host => *host = "host", *service untouched
+
+ when hostserv_prio == BIO_PARSE_PRIO_SERV
+ service => *host untouched, *service = "service"
+
+=head1 SEE ALSO
+
+L<BIO_ADDRINFO(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ BIO *BIO_push(BIO *b, BIO *append);
+ BIO *BIO_pop(BIO *b);
+ void BIO_set_next(BIO *b, BIO *next);
+
+=head1 DESCRIPTION
+
+The BIO_push() function appends the BIO B<append> to B<b>, it returns
+B<b>.
+
+BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
+in the chain, or NULL if there is no next BIO. The removed BIO then
+becomes a single BIO with no association with the original chain,
+it can thus be freed or attached to a different chain.
+
+BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
+by B<next>. The new chain may include some of the same BIOs from the old chain
+or it may be completely different.
+
+=head1 NOTES
+
+The names of these functions are perhaps a little misleading. BIO_push()
+joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
+the deleted BIO does not need to be at the end of a chain.
+
+The process of calling BIO_push() and BIO_pop() on a BIO may have additional
+consequences (a control call is made to the affected BIOs) any effects will
+be noted in the descriptions of individual BIOs.
+
+=head1 EXAMPLES
+
+For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
+a base64 BIO and B<f> is a file BIO.
+
+If the call:
+
+ BIO_push(b64, f);
+
+is made then the new chain will be B<b64-f>. After making the calls
+
+ BIO_push(md2, b64);
+ BIO_push(md1, md2);
+
+the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
+by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
+
+It should be noted that reading causes data to pass in the reverse
+direction, that is data is read from B<f>, base64 B<decoded> and digested
+by B<md1> and B<md2>. If the call:
+
+ BIO_pop(md2);
+
+The call will return B<b64> and the new chain will be B<md1-b64-f> data can
+be written to B<md1> as before.
+
+=head1 RETURN VALUES
+
+BIO_push() returns the end of the chain, B<b>.
+
+BIO_pop() returns the next BIO in the chain, or NULL if there is no next
+BIO.
+
+=head1 SEE ALSO
+
+L<bio>
+
+=head1 HISTORY
+
+The BIO_set_next() function was added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ int BIO_read(BIO *b, void *buf, int len);
+ int BIO_gets(BIO *b, char *buf, int size);
+ int BIO_write(BIO *b, const void *buf, int len);
+ int BIO_puts(BIO *b, const char *buf);
+
+=head1 DESCRIPTION
+
+BIO_read() attempts to read B<len> bytes from BIO B<b> and places
+the data in B<buf>.
+
+BIO_gets() performs the BIOs "gets" operation and places the data
+in B<buf>. Usually this operation will attempt to read a line of data
+from the BIO of maximum length B<len-1>. There are exceptions to this,
+however; for example, BIO_gets() on a digest BIO will calculate and
+return the digest and other BIOs may not support BIO_gets() at all.
+The returned string is always NUL-terminated.
+
+BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
+
+BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
+
+=head1 RETURN VALUES
+
+All these functions return either the amount of data successfully read or
+written (if the return value is positive) or that no data was successfully
+read or written if the result is 0 or -1. If the return value is -2 then
+the operation is not implemented in the specific BIO type. The trailing
+NUL is not included in the length returned by BIO_gets().
+
+=head1 NOTES
+
+A 0 or -1 return is not necessarily an indication of an error. In
+particular when the source/sink is non-blocking or of a certain type
+it may merely be an indication that no data is currently available and that
+the application should retry the operation later.
+
+One technique sometimes used with blocking sockets is to use a system call
+(such as select(), poll() or equivalent) to determine when data is available
+and then call read() to read the data. The equivalent with BIOs (that is call
+select() on the underlying I/O structure and then call BIO_read() to
+read the data) should B<not> be used because a single call to BIO_read()
+can cause several reads (and writes in the case of SSL BIOs) on the underlying
+I/O structure and may block as a result. Instead select() (or equivalent)
+should be combined with non blocking I/O so successive reads will request
+a retry instead of blocking.
+
+See L<BIO_should_retry(3)> for details of how to
+determine the cause of a retry and other I/O issues.
+
+If the BIO_gets() function is not supported by a BIO then it possible to
+work around this by adding a buffering BIO L<BIO_f_buffer(3)>
+to the chain.
+
+=head1 SEE ALSO
+
+L<BIO_should_retry(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
+BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios,
+BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD *BIO_s_accept(void);
+
+ long BIO_set_accept_name(BIO *b, char *name);
+ char *BIO_get_accept_name(BIO *b);
+
+ long BIO_set_accept_port(BIO *b, char *port);
+ char *BIO_get_accept_port(BIO *b);
+
+ BIO *BIO_new_accept(char *host_port);
+
+ long BIO_set_nbio_accept(BIO *b, int n);
+ long BIO_set_accept_bios(BIO *b, char *bio);
+
+ long BIO_set_bind_mode(BIO *b, long mode);
+ long BIO_get_bind_mode(BIO *b);
+
+ int BIO_do_accept(BIO *b);
+
+=head1 DESCRIPTION
+
+BIO_s_accept() returns the accept BIO method. This is a wrapper
+round the platform's TCP/IP socket accept routines.
+
+Using accept BIOs, TCP/IP connections can be accepted and data
+transferred using only BIO routines. In this way any platform
+specific operations are hidden by the BIO abstraction.
+
+Read and write operations on an accept BIO will perform I/O
+on the underlying connection. If no connection is established
+and the port (see below) is set up properly then the BIO
+waits for an incoming connection.
+
+Accept BIOs support BIO_puts() but not BIO_gets().
+
+If the close flag is set on an accept BIO then any active
+connection on that chain is shutdown and the socket closed when
+the BIO is freed.
+
+Calling BIO_reset() on an accept BIO will close any active
+connection and reset the BIO into a state where it awaits another
+incoming connection.
+
+BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
+the accept socket. See L<BIO_s_fd(3)>
+
+BIO_set_accept_name() uses the string B<name> to set the accept
+name. The name is represented as a string of the form "host:port",
+where "host" is the interface to use and "port" is the port.
+The host can be "*" or empty which is interpreted as meaning
+any interface. If the host is an IPv6 address, it has to be
+enclosed in brackets, for example "[::1]:https". "port" has the
+same syntax as the port specified in BIO_set_conn_port() for
+connect BIOs, that is it can be a numerical port string or a
+string to lookup using getservbyname() and a string table.
+
+BIO_set_accept_port() uses the string B<port> to set the accept
+port. "port" has the same syntax as the port specified in
+BIO_set_conn_port() for connect BIOs, that is it can be a numerical
+port string or a string to lookup using getservbyname() and a string
+table.
+
+BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into
+a single call: that is it creates a new accept BIO with port
+B<host_port>.
+
+BIO_set_nbio_accept() sets the accept socket to blocking mode
+(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
+
+BIO_set_accept_bios() can be used to set a chain of BIOs which
+will be duplicated and prepended to the chain when an incoming
+connection is received. This is useful if, for example, a
+buffering or SSL BIO is required for each connection. The
+chain of BIOs must not be freed after this call, they will
+be automatically freed when the accept BIO is freed.
+
+BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
+the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set
+then another socket cannot be bound to the same port. If
+B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
+same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
+attempt is first made to use BIO_BIN_NORMAL, if this fails
+and the port is not in use then a second attempt is made
+using B<BIO_BIND_REUSEADDR>.
+
+BIO_do_accept() serves two functions. When it is first
+called, after the accept BIO has been setup, it will attempt
+to create the accept socket and bind an address to it. Second
+and subsequent calls to BIO_do_accept() will await an incoming
+connection, or request a retry in non blocking mode.
+
+=head1 NOTES
+
+When an accept BIO is at the end of a chain it will await an
+incoming connection before processing I/O calls. When an accept
+BIO is not at then end of a chain it passes I/O calls to the next
+BIO in the chain.
+
+When a connection is established a new socket BIO is created for
+the connection and appended to the chain. That is the chain is now
+accept->socket. This effectively means that attempting I/O on
+an initial accept socket will await an incoming connection then
+perform I/O on it.
+
+If any additional BIOs have been set using BIO_set_accept_bios()
+then they are placed between the socket and the accept BIO,
+that is the chain will be accept->otherbios->socket.
+
+If a server wishes to process multiple connections (as is normally
+the case) then the accept BIO must be made available for further
+incoming connections. This can be done by waiting for a connection and
+then calling:
+
+ connection = BIO_pop(accept);
+
+After this call B<connection> will contain a BIO for the recently
+established connection and B<accept> will now be a single BIO
+again which can be used to await further incoming connections.
+If no further connections will be accepted the B<accept> can
+be freed using BIO_free().
+
+If only a single connection will be processed it is possible to
+perform I/O using the accept BIO itself. This is often undesirable
+however because the accept BIO will still accept additional incoming
+connections. This can be resolved by using BIO_pop() (see above)
+and freeing up the accept BIO after the initial connection.
+
+If the underlying accept socket is non-blocking and BIO_do_accept() is
+called to await an incoming connection it is possible for
+BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
+then it is an indication that an accept attempt would block: the application
+should take appropriate action to wait until the underlying socket has
+accepted a connection and retry the call.
+
+BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(),
+BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
+BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
+
+=head1 RETURN VALUES
+
+BIO_do_accept(),
+BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
+BIO_set_accept_bios(), and BIO_set_bind_mode(), return 1 for success and 0 or
+-1 for failure.
+
+BIO_get_accept_name() returns the accept name or NULL on error.
+
+BIO_get_accept_port() returns the port as a string or NULL on error.
+
+BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
+
+BIO_new_accept() returns a BIO or NULL on error.
+
+=head1 EXAMPLE
+
+This example accepts two connections on port 4444, sends messages
+down each and finally closes both down.
+
+ BIO *abio, *cbio, *cbio2;
+
+ /* First call to BIO_accept() sets up accept BIO */
+ abio = BIO_new_accept("4444");
+ if (BIO_do_accept(abio) <= 0) {
+ fprintf(stderr, "Error setting up accept\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+ /* Wait for incoming connection */
+ if (BIO_do_accept(abio) <= 0) {
+ fprintf(stderr, "Error accepting connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+ fprintf(stderr, "Connection 1 established\n");
+
+ /* Retrieve BIO for connection */
+ cbio = BIO_pop(abio);
+ BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
+ fprintf(stderr, "Sent out data on connection 1\n");
+
+ /* Wait for another connection */
+ if (BIO_do_accept(abio) <= 0) {
+ fprintf(stderr, "Error accepting connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+ fprintf(stderr, "Connection 2 established\n");
+
+ /* Close accept BIO to refuse further connections */
+ cbio2 = BIO_pop(abio);
+ BIO_free(abio);
+ BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
+ fprintf(stderr, "Sent out data on connection 2\n");
+
+ BIO_puts(cbio, "Connection 1: Second connection established\n");
+
+ /* Close the two established connections */
+ BIO_free(cbio);
+ BIO_free(cbio2);
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
+BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
+BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
+BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD *BIO_s_bio(void);
+
+ int BIO_make_bio_pair(BIO *b1, BIO *b2);
+ int BIO_destroy_bio_pair(BIO *b);
+ int BIO_shutdown_wr(BIO *b);
+
+
+ int BIO_set_write_buf_size(BIO *b, long size);
+ size_t BIO_get_write_buf_size(BIO *b, long size);
+
+ int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
+
+ int BIO_get_write_guarantee(BIO *b);
+ size_t BIO_ctrl_get_write_guarantee(BIO *b);
+ int BIO_get_read_request(BIO *b);
+ size_t BIO_ctrl_get_read_request(BIO *b);
+ int BIO_ctrl_reset_read_request(BIO *b);
+
+=head1 DESCRIPTION
+
+BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink
+BIOs where data written to either half of the pair is buffered and can be read from
+the other half. Both halves must usually by handled by the same application thread
+since no locking is done on the internal data structures.
+
+Since BIO chains typically end in a source/sink BIO it is possible to make this
+one half of a BIO pair and have all the data processed by the chain under application
+control.
+
+One typical use of BIO pairs is to place TLS/SSL I/O under application control, this
+can be used when the application wishes to use a non standard transport for
+TLS/SSL or the normal socket routines are inappropriate.
+
+Calls to BIO_read() will read data from the buffer or request a retry if no
+data is available.
+
+Calls to BIO_write() will place data in the buffer or request a retry if the
+buffer is full.
+
+The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
+determine the amount of pending data in the read or write buffer.
+
+BIO_reset() clears any data in the write buffer.
+
+BIO_make_bio_pair() joins two separate BIOs into a connected pair.
+
+BIO_destroy_pair() destroys the association between two connected BIOs. Freeing
+up any half of the pair will automatically destroy the association.
+
+BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
+writes on BIO B<b> are allowed (they will return an error). Reads on the other
+half of the pair will return any pending data or EOF when all pending data has
+been read.
+
+BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
+If the size is not initialized a default value is used. This is currently
+17K, sufficient for a maximum size TLS record.
+
+BIO_get_write_buf_size() returns the size of the write buffer.
+
+BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
+BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
+with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
+zero then the default size is used. BIO_new_bio_pair() does not check whether
+B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
+BIO_free() is not called.
+
+BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
+length of data that can be currently written to the BIO. Writes larger than this
+value will return a value from BIO_write() less than the amount requested or if the
+buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function
+whereas BIO_get_write_guarantee() is a macro.
+
+BIO_get_read_request() and BIO_ctrl_get_read_request() return the
+amount of data requested, or the buffer size if it is less, if the
+last read attempt at the other half of the BIO pair failed due to an
+empty buffer. This can be used to determine how much data should be
+written to the BIO so the next read will succeed: this is most useful
+in TLS/SSL applications where the amount of data read is usually
+meaningful rather than just a buffer size. After a successful read
+this call will return zero. It also will return zero once new data
+has been written satisfying the read request or part of it.
+Note that BIO_get_read_request() never returns an amount larger
+than that returned by BIO_get_write_guarantee().
+
+BIO_ctrl_reset_read_request() can also be used to reset the value returned by
+BIO_get_read_request() to zero.
+
+=head1 NOTES
+
+Both halves of a BIO pair should be freed. That is even if one half is implicit
+freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.
+
+When used in bidirectional applications (such as TLS/SSL) care should be taken to
+flush any data in the write buffer. This can be done by calling BIO_pending()
+on the other half of the pair and, if any data is pending, reading it and sending
+it to the underlying transport. This must be done before any normal processing
+(such as calling select() ) due to a request and BIO_should_read() being true.
+
+To see why this is important consider a case where a request is sent using
+BIO_write() and a response read with BIO_read(), this can occur during an
+TLS/SSL handshake for example. BIO_write() will succeed and place data in the write
+buffer. BIO_read() will initially fail and BIO_should_read() will be true. If
+the application then waits for data to be available on the underlying transport
+before flushing the write buffer it will never succeed because the request was
+never sent!
+
+BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
+shutdown.
+
+BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(),
+BIO_set_write_buf_size(), BIO_get_write_buf_size(),
+BIO_get_write_guarantee(), and BIO_get_read_request() are implemented
+as macros.
+
+=head1 RETURN VALUES
+
+BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
+B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
+locations for B<bio1> and B<bio2>. Check the error stack for more information.
+
+[XXXXX: More return values need to be added here]
+
+=head1 EXAMPLE
+
+The BIO pair can be used to have full control over the network access of an
+application. The application can call select() on the socket as required
+without having to go through the SSL-interface.
+
+ BIO *internal_bio, *network_bio;
+ ...
+ BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
+ SSL_set_bio(ssl, internal_bio, internal_bio);
+ SSL_operations(); //e.g SSL_read and SSL_write
+ ...
+
+ application | TLS-engine
+ | |
+ +----------> SSL_operations()
+ | /\ ||
+ | || \/
+ | BIO-pair (internal_bio)
+ | BIO-pair (network_bio)
+ | || /\
+ | \/ ||
+ +-----------< BIO_operations()
+ | |
+ | |
+ socket
+
+ ...
+ SSL_free(ssl); /* implicitly frees internal_bio */
+ BIO_free(network_bio);
+ ...
+
+As the BIO pair will only buffer the data and never directly access the
+connection, it behaves non-blocking and will return as soon as the write
+buffer is full or the read buffer is drained. Then the application has to
+flush the write buffer and/or fill the read buffer.
+
+Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
+and must be transferred to the network. Use BIO_ctrl_get_read_request() to
+find out, how many bytes must be written into the buffer before the
+SSL_operation() can successfully be continued.
+
+=head1 WARNING
+
+As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
+condition, but there is still data in the write buffer. An application must
+not rely on the error value of SSL_operation() but must assure that the
+write buffer is always flushed first. Otherwise a deadlock may occur as
+the peer might be waiting for the data before being able to continue.
+
+=head1 SEE ALSO
+
+L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
+L<BIO_should_retry(3)>, L<BIO_read(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_set_conn_address, BIO_get_conn_address,
+BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
+BIO_get_conn_hostname,
+BIO_get_conn_port,
+BIO_set_nbio, BIO_do_connect - connect BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD * BIO_s_connect(void);
+
+ BIO *BIO_new_connect(char *name);
+
+ long BIO_set_conn_hostname(BIO *b, char *name);
+ long BIO_set_conn_port(BIO *b, char *port);
+ long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
+ const char *BIO_get_conn_hostname(BIO *b);
+ const char *BIO_get_conn_port(BIO *b);
+ const BIO_ADDR *BIO_get_conn_address(BIO *b);
+
+ long BIO_set_nbio(BIO *b, long n);
+
+ int BIO_do_connect(BIO *b);
+
+=head1 DESCRIPTION
+
+BIO_s_connect() returns the connect BIO method. This is a wrapper
+round the platform's TCP/IP socket connection routines.
+
+Using connect BIOs, TCP/IP connections can be made and data
+transferred using only BIO routines. In this way any platform
+specific operations are hidden by the BIO abstraction.
+
+Read and write operations on a connect BIO will perform I/O
+on the underlying connection. If no connection is established
+and the port and hostname (see below) is set up properly then
+a connection is established first.
+
+Connect BIOs support BIO_puts() but not BIO_gets().
+
+If the close flag is set on a connect BIO then any active
+connection is shutdown and the socket closed when the BIO
+is freed.
+
+Calling BIO_reset() on a connect BIO will close any active
+connection and reset the BIO into a state where it can connect
+to the same host again.
+
+BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
+it also returns the socket . If B<c> is not NULL it should be of
+type (int *).
+
+BIO_set_conn_hostname() uses the string B<name> to set the hostname.
+The hostname can be an IP address; if the address is an IPv6 one, it
+must be enclosed with brackets. The hostname can also include the
+port in the form hostname:port.
+
+BIO_set_conn_port() sets the port to B<port>. B<port> can be the
+numerical form or a string such as "http". A string will be looked
+up first using getservbyname() on the host platform but if that
+fails a standard table of port names will be used. This internal
+list is http, telnet, socks, https, ssl, ftp, and gopher.
+
+BIO_set_conn_address() sets the address and port information using
+a BIO_ADDR(3ssl).
+
+BIO_get_conn_hostname() returns the hostname of the connect BIO or
+NULL if the BIO is initialized but no hostname is set.
+This return value is an internal pointer which should not be modified.
+
+BIO_get_conn_port() returns the port as a string.
+This return value is an internal pointer which should not be modified.
+
+BIO_get_conn_address() returns the address information as a BIO_ADDR.
+This return value is an internal pointer which should not be modified.
+
+BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
+zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
+is set. Blocking I/O is the default. The call to BIO_set_nbio()
+should be made before the connection is established because
+non blocking I/O is set during the connect process.
+
+BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
+a single call: that is it creates a new connect BIO with B<name>.
+
+BIO_do_connect() attempts to connect the supplied BIO. It returns 1
+if the connection was established successfully. A zero or negative
+value is returned if the connection could not be established, the
+call BIO_should_retry() should be used for non blocking connect BIOs
+to determine if the call should be retried.
+
+=head1 NOTES
+
+If blocking I/O is set then a non positive return value from any
+I/O call is caused by an error condition, although a zero return
+will normally mean that the connection was closed.
+
+If the port name is supplied as part of the host name then this will
+override any value set with BIO_set_conn_port(). This may be undesirable
+if the application does not wish to allow connection to arbitrary
+ports. This can be avoided by checking for the presence of the ':'
+character in the passed hostname and either indicating an error or
+truncating the string at that point.
+
+The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
+BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
+connection attempt is made. Before any connection attempt the values
+returned are those set by the application itself.
+
+Applications do not have to call BIO_do_connect() but may wish to do
+so to separate the connection process from other I/O processing.
+
+If non blocking I/O is set then retries will be requested as appropriate.
+
+It addition to BIO_should_read() and BIO_should_write() it is also
+possible for BIO_should_io_special() to be true during the initial
+connection process with the reason BIO_RR_CONNECT. If this is returned
+then this is an indication that a connection attempt would block,
+the application should then take appropriate action to wait until
+the underlying socket has connected and retry the call.
+
+BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(),
+BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(),
+BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and
+BIO_do_connect() are macros.
+
+=head1 RETURN VALUES
+
+BIO_s_connect() returns the connect BIO method.
+
+BIO_get_fd() returns the socket or -1 if the BIO has not
+been initialized.
+
+BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
+BIO_set_conn_int_port() always return 1.
+
+BIO_get_conn_hostname() returns the connected hostname or NULL is
+none was set.
+
+BIO_get_conn_port() returns a string representing the connected
+port or NULL if not set.
+
+BIO_get_conn_ip() returns a pointer to the connected IP address in
+binary form or all zeros if not set.
+
+BIO_get_conn_int_port() returns the connected port or 0 if none was
+set.
+
+BIO_set_nbio() always returns 1.
+
+BIO_do_connect() returns 1 if the connection was successfully
+established and 0 or -1 if the connection failed.
+
+=head1 EXAMPLE
+
+This is example connects to a webserver on the local host and attempts
+to retrieve a page and copy the result to standard output.
+
+
+ BIO *cbio, *out;
+ int len;
+ char tmpbuf[1024];
+
+ cbio = BIO_new_connect("localhost:http");
+ out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ if (BIO_do_connect(cbio) <= 0) {
+ fprintf(stderr, "Error connecting to server\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+ BIO_puts(cbio, "GET / HTTP/1.0\n\n");
+ for ( ; ; ) {
+ len = BIO_read(cbio, tmpbuf, 1024);
+ if (len <= 0)
+ break;
+ BIO_write(out, tmpbuf, len);
+ }
+ BIO_free(cbio);
+ BIO_free(out);
+
+
+=head1 SEE ALSO
+
+L<BIO_ADDR(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD *BIO_s_fd(void);
+
+ int BIO_set_fd(BIO *b, int fd, int c);
+ int BIO_get_fd(BIO *b, int *c);
+
+ BIO *BIO_new_fd(int fd, int close_flag);
+
+=head1 DESCRIPTION
+
+BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
+round the platforms file descriptor routines such as read() and write().
+
+BIO_read() and BIO_write() read or write the underlying descriptor.
+BIO_puts() is supported but BIO_gets() is not.
+
+If the close flag is set then close() is called on the underlying
+file descriptor when the BIO is freed.
+
+BIO_reset() attempts to change the file pointer to the start of file
+such as by using B<lseek(fd, 0, 0)>.
+
+BIO_seek() sets the file pointer to position B<ofs> from start of file
+such as by using B<lseek(fd, ofs, 0)>.
+
+BIO_tell() returns the current file position such as by calling
+B<lseek(fd, 0, 1)>.
+
+BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
+flag to B<c>.
+
+BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
+returns the file descriptor.
+
+BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
+
+=head1 NOTES
+
+The behaviour of BIO_read() and BIO_write() depends on the behavior of the
+platforms read() and write() calls on the descriptor. If the underlying
+file descriptor is in a non blocking mode then the BIO will behave in the
+manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)>
+manual pages.
+
+File descriptor BIOs should not be used for socket I/O. Use socket BIOs
+instead.
+
+BIO_set_fd() and BIO_get_fd() are implemented as macros.
+
+=head1 RETURN VALUES
+
+BIO_s_fd() returns the file descriptor BIO method.
+
+BIO_set_fd() always returns 1.
+
+BIO_get_fd() returns the file descriptor or -1 if the BIO has not
+been initialized.
+
+BIO_new_fd() returns the newly allocated BIO or NULL is an error
+occurred.
+
+=head1 EXAMPLE
+
+This is a file descriptor BIO version of "Hello World":
+
+ BIO *out;
+
+ out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
+ BIO_printf(out, "Hello World\n");
+ BIO_free(out);
+
+=head1 SEE ALSO
+
+L<BIO_seek(3)>, L<BIO_tell(3)>,
+L<BIO_reset(3)>, L<BIO_read(3)>,
+L<BIO_write(3)>, L<BIO_puts(3)>,
+L<BIO_gets(3)>, L<BIO_printf(3)>,
+L<BIO_set_close(3)>, L<BIO_get_close(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
+BIO_read_filename, BIO_write_filename, BIO_append_filename,
+BIO_rw_filename - FILE bio
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD * BIO_s_file(void);
+ BIO *BIO_new_file(const char *filename, const char *mode);
+ BIO *BIO_new_fp(FILE *stream, int flags);
+
+ BIO_set_fp(BIO *b, FILE *fp, int flags);
+ BIO_get_fp(BIO *b, FILE **fpp);
+
+ int BIO_read_filename(BIO *b, char *name)
+ int BIO_write_filename(BIO *b, char *name)
+ int BIO_append_filename(BIO *b, char *name)
+ int BIO_rw_filename(BIO *b, char *name)
+
+=head1 DESCRIPTION
+
+BIO_s_file() returns the BIO file method. As its name implies it
+is a wrapper round the stdio FILE structure and it is a
+source/sink BIO.
+
+Calls to BIO_read() and BIO_write() read and write data to the
+underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
+
+BIO_flush() on a file BIO calls the fflush() function on the wrapped
+stream.
+
+BIO_reset() attempts to change the file pointer to the start of file
+using fseek(stream, 0, 0).
+
+BIO_seek() sets the file pointer to position B<ofs> from start of file
+using fseek(stream, ofs, 0).
+
+BIO_eof() calls feof().
+
+Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
+is freed.
+
+BIO_new_file() creates a new file BIO with mode B<mode> the meaning
+of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
+flag is set on the returned BIO.
+
+BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
+BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
+stream to text mode, default is binary: this only has any effect under
+Win32).
+
+BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same
+meaning as in BIO_new_fp(), it is a macro.
+
+BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
+
+BIO_seek() is a macro that sets the position pointer to B<offset> bytes
+from the start of file.
+
+BIO_tell() returns the value of the position pointer.
+
+BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
+BIO_rw_filename() set the file BIO B<b> to use file B<name> for
+reading, writing, append or read write respectively.
+
+=head1 NOTES
+
+When wrapping stdout, stdin or stderr the underlying stream should not
+normally be closed so the BIO_NOCLOSE flag should be set.
+
+Because the file BIO calls the underlying stdio functions any quirks
+in stdio behaviour will be mirrored by the corresponding BIO.
+
+On Windows BIO_new_files reserves for the filename argument to be
+UTF-8 encoded. In other words if you have to make it work in multi-
+lingual environment, encode file names in UTF-8.
+
+=head1 EXAMPLES
+
+File BIO "hello world":
+
+ BIO *bio_out;
+ bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
+ BIO_printf(bio_out, "Hello World\n");
+
+Alternative technique:
+
+ BIO *bio_out;
+ bio_out = BIO_new(BIO_s_file());
+ if (bio_out == NULL) /* Error ... */
+ if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
+ BIO_printf(bio_out, "Hello World\n");
+
+Write to a file:
+
+ BIO *out;
+ out = BIO_new_file("filename.txt", "w");
+ if (!out) /* Error occurred */
+ BIO_printf(out, "Hello World\n");
+ BIO_free(out);
+
+Alternative technique:
+
+ BIO *out;
+ out = BIO_new(BIO_s_file());
+ if (out == NULL) /* Error ... */
+ if (!BIO_write_filename(out, "filename.txt")) /* Error ... */
+ BIO_printf(out, "Hello World\n");
+ BIO_free(out);
+
+=head1 RETURN VALUES
+
+BIO_s_file() returns the file BIO method.
+
+BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
+occurred.
+
+BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
+(although the current implementation never return 0).
+
+BIO_seek() returns the same value as the underlying fseek() function:
+0 for success or -1 for failure.
+
+BIO_tell() returns the current file position.
+
+BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
+BIO_rw_filename() return 1 for success or 0 for failure.
+
+=head1 BUGS
+
+BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
+stream. The return value for fseek() is 0 for success or -1 if an error
+occurred this differs from other types of BIO which will typically return
+1 for success and a non positive value if an error occurred.
+
+=head1 SEE ALSO
+
+L<BIO_seek(3)>, L<BIO_tell(3)>,
+L<BIO_reset(3)>, L<BIO_flush(3)>,
+L<BIO_read(3)>,
+L<BIO_write(3)>, L<BIO_puts(3)>,
+L<BIO_gets(3)>, L<BIO_printf(3)>,
+L<BIO_set_close(3)>, L<BIO_get_close(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_s_secmem,
+BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
+BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD * BIO_s_mem(void);
+ const BIO_METHOD * BIO_s_secmem(void);
+
+ BIO_set_mem_eof_return(BIO *b, int v)
+ long BIO_get_mem_data(BIO *b, char **pp)
+ BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c)
+ BIO_get_mem_ptr(BIO *b, BUF_MEM **pp)
+
+ BIO *BIO_new_mem_buf(const void *buf, int len);
+
+=head1 DESCRIPTION
+
+BIO_s_mem() return the memory BIO method function.
+
+A memory BIO is a source/sink BIO which uses memory for its I/O. Data
+written to a memory BIO is stored in a BUF_MEM structure which is extended
+as appropriate to accommodate the stored data.
+
+BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used
+for buffer storage.
+
+Any data written to a memory BIO can be recalled by reading from it.
+Unless the memory BIO is read only any data read from it is deleted from
+the BIO.
+
+Memory BIOs support BIO_gets() and BIO_puts().
+
+If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
+BUF_MEM structure is also freed.
+
+Calling BIO_reset() on a read write memory BIO clears any data in it if the
+flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag
+BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and
+the data can be read again.
+
+BIO_eof() is true if no data is in the BIO.
+
+BIO_ctrl_pending() returns the number of bytes currently stored.
+
+BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
+empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
+it will return zero and BIO_should_retry(b) will be false. If B<v> is non
+zero then it will return B<v> when it is empty and it will set the read retry
+flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
+positive return value B<v> should be set to a negative value, typically -1.
+
+BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data
+and returns the total amount of data available. It is implemented as a macro.
+
+BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
+close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
+It is a macro.
+
+BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is
+a macro.
+
+BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
+if B<len> is -1 then the B<buf> is assumed to be nul terminated and its
+length is determined by B<strlen>. The BIO is set to a read only state and
+as a result cannot be written to. This is useful when some data needs to be
+made available from a static area of memory in the form of a BIO. The
+supplied data is read directly from the supplied buffer: it is B<not> copied
+first, so the supplied area of memory must be unchanged until the BIO is freed.
+
+=head1 NOTES
+
+Writes to memory BIOs will always succeed if memory is available: that is
+their size can grow indefinitely.
+
+Every read from a read write memory BIO will remove the data just read with
+an internal copy operation, if a BIO contains a lot of data and it is
+read in small chunks the operation can be very slow. The use of a read only
+memory BIO avoids this problem. If the BIO must be read write then adding
+a buffering BIO to the chain will speed up the process.
+
+Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
+give undefined results, including perhaps a program crash.
+
+=head1 BUGS
+
+There should be an option to set the maximum size of a memory BIO.
+
+=head1 EXAMPLE
+
+Create a memory BIO and write some data to it:
+
+ BIO *mem = BIO_new(BIO_s_mem());
+ BIO_puts(mem, "Hello World\n");
+
+Create a read only memory BIO:
+
+ char data[] = "Hello World";
+ BIO *mem;
+ mem = BIO_new_mem_buf(data, -1);
+
+Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
+
+ BUF_MEM *bptr;
+ BIO_get_mem_ptr(mem, &bptr);
+ BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
+ BIO_free(mem);
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_s_null - null data sink
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD * BIO_s_null(void);
+
+=head1 DESCRIPTION
+
+BIO_s_null() returns the null sink BIO method. Data written to
+the null sink is discarded, reads return EOF.
+
+=head1 NOTES
+
+A null sink BIO behaves in a similar manner to the Unix /dev/null
+device.
+
+A null bio can be placed on the end of a chain to discard any data
+passed through it.
+
+A null sink is useful if, for example, an application wishes to digest some
+data by writing through a digest bio but not send the digested data anywhere.
+Since a BIO chain must normally include a source/sink BIO this can be achieved
+by adding a null sink BIO to the end of the chain
+
+=head1 RETURN VALUES
+
+BIO_s_null() returns the null sink BIO method.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_s_socket, BIO_new_socket - socket BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ const BIO_METHOD *BIO_s_socket(void);
+
+ BIO *BIO_new_socket(int sock, int close_flag);
+
+=head1 DESCRIPTION
+
+BIO_s_socket() returns the socket BIO method. This is a wrapper
+round the platform's socket routines.
+
+BIO_read() and BIO_write() read or write the underlying socket.
+BIO_puts() is supported but BIO_gets() is not.
+
+If the close flag is set then the socket is shut down and closed
+when the BIO is freed.
+
+BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
+
+=head1 NOTES
+
+Socket BIOs also support any relevant functionality of file descriptor
+BIOs.
+
+The reason for having separate file descriptor and socket BIOs is that on some
+platforms sockets are not file descriptors and use distinct I/O routines,
+Windows is one such platform. Any code mixing the two will not work on
+all platforms.
+
+=head1 RETURN VALUES
+
+BIO_s_socket() returns the socket BIO method.
+
+BIO_new_socket() returns the newly allocated BIO or NULL is an error
+occurred.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
+BIO_debug_callback - BIO callback functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+
+ typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
+ long argl, long ret);
+
+ void BIO_set_callback(BIO *b, BIO_callack_fn cb);
+ BIO_callack_fn BIO_get_callback(BIO *b);
+ void BIO_set_callback_arg(BIO *b, char *arg);
+ char *BIO_get_callback_arg(const BIO *b);
+
+ long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
+ long argl, long ret);
+
+=head1 DESCRIPTION
+
+BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
+they are both macros. The callback is called during most high level BIO
+operations. It can be used for debugging purposes to trace operations on
+a BIO or to modify its operation.
+
+BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
+used to set and retrieve an argument for use in the callback.
+
+BIO_debug_callback() is a standard debugging callback which prints
+out information relating to each BIO operation. If the callback
+argument is set it is interpreted as a BIO to send the information
+to, otherwise stderr is used.
+
+BIO_callback_fn() is the type of the callback function. The meaning of each
+argument is described below:
+
+=over
+
+=item B<b>
+
+The BIO the callback is attached to is passed in B<b>.
+
+=item B<oper>
+
+B<oper> is set to the operation being performed. For some operations
+the callback is called twice, once before and once after the actual
+operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
+
+=item B<argp> B<argi> B<argl>
+
+The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
+the value of B<oper>, that is the operation being performed.
+
+=item B<ret>
+
+B<ret> is the return value that would be returned to the
+application if no callback were present. The actual value returned
+is the return value of the callback itself. In the case of callbacks
+called before the actual BIO operation 1 is placed in B<ret>, if
+the return value is not positive it will be immediately returned to
+the application and the BIO operation will not be performed.
+
+=back
+
+The callback should normally simply return B<ret> when it has
+finished processing, unless it specifically wishes to modify the
+value returned to the application.
+
+=head1 CALLBACK OPERATIONS
+
+In the notes below, B<callback> defers to the actual callback
+function that is called.
+
+=over 4
+
+=item B<BIO_free(b)>
+
+callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
+free operation.
+
+=item B<BIO_read(b, out, outl)>
+
+callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
+the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
+after.
+
+=item B<BIO_write(b, in, inl)>
+
+callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
+the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
+after.
+
+=item B<BIO_gets(b, out, outl)>
+
+callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
+the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
+after.
+
+=item B<BIO_puts(b, in)>
+
+callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
+the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
+after.
+
+=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
+
+callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L) is called before the call and
+callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) after.
+
+=back
+
+=head1 EXAMPLE
+
+The BIO_debug_callback() function is a good example, its source is
+in crypto/bio/bio_cb.c
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BIO_should_read, BIO_should_write,
+BIO_should_io_special, BIO_retry_type, BIO_should_retry,
+BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
+functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ int BIO_should_read(BIO *b);
+ int BIO_should_write(BIO *b);
+ int BIO_should_io_special(iBIO *b);
+ int BIO_retry_type(BIO *b);
+ int BIO_should_retry(BIO *b);
+
+ BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
+ int BIO_get_retry_reason(BIO *bio);
+ void BIO_set_retry_reason(BIO *bio, int reason);
+
+=head1 DESCRIPTION
+
+These functions determine why a BIO is not able to read or write data.
+They will typically be called after a failed BIO_read() or BIO_write()
+call.
+
+BIO_should_retry() is true if the call that produced this condition
+should then be retried at a later time.
+
+If BIO_should_retry() is false then the cause is an error condition.
+
+BIO_should_read() is true if the cause of the condition is that a BIO
+needs to read data.
+
+BIO_should_write() is true if the cause of the condition is that a BIO
+needs to read data.
+
+BIO_should_io_special() is true if some "special" condition, that is a
+reason other than reading or writing is the cause of the condition.
+
+BIO_retry_type() returns a mask of the cause of a retry condition
+consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
+B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
+these.
+
+BIO_get_retry_BIO() determines the precise reason for the special
+condition, it returns the BIO that caused this condition and if
+B<reason> is not NULL it contains the reason code. The meaning of
+the reason code and the action that should be taken depends on
+the type of BIO that resulted in this condition.
+
+BIO_get_retry_reason() returns the reason for a special condition if
+passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
+
+BIO_set_retry_reason() sets the retry reason for a special condition for a given
+BIO. This would usually only be called by BIO implementations.
+
+=head1 NOTES
+
+BIO_should_read(), BIO_should_write(), BIO_should_io_special(),
+BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
+
+If BIO_should_retry() returns false then the precise "error condition"
+depends on the BIO type that caused it and the return code of the BIO
+operation. For example if a call to BIO_read() on a socket BIO returns
+0 and BIO_should_retry() is false then the cause will be that the
+connection closed. A similar condition on a file BIO will mean that it
+has reached EOF. Some BIO types may place additional information on
+the error queue. For more details see the individual BIO type manual
+pages.
+
+If the underlying I/O structure is in a blocking mode almost all current
+BIO types will not request a retry, because the underlying I/O
+calls will not. If the application knows that the BIO type will never
+signal a retry then it need not call BIO_should_retry() after a failed
+BIO I/O call. This is typically done with file BIOs.
+
+SSL BIOs are the only current exception to this rule: they can request a
+retry even if the underlying I/O structure is blocking, if a handshake
+occurs during a call to BIO_read(). An application can retry the failed
+call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
+on the underlying SSL structure.
+
+While an application may retry a failed non blocking call immediately
+this is likely to be very inefficient because the call will fail
+repeatedly until data can be processed or is available. An application
+will normally wait until the necessary condition is satisfied. How
+this is done depends on the underlying I/O structure.
+
+For example if the cause is ultimately a socket and BIO_should_read()
+is true then a call to select() may be made to wait until data is
+available and then retry the BIO operation. By combining the retry
+conditions of several non blocking BIOs in a single select() call
+it is possible to service several BIOs in a single thread, though
+the performance may be poor if SSL BIOs are present because long delays
+can occur during the initial handshake process.
+
+It is possible for a BIO to block indefinitely if the underlying I/O
+structure cannot process or return any data. This depends on the behaviour of
+the platforms I/O functions. This is often not desirable: one solution
+is to use non blocking I/O and use a timeout on the select() (or
+equivalent) call.
+
+=head1 BUGS
+
+The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
+that is they cannot retry after a partial read or write. This is usually
+worked around by only passing the relevant data to ASN1 functions when
+the entire structure can be read or written.
+
+=head1 SEE ALSO
+
+L<bio>
+
+=head1 HISTORY
+
+The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
+OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
+BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
+BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread,
+BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags,
+BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
+ BIGNUM *mod);
+ void BN_BLINDING_free(BN_BLINDING *b);
+ int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
+ int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
+ int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
+ int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
+ BN_CTX *ctx);
+ int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
+ BN_CTX *ctx);
+ int BN_BLINDING_is_current_thread(BN_BLINDING *b);
+ void BN_BLINDING_set_current_thread(BN_BLINDING *b);
+ int BN_BLINDING_lock(BN_BLINDING *b);
+ int BN_BLINDING_unlock(BN_BLINDING *b);
+ unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
+ void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
+ BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
+ const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
+ int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
+ BN_MONT_CTX *m_ctx);
+
+=head1 DESCRIPTION
+
+BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
+the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
+
+BN_BLINDING_free() frees the B<BN_BLINDING> structure.
+If B<b> is NULL, nothing is done.
+
+BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
+the B<A> and B<Ai> or, after specific number of uses and if the
+necessary parameters are set, by re-creating the blinding parameters.
+
+BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
+If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
+returned in B<r> (this is useful if a B<RSA> object is shared among
+several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
+inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
+the inverse blinding.
+
+BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
+functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
+with B<r> set to NULL.
+
+BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING>
+structure is owned by the current thread. This is to help users
+provide proper locking if needed for multi-threaded use.
+
+BN_BLINDING_set_current_thread() sets the current thread as the
+owner of the B<BN_BLINDING> structure.
+
+BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
+
+BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
+
+BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
+there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
+B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
+automatic update of the B<BN_BLINDING> parameters after each use
+and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
+of the B<BN_BLINDING> parameters after a fixed number of uses (currently
+32). In newly allocated B<BN_BLINDING> objects no flags are set.
+BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
+
+BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
+using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
+B<m_ctx> can be used to pass special functions for exponentiation
+(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
+
+=head1 RETURN VALUES
+
+BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
+or NULL in case of an error.
+
+BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
+BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
+success and 0 if an error occurred.
+
+BN_BLINDING_is_current_thread() returns 1 if the current thread owns
+the B<BN_BLINDING> object, 0 otherwise.
+
+BN_BLINDING_set_current_thread() doesn't return anything.
+
+BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
+succeeded or 0 on error.
+
+BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
+(a B<unsigned long> value).
+
+BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
+parameters or NULL on error.
+
+=head1 SEE ALSO
+
+L<bn(3)>
+
+=head1 HISTORY
+
+BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it
+deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().
+
+=head1 COPYRIGHT
+
+Copyright 2005-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_CTX *BN_CTX_new(void);
+
+ BN_CTX *BN_CTX_secure_new(void);
+
+ void BN_CTX_free(BN_CTX *c);
+
+=head1 DESCRIPTION
+
+A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
+library functions. Since dynamic memory allocation to create B<BIGNUM>s
+is rather expensive when used in conjunction with repeated subroutine
+calls, the B<BN_CTX> structure is used.
+
+BN_CTX_new() allocates and initializes a B<BN_CTX> structure.
+BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure
+but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the
+B<BIGNUM>s.
+
+BN_CTX_free() frees the components of the B<BN_CTX>, and if it was
+created by BN_CTX_new(), also the structure itself.
+If L<BN_CTX_start(3)> has been used on the B<BN_CTX>,
+L<BN_CTX_end(3)> must be called before the B<BN_CTX>
+may be freed by BN_CTX_free().
+If B<c> is NULL, nothing is done.
+
+=head1 RETURN VALUES
+
+BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>.
+If the allocation fails,
+they return B<NULL> and sets an error code that can be obtained by
+L<ERR_get_error(3)>.
+
+BN_CTX_free() has no return values.
+
+=head1 REMOVED FUNCTIONALITY
+
+ void BN_CTX_init(BN_CTX *c);
+
+BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should
+replace use of BN_CTX_init with BN_CTX_new instead:
+
+ BN_CTX *ctx;
+ ctx = BN_CTX_new();
+ if(!ctx) /* Handle error */
+ ...
+ BN_CTX_free(ctx);
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
+L<BN_CTX_start(3)>
+
+=head1 HISTORY
+
+BN_CTX_init() was removed in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ void BN_CTX_start(BN_CTX *ctx);
+
+ BIGNUM *BN_CTX_get(BN_CTX *ctx);
+
+ void BN_CTX_end(BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+These functions are used to obtain temporary B<BIGNUM> variables from
+a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)>)
+in order to save the overhead of repeatedly creating and
+freeing B<BIGNUM>s in functions that are called from inside a loop.
+
+A function must call BN_CTX_start() first. Then, BN_CTX_get() may be
+called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get()
+calls must be made before calling any other functions that use the
+B<ctx> as an argument.
+
+Finally, BN_CTX_end() must be called before returning from the function.
+When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from
+BN_CTX_get() become invalid.
+
+=head1 RETURN VALUES
+
+BN_CTX_start() and BN_CTX_end() return no values.
+
+BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error.
+Once BN_CTX_get() has failed, the subsequent calls will return B<NULL>
+as well, so it is sufficient to check the return value of the last
+BN_CTX_get() call. In case of an error, an error code is set, which
+can be obtained by L<ERR_get_error(3)>.
+
+
+=head1 SEE ALSO
+
+L<BN_CTX_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
+BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd -
+arithmetic operations on BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
+
+ int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
+
+ int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+
+ int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
+
+ int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
+ BN_CTX *ctx);
+
+ int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+
+ int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+
+ int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+ BN_CTX *ctx);
+
+ int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
+
+ int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
+I<r> may be the same B<BIGNUM> as I<a> or I<b>.
+
+BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
+I<r> may be the same B<BIGNUM> as I<a> or I<b>.
+
+BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
+I<r> may be the same B<BIGNUM> as I<a> or I<b>.
+For multiplication by powers of 2, use L<BN_lshift(3)>.
+
+BN_sqr() takes the square of I<a> and places the result in I<r>
+(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
+This function is faster than BN_mul(r,a,a).
+
+BN_div() divides I<a> by I<d> and places the result in I<dv> and the
+remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may
+be B<NULL>, in which case the respective value is not returned.
+The result is rounded towards zero; thus if I<a> is negative, the
+remainder will be zero or negative.
+For division by powers of 2, use BN_rshift(3).
+
+BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>.
+
+BN_nnmod() reduces I<a> modulo I<m> and places the non-negative
+remainder in I<r>.
+
+BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative
+result in I<r>.
+
+BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the
+non-negative result in I<r>.
+
+BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
+remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
+the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
+repeated computations using the same modulus, see
+L<BN_mod_mul_montgomery(3)> and
+L<BN_mod_mul_reciprocal(3)>.
+
+BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
+result in I<r>.
+
+BN_exp() raises I<a> to the I<p>-th power and places the result in I<r>
+(C<r=a^p>). This function is faster than repeated applications of
+BN_mul().
+
+BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p %
+m>). This function uses less time and space than BN_exp().
+
+BN_gcd() computes the greatest common divisor of I<a> and I<b> and
+places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
+I<b>.
+
+For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
+temporary variables; see L<BN_CTX_new(3)>.
+
+Unless noted otherwise, the result B<BIGNUM> must be different from
+the arguments.
+
+=head1 RETURN VALUES
+
+For all functions, 1 is returned for success, 0 on error. The return
+value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<BN_CTX_new(3)>,
+L<BN_add_word(3)>, L<BN_set_bit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic
+functions on BIGNUMs with integers
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_add_word(BIGNUM *a, BN_ULONG w);
+
+ int BN_sub_word(BIGNUM *a, BN_ULONG w);
+
+ int BN_mul_word(BIGNUM *a, BN_ULONG w);
+
+ BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
+
+ BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
+
+=head1 DESCRIPTION
+
+These functions perform arithmetic operations on BIGNUMs with unsigned
+integers. They are much more efficient than the normal BIGNUM
+arithmetic operations.
+
+BN_add_word() adds B<w> to B<a> (C<a+=w>).
+
+BN_sub_word() subtracts B<w> from B<a> (C<a-=w>).
+
+BN_mul_word() multiplies B<a> and B<w> (C<a*=w>).
+
+BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder.
+
+BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%w>).
+
+For BN_div_word() and BN_mod_word(), B<w> must not be 0.
+
+=head1 RETURN VALUES
+
+BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0
+on error. The error codes can be obtained by L<ERR_get_error(3)>.
+
+BN_mod_word() and BN_div_word() return B<a>%B<w> on success and
+B<(BN_ULONG)-1> if an error occurred.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_bn2binpad,
+BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec,
+BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi,
+BN_mpi2bn - format conversions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_bn2bin(const BIGNUM *a, unsigned char *to);
+ int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);
+ BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
+
+ int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
+ BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
+
+ char *BN_bn2hex(const BIGNUM *a);
+ char *BN_bn2dec(const BIGNUM *a);
+ int BN_hex2bn(BIGNUM **a, const char *str);
+ int BN_dec2bn(BIGNUM **a, const char *str);
+
+ int BN_print(BIO *fp, const BIGNUM *a);
+ int BN_print_fp(FILE *fp, const BIGNUM *a);
+
+ int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
+ BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
+
+=head1 DESCRIPTION
+
+BN_bn2bin() converts the absolute value of B<a> into big-endian form
+and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
+memory.
+
+BN_bn2binpad() also converts the absolute value of B<a> into big-endian form
+and stores it at B<to>. B<tolen> indicates the length of the output buffer
+B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than
+BN_num_bytes(B<a>) an error is returned.
+
+BN_bin2bn() converts the positive integer in big-endian form of length
+B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
+NULL, a new B<BIGNUM> is created.
+
+BN_bn2lebinpad() and BN_bin2lbn() are identical to BN_bn2binpad() and
+BN_bin2bn() except the buffer is in little-endian format.
+
+BN_bn2hex() and BN_bn2dec() return printable strings containing the
+hexadecimal and decimal encoding of B<a> respectively. For negative
+numbers, the string is prefaced with a leading '-'. The string must be
+freed later using OPENSSL_free().
+
+BN_hex2bn() takes as many characters as possible from the string B<str>,
+including the leading character '-' which means negative, to form a valid
+hexadecimal number representation and converts them to a B<BIGNUM> and
+stores it in **B<bn>. If *B<bn> is NULL, a new B<BIGNUM> is created. If
+B<bn> is NULL, it only computes the length of valid representation.
+A "negative zero" is converted to zero.
+BN_dec2bn() is the same using the decimal system.
+
+BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>,
+with a leading '-' for negative numbers, to the B<BIO> or B<FILE>
+B<fp>.
+
+BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format
+that consists of the number's length in bytes represented as a 4-byte
+big-endian number, and the number itself in big-endian format, where
+the most significant bit signals a negative number (the representation
+of numbers with the MSB set is prefixed with null byte).
+
+BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to>
+must be large enough to hold the result. The size can be determined by
+calling BN_bn2mpi(B<a>, NULL).
+
+BN_mpi2bn() converts the B<len> bytes long representation at B<s> to
+a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM>
+if B<ret> is NULL.
+
+=head1 RETURN VALUES
+
+BN_bn2bin() returns the length of the big-endian number placed at B<to>.
+BN_bin2bn() returns the B<BIGNUM>, NULL on error.
+
+BN_bn2binpad() returns the number of bytes written or -1 if the supplied
+buffer is too small.
+
+BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL
+on error. BN_hex2bn() and BN_dec2bn() return the the length of valid
+representation in hexadecimal or decimal digits, and 0 on error, in which
+case no new B<BIGNUM> will be created.
+
+BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
+
+BN_bn2mpi() returns the length of the representation. BN_mpi2bn()
+returns the B<BIGNUM>, and NULL on error.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<BN_zero(3)>,
+L<ASN1_INTEGER_to_BN(3)>,
+L<BN_num_bytes(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_cmp(BIGNUM *a, BIGNUM *b);
+ int BN_ucmp(BIGNUM *a, BIGNUM *b);
+
+ int BN_is_zero(BIGNUM *a);
+ int BN_is_one(BIGNUM *a);
+ int BN_is_word(BIGNUM *a, BN_ULONG w);
+ int BN_is_odd(BIGNUM *a);
+
+=head1 DESCRIPTION
+
+BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their
+absolute values.
+
+BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1,
+or B<w> respectively. BN_is_odd() tests if a is odd.
+
+BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros.
+
+=head1 RETURN VALUES
+
+BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if
+B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values
+of B<a> and B<b>.
+
+BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if
+the condition is true, 0 otherwise.
+
+=head1 SEE ALSO
+
+L<bn(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_copy, BN_dup, BN_with_flags - copy BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);
+
+ BIGNUM *BN_dup(const BIGNUM *from);
+
+ void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);
+
+=head1 DESCRIPTION
+
+BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM>
+containing the value B<from>.
+
+BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places
+significant restrictions on the copied data. Applications that do no adhere to
+these restrictions may encounter unexpected side effects or crashes. For that
+reason use of this function is discouraged. Any flags provided in B<flags> will
+be set in B<dest> in addition to any flags already set in B<b>. For example this
+might commonly be used to create a temporary copy of a BIGNUM with the
+B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in
+B<dest> will share some internal state with B<b>. For this reason the following
+restrictions apply to the use of B<dest>:
+
+=over 4
+
+=item *
+
+B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It
+should not have been used for other purposes or initialised in any way.
+
+=item *
+
+B<dest> must only be used in "read-only" operations, i.e. typically those
+functions where the relevant parameter is declared "const".
+
+=item *
+
+B<dest> must be used and freed before any further subsequent use of B<b>
+
+=back
+
+=head1 RETURN VALUES
+
+BN_copy() returns B<to> on success, NULL on error. BN_dup() returns
+the new B<BIGNUM>, and NULL on error. The error codes can be obtained
+by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
+BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg,
+BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test
+for primality
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
+ const BIGNUM *rem, BN_GENCB *cb);
+
+ int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
+
+ int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
+ int do_trial_division, BN_GENCB *cb);
+
+ int BN_GENCB_call(BN_GENCB *cb, int a, int b);
+
+ BN_GENCB *BN_GENCB_new(void);
+
+ void BN_GENCB_free(BN_GENCB *cb);
+
+ void BN_GENCB_set_old(BN_GENCB *gencb,
+ void (*callback)(int, int, void *), void *cb_arg);
+
+ void BN_GENCB_set(BN_GENCB *gencb,
+ int (*callback)(int, int, BN_GENCB *), void *cb_arg);
+
+ void *BN_GENCB_get_arg(BN_GENCB *cb);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x00908000L
+ BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
+ BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
+
+ int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,
+ void *), BN_CTX *ctx, void *cb_arg);
+
+ int BN_is_prime_fasttest(const BIGNUM *a, int checks,
+ void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
+ int do_trial_division);
+ #endif
+
+=head1 DESCRIPTION
+
+BN_generate_prime_ex() generates a pseudo-random prime number of
+at least bit length B<bits>.
+If B<ret> is not B<NULL>, it will be used to store the number.
+
+If B<cb> is not B<NULL>, it is used as follows:
+
+=over 4
+
+=item *
+
+B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th
+potential prime number.
+
+=item *
+
+While the number is being tested for primality,
+B<BN_GENCB_call(cb, 1, j)> is called as described below.
+
+=item *
+
+When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called.
+
+=back
+
+The prime may have to fulfill additional requirements for use in
+Diffie-Hellman key exchange:
+
+If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add>
+== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given
+generator.
+
+If B<safe> is true, it will be a safe prime (i.e. a prime p so
+that (p-1)/2 is also prime).
+
+The PRNG must be seeded prior to calling BN_generate_prime_ex().
+The prime number generation has a negligible error probability.
+
+BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
+prime. The following tests are performed until one of them shows that
+B<p> is composite; if B<p> passes all these tests, it is considered
+prime.
+
+BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>,
+first attempts trial division by a number of small primes;
+if no divisors are found by this test and B<cb> is not B<NULL>,
+B<BN_GENCB_call(cb, 1, -1)> is called.
+If B<do_trial_division == 0>, this test is skipped.
+
+Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin
+probabilistic primality test with B<nchecks> iterations. If
+B<nchecks == BN_prime_checks>, a number of iterations is used that
+yields a false positive rate of at most 2^-80 for random input.
+
+If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called
+after the j-th iteration (j = 0, 1, ...). B<ctx> is a
+pre-allocated B<BN_CTX> (to save the overhead of allocating and
+freeing the structure in a loop), or B<NULL>.
+
+BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure
+and passes the ints B<a> and B<b> as arguments. There are two types of
+B<BN_GENCB> structure that are supported: "new" style and "old" style. New
+programs should prefer the "new" style, whilst the "old" style is provided
+for backwards compatibility purposes.
+
+A BN_GENCB structure should be created through a call to BN_GENCB_new(),
+and freed through a call to BN_GENCB_free().
+
+For "new" style callbacks a BN_GENCB structure should be initialised with a
+call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of
+type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>.
+"Old" style callbacks are the same except they are initialised with a call
+to BN_GENCB_set_old() and B<callback> is of type
+B<void (*callback)(int, int, void *)>.
+
+A callback is invoked through a call to B<BN_GENCB_call>. This will check
+the type of the callback and will invoke B<callback(a, b, gencb)> for new
+style callbacks or B<callback(a, b, cb_arg)> for old style.
+
+It is possible to obtained the argument associated with a BN_GENCB structure
+(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
+
+BN_generate_prime (deprecated) works in the same way as
+BN_generate_prime_ex but expects an old style callback function
+directly in the B<callback> parameter, and an argument to pass to it in
+the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are
+deprecated and can be compared to BN_is_prime_ex and
+BN_is_prime_fasttest_ex respectively.
+
+=head1 RETURN VALUES
+
+BN_generate_prime_ex() return 1 on success or 0 on error.
+
+BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and
+BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is
+prime with an error probability of less than 0.25^B<nchecks>, and
+-1 on error.
+
+BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
+
+BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL>
+otherwise.
+
+BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB
+structure.
+
+Callback functions should return 1 on success or 0 on error.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 REMOVED FUNCTIONALITY
+
+As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure
+directly, as in:
+
+ BN_GENCB callback;
+
+Instead applications should create a BN_GENCB structure using BN_GENCB_new:
+
+ BN_GENCB *callback;
+ callback = BN_GENCB_new();
+ if(!callback) /* handle error */
+ ...
+ BN_GENCB_free(callback);
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>
+
+=head1 HISTORY
+
+BN_GENCB_new(), BN_GENCB_free(),
+and BN_GENCB_get_arg() were added in OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_mod_inverse - compute inverse modulo n
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
+ BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+BN_mod_inverse() computes the inverse of B<a> modulo B<n>
+places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL,
+a new B<BIGNUM> is created.
+
+B<ctx> is a previously allocated B<BN_CTX> used for temporary
+variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>.
+
+=head1 RETURN VALUES
+
+BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and
+NULL on error. The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_mod_mul_montgomery, BN_MONT_CTX_new,
+BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
+BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_MONT_CTX *BN_MONT_CTX_new(void);
+ void BN_MONT_CTX_free(BN_MONT_CTX *mont);
+
+ int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
+ BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
+
+ int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
+ BN_MONT_CTX *mont, BN_CTX *ctx);
+
+ int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
+ BN_CTX *ctx);
+
+ int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
+ BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+These functions implement Montgomery multiplication. They are used
+automatically when L<BN_mod_exp(3)> is called with suitable input,
+but they may be useful when several operations are to be performed
+using the same modulus.
+
+BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure.
+
+BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m>
+by precomputing its inverse and a value R.
+
+BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>.
+
+BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if
+it was created by BN_MONT_CTX_new(), also the structure itself.
+If B<mont> is NULL, nothing is done.
+
+BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places
+the result in I<r>.
+
+BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1.
+
+BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R.
+Note that I<a> must be non-negative and smaller than the modulus.
+
+For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
+temporary variables.
+
+=head1 RETURN VALUES
+
+BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL
+on error.
+
+BN_MONT_CTX_free() has no return value.
+
+For the other functions, 1 is returned for success, 0 on error.
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 WARNING
+
+The inputs must be reduced modulo B<m>, otherwise the result will be
+outside the expected range.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
+L<BN_CTX_new(3)>
+
+=head1 HISTORY
+
+BN_MONT_CTX_init() was removed in OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new,
+BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
+reciprocal
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BN_RECP_CTX *BN_RECP_CTX_new(void);
+ void BN_RECP_CTX_free(BN_RECP_CTX *recp);
+
+ int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
+
+ int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp,
+ BN_CTX *ctx);
+
+ int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
+ BN_RECP_CTX *recp, BN_CTX *ctx);
+
+=head1 DESCRIPTION
+
+BN_mod_mul_reciprocal() can be used to perform an efficient
+L<BN_mod_mul(3)> operation when the operation will be performed
+repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m>
+using B<recp>=1/B<m>, which is set as described below. B<ctx> is a
+previously allocated B<BN_CTX> used for temporary variables.
+
+BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure.
+
+BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it
+was created by BN_RECP_CTX_new(), also the structure itself.
+If B<recp> is NULL, nothing is done.
+
+BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing
+1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an
+integer. The result and the number of bits it was shifted left will
+later be stored in B<recp>.
+
+BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient
+in B<dv> and the remainder in B<rem>.
+
+The B<BN_RECP_CTX> structure cannot be shared between threads.
+
+=head1 RETURN VALUES
+
+BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL
+on error.
+
+BN_RECP_CTX_free() has no return value.
+
+For the other functions, 1 is returned for success, 0 on error.
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
+L<BN_CTX_new(3)>
+
+=head1 HISTORY
+
+BN_RECP_CTX_init() was removed in OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ BIGNUM *BN_new(void);
+
+ BIGNUM *BN_secure_new(void);
+
+ void BN_clear(BIGNUM *a);
+
+ void BN_free(BIGNUM *a);
+
+ void BN_clear_free(BIGNUM *a);
+
+=head1 DESCRIPTION
+
+BN_new() allocates and initializes a B<BIGNUM> structure.
+BN_secure_new() does the same except that the secure heap
+OPENSSL_secure_malloc(3) is used to store the value.
+
+BN_clear() is used to destroy sensitive data such as keys when they
+are no longer needed. It erases the memory used by B<a> and sets it
+to the value 0.
+
+BN_free() frees the components of the B<BIGNUM>, and if it was created
+by BN_new(), also the structure itself. BN_clear_free() additionally
+overwrites the data before the memory is returned to the system.
+If B<a> is NULL, nothing is done.
+
+=head1 RETURN VALUES
+
+BN_new() and BN_secure_new()
+return a pointer to the B<BIGNUM>. If the allocation fails,
+they return B<NULL> and set an error code that can be obtained
+by L<ERR_get_error(3)>.
+
+BN_clear(), BN_free() and BN_clear_free() have no return values.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>
+
+=head1 HISTORY
+
+BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_num_bytes(const BIGNUM *a);
+
+ int BN_num_bits(const BIGNUM *a);
+
+ int BN_num_bits_word(BN_ULONG w);
+
+=head1 DESCRIPTION
+
+BN_num_bytes() returns the size of a B<BIGNUM> in bytes.
+
+BN_num_bits_word() returns the number of significant bits in a word.
+If we take 0x00000432 as an example, it returns 11, not 16, not 32.
+Basically, except for a zero, it returns I<floor(log2(w))+1>.
+
+BN_num_bits() returns the number of significant bits in a B<BIGNUM>,
+following the same principle as BN_num_bits_word().
+
+BN_num_bytes() is a macro.
+
+=head1 RETURN VALUES
+
+The size.
+
+=head1 NOTES
+
+Some have tried using BN_num_bits() on individual numbers in RSA keys,
+DH keys and DSA keys, and found that they don't always come up with
+the number of bits they expected (something like 512, 1024, 2048,
+...). This is because generating a number with some specific number
+of bits doesn't always set the highest bits, thereby making the number
+of I<significant> bits a little lower. If you want to know the "key
+size" of such a key, either use functions like RSA_size(), DH_size()
+and DSA_size(), or use BN_num_bytes() and multiply with 8 (although
+there's no real guarantee that will match the "key size", just a lot
+more probability).
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<DH_size(3)>, L<DSA_size(3)>,
+L<RSA_size(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
+
+ int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
+
+ int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
+
+ int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
+
+=head1 DESCRIPTION
+
+BN_rand() generates a cryptographically strong pseudo-random number of
+B<bits> in length and stores it in B<rnd>.
+If B<bits> is less than zero, or too small to
+accomodate the requirements specified by the B<top> and B<bottom>
+parameters, an error is returned.
+The B<top> parameters specifies
+requirements on the most significant bit of the generated number.
+If it is B<BN_RAND_TOP_ANY>, there is no constraint.
+If it is B<BN_RAND_TOP_ONE>, the top bit must be one.
+If it is B<BN_RAND_TOP_TWO>, the two most significant bits of
+the number will be set to 1, so that the product of two such random
+numbers will always have 2*B<bits> length.
+If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
+is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
+If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
+
+BN_pseudo_rand() does the same, but pseudo-random numbers generated by
+this function are not necessarily unpredictable. They can be used for
+non-cryptographic purposes and for certain purposes in cryptographic
+protocols, but usually not for key generation etc.
+
+BN_rand_range() generates a cryptographically strong pseudo-random
+number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
+BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(),
+and hence numbers generated by it are not necessarily unpredictable.
+
+The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
+
+=head1 RETURN VALUES
+
+The functions return 1 on success, 0 on error.
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>,
+L<RAND_add(3)>, L<RAND_bytes(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift,
+BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ int BN_set_bit(BIGNUM *a, int n);
+ int BN_clear_bit(BIGNUM *a, int n);
+
+ int BN_is_bit_set(const BIGNUM *a, int n);
+
+ int BN_mask_bits(BIGNUM *a, int n);
+
+ int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
+ int BN_lshift1(BIGNUM *r, BIGNUM *a);
+
+ int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
+ int BN_rshift1(BIGNUM *r, BIGNUM *a);
+
+=head1 DESCRIPTION
+
+BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The
+number is expanded if necessary.
+
+BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An
+error occurs if B<a> is shorter than B<n> bits.
+
+BN_is_bit_set() tests if bit B<n> in B<a> is set.
+
+BN_mask_bits() truncates B<a> to an B<n> bit number
+(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is
+shorter than B<n> bits.
+
+BN_lshift() shifts B<a> left by B<n> bits and places the result in
+B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts
+B<a> left by one and places the result in B<r> (C<r=2*a>).
+
+BN_rshift() shifts B<a> right by B<n> bits and places the result in
+B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts
+B<a> right by one and places the result in B<r> (C<r=a/2>).
+
+For the shift functions, B<r> and B<a> may be the same variable.
+
+=head1 RETURN VALUES
+
+BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.
+
+All other functions return 1 for success, 0 on error. The error codes
+can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<BN_num_bytes(3)>, L<BN_add(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=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)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment
+operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/bn.h>
+
+ void BN_zero(BIGNUM *a);
+ int BN_one(BIGNUM *a);
+
+ const BIGNUM *BN_value_one(void);
+
+ int BN_set_word(BIGNUM *a, unsigned long w);
+ unsigned long BN_get_word(BIGNUM *a);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x00908000L
+ int BN_zero(BIGNUM *a);
+ #endif
+
+=head1 DESCRIPTION
+
+BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
+B<w> respectively. BN_zero() and BN_one() are macros.
+
+BN_value_one() returns a B<BIGNUM> constant of value 1. This constant
+is useful for use in comparisons and assignment.
+
+BN_get_word() returns B<a>, if it can be represented as an unsigned
+long.
+
+=head1 RETURN VALUES
+
+BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot
+be represented as an unsigned long.
+
+BN_one(), BN_set_word() and the deprecated version of BN_zero()
+return 1 on success, 0 otherwise.
+BN_value_one() returns the constant.
+The preferred version of BN_zero() never fails and returns no value.
+
+=head1 BUGS
+
+Someone might change the constant.
+
+If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an
+unsigned long but this value is also returned on error.
+
+=head1 SEE ALSO
+
+L<bn(3)>, L<BN_bn2bin(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow
+BUF_MEM_grow_clean, BUF_reverse
+- simple character array structure
+
+standard C library equivalents
+
+=head1 SYNOPSIS
+
+ #include <openssl/buffer.h>
+
+ BUF_MEM *BUF_MEM_new(void);
+
+ BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
+
+ void BUF_MEM_free(BUF_MEM *a);
+
+ int BUF_MEM_grow(BUF_MEM *str, int len);
+ size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len);
+
+ void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size);
+
+=head1 DESCRIPTION
+
+The buffer library handles simple character arrays. Buffers are used for
+various purposes in the library, most notably memory BIOs.
+
+BUF_MEM_new() allocates a new buffer of zero size.
+
+BUF_MEM_new_ex() allocates a buffer with the specified flags.
+The flag B<BUF_MEM_FLAG_SECURE> specifies that the B<data> pointer
+should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>.
+
+BUF_MEM_free() frees up an already existing buffer. The data is zeroed
+before freeing up in case the buffer contains sensitive data.
+
+BUF_MEM_grow() changes the size of an already existing buffer to
+B<len>. Any data already in the buffer is preserved if it increases in
+size.
+
+BUF_MEM_grow_clean() is similar to BUF_MEM_grow() but it sets any free'd
+or additionally-allocated memory to zero.
+
+BUF_reverse() reverses B<size> bytes at B<in> into B<out>. If B<out>
+is NULL, the array is reversed in-place.
+
+=head1 RETURN VALUES
+
+BUF_MEM_new() returns the buffer or NULL on error.
+
+BUF_MEM_free() has no return value.
+
+BUF_MEM_grow() and BUF_MEM_grow_clean() return
+zero on error or the new size (i.e., B<len>).
+
+=head1 SEE ALSO
+
+L<bio(3)>,
+L<CRYPTO_secure_malloc(3)>.
+
+=head1 HISTORY
+
+BUF_MEM_new_ex() was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);
+ int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);
+ STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);
+
+ int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);
+ int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl);
+ STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);
+
+
+=head1 DESCRIPTION
+
+CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>.
+must be of type signed data or enveloped data.
+
+CMS_get1_certs() returns all certificates in B<cms>.
+
+CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls()
+returns any CRLs in B<cms>.
+
+=head1 NOTES
+
+The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped
+data or an error will be returned.
+
+For signed data certificates and CRLs are added to the B<certificates> and
+B<crls> fields of SignedData structure. For enveloped data they are added to
+B<OriginatorInfo>.
+
+As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it
+must not be freed up after the call as opposed to CMS_add1_cert() where B<cert>
+must be freed up.
+
+The same certificate or CRL must not be added to the same cms structure more
+than once.
+
+=head1 RETURN VALUES
+
+CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return
+1 for success and 0 for failure.
+
+CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
+or NULL if there are none or an error occurs. The only error which will occur
+in practice is if the B<cms> type is invalid.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<CMS_sign(3)>,
+L<CMS_encrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags);
+
+ CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType);
+
+=head1 DESCRIPTION
+
+CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
+data structure B<cms> as a KeyTransRecipientInfo structure.
+
+CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using
+wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional
+values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped
+data structure B<cms> as a KEKRecipientInfo structure.
+
+The CMS_ContentInfo structure should be obtained from an initial call to
+CMS_encrypt() with the flag B<CMS_PARTIAL> set.
+
+=head1 NOTES
+
+The main purpose of this function is to provide finer control over a CMS
+enveloped data structure where the simpler CMS_encrypt() function defaults are
+not appropriate. For example if one or more KEKRecipientInfo structures
+need to be added. New attributes can also be added using the returned
+CMS_RecipientInfo structure and the CMS attribute utility functions.
+
+OpenSSL will by default identify recipient certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if all recipient certificates do not
+have a subject key identifier extension.
+
+Currently only AES based key wrapping algorithms are supported for B<nid>,
+specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap.
+If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used
+consistent with B<keylen>.
+
+=head1 RETURN VALUES
+
+CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal
+pointer to the CMS_RecipientInfo structure just added or NULL if an error
+occurs.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
+L<CMS_final(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
+
+ int CMS_SignerInfo_sign(CMS_SignerInfo *si);
+
+
+=head1 DESCRIPTION
+
+CMS_add1_signer() adds a signer with certificate B<signcert> and private
+key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
+structure B<cms>.
+
+The CMS_ContentInfo structure should be obtained from an initial call to
+CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a
+valid CMS_ContentInfo SignedData structure.
+
+If the B<md> parameter is B<NULL> then the default digest for the public
+key algorithm will be used.
+
+Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo
+structure is not complete and must be finalized either by streaming (if
+applicable) or a call to CMS_final().
+
+The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo
+structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags
+are both set.
+
+=head1 NOTES
+
+The main purpose of CMS_add1_signer() is to provide finer control
+over a CMS signed data structure where the simpler CMS_sign() function defaults
+are not appropriate. For example if multiple signers or non default digest
+algorithms are needed. New attributes can also be added using the returned
+CMS_SignerInfo structure and the CMS attribute utility functions or the
+CMS signed receipt request functions.
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter.
+
+If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content
+digest value from the CMS_ContentInfo structure: to add a signer to an existing
+structure. An error occurs if a matching digest value cannot be found to copy.
+The returned CMS_ContentInfo structure will be valid and finalized when this
+flag is set.
+
+If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the
+CMS_SignerInfo structure will not be finalized so additional attributes
+can be added. In this case an explicit call to CMS_SignerInfo_sign() is
+needed to finalize it.
+
+If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
+CMS_ContentInfo structure, the signer's certificate must still be supplied in
+the B<signcert> parameter though. This can reduce the size of the signature if
+the signers certificate can be obtained by other means: for example a
+previously signed message.
+
+The SignedData structure includes several CMS signedAttributes including the
+signing time, the CMS content type and the supported list of ciphers in an
+SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
+will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
+omitted.
+
+OpenSSL will by default identify signing certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if the signing certificate does not
+have a subject key identifier extension.
+
+If present the SMIMECapabilities attribute indicates support for the following
+algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
+bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
+If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
+not loaded.
+
+CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
+structure just added, this can be used to set additional attributes
+before it is finalized.
+
+=head1 RETURN VALUES
+
+CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
+structure just added or NULL if an error occurs.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>,
+L<CMS_final(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_compress - create a CMS CompressedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid>
+is the compression algorithm to use or B<NID_undef> to use the default
+algorithm (zlib compression). B<in> is the content to be compressed.
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+The only currently supported compression algorithm is zlib using the NID
+NID_zlib_compression.
+
+If zlib support is not compiled into OpenSSL then CMS_compress() will return
+an error.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
+prepended to the data.
+
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
+occurs. This option should be used if the supplied data is in binary format
+otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
+B<CMS_TEXT> is ignored.
+
+If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
+returned suitable for streaming I/O: no data is read from the BIO B<in>.
+
+The compressed data is included in the CMS_ContentInfo structure, unless
+B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
+practice and is not supported by SMIME_write_CMS().
+
+=head1 NOTES
+
+If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
+B<not> complete and outputting its contents via a function that does not
+properly finalize the B<CMS_ContentInfo> structure will give unpredictable
+results.
+
+Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
+PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_CMS().
+
+Additional compression parameters such as the zlib compression level cannot
+currently be set.
+
+=head1 RETURN VALUES
+
+CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_uncompress(3)>
+
+=head1 HISTORY
+
+The B<CMS_STREAM> flag was added in OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_decrypt - decrypt content from a CMS envelopedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData
+structure. B<pkey> is the private key of the recipient, B<cert> is the
+recipient's certificate, B<out> is a BIO to write the content to and
+B<flags> is an optional set of flags.
+
+The B<dcont> parameter is used in the rare case where the encrypted content
+is detached. It will normally be set to NULL.
+
+=head1 NOTES
+
+Although the recipients certificate is not needed to decrypt the data it is
+needed to locate the appropriate (of possible several) recipients in the CMS
+structure.
+
+If B<cert> is set to NULL all possible recipients are tried. This case however
+is problematic. To thwart the MMA attack (Bleichenbacher's attack on
+PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
+not. If no recipient succeeds then a random symmetric key is used to decrypt
+the content: this will typically output garbage and may (but is not guaranteed
+to) ultimately return a padding error only. If CMS_decrypt() just returned an
+error when all recipient encrypted keys failed to decrypt an attacker could
+use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set
+then the above behaviour is modified and an error B<is> returned if no
+recipient encrypted key can be decrypted B<without> generating a random
+content encryption key. Applications should use this flag with
+B<extreme caution> especially in automated gateways as it can leave them
+open to attack.
+
+It is possible to determine the correct recipient key by other means (for
+example looking them up in a database) and setting them in the CMS structure
+in advance using the CMS utility functions such as CMS_set1_pkey(). In this
+case both B<cert> and B<pkey> should be set to NULL.
+
+To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
+and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and
+B<cert> and B<pkey> set to NULL.
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+=head1 RETURN VALUES
+
+CMS_decrypt() returns either 1 for success or 0 for failure.
+The error can be obtained from ERR_get_error(3)
+
+=head1 BUGS
+
+The lack of single pass processing and the need to hold all data in memory as
+mentioned in CMS_verify() also applies to CMS_decrypt().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_encrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_encrypt - create a CMS envelopedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs>
+is a list of recipient certificates. B<in> is the content to be encrypted.
+B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Only certificates carrying RSA keys are supported so the recipient certificates
+supplied to this function must all contain RSA public keys, though they do not
+have to be signed using the RSA algorithm.
+
+EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
+because most clients will support it.
+
+The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
+its parameters.
+
+Many browsers implement a "sign and encrypt" option which is simply an S/MIME
+envelopedData containing an S/MIME signed message. This can be readily produced
+by storing the S/MIME signed message in a memory BIO and passing it to
+CMS_encrypt().
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are
+prepended to the data.
+
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
+occurs. This option should be used if the supplied data is in binary format
+otherwise the translation will corrupt it. If B<CMS_BINARY> is set then
+B<CMS_TEXT> is ignored.
+
+OpenSSL will by default identify recipient certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if all recipient certificates do not
+have a subject key identifier extension.
+
+If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
+returned suitable for streaming I/O: no data is read from the BIO B<in>.
+
+If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
+returned to which additional recipients and attributes can be added before
+finalization.
+
+The data being encrypted is included in the CMS_ContentInfo structure, unless
+B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
+practice and is not supported by SMIME_write_CMS().
+
+=head1 NOTES
+
+If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
+B<not> complete and outputting its contents via a function that does not
+properly finalize the B<CMS_ContentInfo> structure will give unpredictable
+results.
+
+Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
+PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_CMS().
+
+The recipients specified in B<certs> use a CMS KeyTransRecipientInfo info
+structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL>
+and CMS_add0_recipient_key().
+
+The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients
+added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().
+
+=head1 RETURN VALUES
+
+CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_decrypt(3)>
+
+=head1 HISTORY
+
+The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_final - finalise a CMS_ContentInfo structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_final() finalises the structure B<cms>. It's purpose is to perform any
+operations necessary on B<cms> (digest computation for example) and set the
+appropriate fields. The parameter B<data> contains the content to be
+processed. The B<dcont> parameter contains a BIO to write content to after
+processing: this is only used with detached data and will usually be set to
+NULL.
+
+=head1 NOTES
+
+This function will normally be called when the B<CMS_PARTIAL> flag is used. It
+should only be used when streaming is not performed because the streaming
+I/O functions perform finalisation operations internally.
+
+=head1 RETURN VALUES
+
+CMS_final() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>,
+L<CMS_encrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
+CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
+CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
+CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key,
+CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt
+- CMS envelopedData RecipientInfo routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);
+ int CMS_RecipientInfo_type(CMS_RecipientInfo *ri);
+
+ int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
+ int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
+ int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
+
+ int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype);
+ int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen);
+ int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
+
+ int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
+ int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
+
+=head1 DESCRIPTION
+
+The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo
+structures associated with a CMS EnvelopedData structure.
+
+CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>.
+It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE,
+CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.
+
+CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient
+identifier associated with a specific CMS_RecipientInfo structure B<ri>, which
+must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in
+B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>.
+
+CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the
+CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS.
+It returns zero if the comparison is successful and non zero if not.
+
+CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
+the CMS_RecipientInfo structure B<ri>, which must be of type
+CMS_RECIPINFO_TRANS.
+
+CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
+CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any
+of the remaining parameters can be NULL if the application is not interested in
+the value of a field. Where a field is optional and absent NULL will be written
+to the corresponding parameter. The keyEncryptionAlgorithm field is written to
+B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if
+present is written to B<pdate>, if the B<other> field is present the components
+B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and
+B<pothertype>.
+
+CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen>
+parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>,
+which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is
+successful and non zero if not.
+
+CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length
+B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type
+CMS_RECIPINFO_KEK.
+
+CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
+B<ri> in structure B<cms>. A key must have been associated with the structure
+first.
+
+CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
+B<ri> in structure B<cms>. A key must have been associated with the structure
+first and the content encryption key must be available: for example by a
+previous call to CMS_RecipientInfo_decrypt().
+
+=head1 NOTES
+
+The main purpose of these functions is to enable an application to lookup
+recipient keys using any appropriate technique when the simpler method
+of CMS_decrypt() is not appropriate.
+
+In typical usage and application will retrieve all CMS_RecipientInfo structures
+using CMS_get0_RecipientInfos() and check the type of each using
+CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure
+can be ignored or its key identifier data retrieved using an appropriate
+function. Then if the corresponding secret or private key can be obtained by
+any appropriate means it can then associated with the structure and
+CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
+with a NULL key to decrypt the enveloped content.
+
+The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
+existing enveloped data structure. Typically an application will first decrypt
+an appropriate CMS_RecipientInfo structure to make the content encrypt key
+available, it will then add a new recipient using a function such as
+CMS_add1_recipient_cert() and finally encrypt the content encryption key
+using CMS_RecipientInfo_encrypt().
+
+=head1 RETURN VALUES
+
+CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
+an error occurs.
+
+CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
+CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
+CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
+CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
+
+CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
+for a successful comparison and non zero otherwise.
+
+Any error can be obtained from L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_decrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_SignerInfo_set1_signer_cert,
+CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id,
+CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp,
+- CMS signedData signer functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
+
+ int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
+ ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);
+ int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
+ void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
+
+=head1 DESCRIPTION
+
+The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures
+associated with a CMS signedData structure.
+
+CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier
+associated with a specific CMS_SignerInfo structure B<si>. Either the
+keyidentifier will be set in B<keyid> or B<both> issuer name and serial number
+in B<issuer> and B<sno>.
+
+CMS_SignerInfo_get0_signature() retrieves the signature associated with
+B<si> in a pointer to an ASN1_OCTET_STRING structure. This pointer returned
+corresponds to the internal signature value if B<si> so it may be read or
+modified.
+
+CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer
+identifier B<si>. It returns zero if the comparison is successful and non zero
+if not.
+
+CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to
+B<signer>.
+
+=head1 NOTES
+
+The main purpose of these functions is to enable an application to lookup
+signers certificates using any appropriate technique when the simpler method
+of CMS_verify() is not appropriate.
+
+In typical usage and application will retrieve all CMS_SignerInfo structures
+using CMS_get0_SignerInfo() and retrieve the identifier information using
+CMS. It will then obtain the signer certificate by some unspecified means
+(or return and error if it cannot be found) and set it using
+CMS_SignerInfo_set1_signer_cert().
+
+Once all signer certificates have been set CMS_verify() can be used.
+
+Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if
+there are no signers this is not a problem in practice because the only
+error which can occur is if the B<cms> structure is not of type signedData
+due to application error.
+
+=head1 RETURN VALUES
+
+CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there
+are no signers or an error occurs.
+
+CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.
+
+CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non
+zero otherwise.
+
+CMS_SignerInfo_set1_signer_cert() does not return a value.
+
+Any error can be obtained from L<ERR_get_error(3)>
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms);
+ int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
+ const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
+ ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
+
+=head1 DESCRIPTION
+
+CMS_get0_type() returns the content type of a CMS_ContentInfo structure as
+and ASN1_OBJECT pointer. An application can then decide how to process the
+CMS_ContentInfo structure based on this value.
+
+CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo
+structure. It should be called with CMS functions with the B<CMS_PARTIAL>
+flag and B<before> the structure is finalised, otherwise the results are
+undefined.
+
+ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
+content type.
+
+CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer
+containing the embedded content.
+
+=head1 NOTES
+
+As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and
+CMS_get0_content() return internal pointers which should B<not> be freed up.
+CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up
+after use.
+
+The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
+using OBJ_obj2nid(). For the currently supported content types the following
+values are returned:
+
+ NID_pkcs7_data
+ NID_pkcs7_signed
+ NID_pkcs7_digest
+ NID_id_smime_ct_compressedData:
+ NID_pkcs7_encrypted
+ NID_pkcs7_enveloped
+
+The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING>
+content pointer. That means that for example:
+
+ ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
+
+B<*pconf> could be NULL if there is no embedded content. Applications can
+access, modify or create the embedded content in a B<CMS_ContentInfo> structure
+using this function. Applications usually will not need to modify the
+embedded content as it is normally set by higher level functions.
+
+=head1 RETURN VALUES
+
+CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure.
+
+CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The
+error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);
+ int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);
+ int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);
+ void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto);
+
+=head1 DESCRIPTION
+
+CMS_ReceiptRequest_create0() creates a signed receipt request structure. The
+B<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set
+to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL
+the allOrFirstTier option in B<receiptsFrom> is used and set to the value of
+the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList>
+option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the
+B<receiptsTo> field value.
+
+The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr>
+to SignerInfo structure B<si>.
+
+int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if
+any is found it is decoded and written to B<prr>.
+
+CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request.
+The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier>
+option of B<receiptsFrom> is used its value is copied to B<pallorfirst>
+otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo>
+parameter is copied to B<prto>.
+
+=head1 NOTES
+
+For more details of the meaning of the fields see RFC2634.
+
+The contents of a signed receipt should only be considered meaningful if the
+corresponding CMS_ContentInfo structure can be successfully verified using
+CMS_verify().
+
+=head1 RETURN VALUES
+
+CMS_ReceiptRequest_create0() returns a signed receipt request structure or
+NULL if an error occurred.
+
+CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred.
+
+CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and
+decoded. It returns 0 if a signed receipt request is not present and -1 if
+it is present but malformed.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>,
+L<CMS_sign_receipt(3)>, L<CMS_verify(3)>
+L<CMS_verify_receipt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_sign - create a CMS SignedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is
+the certificate to sign with, B<pkey> is the corresponding private key.
+B<certs> is an optional additional set of certificates to include in the CMS
+structure (for example any intermediate CAs in the chain). Any or all of
+these parameters can be B<NULL>, see B<NOTES> below.
+
+The data to be signed is read from BIO B<data>.
+
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter.
+
+Many S/MIME clients expect the signed content to include valid MIME headers. If
+the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended
+to the data.
+
+If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
+CMS_ContentInfo structure, the signer's certificate must still be supplied in
+the B<signcert> parameter though. This can reduce the size of the signature if
+the signers certificate can be obtained by other means: for example a
+previously signed message.
+
+The data being signed is included in the CMS_ContentInfo structure, unless
+B<CMS_DETACHED> is set in which case it is omitted. This is used for
+CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
+messages for example.
+
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
+occurs. This option should be used if the supplied data is in binary format
+otherwise the translation will corrupt it.
+
+The SignedData structure includes several CMS signedAttributes including the
+signing time, the CMS content type and the supported list of ciphers in an
+SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
+will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
+omitted.
+
+If present the SMIMECapabilities attribute indicates support for the following
+algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
+bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
+If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
+not loaded.
+
+OpenSSL will by default identify signing certificates using issuer name
+and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
+identifier value instead. An error occurs if the signing certificate does not
+have a subject key identifier extension.
+
+If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo>
+structure is just initialized ready to perform the signing operation. The
+signing is however B<not> performed and the data to be signed is not read from
+the B<data> parameter. Signing is deferred until after the data has been
+written. In this way data can be signed in a single pass.
+
+If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
+output to which additional signers and capabilities can be added before
+finalization.
+
+If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
+B<not> complete and outputting its contents via a function that does not
+properly finalize the B<CMS_ContentInfo> structure will give unpredictable
+results.
+
+Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
+PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_CMS().
+
+If a signer is specified it will use the default digest for the signing
+algorithm. This is B<SHA1> for both RSA and DSA keys.
+
+If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is
+output.
+
+The function CMS_sign() is a basic CMS signing function whose output will be
+suitable for many purposes. For finer control of the output format the
+B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the
+B<CMS_PARTIAL> flag set. Then one or more signers can be added using the
+function CMS_sign_add1_signer(), non default digests can be used and custom
+attributes added. CMS_final() must then be called to finalize the
+structure if streaming is not enabled.
+
+=head1 BUGS
+
+Some attributes such as counter signatures are not supported.
+
+=head1 RETURN VALUES
+
+CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_verify(3)>
+
+=head1 HISTORY
+
+The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8,
+it is supported for embedded data in OpenSSL 1.0.0 and later.
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_sign_receipt - create a CMS signed receipt
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_sign_receipt() creates and returns a CMS signed receipt structure. B<si> is
+the B<CMS_SignerInfo> structure containing the signed receipt request.
+B<signcert> is the certificate to sign with, B<pkey> is the corresponding
+private key. B<certs> is an optional additional set of certificates to include
+in the CMS structure (for example any intermediate CAs in the chain).
+
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+This functions behaves in a similar way to CMS_sign() except the flag values
+B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM>
+are not supported since they do not make sense in the context of signed
+receipts.
+
+=head1 RETURN VALUES
+
+CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if
+an error occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<CMS_verify_receipt(3)>,
+L<CMS_sign(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_uncompress - uncompress a CMS CompressedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_uncompress() extracts and uncompresses the content from a CMS
+CompressedData structure B<cms>. B<data> is a BIO to write the content to and
+B<flags> is an optional set of flags.
+
+The B<dcont> parameter is used in the rare case where the compressed content
+is detached. It will normally be set to NULL.
+
+=head1 NOTES
+
+The only currently supported compression algorithm is zlib: if the structure
+indicates the use of any other algorithm an error is returned.
+
+If zlib support is not compiled into OpenSSL then CMS_uncompress() will always
+return an error.
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+=head1 RETURN VALUES
+
+CMS_uncompress() returns either 1 for success or 0 for failure. The error can
+be obtained from ERR_get_error(3)
+
+=head1 BUGS
+
+The lack of single pass processing and the need to hold all data in memory as
+mentioned in CMS_verify() also applies to CMS_decompress().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_compress(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_verify, CMS_get0_signers - verify a CMS SignedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags);
+
+ STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
+
+=head1 DESCRIPTION
+
+CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
+structure to verify. B<certs> is a set of certificates in which to search for
+the signing certificate(s). B<store> is a trusted certificate store used for
+chain verification. B<indata> is the detached content if the content is not
+present in B<cms>. The content is written to B<out> if it is not NULL.
+
+B<flags> is an optional set of flags, which can be used to modify the verify
+operation.
+
+CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must
+be called after a successful CMS_verify() operation.
+
+=head1 VERIFY PROCESS
+
+Normally the verify process proceeds as follows.
+
+Initially some sanity checks are performed on B<cms>. The type of B<cms> must
+be SignedData. There must be at least one signature on the data and if
+the content is detached B<indata> cannot be B<NULL>.
+
+An attempt is made to locate all the signing certificate(s), first looking in
+the B<certs> parameter (if it is not NULL) and then looking in any
+certificates contained in the B<cms> structure itself. If any signing
+certificate cannot be located the operation fails.
+
+Each signing certificate is chain verified using the B<smimesign> purpose and
+the supplied trusted certificate store. Any internal certificates in the message
+are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
+CRLs are used in addition to attempting to look them up in B<store>. If any
+chain verify fails an error code is returned.
+
+Finally the signed content is read (and written to B<out> is it is not NULL)
+and the signature's checked.
+
+If all signature's verify correctly then the function is successful.
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter to change the default verify behaviour.
+
+If B<CMS_NOINTERN> is set the certificates in the message itself are not
+searched when locating the signing certificate(s). This means that all the
+signing certificates must be in the B<certs> parameter.
+
+If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
+CRLs in the message itself are ignored.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
+verified.
+
+If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not
+verified.
+
+If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
+
+=head1 NOTES
+
+One application of B<CMS_NOINTERN> is to only accept messages signed by
+a small number of certificates. The acceptable certificates would be passed
+in the B<certs> parameter. In this case if the signer is not one of the
+certificates supplied in B<certs> then the verify will fail because the
+signer cannot be found.
+
+In some cases the standard techniques for looking up and validating
+certificates are not appropriate: for example an application may wish to
+lookup certificates in a database or perform customised verification. This
+can be achieved by setting and verifying the signers certificates manually
+using the signed data utility functions.
+
+Care should be taken when modifying the default verify behaviour, for example
+setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification
+and any modified content will be considered valid. This combination is however
+useful if one merely wishes to write the content to B<out> and its validity
+is not considered important.
+
+Chain verification should arguably be performed using the signing time rather
+than the current time. However since the signing time is supplied by the
+signer it cannot be trusted without additional evidence (such as a trusted
+timestamp).
+
+=head1 RETURN VALUES
+
+CMS_verify() returns 1 for a successful verification and zero if an error
+occurred.
+
+CMS_get0_signers() returns all signers or NULL if an error occurred.
+
+The error can be obtained from L<ERR_get_error(3)>
+
+=head1 BUGS
+
+The trusted certificate store is not searched for the signing certificate,
+this is primarily due to the inadequacies of the current B<X509_STORE>
+functionality.
+
+The lack of single pass processing means that the signed content must all
+be held in memory if it is not detached.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CMS_verify_receipt - verify a CMS signed receipt
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed
+receipt to verify. B<ocms> is the original SignedData structure containing the
+receipt request. B<certs> is a set of certificates in which to search for the
+signing certificate. B<store> is a trusted certificate store (used for chain
+verification).
+
+B<flags> is an optional set of flags, which can be used to modify the verify
+operation.
+
+=head1 NOTES
+
+This functions behaves in a similar way to CMS_verify() except the flag values
+B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> are not
+supported since they do not make sense in the context of signed receipts.
+
+=head1 RETURN VALUES
+
+CMS_verify_receipt() returns 1 for a successful verification and zero if an
+error occurred.
+
+The error can be obtained from L<ERR_get_error(3)>
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<CMS_sign_receipt(3)>,
+L<CMS_verify(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CONF_modules_free, CONF_modules_finish, CONF_modules_unload -
+OpenSSL configuration cleanup functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ void CONF_modules_finish(void);
+ void CONF_modules_unload(int all);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void CONF_modules_free(void)
+ #endif
+
+=head1 DESCRIPTION
+
+CONF_modules_free() closes down and frees up all memory allocated by all
+configuration modules.
+
+CONF_modules_finish() calls each configuration modules B<finish> handler
+to free up any configuration that module may have performed.
+
+CONF_modules_unload() finishes and unloads configuration modules. If
+B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
+B<all> is B<1> all modules, including builtin modules will be unloaded.
+
+=head1 NOTES
+
+Normally in versions of OpenSSL prior to 1.1.0 applications will only call
+CONF_modules_free() at application exit to tidy up any configuration performed.
+From 1.1.0 CONF_modules_free() is deprecated and no explicit CONF cleanup is
+required at all. For more information see L<OPENSSL_init_crypto(3)>.
+
+=head1 RETURN VALUE
+
+None of the functions return a value.
+
+=head1 SEE ALSO
+
+L<conf(5)>, L<OPENSSL_config(3)>,
+L<CONF_modules_load_file(3)>
+
+=head1 HISTORY
+
+CONF_modules_free() was deprecated in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ int CONF_modules_load_file(const char *filename, const char *appname,
+ unsigned long flags);
+ int CONF_modules_load(const CONF *cnf, const char *appname,
+ unsigned long flags);
+
+=head1 DESCRIPTION
+
+The function CONF_modules_load_file() configures OpenSSL using file
+B<filename> and application name B<appname>. If B<filename> is NULL
+the standard OpenSSL configuration file is used. If B<appname> is
+NULL the standard OpenSSL application name B<openssl_conf> is used.
+The behaviour can be customized using B<flags>.
+
+CONF_modules_load() is identical to CONF_modules_load_file() except it
+reads configuration information from B<cnf>.
+
+=head1 NOTES
+
+The following B<flags> are currently recognized:
+
+B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
+configuration modules are ignored. If not set the first module error is
+considered fatal and no further modules are loaded.
+
+Normally any modules errors will add error information to the error queue. If
+B<CONF_MFLAGS_SILENT> is set no error information is added.
+
+If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
+disabled.
+
+B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
+ignore missing configuration files. Normally a missing configuration file
+return an error.
+
+B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
+default section pointed to by B<openssl_conf> if B<appname> does not exist.
+
+By using CONF_modules_load_file() with appropriate flags an application can
+customise application configuration to best suit its needs. In some cases the
+use of a configuration file is optional and its absence is not an error: in
+this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
+
+Errors during configuration may also be handled differently by different
+applications. For example in some cases an error may simply print out a warning
+message and the application continue. In other cases an application might
+consider a configuration file error as fatal and exit immediately.
+
+Applications can use the CONF_modules_load() function if they wish to load a
+configuration file themselves and have finer control over how errors are
+treated.
+
+=head1 EXAMPLES
+
+Load a configuration file and print out any errors and exit (missing file
+considered fatal):
+
+ if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
+ fprintf(stderr, "FATAL: error loading configuration file\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+Load default configuration file using the section indicated by "myapp",
+tolerate missing files, but exit on other errors:
+
+ if (CONF_modules_load_file(NULL, "myapp",
+ CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
+ fprintf(stderr, "FATAL: error loading configuration file\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+
+Load custom configuration file and section, only print warnings on error,
+missing configuration file ignored:
+
+ if (CONF_modules_load_file("/something/app.cnf", "myapp",
+ CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
+ fprintf(stderr, "WARNING: error loading configuration file\n");
+ ERR_print_errors_fp(stderr);
+ }
+
+Load and parse configuration file manually, custom error handling:
+
+ FILE *fp;
+ CONF *cnf = NULL;
+ long eline;
+ fp = fopen("/somepath/app.cnf", "r");
+ if (fp == NULL) {
+ fprintf(stderr, "Error opening configuration file\n");
+ /* Other missing configuration file behaviour */
+ } else {
+ cnf = NCONF_new(NULL);
+ if (NCONF_load_fp(cnf, fp, &eline) == 0) {
+ fprintf(stderr, "Error on line %ld of configuration file\n", eline);
+ ERR_print_errors_fp(stderr);
+ /* Other malformed configuration file behaviour */
+ } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
+ fprintf(stderr, "Error configuring application\n");
+ ERR_print_errors_fp(stderr);
+ /* Other configuration error behaviour */
+ }
+ fclose(fp);
+ NCONF_free(cnf);
+ }
+
+=head1 RETURN VALUES
+
+These functions return 1 for success and a zero or negative value for
+failure. If module errors are not ignored the return code will reflect the
+return value of the failing module (this will always be zero or negative).
+
+=head1 SEE ALSO
+
+L<conf(5)>, L<OPENSSL_config(3)>,
+L<CONF_free(3)>, L<err(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CRYPTO_THREAD_run_once,
+CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
+CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
+ int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
+
+ CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
+ int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
+ int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
+ int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);
+ void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
+
+ int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
+
+=head1 DESCRIPTION
+
+OpenSSL can be safely used in multi-threaded applications provided that
+support for the underlying OS threading API is built-in. Currently, OpenSSL
+supports the pthread and Windows APIs. OpenSSL can also be built without
+any multi-threading support, for example on platforms that don't provide
+any threading support or that provide a threading API that is not yet
+supported by OpenSSL.
+
+The following multi-threading function are provided:
+
+=over 4
+
+=item *
+CRYPTO_THREAD_run_once() can be used to perform one-time initialization.
+The B<once> argument must be a pointer to a static object of type
+B<CRYPTO_ONCE> that was statically initialized to the value
+B<CRYPTO_ONCE_STATIC_INIT>.
+The B<init> argument is a pointer to a function that performs the desired
+exactly once initialization.
+In particular, this can be used to allocate locks in a thread-safe manner,
+which can then be used with the locking functions below.
+
+=item *
+CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
+lock.
+
+=item *
+CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading.
+
+=item *
+CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
+
+=item *
+CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
+
+=item *
+CRYPTO_THREAD_lock_frees() frees the provided B<lock>.
+
+=item *
+CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the
+result of the operation in B<ret>. B<lock> will be locked, unless atomic
+operations are supported on the specific platform. Because of this, if a
+variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must
+be the only way that the variable is modified.
+
+=back
+
+=head1 RETURN VALUES
+
+CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.
+
+CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
+
+CRYPTO_THREAD_lock_frees() returns no value.
+
+The other functions return 1 on success or 0 on error.
+
+=head1 NOTES
+
+On Windows platforms the CRYPTO_THREAD_* types and functions in the
+openssl/crypto.h header are dependent on some of the types customarily
+made available by including windows.h. The application developer is
+likely to require control over when the latter is included, commonly as
+one of the first included headers. Therefore it is defined as an
+application developer's responsibility to include windows.h prior to
+crypto.h where use of CRYPTO_THREAD_* types and functions is required.
+
+=head1 EXAMPLE
+
+This example safely initializes and uses a lock.
+
+ #ifdef _WIN32
+ # include <windows.h>
+ #endif
+ #include <openssl/crypto.h>
+
+ static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
+ static CRYPTO_RWLOCK *lock;
+
+ static void myinit(void)
+ {
+ lock = CRYPTO_THREAD_lock_new();
+ }
+
+ static int mylock(void)
+ {
+ if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)
+ return 0;
+ return CRYPTO_THREAD_write_lock(lock);
+ }
+
+ static int myunlock(void)
+ {
+ return CRYPTO_THREAD_unlock(lock);
+ }
+
+ int serialized(void)
+ {
+ int ret = 0;
+
+ if (mylock()) {
+ /* Your code here, do not return without releasing the lock! */
+ ret = ... ;
+ }
+ myunlock();
+ return ret;
+ }
+
+Finalization of locks is an advanced topic, not covered in this example.
+This can only be done at process exit or when a dynamically loaded library is
+no longer in use and is unloaded.
+The simplest solution is to just "leak" the lock in applications and not
+repeatedly load/unload shared libraries that allocate locks.
+
+=head1 NOTES
+
+You can find out if OpenSSL was configured with thread support:
+
+ #include <openssl/opensslconf.h>
+ #if defined(OPENSSL_THREADS)
+ // thread support enabled
+ #else
+ // no thread support
+ #endif
+
+=head1 SEE ALSO
+
+L<crypto(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,
+CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data,
+CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
+- functions supporting application-specific data
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ int CRYPTO_get_ex_new_index(int class_index,
+ long argl, void *argp,
+ CRYPTO_EX_new *new_func,
+ CRYPTO_EX_dup *dup_func,
+ CRYPTO_EX_free *free_func);
+
+ typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+ int idx, long argl, void *argp);
+ typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
+ void *from_d, int idx, long argl, void *argp);
+
+ int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
+
+ int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
+
+ void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
+
+ void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);
+
+ int CRYPTO_free_ex_index(int class_index, int idx);
+
+=head1 DESCRIPTION
+
+Several OpenSSL structures can have application-specific data attached to them,
+known as "exdata."
+The specific structures are:
+
+ SSL
+ SSL_CTX
+ SSL_SESSION
+ X509
+ X509_STORE
+ X509_STORE_CTX
+ DH
+ DSA
+ EC_KEY
+ RSA
+ ENGINE
+ UI
+ BIO
+
+Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
+header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for
+applications to use this facility for their own structures.
+
+The API described here is used by OpenSSL to manipulate exdata for specific
+structures. Since the application data can be anything at all it is passed
+and retrieved as a B<void *> type.
+
+The B<CRYPTO_EX_DATA> type is opaque. To initialize the exdata part of
+a structure, call CRYPTO_new_ex_data(). This is only necessary for
+B<CRYPTO_EX_INDEX_APP> objects.
+
+Exdata types are identified by an B<index>, an integer guaranteed to be
+unique within structures for the lifetime of the program. Applications
+using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and
+store the result in a global variable, or write a wrapper function to
+provide lazy evaluation. The B<class_index> should be one of the
+B<CRYPTO_EX_INDEX_xxx> values. The B<argl> and B<argp> parameters are saved
+to be passed to the callbacks but are otherwise not used. In order to
+transparently manipulate exdata, three callbacks must be provided. The
+semantics of those callbacks are described below.
+
+When copying or releasing objects with exdata, the callback functions
+are called in increasing order of their B<index> value.
+
+If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index()
+when this is done.
+This will replace the callbacks with no-ops
+so that applications don't crash. Any existing exdata will be leaked.
+
+To set or get the exdata on an object, the appropriate type-specific
+routine must be used. This is because the containing structure is opaque
+and the B<CRYPTO_EX_DATA> field is not accessible. In both API's, the
+B<idx> parameter should be an already-created index value.
+
+When setting exdata, the pointer specified with a particular index is saved,
+and returned on a subsequent "get" call. If the application is going to
+release the data, it must make sure to set a B<NULL> value at the index,
+to avoid likely double-free crashes.
+
+The function B<CRYPTO_free_ex_data> is used to free all exdata attached
+to a structure. The appropriate type-specific routine must be used.
+The B<class_index> identifies the structure type, the B<obj> is
+be the pointer to the actual structure, and B<r> is a pointer to the
+structure's exdata field.
+
+=head2 Callback Functions
+
+This section describes how the callback functions are used. Applications
+that are defining their own exdata using B<CYPRTO_EX_INDEX_APP> must
+call them as described here.
+
+When a structure is initially allocated (such as RSA_new()) then the
+new_func() is called for every defined index. There is no requirement
+that the entire parent, or containing, structure has been set up.
+The new_func() is typically used only to allocate memory to store the
+exdata, and perhaps an "initialized" flag within that memory.
+The exdata value should be set by calling CRYPTO_set_ex_data().
+
+When a structure is free'd (such as SSL_CTX_free()) then the
+free_func() is called for every defined index. Again, the state of the
+parent structure is not guaranteed. The free_func() may be called with a
+NULL pointer.
+
+Both new_func() and free_func() take the same parameters.
+The B<parent> is the pointer to the structure that contains the exdata.
+The B<ptr> is the current exdata item; for new_func() this will typically
+be NULL. The B<r> parameter is a pointer to the exdata field of the object.
+The B<idx> is the index and is the value returned when the callbacks were
+initially registered via CRYPTO_get_ex_new_index() and can be used if
+the same callback handles different types of exdata.
+
+dup_func() is called when a structure is being copied. This is only done
+for B<SSL> and B<SSL_SESSION> objects. The B<to> and B<from> parameters
+are pointers to the destination and source B<CRYPTO_EX_DATA> structures,
+respectively. The B<srcp> parameter is a pointer to the source exdata.
+When the dup_func() returns, the value in B<srcp> is copied to the
+destination ex_data. If the pointer contained in B<srcp> is not modified
+by the dup_func(), then both B<to> and B<from> will point to the same data.
+The B<idx>, B<argl> and B<argp> parameters are as described for the other
+two callbacks.
+
+=head1 RETURN VALUES
+
+CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the
+value B<0> is reserved for the legacy "app_data" API's.
+
+CRYPTO_free_ex_index() and
+CRYPTO_set_ex_data() return 1 on success or 0 on failure.
+
+CRYPTO_get_ex_data() returns the application data or NULL on failure;
+note that NULL may be a valid value.
+
+dup_func() should return 0 for failure and 1 for success.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CTLOG_STORE_get0_log_by_id -
+Get a Certificate Transparency log from a CTLOG_STORE
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store,
+ const uint8_t *log_id,
+ size_t log_id_len);
+
+=head1 DESCRIPTION
+
+A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency
+(CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2).
+Therefore, it is useful to be able to look up more information about a log
+(e.g. its public key) using this LogID.
+
+CTLOG_STORE_get0_log_by_id() provides a way to do this. It will find a CTLOG
+in a CTLOG_STORE that has a given LogID.
+
+=head1 RETURN VALUES
+
+B<CTLOG_STORE_get0_log_by_id> returns a CTLOG with the given LogID, if it
+exists in the given CTLOG_STORE, otherwise it returns NULL.
+
+=head1 SEE ALSO
+
+L<ct(3)>,
+L<CTLOG_STORE_new(3)>
+
+=head1 HISTORY
+
+This function was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CTLOG_STORE_new, CTLOG_STORE_free,
+CTLOG_STORE_load_default_file, CTLOG_STORE_load_file -
+Create and populate a Certificate Transparency log list
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ CTLOG_STORE *CTLOG_STORE_new(void);
+ void CTLOG_STORE_free(CTLOG_STORE *store);
+
+ int CTLOG_STORE_load_default_file(CTLOG_STORE *store);
+ int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file);
+
+=head1 DESCRIPTION
+
+A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency
+logs). The list can be loaded from one or more files and then searched by LogID
+(see RFC 6962, Section 3.2, for the definition of a LogID).
+
+CTLOG_STORE_new() creates an empty list of CT logs. This is then populated
+by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file().
+CTLOG_STORE_load_default_file() loads from the default file, which is named
+"ct_log_list.cnf" in OPENSSLDIR (see the output of L<version>). This can be
+overridden using an environment variable named "CTLOG_FILE".
+CTLOG_STORE_load_file() loads from a caller-specified file path instead.
+Both of these functions append any loaded CT logs to the CTLOG_STORE.
+
+The expected format of the file is:
+
+ enabled_logs=foo,bar
+
+ [foo]
+ description = Log 1
+ key = <base64-encoded DER SubjectPublicKeyInfo here>
+
+ [bar]
+ description = Log 2
+ key = <base64-encoded DER SubjectPublicKeyInfo here>
+
+Once a CTLOG_STORE is no longer required, it should be passed to
+CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along
+with the CTLOG_STORE itself.
+
+=head1 NOTES
+
+If there are any invalid CT logs in a file, they are skipped and the remaining
+valid logs will still be added to the CTLOG_STORE. A CT log will be considered
+invalid if it is missing a "key" or "description" field.
+
+=head1 RETURN VALUES
+
+Both B<CTLOG_STORE_load_default_file> and B<CTLOG_STORE_load_file> return 1 if
+all CT logs in the file are successfully parsed and loaded, 0 otherwise.
+
+=head1 SEE ALSO
+
+L<ct(3)>,
+L<CTLOG_STORE_get0_log_by_id(3)>,
+L<SSL_CTX_set_ctlog_list_file(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CTLOG_new, CTLOG_new_from_base64, CTLOG_free,
+CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key -
+encapsulates information about a Certificate Transparency log
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);
+ int CTLOG_new_from_base64(CTLOG ** ct_log,
+ const char *pkey_base64, const char *name);
+ void CTLOG_free(CTLOG *log);
+ const char *CTLOG_get0_name(const CTLOG *log);
+ void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id,
+ size_t *log_id_len);
+ EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log);
+
+=head1 DESCRIPTION
+
+CTLOG_new() returns a new CTLOG that represents the Certificate Transparency
+(CT) log with the given public key. A name must also be provided that can be
+used to help users identify this log. Ownership of the public key is
+transferred.
+
+CTLOG_new_from_base64() also creates a new CTLOG, but takes the public key in
+base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG.
+The base64 will be decoded and the public key parsed.
+
+Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the
+caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer
+needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that
+was passed to it.
+
+CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was
+created. Ownership of the string remains with the CTLOG.
+
+CTLOG_get0_log_id() sets *log_id to point to a string containing that log's
+LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a
+v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of
+the string remains with the CTLOG.
+
+CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the
+EVP_PKEY remains with the CTLOG.
+
+=head1 RETURN VALUES
+
+CTLOG_new() will return NULL if an error occurs.
+
+CTLOG_new_from_base64() will return 1 on success, 0 otherwise.
+
+=head1 SEE ALSO
+
+L<ct(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free,
+CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert,
+CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer,
+CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE -
+Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);
+ void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);
+ X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);
+ int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert);
+ X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);
+ int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);
+ const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);
+ void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store);
+
+=head1 DESCRIPTION
+
+A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed
+Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy.
+This policy may be, for example, that at least one valid SCT is available. To
+determine this, an SCT's signature must be verified. This requires:
+
+=over
+
+=item * the public key of the log that issued the SCT
+
+=item * the certificate that the SCT was issued for
+
+=item * the issuer certificate (if the SCT was issued for a pre-certificate)
+
+=back
+
+The above requirements are met using the setters described below.
+
+CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This
+should then be populated using:
+
+=over
+
+=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for
+
+Increments the reference count of the certificate.
+
+=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate
+
+Increments the reference count of the certificate.
+
+=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs
+
+Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the
+CT_POLICY_EVAL_CTX.
+
+=back
+
+Each setter has a matching getter for accessing the current value.
+
+When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to
+CT_POLICY_EVAL_CTX_free() to delete it.
+
+=head1 NOTES
+
+The issuer certificate only needs to be provided if at least one of the SCTs
+was issued for a pre-certificate. This will be the case for SCTs embedded in a
+certificate (i.e. those in an X.509 extension), but may not be the case for SCTs
+found in the TLS SCT extension or OCSP response.
+
+=head1 RETURN VALUES
+
+CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails.
+
+=head1 SEE ALSO
+
+L<ct(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,
+DEFINE_SPECIAL_STACK_OF_CONST,
+OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
+OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free,
+OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null,
+OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push,
+OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort,
+OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero,
+sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_free,
+sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push,
+sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free,
+sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort,
+sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func -
+stack container
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ #include <openssl/safestack.h>
+
+ STACK_OF(TYPE)
+ DEFINE_STACK_OF(TYPE)
+ DEFINE_STACK_OF_CONST(TYPE)
+ DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)
+ DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)
+
+ typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);
+ typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);
+ typedef void (*sk_TYPE_freefunc)(TYPE *a);
+
+ int sk_TYPE_num(const STACK_OF(TYPE) *sk);
+ TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);
+ STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);
+ STACK_OF(TYPE) *sk_TYPE_new_null(void);
+ void sk_TYPE_free(const STACK_OF(TYPE) *sk);
+ void sk_TYPE_zero(const STACK_OF(TYPE) *sk);
+ TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);
+ TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);
+ int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);
+ int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);
+ TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);
+ TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);
+ void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);
+ int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);
+ TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);
+ int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);
+ int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);
+ void sk_TYPE_sort(const STACK_OF(TYPE) *sk);
+ int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);
+ STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);
+ STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,
+ sk_TYPE_copyfunc copyfunc,
+ sk_TYPE_freefunc freefunc);
+ sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, sk_TYPE_compfunc compare);
+
+=head1 DESCRIPTION
+
+Applications can create and use their own stacks by placing any of the macros
+described below in a header file. These macros define typesafe inline
+functions that wrap around the utility B<OPENSSL_sk_> API.
+In the description here, I<TYPE> is used
+as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
+
+STACK_OF() returns the name for a stack of the specified B<TYPE>.
+DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This
+will mean that type B<TYPE> is stored in each stack, the type is referenced by
+STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example:
+
+ TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
+
+DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except
+each element is constant. For example:
+
+ const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
+
+DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but
+each function uses B<FUNCNAME> in the function name. For example:
+
+ TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
+
+DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is
+constant:
+
+ const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
+
+sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is
+B<NULL>.
+
+sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at
+zero. If B<idx> is out of range then B<NULL> is returned.
+
+sk_TYPE_new() allocates a new empty stack using comparison function B<compar>.
+If B<compar> is B<NULL> then no comparison function is used.
+
+sk_TYPE_new_null() allocates a new empty stack with no comparison function.
+
+sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compar>.
+The previous comparison function is returned or B<NULL> if there was
+no previous comparison function.
+
+sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any
+elements of B<sk>. After this call B<sk> is no longer valid.
+
+sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free
+B<sk> so after this call B<sk> is still valid.
+
+sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The
+free function freefunc() is called on each element to free it.
+
+sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted
+element or B<NULL> if B<i> is out of range.
+
+sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns
+the deleted element or B<NULL> if no element matching B<ptr> was found.
+
+sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing
+elements at or after B<idx> are moved downwards. If B<idx> is out of range
+the new element is appended to B<sk>. sk_TYPE_insert() either returns the
+number of elements in B<sk> after the new element is inserted or zero if
+an error (such as memory allocation failure) occurred.
+
+sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to:
+
+ sk_TYPE_insert(sk, ptr, -1);
+
+sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to:
+
+ sk_TYPE_insert(sk, ptr, 0);
+
+sk_TYPE_pop() returns and removes the last element from B<sk>.
+
+sk_TYPE_shift() returns and removes the first element from B<sk>.
+
+sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current
+element. The new element value is returned or B<NULL> if an error occurred:
+this will only happen if B<sk> is B<NULL> or B<idx> is out of range.
+
+sk_TYPE_find() and sk_TYPE_find_ex() search B<sk> using the supplied
+comparison function for an element matching B<ptr>. sk_TYPE_find() returns
+the index of the first matching element or B<-1> if there is no match.
+sk_TYPE_find_ex() returns a matching element or the nearest element that
+does not match B<ptr>. Note: if a comparison function is set then B<sk> is
+sorted before the search which may change its order. If no comparison
+function is set then a linear search is made for a pointer matching B<ptr>
+and the stack is not reordered.
+
+sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
+
+sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
+
+sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy
+are identical to the original.
+
+sk_TYPE_deep_copy() returns a new stack where each element has been copied.
+Copying is performed by the supplied copyfunc() and freeing by freefunc(). The
+function freefunc() is only called if an error occurs.
+
+=head1 NOTES
+
+Care should be taken when accessing stacks in multi-threaded environments.
+Any operation which increases the size of a stack such as sk_TYPE_insert() or
+sk_push() can "grow" the size of an internal array and cause race conditions
+if the same stack is accessed in a different thread. Operations such as
+sk_find() and sk_sort() can also reorder the stack.
+
+Any comparison function supplied should use a metric suitable
+for use in a binary search operation. That is it should return zero, a
+positive or negative value if B<a> is equal to, greater than
+or less than B<b> respectively.
+
+Care should be taken when checking the return values of the functions
+sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the
+matching element. In particular B<0> indicates a matching first element.
+A failed search is indicated by a B<-1> return value.
+
+STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and
+DEFINE_SPECIAL_STACK_OF() are implemented as macros.
+
+=head1 RETURN VALUES
+
+sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
+passed stack is B<NULL>.
+
+sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
+index is out of range.
+
+sk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B<NULL> if
+an error occurs.
+
+sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if
+there was no old comparison function.
+
+sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do
+not return values.
+
+sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr()
+return a pointer to the deleted element or B<NULL> on error.
+
+sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total
+number of elements in the stack and 0 if an error occurred.
+
+sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on
+error.
+
+sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element
+or B<-1> on error.
+
+sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is
+not.
+
+sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the
+stack.
+
+=head1 HISTORY
+
+Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
+and was not a public API.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked,
+DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key,
+DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt,
+DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
+DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt,
+DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt,
+DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
+DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
+DES_fcrypt, DES_crypt - DES encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/des.h>
+
+ void DES_random_key(DES_cblock *ret);
+
+ int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);
+ int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);
+ int DES_set_key_checked(const_DES_cblock *key,
+ DES_key_schedule *schedule);
+ void DES_set_key_unchecked(const_DES_cblock *key,
+ DES_key_schedule *schedule);
+
+ void DES_set_odd_parity(DES_cblock *key);
+ int DES_is_weak_key(const_DES_cblock *key);
+
+ void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,
+ DES_key_schedule *ks, int enc);
+ void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
+ DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
+ void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
+ DES_key_schedule *ks1, DES_key_schedule *ks2,
+ DES_key_schedule *ks3, int enc);
+
+ void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int enc);
+ void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
+ int numbits, long length, DES_key_schedule *schedule,
+ DES_cblock *ivec, int enc);
+ void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
+ int numbits, long length, DES_key_schedule *schedule,
+ DES_cblock *ivec);
+ void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int enc);
+ void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int *num, int enc);
+ void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ int *num);
+
+ void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,
+ long length, DES_key_schedule *schedule, DES_cblock *ivec,
+ const_DES_cblock *inw, const_DES_cblock *outw, int enc);
+
+ void DES_ede2_cbc_encrypt(const unsigned char *input,
+ unsigned char *output, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_cblock *ivec, int enc);
+ void DES_ede2_cfb64_encrypt(const unsigned char *in,
+ unsigned char *out, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc);
+ void DES_ede2_ofb64_encrypt(const unsigned char *in,
+ unsigned char *out, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_cblock *ivec, int *num);
+
+ void DES_ede3_cbc_encrypt(const unsigned char *input,
+ unsigned char *output, long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec,
+ int enc);
+ void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
+ DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc);
+ void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
+ long length, DES_key_schedule *ks1,
+ DES_key_schedule *ks2, DES_key_schedule *ks3,
+ DES_cblock *ivec, int *num);
+
+ DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,
+ long length, DES_key_schedule *schedule,
+ const_DES_cblock *ivec);
+ DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
+ long length, int out_count, DES_cblock *seed);
+ void DES_string_to_key(const char *str, DES_cblock *key);
+ void DES_string_to_2keys(const char *str, DES_cblock *key1,
+ DES_cblock *key2);
+
+ char *DES_fcrypt(const char *buf, const char *salt, char *ret);
+ char *DES_crypt(const char *buf, const char *salt);
+
+=head1 DESCRIPTION
+
+This library contains a fast implementation of the DES encryption
+algorithm.
+
+There are two phases to the use of DES encryption. The first is the
+generation of a I<DES_key_schedule> from a key, the second is the
+actual encryption. A DES key is of type I<DES_cblock>. This type is
+consists of 8 bytes with odd parity. The least significant bit in
+each byte is the parity bit. The key schedule is an expanded form of
+the key; it is used to speed the encryption process.
+
+DES_random_key() generates a random key. The PRNG must be seeded
+prior to using this function (see L<rand(3)>). If the PRNG
+could not generate a secure key, 0 is returned.
+
+Before a DES key can be used, it must be converted into the
+architecture dependent I<DES_key_schedule> via the
+DES_set_key_checked() or DES_set_key_unchecked() function.
+
+DES_set_key_checked() will check that the key passed is of odd parity
+and is not a week or semi-weak key. If the parity is wrong, then -1
+is returned. If the key is a weak key, then -2 is returned. If an
+error is returned, the key schedule is not generated.
+
+DES_set_key() works like
+DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
+otherwise like DES_set_key_unchecked(). These functions are available
+for compatibility; it is recommended to use a function that does not
+depend on a global variable.
+
+DES_set_odd_parity() sets the parity of the passed I<key> to odd.
+
+DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it
+is ok.
+
+The following routines mostly operate on an input and output stream of
+I<DES_cblock>s.
+
+DES_ecb_encrypt() is the basic DES encryption routine that encrypts or
+decrypts a single 8-byte I<DES_cblock> in I<electronic code book>
+(ECB) mode. It always transforms the input data, pointed to by
+I<input>, into the output data, pointed to by the I<output> argument.
+If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input>
+(cleartext) is encrypted in to the I<output> (ciphertext) using the
+key_schedule specified by the I<schedule> argument, previously set via
+I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now
+ciphertext) is decrypted into the I<output> (now cleartext). Input
+and output may overlap. DES_ecb_encrypt() does not return a value.
+
+DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using
+three-key Triple-DES encryption in ECB mode. This involves encrypting
+the input with I<ks1>, decrypting with the key schedule I<ks2>, and
+then encrypting with I<ks3>. This routine greatly reduces the chances
+of brute force breaking of DES and has the advantage of if I<ks1>,
+I<ks2> and I<ks3> are the same, it is equivalent to just encryption
+using ECB mode and I<ks1> as the key.
+
+The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES
+encryption by using I<ks1> for the final encryption.
+
+DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining>
+(CBC) mode of DES. If the I<encrypt> argument is non-zero, the
+routine cipher-block-chain encrypts the cleartext data pointed to by
+the I<input> argument into the ciphertext pointed to by the I<output>
+argument, using the key schedule provided by the I<schedule> argument,
+and initialization vector provided by the I<ivec> argument. If the
+I<length> argument is not an integral multiple of eight bytes, the
+last block is copied to a temporary area and zero filled. The output
+is always an integral multiple of eight bytes.
+
+DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and
+I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret
+(unlike the iv) and are as such, part of the key. So the key is sort
+of 24 bytes. This is much better than CBC DES.
+
+DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with
+three keys. This means that each DES operation inside the CBC mode is
+an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
+
+The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by
+reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>.
+This form of Triple-DES is used by the RSAREF library.
+
+DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block
+chaining mode used by Kerberos v4. Its parameters are the same as
+DES_ncbc_encrypt().
+
+DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This
+method takes an array of characters as input and outputs and array of
+characters. It does not require any padding to 8 character groups.
+Note: the I<ivec> variable is changed and the new changed value needs to
+be passed to the next call to this function. Since this function runs
+a complete DES ECB encryption per I<numbits>, this function is only
+suggested for use when sending small numbers of characters.
+
+DES_cfb64_encrypt()
+implements CFB mode of DES with 64bit feedback. Why is this
+useful you ask? Because this routine will allow you to encrypt an
+arbitrary number of bytes, no 8 byte padding. Each call to this
+routine will encrypt the input bytes to output and then update ivec
+and num. num contains 'how far' we are though ivec. If this does
+not make much sense, read more about cfb mode of DES :-).
+
+DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as
+DES_cfb64_encrypt() except that Triple-DES is used.
+
+DES_ofb_encrypt() encrypts using output feedback mode. This method
+takes an array of characters as input and outputs and array of
+characters. It does not require any padding to 8 character groups.
+Note: the I<ivec> variable is changed and the new changed value needs to
+be passed to the next call to this function. Since this function runs
+a complete DES ECB encryption per numbits, this function is only
+suggested for use when sending small numbers of characters.
+
+DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output
+Feed Back mode.
+
+DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as
+DES_ofb64_encrypt(), using Triple-DES.
+
+The following functions are included in the DES library for
+compatibility with the MIT Kerberos library.
+
+DES_cbc_cksum() produces an 8 byte checksum based on the input stream
+(via CBC encryption). The last 4 bytes of the checksum are returned
+and the complete 8 bytes are placed in I<output>. This function is
+used by Kerberos v4. Other applications should use
+L<EVP_DigestInit(3)> etc. instead.
+
+DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte
+checksum from the input bytes. The algorithm can be iterated over the
+input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is
+non-NULL, the 8 bytes generated by each pass are written into
+I<output>.
+
+The following are DES-based transformations:
+
+DES_fcrypt() is a fast version of the Unix crypt(3) function. This
+version takes only a small amount of space relative to other fast
+crypt() implementations. This is different to the normal crypt in
+that the third parameter is the buffer that the return value is
+written into. It needs to be at least 14 bytes long. This function
+is thread safe, unlike the normal crypt.
+
+DES_crypt() is a faster replacement for the normal system crypt().
+This function calls DES_fcrypt() with a static array passed as the
+third parameter. This mostly emulates the normal non-thread-safe semantics
+of crypt(3).
+The B<salt> must be two ASCII characters.
+
+DES_enc_write() writes I<len> bytes to file descriptor I<fd> from
+buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default)
+using I<sched> for the key and I<iv> as a starting vector. The actual
+data send down I<fd> consists of 4 bytes (in network byte order)
+containing the length of the following encrypted data. The encrypted
+data then follows, padded with random data out to a multiple of 8
+bytes.
+
+=head1 BUGS
+
+DES_3cbc_encrypt() is flawed and must not be used in applications.
+
+DES_cbc_encrypt() does not modify B<ivec>; use DES_ncbc_encrypt()
+instead.
+
+DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits.
+What this means is that if you set numbits to 12, and length to 2, the
+first 12 bits will come from the 1st input byte and the low half of
+the second input byte. The second 12 bits will have the low 8 bits
+taken from the 3rd input byte and the top 4 bits taken from the 4th
+input byte. The same holds for output. This function has been
+implemented this way because most people will be using a multiple of 8
+and because once you get into pulling bytes input bytes apart things
+get ugly!
+
+DES_string_to_key() is available for backward compatibility with the
+MIT library. New applications should use a cryptographic hash function.
+The same applies for DES_string_to_2key().
+
+=head1 NOTES
+
+The B<des> library was written to be source code compatible with
+the MIT Kerberos library.
+
+Applications should use the higher level functions
+L<EVP_EncryptInit(3)> etc. instead of calling these
+functions directly.
+
+Single-key DES is insecure due to its short key size. ECB mode is
+not suitable for most applications; see L<des_modes(7)>.
+
+=head1 HISTORY
+
+The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
+be two ASCII characters was first enforced in
+OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A>
+if both character were not present, and could crash when given non-ASCII
+on some platforms.
+
+=head1 SEE ALSO
+
+L<des_modes(7)>,
+L<EVP_EncryptInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ int DH_generate_key(DH *dh);
+
+ int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
+
+=head1 DESCRIPTION
+
+DH_generate_key() performs the first step of a Diffie-Hellman key
+exchange by generating private and public DH values. By calling
+DH_compute_key(), these are combined with the other party's public
+value to compute the shared key.
+
+DH_generate_key() expects B<dh> to contain the shared parameters
+B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value
+unless B<dh-E<gt>priv_key> is already set, and computes the
+corresponding public value B<dh-E<gt>pub_key>, which can then be
+published.
+
+DH_compute_key() computes the shared secret from the private DH value
+in B<dh> and the other party's public value in B<pub_key> and stores
+it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory.
+
+=head1 RETURN VALUES
+
+DH_generate_key() returns 1 on success, 0 otherwise.
+
+DH_compute_key() returns the size of the shared secret on success, -1
+on error.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>, L<DH_size(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_generate_parameters_ex, DH_generate_parameters,
+DH_check - generate and check Diffie-Hellman parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);
+
+ int DH_check(DH *dh, int *codes);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x00908000L
+ DH *DH_generate_parameters(int prime_len, int generator,
+ void (*callback)(int, int, void *), void *cb_arg);
+ #endif
+
+=head1 DESCRIPTION
+
+DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
+be shared among a group of users, and stores them in the provided B<DH>
+structure. The pseudo-random number generator must be
+seeded prior to calling DH_generate_parameters().
+
+B<prime_len> is the length in bits of the safe prime to be generated.
+B<generator> is a small number E<gt> 1, typically 2 or 5.
+
+A callback function may be used to provide feedback about the progress
+of the key generation. If B<cb> is not B<NULL>, it will be
+called as described in L<BN_generate_prime(3)> while a random prime
+number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)>
+is called. See L<BN_generate_prime(3)> for information on
+the BN_GENCB_call() function.
+
+DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The
+value of B<*codes> is updated with any problems found. If B<*codes> is zero then
+no problems were found, otherwise the following bits may be set:
+
+=over 4
+
+=item DH_CHECK_P_NOT_PRIME
+
+The parameter B<p> is not prime.
+
+=item DH_CHECK_P_NOT_SAFE_PRIME
+
+The parameter B<p> is not a safe prime and no B<q> value is present.
+
+=item DH_UNABLE_TO_CHECK_GENERATOR
+
+The generator B<g> cannot be checked for suitability.
+
+=item DH_NOT_SUITABLE_GENERATOR
+
+The generator B<g> is not suitable.
+
+=item DH_CHECK_Q_NOT_PRIME
+
+The parameter B<q> is not prime.
+
+=item DH_CHECK_INVALID_Q_VALUE
+
+The parameter B<q> is invalid.
+
+=item DH_CHECK_INVALID_J_VALUE
+
+The parameter B<j> is invalid.
+
+=back
+
+=head1 RETURN VALUES
+
+DH_generate_parameters_ex() and DH_check() return 1 if the check could be
+performed, 0 otherwise.
+
+DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or
+NULL if the parameter generation fails.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 NOTES
+
+DH_generate_parameters_ex() and DH_generate_parameters() may run for several
+hours before finding a suitable prime.
+
+The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters()
+are not to be used in signature schemes.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>,
+L<DH_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_clear_flags,
+DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length,
+DH_set_length - Routines for getting and setting data in a DH object
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ void DH_get0_pqg(const DH *dh,
+ const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);
+ int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);
+ void DH_get0_key(const DH *dh,
+ const BIGNUM **pub_key, const BIGNUM **priv_key);
+ int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key);
+ void DH_clear_flags(DH *dh, int flags);
+ int DH_test_flags(const DH *dh, int flags);
+ void DH_set_flags(DH *dh, int flags);
+ ENGINE *DH_get0_engine(DH *d);
+ long DH_get_length(const DH *dh);
+ int DH_set_length(DH *dh, long length);
+
+=head1 DESCRIPTION
+
+A DH object contains the parameters B<p>, B<q> and B<g>. Note that the B<q>
+parameter is optional. It also contains a public key (B<pub_key>) and
+(optionally) a private key (B<priv_key>).
+
+The B<p>, B<q> and B<g> parameters can be obtained by calling DH_get0_pqg().
+If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set
+to NULL. Otherwise they are set to pointers to their respective values. These
+point directly to the internal representations of the values and therefore
+should not be freed directly.
+
+The B<p>, B<q> and B<g> values can be set by calling DH_set0_pqg() and passing
+the new values for B<p>, B<q> and B<g> as parameters to the function. Calling
+this function transfers the memory management of the values to the DH object,
+and therefore the values that have been passed in should not be freed directly
+after this function has been called. The B<q> parameter may be NULL.
+
+To get the public and private key values use the DH_get0_key() function. A
+pointer to the public key will be stored in B<*pub_key>, and a pointer to the
+private key will be stored in B<*priv_key>. Either may be NULL if they have not
+been set yet, although if the private key has been set then the public key must
+be. The values point to the internal representation of the public key and
+private key values. This memory should not be freed directly.
+
+The public and private key values can be set using DH_set0_key(). The public
+key must be non-NULL the first time this function is called on a given DH
+object. The private key may be NULL. On subsequent calls, either may be NULL,
+which means the corresponding DH field is left untouched. As for DH_set0_pqg()
+this function transfers the memory management of the key values to the DH
+object, and therefore they should not be freed directly after this function has
+been called.
+
+DH_set_flags() sets the flags in the B<flags> parameter on the DH object.
+Multiple flags can be passed in one go (bitwise ORed together). Any flags that
+are already set are left set. DH_test_flags() tests to see whether the flags
+passed in the B<flags> parameter are currently set in the DH object. Multiple
+flags can be tested in one go. All flags that are currently set are returned, or
+zero if none of the flags are set. DH_clear_flags() clears the specified flags
+within the DH object.
+
+DH_get0_engine() returns a handle to the ENGINE that has been set for this DH
+object, or NULL if no such ENGINE has been set.
+
+The DH_get_length() and DH_set_length() functions get and set the optional
+length parameter associated with this DH object. If the length is non-zero then
+it is used, otherwise it is ignored. The B<length> parameter indicates the
+length of the secret exponent (private key) in bits.
+
+=head1 NOTES
+
+Values retrieved with DH_get0_key() are owned by the DH object used
+in the call and may therefore I<not> be passed to DH_set0_key(). If
+needed, duplicate the received value using BN_dup() and pass the
+duplicate. The same applies to DH_get0_pqg() and DH_set0_pqg().
+
+=head1 RETURN VALUES
+
+DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure.
+
+DH_test_flags() returns the current state of the flags in the DH object.
+
+DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE
+has been set.
+
+DH_get_length() returns the length of the secret exponent (private key) in bits,
+or zero if no such length has been explicitly set.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
+L<DH_set_method(3)>, L<DH_size(3)>, L<DH_meth_new(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_get_1024_160,
+DH_get_2048_224,
+DH_get_2048_256,
+BN_get0_nist_prime_192,
+BN_get0_nist_prime_224,
+BN_get0_nist_prime_256,
+BN_get0_nist_prime_384,
+BN_get0_nist_prime_521,
+BN_get_rfc2409_prime_768,
+BN_get_rfc2409_prime_1024,
+BN_get_rfc3526_prime_1536,
+BN_get_rfc3526_prime_2048,
+BN_get_rfc3526_prime_3072,
+BN_get_rfc3526_prime_4096,
+BN_get_rfc3526_prime_6144,
+BN_get_rfc3526_prime_8192
+- Create standardized public primes or DH pairs
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+ DH *DH_get_1024_160(void)
+ DH *DH_get_2048_224(void)
+ DH *DH_get_2048_256(void)
+
+ const BIGNUM *BN_get0_nist_prime_192(void)
+ const BIGNUM *BN_get0_nist_prime_224(void)
+ const BIGNUM *BN_get0_nist_prime_256(void)
+ const BIGNUM *BN_get0_nist_prime_384(void)
+ const BIGNUM *BN_get0_nist_prime_521(void)
+
+ BIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn)
+ BIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn)
+ BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn)
+ BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn)
+ BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn)
+ BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn)
+ BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn)
+ BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn)
+
+=head1 DESCRIPTION
+
+DH_get_1024_160(), DH_get_2048_224(), and DH_get_2048_256() each return
+a DH object for the IETF RFC 5114 value.
+
+BN_get0_nist_prime_192(), BN_get0_nist_prime_224(), BN_get0_nist_prime_256(),
+BN_get0_nist_prime_384(), and BN_get0_nist_prime_521() functions return
+a BIGNUM for the specific NIST prime curve (e.g., P-256).
+
+BN_get_rfc2409_prime_768(), BN_get_rfc2409_prime_1024(),
+BN_get_rfc3526_prime_1536(), BN_get_rfc3526_prime_2048(),
+BN_get_rfc3526_prime_3072(), BN_get_rfc3526_prime_4096(),
+BN_get_rfc3526_prime_6144(), and BN_get_rfc3526_prime_8192() functions
+return a BIGNUM for the specified size from IETF RFC 2409. If B<bn>
+is not NULL, the BIGNUM will be set into that location as well.
+
+=head1 RETURN VALUES
+
+Defined above.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name,
+DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data,
+DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key,
+DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp,
+DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish,
+DH_meth_set_finish, DH_meth_get_generate_params,
+DH_meth_set_generate_params - Routines to build up DH methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ DH_METHOD *DH_meth_new(const char *name, int flags);
+ void DH_meth_free(DH_METHOD *dhm);
+ DH_METHOD *DH_meth_dup(const DH_METHOD *dhm);
+ const char *DH_meth_get0_name(const DH_METHOD *dhm);
+ int DH_meth_set1_name(DH_METHOD *dhm, const char *name);
+ int DH_meth_get_flags(DH_METHOD *dhm);
+ int DH_meth_set_flags(DH_METHOD *dhm, int flags);
+ void *DH_meth_get0_app_data(const DH_METHOD *dhm);
+ int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data);
+ int (*DH_meth_get_generate_key(const DH_METHOD *dhm)) (DH *);
+ int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key) (DH *));
+ int (*DH_meth_get_compute_key(const DH_METHOD *dhm))
+ (unsigned char *key, const BIGNUM *pub_key, DH *dh);
+ int DH_meth_set_compute_key(DH_METHOD *dhm,
+ int (*compute_key) (unsigned char *key, const BIGNUM *pub_key, DH *dh));
+ int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm))
+ (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
+ int DH_meth_set_bn_mod_exp(DH_METHOD *dhm,
+ int (*bn_mod_exp) (const DH *dh, BIGNUM *r, const BIGNUM *a,
+ const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,
+ BN_MONT_CTX *m_ctx));
+ int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *);
+ int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *));
+ int (*DH_meth_get_finish(const DH_METHOD *dhm)) (DH *);
+ int DH_meth_set_finish(DH_METHOD *dhm, int (*finish) (DH *));
+ int (*DH_meth_get_generate_params(const DH_METHOD *dhm))
+ (DH *, int, int, BN_GENCB *);
+ int DH_meth_set_generate_params(DH_METHOD *dhm,
+ int (*generate_params) (DH *, int, int, BN_GENCB *));
+
+=head1 DESCRIPTION
+
+The B<DH_METHOD> type is a structure used for the provision of custom DH
+implementations. It provides a set of of functions used by OpenSSL for the
+implementation of the various DH capabilities.
+
+DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a
+unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated
+string, which will be duplicated and stored in the B<DH_METHOD> object. It is
+the callers responsibility to free the original string. The flags will be used
+during the construction of a new B<DH> object based on this B<DH_METHOD>. Any
+new B<DH> object will have those flags set by default.
+
+DH_meth_dup() creates a duplicate copy of the B<DH_METHOD> object passed as a
+parameter. This might be useful for creating a new B<DH_METHOD> based on an
+existing one, but with some differences.
+
+DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory
+associated with it.
+
+DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This
+is a pointer to the internal name string and so should not be freed by the
+caller. DH_meth_set1_name() sets the name of the DH_METHOD to B<name>. The
+string is duplicated and the copy is stored in the DH_METHOD structure, so the
+caller remains responsible for freeing the memory associated with the name.
+
+DH_meth_get_flags() returns the current value of the flags associated with this
+DH_METHOD. DH_meth_set_flags() provides the ability to set these flags.
+
+The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the
+ability to associate implementation specific data with the DH_METHOD. It is
+the application's responsibility to free this data before the DH_METHOD is
+freed via a call to DH_meth_free().
+
+DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the
+function used for generating a new DH key pair respectively. This function will
+be called in response to the application calling DH_generate_key(). The
+parameter for the function has the same meaning as for DH_generate_key().
+
+DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the
+function used for computing a new DH shared secret respectively. This function
+will be called in response to the application calling DH_compute_key(). The
+parameters for the function have the same meaning as for DH_compute_key().
+
+DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function
+used for computing the following value:
+
+ r = a ^ p mod m
+
+This function will be called by the default OpenSSL function for
+DH_generate_key(). The result is stored in the B<r> parameter. This function
+may be NULL unless using the default generate key function, in which case it
+must be present.
+
+DH_meth_get_init() and DH_meth_set_init() get and set the function used
+for creating a new DH instance respectively. This function will be
+called in response to the application calling DH_new() (if the current default
+DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method()
+functions will allocate the memory for the new DH object, and a pointer to this
+newly allocated structure will be passed as a parameter to the function. This
+function may be NULL.
+
+DH_meth_get_finish() and DH_meth_set_finish() get and set the function used
+for destroying an instance of a DH object respectively. This function will be
+called in response to the application calling DH_free(). A pointer to the DH
+to be destroyed is passed as a parameter. The destroy function should be used
+for DH implementation specific clean up. The memory for the DH itself should
+not be freed by this function. This function may be NULL.
+
+DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the
+function used for generating DH parameters respectively. This function will be
+called in response to the application calling DH_generate_parameters_ex() (or
+DH_generate_parameters()). The parameters for the function have the same
+meaning as for DH_generate_parameters_ex(). This function may be NULL.
+
+=head1 RETURN VALUES
+
+DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object
+or NULL on failure.
+
+DH_meth_get0_name() and DH_meth_get_flags() return the name and flags
+associated with the DH_METHOD respectively.
+
+All other DH_meth_get_*() functions return the appropriate function pointer
+that has been set in the DH_METHOD, or NULL if no such pointer has yet been
+set.
+
+DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or
+0 on failure.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
+L<DH_set_method(3)>, L<DH_size(3)>, L<DH_get0_pqg(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_new, DH_free - allocate and free DH objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ DH* DH_new(void);
+
+ void DH_free(DH *dh);
+
+=head1 DESCRIPTION
+
+DH_new() allocates and initializes a B<DH> structure.
+
+DH_free() frees the B<DH> structure and its components. The values are
+erased before the memory is returned to the system.
+If B<dh> is NULL nothing is done.
+
+=head1 RETURN VALUES
+
+If the allocation fails, DH_new() returns B<NULL> and sets an error
+code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns
+a pointer to the newly allocated structure.
+
+DH_free() returns no value.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<ERR_get_error(3)>,
+L<DH_generate_parameters(3)>,
+L<DH_generate_key(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_set_default_method, DH_get_default_method,
+DH_set_method, DH_new_method, DH_OpenSSL - select DH method
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ void DH_set_default_method(const DH_METHOD *meth);
+
+ const DH_METHOD *DH_get_default_method(void);
+
+ int DH_set_method(DH *dh, const DH_METHOD *meth);
+
+ DH *DH_new_method(ENGINE *engine);
+
+ const DH_METHOD *DH_OpenSSL(void);
+
+=head1 DESCRIPTION
+
+A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
+operations. By modifying the method, alternative implementations
+such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these DH API functions are affected by the use
+of B<ENGINE> API calls.
+
+Initially, the default DH_METHOD is the OpenSSL internal implementation, as
+returned by DH_OpenSSL().
+
+DH_set_default_method() makes B<meth> the default method for all DH
+structures created later. B<NB>: This is true only whilst no ENGINE has been set
+as a default for DH, so this function is no longer recommended.
+
+DH_get_default_method() returns a pointer to the current default DH_METHOD.
+However, the meaningfulness of this result is dependent on whether the ENGINE
+API is being used, so this function is no longer recommended.
+
+DH_set_method() selects B<meth> to perform all operations using the key B<dh>.
+This will replace the DH_METHOD used by the DH key and if the previous method
+was supplied by an ENGINE, the handle to that ENGINE will be released during the
+change. It is possible to have DH keys that only work with certain DH_METHOD
+implementations (eg. from an ENGINE module that supports embedded
+hardware-protected keys), and in such cases attempting to change the DH_METHOD
+for the key can have unexpected results.
+
+DH_new_method() allocates and initializes a DH structure so that B<engine> will
+be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
+operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
+DH_set_default_method() is used.
+
+A new DH_METHOD object may be constructed using DH_meth_new() (see
+L<DH_meth_new(3)>).
+
+=head1 RETURN VALUES
+
+DH_OpenSSL() and DH_get_default_method() return pointers to the respective
+B<DH_METHOD>s.
+
+DH_set_default_method() returns no value.
+
+DH_set_method() returns non-zero if the provided B<meth> was successfully set as
+the method for B<dh> (including unloading the ENGINE handle if the previous
+method was supplied by an ENGINE).
+
+DH_new_method() returns NULL and sets an error code that can be obtained by
+L<ERR_get_error(3)> if the allocation fails. Otherwise it
+returns a pointer to the newly allocated structure.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<DH_new(3)>, L<DH_meth_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DH_size, DH_bits - get Diffie-Hellman prime size
+
+=head1 SYNOPSIS
+
+#include <openssl/dh.h>
+
+int DH_size(const DH *dh);
+
+int DH_bits(const DH *dh);
+
+=head1 DESCRIPTION
+
+DH_size() returns the Diffie-Hellman prime size in bytes. It can be used
+to determine how much memory must be allocated for the shared secret
+computed by DH_compute_key().
+
+DH_bits() returns the number of significant bits.
+
+B<dh> and B<dh-E<gt>p> must not be B<NULL>.
+
+=head1 RETURN VALUE
+
+The size.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<DH_generate_key(3)>,
+L<BN_num_bits(3)>
+
+=head1 HISTORY
+
+DH_bits() was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_SIG_get0, DSA_SIG_set0,
+DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA_SIG *DSA_SIG_new(void);
+ void DSA_SIG_free(DSA_SIG *a);
+ void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
+ int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s);
+
+=head1 DESCRIPTION
+
+DSA_SIG_new() allocates an empty B<DSA_SIG> structure.
+
+DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
+values are erased before the memory is returned to the system.
+
+DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained
+in B<sig>.
+
+The B<r> and B<s> values can be set by calling DSA_SIG_set0() and passing the
+new values for B<r> and B<s> as parameters to the function. Calling this
+function transfers the memory management of the values to the DSA_SIG object,
+and therefore the values that have been passed in should not be freed directly
+after this function has been called.
+
+=head1 RETURN VALUES
+
+If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an
+error code that can be obtained by
+L<ERR_get_error(3)>. Otherwise it returns a pointer
+to the newly allocated structure.
+
+DSA_SIG_free() returns no value.
+
+DSA_SIG_set0() returns 1 on success or 0 on failure.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<ERR_get_error(3)>,
+L<DSA_do_sign(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_do_sign, DSA_do_verify - raw DSA signature operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
+
+ int DSA_do_verify(const unsigned char *dgst, int dgst_len,
+ DSA_SIG *sig, DSA *dsa);
+
+=head1 DESCRIPTION
+
+DSA_do_sign() computes a digital signature on the B<len> byte message
+digest B<dgst> using the private key B<dsa> and returns it in a
+newly allocated B<DSA_SIG> structure.
+
+L<DSA_sign_setup(3)> may be used to precompute part
+of the signing operation in case signature generation is
+time-critical.
+
+DSA_do_verify() verifies that the signature B<sig> matches a given
+message digest B<dgst> of size B<len>. B<dsa> is the signer's public
+key.
+
+=head1 RETURN VALUES
+
+DSA_do_sign() returns the signature, NULL on error. DSA_do_verify()
+returns 1 for a valid signature, 0 for an incorrect signature and -1
+on error. The error codes can be obtained by
+L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
+L<DSA_SIG_new(3)>,
+L<DSA_sign(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_dup_DH - create a DH structure out of DSA structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DH * DSA_dup_DH(const DSA *r);
+
+=head1 DESCRIPTION
+
+DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
+is lost during that conversion, but the resulting DH parameters
+contain its length.
+
+=head1 RETURN VALUE
+
+DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The
+error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 NOTE
+
+Be careful to avoid small subgroup attacks when using this.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<dsa(3)>, L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_generate_key - generate DSA key pair
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ int DSA_generate_key(DSA *a);
+
+=head1 DESCRIPTION
+
+DSA_generate_key() expects B<a> to contain DSA parameters. It generates
+a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
+
+The PRNG must be seeded prior to calling DSA_generate_key().
+
+=head1 RETURN VALUE
+
+DSA_generate_key() returns 1 on success, 0 otherwise.
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
+L<DSA_generate_parameters(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ int DSA_generate_parameters_ex(DSA *dsa, int bits,
+ const unsigned char *seed, int seed_len,
+ int *counter_ret, unsigned long *h_ret, BN_GENCB *cb);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x00908000L
+ DSA *DSA_generate_parameters(int bits, unsigned char *seed,
+ int seed_len, int *counter_ret, unsigned long *h_ret,
+ void (*callback)(int, int, void *), void *cb_arg);
+ #endif
+
+=head1 DESCRIPTION
+
+DSA_generate_parameters_ex() generates primes p and q and a generator g
+for use in the DSA and stores the result in B<dsa>.
+
+B<bits> is the length of the prime p to be generated.
+For lengths under 2048 bits, the length of q is 160 bits; for lengths
+greater than or equal to 2048 bits, the length of q is set to 256 bits.
+
+If B<seed> is NULL, the primes will be generated at random.
+If B<seed_len> is less than the length of q, an error is returned.
+
+DSA_generate_parameters_ex() places the iteration count in
+*B<counter_ret> and a counter used for finding a generator in
+*B<h_ret>, unless these are B<NULL>.
+
+A callback function may be used to provide feedback about the progress
+of the key generation. If B<cb> is not B<NULL>, it will be
+called as shown below. For information on the BN_GENCB structure and the
+BN_GENCB_call function discussed below, refer to
+L<BN_generate_prime(3)>.
+
+=over 4
+
+=item *
+
+When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called
+(m is 0 for the first candidate).
+
+=item *
+
+When a candidate for q has passed a test by trial division,
+B<BN_GENCB_call(cb, 1, -1)> is called.
+While a candidate for q is tested by Miller-Rabin primality tests,
+B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
+(once for each witness that confirms that the candidate may be prime);
+i is the loop counter (starting at 0).
+
+=item *
+
+When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and
+B<BN_GENCB_call(cb, 3, 0)> are called.
+
+=item *
+
+Before a candidate for p (other than the first) is generated and tested,
+B<BN_GENCB_call(cb, 0, counter)> is called.
+
+=item *
+
+When a candidate for p has passed the test by trial division,
+B<BN_GENCB_call(cb, 1, -1)> is called.
+While it is tested by the Miller-Rabin primality test,
+B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
+(once for each witness that confirms that the candidate may be prime).
+i is the loop counter (starting at 0).
+
+=item *
+
+When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called.
+
+=item *
+
+When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called.
+
+=back
+
+DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and
+instead a newly allocated B<DSA> structure is returned. Additionally "old
+style" callbacks are used instead of the newer BN_GENCB based approach.
+Refer to L<BN_generate_prime(3)> for further information.
+
+=head1 RETURN VALUE
+
+DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise.
+
+DSA_generate_parameters() returns a pointer to the DSA structure, or
+B<NULL> if the parameter generation fails.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 BUGS
+
+Seed lengths E<gt> 20 are not supported.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
+L<DSA_free(3)>, L<BN_generate_prime(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, DSA_clear_flags,
+DSA_test_flags, DSA_set_flags, DSA_get0_engine - Routines for getting and
+setting data in a DSA object
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ void DSA_get0_pqg(const DSA *d,
+ const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);
+ int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g);
+ void DSA_get0_key(const DSA *d,
+ const BIGNUM **pub_key, const BIGNUM **priv_key);
+ int DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key);
+ void DSA_clear_flags(DSA *d, int flags);
+ int DSA_test_flags(const DSA *d, int flags);
+ void DSA_set_flags(DSA *d, int flags);
+ ENGINE *DSA_get0_engine(DSA *d);
+
+=head1 DESCRIPTION
+
+A DSA object contains the parameters B<p>, B<q> and B<g>. It also contains a
+public key (B<pub_key>) and (optionally) a private key (B<priv_key>).
+
+The B<p>, B<q> and B<g> parameters can be obtained by calling DSA_get0_pqg().
+If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set
+to NULL. Otherwise they are set to pointers to their respective values. These
+point directly to the internal representations of the values and therefore
+should not be freed directly.
+
+The B<p>, B<q> and B<g> values can be set by calling DSA_set0_pqg() and passing
+the new values for B<p>, B<q> and B<g> as parameters to the function. Calling
+this function transfers the memory management of the values to the DSA object,
+and therefore the values that have been passed in should not be freed directly
+after this function has been called.
+
+To get the public and private key values use the DSA_get0_key() function. A
+pointer to the public key will be stored in B<*pub_key>, and a pointer to the
+private key will be stored in B<*priv_key>. Either may be NULL if they have not
+been set yet, although if the private key has been set then the public key must
+be. The values point to the internal representation of the public key and
+private key values. This memory should not be freed directly.
+
+The public and private key values can be set using DSA_set0_key(). The public
+key must be non-NULL the first time this function is called on a given DSA
+object. The private key may be NULL. On subsequent calls, either may be NULL,
+which means the corresponding DSA field is left untouched. As for DSA_set0_pqg()
+this function transfers the memory management of the key values to the DSA
+object, and therefore they should not be freed directly after this function has
+been called.
+
+DSA_set_flags() sets the flags in the B<flags> parameter on the DSA object.
+Multiple flags can be passed in one go (bitwise ORed together). Any flags that
+are already set are left set. DSA_test_flags() tests to see whether the flags
+passed in the B<flags> parameter are currently set in the DSA object. Multiple
+flags can be tested in one go. All flags that are currently set are returned, or
+zero if none of the flags are set. DSA_clear_flags() clears the specified flags
+within the DSA object.
+
+DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA
+object, or NULL if no such ENGINE has been set.
+
+=head1 NOTES
+
+Values retrieved with DSA_get0_key() are owned by the DSA object used
+in the call and may therefore I<not> be passed to DSA_set0_key(). If
+needed, duplicate the received value using BN_dup() and pass the
+duplicate. The same applies to DSA_get0_pqg() and DSA_set0_pqg().
+
+=head1 RETURN VALUES
+
+DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure.
+
+DSA_test_flags() returns the current state of the flags in the DSA object.
+
+DSA_get0_engine() returns the ENGINE set for the DSA object or NULL if no ENGINE
+has been set.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>,
+L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>,
+L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_meth_new(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name,
+DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags,
+DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign,
+DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup,
+DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp,
+DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp,
+DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish,
+DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen,
+DSA_meth_set_keygen - Routines to build up DSA methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA_METHOD *DSA_meth_new(const char *name, int flags);
+ void DSA_meth_free(DSA_METHOD *dsam);
+ DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth);
+ const char *DSA_meth_get0_name(const DSA_METHOD *dsam);
+ int DSA_meth_set1_name(DSA_METHOD *dsam, const char *name);
+ int DSA_meth_get_flags(DSA_METHOD *dsam);
+ int DSA_meth_set_flags(DSA_METHOD *dsam, int flags);
+ void *DSA_meth_get0_app_data(const DSA_METHOD *dsam);
+ int DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data);
+ DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))
+ (const unsigned char *, int, DSA *);
+ int DSA_meth_set_sign(DSA_METHOD *dsam,
+ DSA_SIG *(*sign) (const unsigned char *, int, DSA *));
+ int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))
+ (DSA *, BN_CTX *, BIGNUM **, BIGNUM **);
+ int DSA_meth_set_sign_setup(DSA_METHOD *dsam,
+ int (*sign_setup) (DSA *, BN_CTX *, BIGNUM **, BIGNUM **));
+ int (*DSA_meth_get_verify(const DSA_METHOD *dsam))
+ (const unsigned char *, int , DSA_SIG *, DSA *);
+ int DSA_meth_set_verify(DSA_METHOD *dsam,
+ int (*verify) (const unsigned char *, int, DSA_SIG *, DSA *));
+ int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))
+ (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2, BIGNUM *p2,
+ BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont);
+ int DSA_meth_set_mod_exp(DSA_METHOD *dsam,
+ int (*mod_exp) (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2,
+ BIGNUM *p2, BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont));
+ int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))
+ (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m,
+ BN_CTX *ctx, BN_MONT_CTX *mont);
+ int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam,
+ int (*bn_mod_exp) (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont));
+ int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *);
+ int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *));
+ int (*DSA_meth_get_finish(const DSA_METHOD *dsam)) (DSA *);
+ int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish) (DSA *));
+ int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))
+ (DSA *, int, const unsigned char *, int, int *, unsigned long *,
+ BN_GENCB *);
+ int DSA_meth_set_paramgen(DSA_METHOD *dsam,
+ int (*paramgen) (DSA *, int, const unsigned char *, int, int *,
+ unsigned long *, BN_GENCB *));
+ int (*DSA_meth_get_keygen(const DSA_METHOD *dsam)) (DSA *);
+ int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen) (DSA *));
+
+=head1 DESCRIPTION
+
+The B<DSA_METHOD> type is a structure used for the provision of custom DSA
+implementations. It provides a set of of functions used by OpenSSL for the
+implementation of the various DSA capabilities. See the L<dsa> page for more
+information.
+
+DSA_meth_new() creates a new B<DSA_METHOD> structure. It should be given a
+unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated
+string, which will be duplicated and stored in the B<DSA_METHOD> object. It is
+the callers responsibility to free the original string. The flags will be used
+during the construction of a new B<DSA> object based on this B<DSA_METHOD>. Any
+new B<DSA> object will have those flags set by default.
+
+DSA_meth_dup() creates a duplicate copy of the B<DSA_METHOD> object passed as a
+parameter. This might be useful for creating a new B<DSA_METHOD> based on an
+existing one, but with some differences.
+
+DSA_meth_free() destroys a B<DSA_METHOD> structure and frees up any memory
+associated with it.
+
+DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This
+is a pointer to the internal name string and so should not be freed by the
+caller. DSA_meth_set1_name() sets the name of the DSA_METHOD to B<name>. The
+string is duplicated and the copy is stored in the DSA_METHOD structure, so the
+caller remains responsible for freeing the memory associated with the name.
+
+DSA_meth_get_flags() returns the current value of the flags associated with this
+DSA_METHOD. DSA_meth_set_flags() provides the ability to set these flags.
+
+The functions DSA_meth_get0_app_data() and DSA_meth_set0_app_data() provide the
+ability to associate implementation specific data with the DSA_METHOD. It is
+the application's responsibility to free this data before the DSA_METHOD is
+freed via a call to DSA_meth_free().
+
+DSA_meth_get_sign() and DSA_meth_set_sign() get and set the function used for
+creating a DSA signature respectively. This function will be
+called in response to the application calling DSA_do_sign() (or DSA_sign()). The
+parameters for the function have the same meaning as for DSA_do_sign().
+
+DSA_meth_get_sign_setup() and DSA_meth_set_sign_setup() get and set the function
+used for precalculating the DSA signature values B<k^-1> and B<r>. This function
+will be called in response to the application calling DSA_sign_setup(). The
+parameters for the function have the same meaning as for DSA_sign_setup().
+
+DSA_meth_get_verify() and DSA_meth_set_verify() get and set the function used
+for verifying a DSA signature respectively. This function will be called in
+response to the application calling DSA_do_verify() (or DSA_verify()). The
+parameters for the function have the same meaning as for DSA_do_verify().
+
+DSA_meth_get_mod_exp() and DSA_meth_set_mod_exp() get and set the function used
+for computing the following value:
+
+ rr = a1^p1 * a2^p2 mod m
+
+This function will be called by the default OpenSSL method during verification
+of a DSA signature. The result is stored in the B<rr> parameter. This function
+may be NULL.
+
+DSA_meth_get_bn_mod_exp() and DSA_meth_set_bn_mod_exp() get and set the function
+used for computing the following value:
+
+ r = a ^ p mod m
+
+This function will be called by the default OpenSSL function for
+DSA_sign_setup(). The result is stored in the B<r> parameter. This function
+may be NULL.
+
+DSA_meth_get_init() and DSA_meth_set_init() get and set the function used
+for creating a new DSA instance respectively. This function will be
+called in response to the application calling DSA_new() (if the current default
+DSA_METHOD is this one) or DSA_new_method(). The DSA_new() and DSA_new_method()
+functions will allocate the memory for the new DSA object, and a pointer to this
+newly allocated structure will be passed as a parameter to the function. This
+function may be NULL.
+
+DSA_meth_get_finish() and DSA_meth_set_finish() get and set the function used
+for destroying an instance of a DSA object respectively. This function will be
+called in response to the application calling DSA_free(). A pointer to the DSA
+to be destroyed is passed as a parameter. The destroy function should be used
+for DSA implementation specific clean up. The memory for the DSA itself should
+not be freed by this function. This function may be NULL.
+
+DSA_meth_get_paramgen() and DSA_meth_set_paramgen() get and set the function
+used for generating DSA parameters respectively. This function will be called in
+response to the application calling DSA_generate_parameters_ex() (or
+DSA_generate_parameters()). The parameters for the function have the same
+meaning as for DSA_generate_parameters_ex().
+
+DSA_meth_get_keygen() and DSA_meth_set_keygen() get and set the function
+used for generating a new DSA key pair respectively. This function will be
+called in response to the application calling DSA_generate_key(). The parameter
+for the function has the same meaning as for DSA_generate_key().
+
+=head1 RETURN VALUES
+
+DSA_meth_new() and DSA_meth_dup() return the newly allocated DSA_METHOD object
+or NULL on failure.
+
+DSA_meth_get0_name() and DSA_meth_get_flags() return the name and flags
+associated with the DSA_METHOD respectively.
+
+All other DSA_meth_get_*() functions return the appropriate function pointer
+that has been set in the DSA_METHOD, or NULL if no such pointer has yet been
+set.
+
+DSA_meth_set1_name() and all DSA_meth_set_*() functions return 1 on success or
+0 on failure.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>,
+L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>,
+L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_get0_pqg(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_new, DSA_free - allocate and free DSA objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ DSA* DSA_new(void);
+
+ void DSA_free(DSA *dsa);
+
+=head1 DESCRIPTION
+
+DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to
+calling DSA_new_method(NULL).
+
+DSA_free() frees the B<DSA> structure and its components. The values are
+erased before the memory is returned to the system.
+If B<dsa> is NULL nothing is done.
+
+=head1 RETURN VALUES
+
+If the allocation fails, DSA_new() returns B<NULL> and sets an error
+code that can be obtained by
+L<ERR_get_error(3)>. Otherwise it returns a pointer
+to the newly allocated structure.
+
+DSA_free() returns no value.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<ERR_get_error(3)>,
+L<DSA_generate_parameters(3)>,
+L<DSA_generate_key(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_set_default_method, DSA_get_default_method,
+DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ void DSA_set_default_method(const DSA_METHOD *meth);
+
+ const DSA_METHOD *DSA_get_default_method(void);
+
+ int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
+
+ DSA *DSA_new_method(ENGINE *engine);
+
+ DSA_METHOD *DSA_OpenSSL(void);
+
+=head1 DESCRIPTION
+
+A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
+operations. By modifying the method, alternative implementations
+such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these DSA API functions are affected by the use
+of B<ENGINE> API calls.
+
+Initially, the default DSA_METHOD is the OpenSSL internal implementation,
+as returned by DSA_OpenSSL().
+
+DSA_set_default_method() makes B<meth> the default method for all DSA
+structures created later. B<NB>: This is true only whilst no ENGINE has
+been set as a default for DSA, so this function is no longer recommended.
+
+DSA_get_default_method() returns a pointer to the current default
+DSA_METHOD. However, the meaningfulness of this result is dependent on
+whether the ENGINE API is being used, so this function is no longer
+recommended.
+
+DSA_set_method() selects B<meth> to perform all operations using the key
+B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
+previous method was supplied by an ENGINE, the handle to that ENGINE will
+be released during the change. It is possible to have DSA keys that only
+work with certain DSA_METHOD implementations (eg. from an ENGINE module
+that supports embedded hardware-protected keys), and in such cases
+attempting to change the DSA_METHOD for the key can have unexpected
+results. See L<DSA_meth_new> for information on constructing custom DSA_METHOD
+objects;
+
+DSA_new_method() allocates and initializes a DSA structure so that B<engine>
+will be used for the DSA operations. If B<engine> is NULL, the default engine
+for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
+controlled by DSA_set_default_method() is used.
+
+=head1 RETURN VALUES
+
+DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective
+B<DSA_METHOD>s.
+
+DSA_set_default_method() returns no value.
+
+DSA_set_method() returns non-zero if the provided B<meth> was successfully set as
+the method for B<dsa> (including unloading the ENGINE handle if the previous
+method was supplied by an ENGINE).
+
+DSA_new_method() returns NULL and sets an error code that can be
+obtained by L<ERR_get_error(3)> if the allocation
+fails. Otherwise it returns a pointer to the newly allocated structure.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<DSA_new(3)>, L<DSA_meth_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ int DSA_sign(int type, const unsigned char *dgst, int len,
+ unsigned char *sigret, unsigned int *siglen, DSA *dsa);
+
+ int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
+ BIGNUM **rp);
+
+ int DSA_verify(int type, const unsigned char *dgst, int len,
+ unsigned char *sigbuf, int siglen, DSA *dsa);
+
+=head1 DESCRIPTION
+
+DSA_sign() computes a digital signature on the B<len> byte message
+digest B<dgst> using the private key B<dsa> and places its ASN.1 DER
+encoding at B<sigret>. The length of the signature is places in
+*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory.
+
+DSA_sign_setup() may be used to precompute part of the signing
+operation in case signature generation is time-critical. It expects
+B<dsa> to contain DSA parameters. It places the precomputed values
+in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing
+the old ones unless *B<kinvp> and *B<rp> are NULL. These values may
+be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>.
+B<ctx> is a pre-allocated B<BN_CTX> or NULL.
+
+DSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
+matches a given message digest B<dgst> of size B<len>.
+B<dsa> is the signer's public key.
+
+The B<type> parameter is ignored.
+
+The PRNG must be seeded before DSA_sign() (or DSA_sign_setup())
+is called.
+
+=head1 RETURN VALUES
+
+DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error.
+DSA_verify() returns 1 for a valid signature, 0 for an incorrect
+signature and -1 on error. The error codes can be obtained by
+L<ERR_get_error(3)>.
+
+=head1 CONFORMING TO
+
+US Federal Information Processing Standard FIPS 186 (Digital Signature
+Standard, DSS), ANSI X9.30
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>,
+L<DSA_do_sign(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DSA_size, DSA_bits - get DSA signature size or key bits
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ int DSA_size(const DSA *dsa);
+ int DSA_bits(const DSA *dsa);
+
+=head1 DESCRIPTION
+
+DSA_size() returns the maximum size of an ASN.1 encoded DSA signature
+for key B<dsa> in bytes. It can be used to determine how much memory must
+be allocated for a DSA signature.
+
+B<dsa-E<gt>q> must not be B<NULL>.
+
+DSA_bits() returns the number of bits in key B<dsa>: this is the number
+of bits in the B<p> parameter.
+
+=head1 RETURN VALUE
+
+DSA_size() returns the size in bytes.
+
+DSA_bits() returns the number of bits in the key.
+
+=head1 SEE ALSO
+
+L<dsa(3)>, L<DSA_sign(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DTLSv1_listen - listen for incoming DTLS connections
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);
+
+=head1 DESCRIPTION
+
+DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is
+received that does not contain a cookie, then DTLSv1_listen() responds with a
+HelloVerifyRequest. If a ClientHello is received with a cookie that is verified
+then control is returned to user code to enable the handshake to be completed
+(for example by using SSL_accept()).
+
+=head1 NOTES
+
+Datagram based protocols can be susceptible to Denial of Service attacks. A
+DTLS attacker could, for example, submit a series of handshake initiation
+requests that cause the server to allocate state (and possibly perform
+cryptographic operations) thus consuming server resources. The attacker could
+also (with UDP) quite simply forge the source IP address in such an attack.
+
+As a counter measure to that DTLS includes a stateless cookie mechanism. The
+idea is that when a client attempts to connect to a server it sends a
+ClientHello message. The server responds with a HelloVerifyRequest which
+contains a unique cookie. The client then resends the ClientHello, but this time
+includes the cookie in the message thus proving that the client is capable of
+receiving messages sent to that address. All of this can be done by the server
+without allocating any state, and thus without consuming expensive resources.
+
+OpenSSL implements this capability via the DTLSv1_listen() function. The B<ssl>
+parameter should be a newly allocated SSL object with its read and write BIOs
+set, in the same way as might be done for a call to SSL_accept(). Typically the
+read BIO will be in an "unconnected" state and thus capable of receiving
+messages from any peer.
+
+When a ClientHello is received that contains a cookie that has been verified,
+then DTLSv1_listen() will return with the B<ssl> parameter updated into a state
+where the handshake can be continued by a call to (for example) SSL_accept().
+Additionally the B<BIO_ADDR> pointed to by B<peer> will be filled in with
+details of the peer that sent the ClientHello. If the underlying BIO is unable
+to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not
+support this), then B<*peer> will be cleared and the family set to AF_UNSPEC.
+Typically user code is expected to "connect" the underlying socket to the peer
+and continue the handshake in a connected state.
+
+Prior to calling DTLSv1_listen() user code must ensure that cookie generation
+and verification callbacks have been set up using
+SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
+respectively.
+
+Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
+ClientHellos it is unable to process fragmented messages (since this would
+require the allocation of state). An implication of this is that DTLSv1_listen()
+B<only> supports ClientHellos that fit inside a single datagram.
+
+=head1 RETURN VALUES
+
+From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance
+the B<peer> value will be filled in and the B<ssl> object set up ready to
+continue the handshake.
+
+A return value of 0 indicates a non-fatal error. This could (for
+example) be because of non-blocking IO, or some invalid message having been
+received from a peer. Errors may be placed on the OpenSSL error queue with
+further information if appropriate. Typically user code is expected to retry the
+call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the
+error queue will be cleared in the subsequent call.
+
+A return value of <0 indicates a fatal error. This could (for example) be
+because of a failure to allocate sufficient memory for the operation.
+
+Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes
+<= 0 (in typical implementations user code treats all errors as non-fatal),
+whilst return codes >0 indicate success.
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_accept(3)>,
+L<ssl(3)>, L<bio(3)>
+
+=head1 HISTORY
+
+DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer"
+also changed in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ECDSA_SIG_get0, ECDSA_SIG_set0,
+ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size,
+ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup,
+ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic curve digital signature
+algorithm (ECDSA) functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ecdsa.h>
+
+ ECDSA_SIG *ECDSA_SIG_new(void);
+ void ECDSA_SIG_free(ECDSA_SIG *sig);
+ void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);
+ int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
+ int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
+ ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len);
+ int ECDSA_size(const EC_KEY *eckey);
+
+ int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
+ unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
+ ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
+ EC_KEY *eckey);
+
+ int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,
+ const unsigned char *sig, int siglen, EC_KEY *eckey);
+ int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
+ const ECDSA_SIG *sig, EC_KEY* eckey);
+
+ ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
+ const BIGNUM *kinv, const BIGNUM *rp,
+ EC_KEY *eckey);
+ int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);
+ int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
+ unsigned char *sig, unsigned int *siglen,
+ const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
+
+=head1 DESCRIPTION
+
+Note: these functions provide a low level interface to ECDSA. Most
+applications should use the higher level B<EVP> interface such as
+L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)> instead.
+
+B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the
+B<r> and B<s> value of an ECDSA signature (see X9.62 or FIPS 186-2).
+
+ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure. Note: before
+OpenSSL 1.1.0 the: the B<r> and B<s> components were initialised.
+
+ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>.
+
+ECDSA_SIG_get0() returns internal pointers the B<r> and B<s> values contained
+in B<sig>.
+
+The B<r> and B<s> values can be set by calling ECDSA_SIG_set0() and passing the
+new values for B<r> and B<s> as parameters to the function. Calling this
+function transfers the memory management of the values to the ECDSA_SIG object,
+and therefore the values that have been passed in should not be freed directly
+after this function has been called.
+
+i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B<sig> and
+writes the encoded signature to B<*pp> (note: if B<pp> is NULL i2d_ECDSA_SIG()
+returns the expected length in bytes of the DER encoded signature).
+i2d_ECDSA_SIG() returns the length of the DER encoded signature (or 0 on
+error).
+
+d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the decoded
+signature in a newly allocated B<ECDSA_SIG> structure. B<*sig> points to the
+buffer containing the DER encoded signature of size B<len>.
+
+ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
+created with the private EC key B<eckey>.
+
+ECDSA_sign() computes a digital signature of the B<dgstlen> bytes hash value
+B<dgst> using the private EC key B<eckey>. The DER encoded signatures is
+stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> must
+point to ECDSA_size(eckey) bytes of memory. The parameter B<type> is currently
+ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B<kinv>
+and B<rp> set to NULL.
+
+ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned
+as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign()
+is a wrapper function for ECDSA_do_sign_ex() with B<kinv> and B<rp> set to
+NULL.
+
+ECDSA_verify() verifies that the signature in B<sig> of size B<siglen> is a
+valid ECDSA signature of the hash value B<dgst> of size B<dgstlen> using the
+public key B<eckey>. The parameter B<type> is ignored.
+
+ECDSA_do_verify() is similar to ECDSA_verify() except the signature is
+presented in the form of a pointer to an B<ECDSA_SIG> structure.
+
+The remaining functions utilise the internal B<kinv> and B<r> values used
+during signature computation. Most applications will never need to call these
+and some external ECDSA ENGINE implementations may not support them at all if
+either B<kinv> or B<r> is not B<NULL>.
+
+ECDSA_sign_setup() may be used to precompute parts of the signing operation.
+B<eckey> is the private EC key and B<ctx> is a pointer to B<BN_CTX> structure
+(or NULL). The precomputed values or returned in B<kinv> and B<rp> and can be
+used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().
+
+ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes hash value
+B<dgst> using the private EC key B<eckey> and the optional pre-computed values
+B<kinv> and B<rp>. The DER encoded signatures is stored in B<sig> and it's
+length is returned in B<sig_len>. Note: B<sig> must point to ECDSA_size(eckey)
+bytes of memory. The parameter B<type> is ignored.
+
+ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is
+returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error).
+
+=head1 RETURN VALUES
+
+ECDSA_SIG_set0() returns 1 on success or 0 on failure.
+
+ECDSA_size() returns the maximum length signature or 0 on error.
+
+ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful
+or 0 on error.
+
+ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated
+B<ECDSA_SIG> structure or NULL on error.
+
+ECDSA_verify() and ECDSA_do_verify() return 1 for a valid
+signature, 0 for an invalid signature and -1 on error.
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 EXAMPLES
+
+Creating an ECDSA signature of a given SHA-256 hash value using the
+named curve prime256v1 (aka P-256).
+
+First step: create an EC_KEY object (note: this part is B<not> ECDSA
+specific)
+
+ int ret;
+ ECDSA_SIG *sig;
+ EC_KEY *eckey;
+ eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
+ if (eckey == NULL) {
+ /* error */
+ }
+ if (EC_KEY_generate_key(eckey) == 0) {
+ /* error */
+ }
+
+Second step: compute the ECDSA signature of a SHA-256 hash value
+using ECDSA_do_sign():
+
+ sig = ECDSA_do_sign(digest, 32, eckey);
+ if (sig == NULL) {
+ /* error */
+ }
+
+or using ECDSA_sign():
+
+ unsigned char *buffer, *pp;
+ int buf_len;
+ buf_len = ECDSA_size(eckey);
+ buffer = OPENSSL_malloc(buf_len);
+ pp = buffer;
+ if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) {
+ /* error */
+ }
+
+Third step: verify the created ECDSA signature using ECDSA_do_verify():
+
+ ret = ECDSA_do_verify(digest, 32, sig, eckey);
+
+or using ECDSA_verify():
+
+ ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);
+
+and finally evaluate the return value:
+
+ if (ret == 1) {
+ /* signature ok */
+ } else if (ret == 0) {
+ /* incorrect signature */
+ } else {
+ /* error */
+ }
+
+=head1 CONFORMING TO
+
+ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
+(Digital Signature Standard, DSS)
+
+=head1 SEE ALSO
+
+L<dsa(3)>,
+L<EVP_DigestSignInit(3)>,
+L<EVP_DigestVerifyInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and
+encoding ASN1 representations of elliptic curve entities
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off);
+ int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off);
+
+=head1 DESCRIPTION
+
+The ECPKParameters represent the public parameters for an
+B<EC_GROUP> structure, which represents a curve.
+
+The ECPKParameters_print() and ECPKParameters_print_fp() functions print
+a human-readable output of the public parameters of the EC_GROUP to B<bp>
+or B<fp>. The output lines are indented by B<off> spaces.
+
+=head1 RETURN VALUES
+
+ECPKParameters_print() and ECPKParameters_print_fp()
+return 1 for success and 0 if an error occurs.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
+L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
+L<EC_GFp_simple_method(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining EC_METHOD objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ const EC_METHOD *EC_GFp_simple_method(void);
+ const EC_METHOD *EC_GFp_mont_method(void);
+ const EC_METHOD *EC_GFp_nist_method(void);
+ const EC_METHOD *EC_GFp_nistp224_method(void);
+ const EC_METHOD *EC_GFp_nistp256_method(void);
+ const EC_METHOD *EC_GFp_nistp521_method(void);
+
+ const EC_METHOD *EC_GF2m_simple_method(void);
+
+ int EC_METHOD_get_field_type(const EC_METHOD *meth);
+
+=head1 DESCRIPTION
+
+The Elliptic Curve library provides a number of different implementations through a single common interface.
+When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)>) an
+implementation method must be provided. The functions described here all return a const pointer to an
+B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation
+type for the form of curve selected is used.
+
+For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method.
+
+For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All
+other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the
+use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)>). EC_GFp_nist_method
+offers an implementation optimised for use with NIST recommended curves (NIST curves are available through
+EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)>).
+
+The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit
+optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these
+implementations are not available on all platforms.
+
+EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either
+F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is
+F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the
+obj_mac.h header file.
+
+=head1 RETURN VALUES
+
+All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure.
+
+EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
+L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
+L<d2i_ECPKParameters(3)>,
+L<BN_mod_mul_montgomery(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor,
+EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator,
+EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor,
+EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag,
+EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form,
+EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed,
+EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree,
+EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp,
+EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis,
+EC_GROUP_get_pentanomial_basis
+- Functions for manipulating EC_GROUP objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
+ EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
+
+ const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
+
+ int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor);
+ const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
+
+ int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);
+ const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);
+ int EC_GROUP_order_bits(const EC_GROUP *group);
+ int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);
+ const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group);
+
+ void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
+ int EC_GROUP_get_curve_name(const EC_GROUP *group);
+
+ void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);
+ int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
+
+ void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
+ point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *);
+
+ unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x);
+ size_t EC_GROUP_get_seed_len(const EC_GROUP *);
+ size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len);
+
+ int EC_GROUP_get_degree(const EC_GROUP *group);
+
+ int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
+
+ int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
+
+ int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);
+
+ int EC_GROUP_get_basis_type(const EC_GROUP *);
+ int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k);
+ int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
+ unsigned int *k2, unsigned int *k3);
+
+=head1 DESCRIPTION
+
+EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
+
+EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created
+EC_GROUP object.
+
+EC_GROUP_method_of obtains the EC_METHOD of B<group>.
+
+EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These
+parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
+curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
+n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve.
+
+EC_GROUP_get0_generator returns the generator for the identified B<group>.
+
+The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters
+with the respective order and cofactors for the B<group>.
+
+The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
+(see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
+will return 0.
+
+The asn1_flag value is used to determine whether the curve encoding uses
+explicit parameters or a named curve using an ASN1 OID: many applications only
+support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the
+named curve form is used and the parameters must have a corresponding
+named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the
+parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and
+EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve.
+Note: B<OPENSSL_EC_EXPLICIT_CURVE> was first added to OpenSSL 1.1.0, for
+previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL
+1.1.0 the default form was to use explicit parameters (meaning that
+applications would have to explicitly set the named curve form) in OpenSSL
+1.1.0 and later the named curve form is the default.
+
+The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA).
+point_conversion_form_t is an enum defined as follows:
+
+ typedef enum {
+ /** the point is encoded as z||x, where the octet z specifies
+ * which solution of the quadratic equation y is */
+ POINT_CONVERSION_COMPRESSED = 2,
+ /** the point is encoded as z||x||y, where z is the octet 0x04 */
+ POINT_CONVERSION_UNCOMPRESSED = 4,
+ /** the point is encoded as z||x||y, where the octet z specifies
+ * which solution of the quadratic equation y is */
+ POINT_CONVERSION_HYBRID = 6
+ } point_conversion_form_t;
+
+For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by
+the octets for x, followed by the octets for y.
+
+For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For
+POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of
+the two possible solutions for y has been used, followed by the octets for x.
+
+For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
+possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
+
+The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form
+for the curve respectively.
+
+ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages
+in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it.
+If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library
+does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block
+containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the
+builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
+EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
+this seed value, although it will be preserved in any ASN1 based communications.
+
+EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
+the value m.
+
+The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid.
+For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
+simply b. In either case for the curve to be valid the discriminant must be non zero.
+
+The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include
+verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
+the correct order.
+
+EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
+
+The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
+defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial
+function f(x). This function is either a trinomial of the form:
+
+f(x) = x^m + x^k + 1 with m > k >= 1
+
+or a pentanomial of the form:
+
+f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
+
+The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
+function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
+the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
+B<k2> and B<k3> respectively.
+
+=head1 RETURN VALUES
+
+The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check,
+EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis.
+
+EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error.
+
+EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error.
+
+EC_GROUP_get0_generator returns the generator for the given curve or NULL on error.
+
+EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form
+and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
+specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
+
+EC_GROUP_get0_order() returns an internal pointer to the group order.
+EC_GROUP_get_order_bits() returns the number of bits in the group order.
+EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor.
+
+EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
+specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
+
+EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
+0, the return value will be 1. On error 0 is returned.
+
+EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
+
+EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
+trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>,
+L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
+L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters,
+EC_GROUP_new, EC_GROUP_new_from_ecparameters,
+EC_GROUP_new_from_ecpkparameters,
+EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp,
+EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp,
+EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m,
+EC_get_builtin_curves - Functions for creating and destroying EC_GROUP
+objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
+ EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
+ EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
+ void EC_GROUP_free(EC_GROUP *group);
+ void EC_GROUP_clear_free(EC_GROUP *group);
+
+ EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
+ EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
+ EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
+
+ int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
+ int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+ int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
+ int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+
+ ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params)
+ ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params)
+
+ size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
+
+=head1 DESCRIPTION
+
+Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
+prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised
+elliptic curve equation as follows:
+
+y^2 mod p = x^3 +ax + b mod p
+
+The second form is those defined over a binary field F2^m where the elements of the field are integers of length at
+most m bits. For this form the elliptic curve equation is modified to:
+
+y^2 + xy = x^3 + ax^2 + b (where b != 0)
+
+Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
+use a trinomial or a pentanomial for this parameter.
+
+A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
+L<EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or
+EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively.
+EC_GROUP_new_from_ecparameters() will create a group from the
+specified B<params> and
+EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>.
+
+EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>.
+EC_group_get_curve_GFp obtains the previously set curve parameters.
+
+EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents
+the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three
+or five bits set dependent on whether the polynomial is a trinomial or a pentanomial.
+EC_group_get_curve_GF2m obtains the previously set curve parameters.
+
+The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the
+appropriate EC_group_set_curve function. An appropriate default implementation method will be used.
+
+Whilst the library can be used to create any curve using the functions described above, there are also a number of
+predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
+EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
+will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
+curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
+provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
+not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
+The EC_builtin_curve structure is defined as follows:
+
+ typedef struct {
+ int nid;
+ const char *comment;
+ } EC_builtin_curve;
+
+Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
+
+In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to
+be constructed.
+
+EC_GROUP_free frees the memory associated with the EC_GROUP.
+If B<group> is NULL nothing is done.
+
+EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
+If B<group> is NULL nothing is done.
+
+=head1 RETURN VALUES
+
+All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
+
+EC_get_builtin_curves returns the number of builtin curves that are available.
+
+EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_copy(3)>,
+L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
+L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EC_KEY_get_enc_flags, EC_KEY_set_enc_flags
+- Get and set flags for encoding EC_KEY structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ unsigned int EC_KEY_get_enc_flags(const EC_KEY *key);
+ void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);
+
+=head1 DESCRIPTION
+
+The format of the external representation of the public key written by
+i2d_ECPrivateKey() (such as whether it is stored in a compressed form or not) is
+described by the point_conversion_form. See L<EC_GROUP_copy(3)>
+for a description of point_conversion_form.
+
+When reading a private key encoded without an associated public key (e.g. if
+EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey() generates
+the missing public key automatically. Private keys encoded without parameters
+(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using
+d2i_ECPrivateKey().
+
+The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the
+value of the encoding flags for the B<key>. There are two encoding flags
+currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags
+define the behaviour of how the B<key> is converted into ASN1 in a call to
+i2d_ECPrivateKey(). If EC_PKEY_NO_PARAMETERS is set then the public parameters for
+the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is
+set then the public key is not encoded along with the private key.
+
+=head1 RETURN VALUES
+
+EC_KEY_get_enc_flags() returns the value of the current encoding flags for the
+EC_KEY.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>,
+L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>,
+L<EC_POINT_add(3)>,
+L<EC_GFp_simple_method(3)>,
+L<d2i_ECPKParameters(3)>,
+L<d2i_ECPrivateKey(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EC_KEY_get_method, EC_KEY_set_method,
+EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags,
+EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref,
+EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key,
+EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key,
+EC_KEY_get_conv_form,
+EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult,
+EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates,
+EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct,
+EC_KEY_priv2buf - Functions for creating, destroying and manipulating
+EC_KEY objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ EC_KEY *EC_KEY_new(void);
+ int EC_KEY_get_flags(const EC_KEY *key);
+ void EC_KEY_set_flags(EC_KEY *key, int flags);
+ void EC_KEY_clear_flags(EC_KEY *key, int flags);
+ EC_KEY *EC_KEY_new_by_curve_name(int nid);
+ void EC_KEY_free(EC_KEY *key);
+ EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
+ EC_KEY *EC_KEY_dup(const EC_KEY *src);
+ int EC_KEY_up_ref(EC_KEY *key);
+ const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
+ int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
+ const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);
+ int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv);
+ const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);
+ int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);
+ point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
+ void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);
+ void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);
+ int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
+ int EC_KEY_generate_key(EC_KEY *key);
+ int EC_KEY_check_key(const EC_KEY *key);
+ int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key,
+ BIGNUM *x, BIGNUM *y);
+ const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key);
+ int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth);
+
+ int EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len,
+ BN_CTX *ctx);
+ size_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form,
+ unsigned char **pbuf, BN_CTX *ctx);
+
+ int EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len);
+ size_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len);
+
+ size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf);
+
+=head1 DESCRIPTION
+
+An EC_KEY represents a public key and, optionally, the associated private
+key. A new EC_KEY with no associated curve can be constructed by calling
+EC_KEY_new(). The reference count for the newly created EC_KEY is initially
+set to 1. A curve can be associated with the EC_KEY by calling
+EC_KEY_set_group().
+
+Alternatively a new EC_KEY can be constructed by calling
+EC_KEY_new_by_curve_name() and supplying the nid of the associated curve. See
+L<EC_GROUP_new(3)> for a description of curve names. This function simply
+wraps calls to EC_KEY_new() and EC_GROUP_new_by_curve_name().
+
+Calling EC_KEY_free() decrements the reference count for the EC_KEY object,
+and if it has dropped to zero then frees the memory associated with it. If
+B<key> is NULL nothing is done.
+
+EC_KEY_copy() copies the contents of the EC_KEY in B<src> into B<dest>.
+
+EC_KEY_dup() creates a new EC_KEY object and copies B<ec_key> into it.
+
+EC_KEY_up_ref() increments the reference count associated with the EC_KEY
+object.
+
+EC_KEY_generate_key() generates a new public and private key for the supplied
+B<eckey> object. B<eckey> must have an EC_GROUP object associated with it
+before calling this function. The private key is a random integer (0 < priv_key
+< order, where I<order> is the order of the EC_GROUP object). The public key is
+an EC_POINT on the curve calculated by multiplying the generator for the
+curve by the private key.
+
+EC_KEY_check_key() performs various sanity checks on the EC_KEY object to
+confirm that it is valid.
+
+EC_KEY_set_public_key_affine_coordinates() sets the public key for B<key> based
+on its affine co-ordinates; i.e., it constructs an EC_POINT object based on
+the supplied B<x> and B<y> values and sets the public key to be this
+EC_POINT. It also performs certain sanity checks on the key to confirm
+that it is valid.
+
+The functions EC_KEY_get0_group(), EC_KEY_set_group(),
+EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(),
+and EC_KEY_set_public_key() get and set the EC_GROUP object, the private key,
+and the EC_POINT public key for the B<key> respectively.
+
+The functions EC_KEY_get_conv_form() and EC_KEY_set_conv_form() get and set the
+point_conversion_form for the B<key>. For a description of
+point_conversion_forms please see L<EC_POINT_new(3)>.
+
+EC_KEY_set_flags() sets the flags in the B<flags> parameter on the EC_KEY
+object. Any flags that are already set are left set. The flags currently
+defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In
+addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH.
+EC_KEY_get_flags() returns the current flags that are set for this EC_KEY.
+EC_KEY_clear_flags() clears the flags indicated by the B<flags> parameter; all
+other flags are left in their existing state.
+
+EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object
+(if set). Refer to L<EC_GROUP_copy(3)> for further information on the
+asn1_flag.
+
+EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator
+for faster point multiplication. See also L<EC_POINT_add(3)>.
+
+EC_KEY_oct2key() and EC_KEY_key2buf() are identical to the functions
+EC_POINT_oct2point() and EC_KEY_point2buf() except they use the public key
+EC_POINT in B<eckey>.
+
+EC_KEY_oct2priv() and EC_KEY_priv2oct() convert between the private key
+component of B<eckey> and octet form. The octet form consists of the content
+octets of the B<privateKey> OCTET STRING in an B<ECPrivateKey> ASN.1 structure.
+
+The function EC_KEY_priv2oct() must be supplied with a buffer long enough to
+store the octet form. The return value provides the number of octets stored.
+Calling the function with a NULL buffer will not perform the conversion but
+will just return the required buffer length.
+
+The function EC_KEY_priv2buf() allocates a buffer of suitable length and writes
+an EC_KEY to it in octet format. The allocated buffer is written to B<*pbuf>
+and its length is returned. The caller must free up the allocated buffer with a
+call to OPENSSL_free(). Since the allocated buffer value is written to B<*pbuf>
+the B<pbuf> parameter B<MUST NOT> be B<NULL>.
+
+EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer.
+
+=head1 RETURN VALUES
+
+EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to
+the newly created EC_KEY object, or NULL on error.
+
+EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an
+integer.
+
+EC_KEY_copy() returns a pointer to the destination key, or NULL on error.
+
+EC_KEY_up_ref(), EC_KEY_set_group(), EC_KEY_set_private_key(),
+EC_KEY_set_public_key(), EC_KEY_precompute_mult(), EC_KEY_generate_key(),
+EC_KEY_check_key(), EC_KEY_set_public_key_affine_coordinates(),
+EC_KEY_oct2key() and EC_KEY_oct2priv() return 1 on success or 0 on error.
+
+EC_KEY_get0_group() returns the EC_GROUP associated with the EC_KEY.
+
+EC_KEY_get0_private_key() returns the private key associated with the EC_KEY.
+
+EC_KEY_get_conv_form() return the point_conversion_form for the EC_KEY.
+
+EC_KEY_key2buf(), EC_KEY_priv2oct() and EC_KEY_priv2buf() return the length
+of the buffer or 0 on error.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>,
+L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>,
+L<EC_POINT_add(3)>,
+L<EC_GFp_simple_method(3)>,
+L<d2i_ECPKParameters(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on EC_POINT objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
+ int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);
+ int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);
+ int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
+ int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
+ int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
+ int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
+ int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx);
+ int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
+ int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
+ int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
+ int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
+
+
+=head1 DESCRIPTION
+
+EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the
+result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>.
+
+EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>.
+
+The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.
+
+EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.
+
+EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.
+
+The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
+co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
+forced.
+
+EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>.
+
+EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value
+B<n> may be NULL.
+
+The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
+EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information
+about the generator.
+
+
+=head1 RETURN VALUES
+
+The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine,
+EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.
+
+EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.
+
+EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.
+
+EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.
+
+EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
+L<EC_POINT_new(3)>, L<EC_KEY_new(3)>,
+L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf,
+EC_POINT_new, EC_POINT_free, EC_POINT_clear_free,
+EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of,
+EC_POINT_set_to_infinity,
+EC_POINT_get_Jprojective_coordinates_GFp,
+EC_POINT_set_affine_coordinates_GFp,
+EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp,
+EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m,
+EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct,
+EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex,
+EC_POINT_hex2point
+- Functions for creating, destroying and manipulating EC_POINT objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ec.h>
+
+ EC_POINT *EC_POINT_new(const EC_GROUP *group);
+ void EC_POINT_free(EC_POINT *point);
+ void EC_POINT_clear_free(EC_POINT *point);
+ int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
+ EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
+ const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
+ int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
+ int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,
+ EC_POINT *p,
+ const BIGNUM *x, const BIGNUM *y,
+ const BIGNUM *z, BN_CTX *ctx);
+ int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
+ const EC_POINT *p,
+ BIGNUM *x, BIGNUM *y, BIGNUM *z,
+ BN_CTX *ctx);
+ int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
+ const BIGNUM *x, const BIGNUM *y,
+ BN_CTX *ctx);
+ int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
+ const EC_POINT *p,
+ BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
+ int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group,
+ EC_POINT *p,
+ const BIGNUM *x, int y_bit,
+ BN_CTX *ctx);
+ int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
+ const BIGNUM *x, const BIGNUM *y,
+ BN_CTX *ctx);
+ int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
+ const EC_POINT *p,
+ BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
+ int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group,
+ EC_POINT *p,
+ const BIGNUM *x, int y_bit,
+ BN_CTX *ctx);
+ size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
+ point_conversion_form_t form,
+ unsigned char *buf, size_t len, BN_CTX *ctx);
+ size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point,
+ point_conversion_form_t form,
+ unsigned char **pbuf, BN_CTX *ctx);
+ int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
+ const unsigned char *buf, size_t len, BN_CTX *ctx);
+ BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p,
+ point_conversion_form_t form, BIGNUM *bn,
+ BN_CTX *ctx);
+ EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn,
+ EC_POINT *p, BN_CTX *ctx);
+ char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p,
+ point_conversion_form_t form, BN_CTX *ctx);
+ EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex,
+ EC_POINT *p, BN_CTX *ctx);
+
+
+=head1 DESCRIPTION
+
+An B<EC_POINT> structure represents a point on a curve. A new point is
+constructed by calling the function EC_POINT_new() and providing the
+B<group> object that the point relates to.
+
+EC_POINT_free() frees the memory associated with the B<EC_POINT>.
+if B<point> is NULL nothing is done.
+
+EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and
+then frees its memory. If B<point> is NULL nothing is done.
+
+EC_POINT_copy() copies the point B<src> into B<dst>. Both B<src> and B<dst>
+must use the same B<EC_METHOD>.
+
+EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from
+B<src> to the newly created B<EC_POINT> object.
+
+EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>.
+
+A valid point on a curve is the special point at infinity. A point is set to
+be at infinity by calling EC_POINT_set_to_infinity().
+
+The affine co-ordinates for a point describe a point in terms of its x and y
+position. The functions EC_POINT_set_affine_coordinates_GFp() and
+EC_POINT_set_affine_coordinates_GF2m() set the B<x> and B<y> co-ordinates for
+the point B<p> defined over the curve given in B<group>.
+
+As well as the affine co-ordinates, a point can alternatively be described in
+terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian
+projective co-ordinates are expressed as three values x, y and z. Working in
+this co-ordinate system provides more efficient point multiplication
+operations. A mapping exists between Jacobian projective co-ordinates and
+affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written
+as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian
+projective from affine co-ordinates is simple. The co-ordinate (x, y) is mapped
+to (x, y, 1). To set or get the projective co-ordinates use
+EC_POINT_set_Jprojective_coordinates_GFp() and
+EC_POINT_get_Jprojective_coordinates_GFp() respectively.
+
+Points can also be described in terms of their compressed co-ordinates. For a
+point (x, y), for any given value for x such that the point is on the curve
+there will only ever be two possible values for y. Therefore a point can be set
+using the EC_POINT_set_compressed_coordinates_GFp() and
+EC_POINT_set_compressed_coordinates_GF2m() functions where B<x> is the x
+co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two
+possible values for y should be used.
+
+In addition B<EC_POINT> can be converted to and from various external
+representations. The octet form is the binary encoding of the B<ECPoint>
+structure (as defined in RFC5480 and used in certificates and TLS records):
+only the content octets are present, the B<OCTET STRING> tag and length are
+not included. B<BIGNUM> form is the octet form interpreted as a big endian
+integer converted to a B<BIGNUM> structure. Hexadecimal form is the octet
+form converted to a NULL terminated character string where each character
+is one of the printable values 0-9 or A-F (or a-f).
+
+The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(),
+EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from
+and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively.
+
+The function EC_POINT_point2oct() must be supplied with a buffer long enough to
+store the octet form. The return value provides the number of octets stored.
+Calling the function with a NULL buffer will not perform the conversion but
+will still return the required buffer length.
+
+The function EC_POINT_point2buf() allocates a buffer of suitable length and
+writes an EC_POINT to it in octet format. The allocated buffer is written to
+B<*pbuf> and its length is returned. The caller must free up the allocated
+buffer with a call to OPENSSL_free(). Since the allocated buffer value is
+written to B<*pbuf> the B<pbuf> parameter B<MUST NOT> be B<NULL>.
+
+The function EC_POINT_point2hex() will allocate sufficient memory to store the
+hexadecimal string. It is the caller's responsibility to free this memory with
+a subsequent call to OPENSSL_free().
+
+=head1 RETURN VALUES
+
+EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL
+on error.
+
+The following functions return 1 on success or 0 on error: EC_POINT_copy(),
+EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(),
+EC_POINT_get_Jprojective_coordinates_GFp(),
+EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(),
+EC_POINT_set_compressed_coordinates_GFp(),
+EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(),
+EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point().
+
+EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.
+
+EC_POINT_point2oct() and EC_point2buf() return the length of the required
+buffer or 0 on error.
+
+EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on
+error.
+
+EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on
+error.
+
+EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error.
+
+EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on
+error.
+
+=head1 SEE ALSO
+
+L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
+L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
+L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ENGINE_get_DH, ENGINE_get_DSA, ENGINE_get_ECDH, ENGINE_get_ECDSA,
+ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH,
+ENGINE_get_default_DSA, ENGINE_get_default_ECDH,
+ENGINE_get_default_ECDSA, ENGINE_get_default_RAND,
+ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first,
+ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new,
+ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests,
+ENGINE_get_destroy_function, ENGINE_get_finish_function,
+ENGINE_get_init_function, ENGINE_get_load_privkey_function,
+ENGINE_get_load_pubkey_function, ENGINE_load_private_key,
+ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id,
+ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher,
+ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable,
+ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string,
+ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init,
+ENGINE_register_DH, ENGINE_register_DSA, ENGINE_register_ECDH,
+ENGINE_register_ECDSA, ENGINE_register_RAND, ENGINE_register_RSA,
+ENGINE_register_all_complete, ENGINE_register_ciphers,
+ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove,
+ENGINE_set_DH, ENGINE_set_DSA, ENGINE_set_ECDH, ENGINE_set_ECDSA,
+ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers,
+ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default,
+ENGINE_set_default_DH, ENGINE_set_default_DSA, ENGINE_set_default_ECDH,
+ENGINE_set_default_ECDSA, ENGINE_set_default_RAND, ENGINE_set_default_RSA,
+ENGINE_set_default_ciphers, ENGINE_set_default_digests,
+ENGINE_set_default_string, ENGINE_set_destroy_function,
+ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags,
+ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function,
+ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref,
+ENGINE_get_table_flags, ENGINE_cleanup,
+ENGINE_load_builtin_engines, ENGINE_register_all_DH,
+ENGINE_register_all_DSA, ENGINE_register_all_ECDH,
+ENGINE_register_all_ECDSA, ENGINE_register_all_RAND,
+ENGINE_register_all_RSA, ENGINE_register_all_ciphers,
+ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH,
+ENGINE_unregister_DSA, ENGINE_unregister_ECDH, ENGINE_unregister_ECDSA,
+ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers,
+ENGINE_unregister_digests
+- ENGINE cryptographic module support
+
+=head1 SYNOPSIS
+
+ #include <openssl/engine.h>
+
+ ENGINE *ENGINE_get_first(void);
+ ENGINE *ENGINE_get_last(void);
+ ENGINE *ENGINE_get_next(ENGINE *e);
+ ENGINE *ENGINE_get_prev(ENGINE *e);
+
+ int ENGINE_add(ENGINE *e);
+ int ENGINE_remove(ENGINE *e);
+
+ ENGINE *ENGINE_by_id(const char *id);
+
+ int ENGINE_init(ENGINE *e);
+ int ENGINE_finish(ENGINE *e);
+
+ void ENGINE_load_builtin_engines(void);
+
+ ENGINE *ENGINE_get_default_RSA(void);
+ ENGINE *ENGINE_get_default_DSA(void);
+ ENGINE *ENGINE_get_default_ECDH(void);
+ ENGINE *ENGINE_get_default_ECDSA(void);
+ ENGINE *ENGINE_get_default_DH(void);
+ ENGINE *ENGINE_get_default_RAND(void);
+ ENGINE *ENGINE_get_cipher_engine(int nid);
+ ENGINE *ENGINE_get_digest_engine(int nid);
+
+ int ENGINE_set_default_RSA(ENGINE *e);
+ int ENGINE_set_default_DSA(ENGINE *e);
+ int ENGINE_set_default_ECDH(ENGINE *e);
+ int ENGINE_set_default_ECDSA(ENGINE *e);
+ int ENGINE_set_default_DH(ENGINE *e);
+ int ENGINE_set_default_RAND(ENGINE *e);
+ int ENGINE_set_default_ciphers(ENGINE *e);
+ int ENGINE_set_default_digests(ENGINE *e);
+ int ENGINE_set_default_string(ENGINE *e, const char *list);
+
+ int ENGINE_set_default(ENGINE *e, unsigned int flags);
+
+ unsigned int ENGINE_get_table_flags(void);
+ void ENGINE_set_table_flags(unsigned int flags);
+
+ int ENGINE_register_RSA(ENGINE *e);
+ void ENGINE_unregister_RSA(ENGINE *e);
+ void ENGINE_register_all_RSA(void);
+ int ENGINE_register_DSA(ENGINE *e);
+ void ENGINE_unregister_DSA(ENGINE *e);
+ void ENGINE_register_all_DSA(void);
+ int ENGINE_register_ECDH(ENGINE *e);
+ void ENGINE_unregister_ECDH(ENGINE *e);
+ void ENGINE_register_all_ECDH(void);
+ int ENGINE_register_ECDSA(ENGINE *e);
+ void ENGINE_unregister_ECDSA(ENGINE *e);
+ void ENGINE_register_all_ECDSA(void);
+ int ENGINE_register_DH(ENGINE *e);
+ void ENGINE_unregister_DH(ENGINE *e);
+ void ENGINE_register_all_DH(void);
+ int ENGINE_register_RAND(ENGINE *e);
+ void ENGINE_unregister_RAND(ENGINE *e);
+ void ENGINE_register_all_RAND(void);
+ int ENGINE_register_ciphers(ENGINE *e);
+ void ENGINE_unregister_ciphers(ENGINE *e);
+ void ENGINE_register_all_ciphers(void);
+ int ENGINE_register_digests(ENGINE *e);
+ void ENGINE_unregister_digests(ENGINE *e);
+ void ENGINE_register_all_digests(void);
+ int ENGINE_register_complete(ENGINE *e);
+ int ENGINE_register_all_complete(void);
+
+ int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
+ int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
+ int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
+ long i, void *p, void (*f)(void), int cmd_optional);
+ int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
+ int cmd_optional);
+
+ ENGINE *ENGINE_new(void);
+ int ENGINE_free(ENGINE *e);
+ int ENGINE_up_ref(ENGINE *e);
+
+ int ENGINE_set_id(ENGINE *e, const char *id);
+ int ENGINE_set_name(ENGINE *e, const char *name);
+ int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
+ int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
+ int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth);
+ int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth);
+ int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
+ int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
+ int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
+ int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
+ int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
+ int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
+ int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
+ int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
+ int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
+ int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
+ int ENGINE_set_flags(ENGINE *e, int flags);
+ int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
+
+ const char *ENGINE_get_id(const ENGINE *e);
+ const char *ENGINE_get_name(const ENGINE *e);
+ const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
+ const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
+ const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e);
+ const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e);
+ const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
+ const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
+ ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
+ ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
+ ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
+ ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
+ ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
+ const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
+ const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
+ int ENGINE_get_flags(const ENGINE *e);
+ const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
+
+ EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
+ UI_METHOD *ui_method, void *callback_data);
+ EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
+ UI_METHOD *ui_method, void *callback_data);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void ENGINE_cleanup(void)
+ #endif
+
+=head1 DESCRIPTION
+
+These functions create, manipulate, and use cryptographic modules in the
+form of B<ENGINE> objects. These objects act as containers for
+implementations of cryptographic algorithms, and support a
+reference-counted mechanism to allow them to be dynamically loaded in and
+out of the running application.
+
+The cryptographic functionality that can be provided by an B<ENGINE>
+implementation includes the following abstractions;
+
+ RSA_METHOD - for providing alternative RSA implementations
+ DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD,
+ - similarly for other OpenSSL APIs
+ EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid')
+ EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid')
+ key-loading - loading public and/or private EVP_PKEY keys
+
+=head2 Reference counting and handles
+
+Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be
+treated as handles - ie. not only as pointers, but also as references to
+the underlying ENGINE object. Ie. one should obtain a new reference when
+making copies of an ENGINE pointer if the copies will be used (and
+released) independently.
+
+ENGINE objects have two levels of reference-counting to match the way in
+which the objects are used. At the most basic level, each ENGINE pointer is
+inherently a B<structural> reference - a structural reference is required
+to use the pointer value at all, as this kind of reference is a guarantee
+that the structure can not be deallocated until the reference is released.
+
+However, a structural reference provides no guarantee that the ENGINE is
+initialised and able to use any of its cryptographic
+implementations. Indeed it's quite possible that most ENGINEs will not
+initialise at all in typical environments, as ENGINEs are typically used to
+support specialised hardware. To use an ENGINE's functionality, you need a
+B<functional> reference. This kind of reference can be considered a
+specialised form of structural reference, because each functional reference
+implicitly contains a structural reference as well - however to avoid
+difficult-to-find programming bugs, it is recommended to treat the two
+kinds of reference independently. If you have a functional reference to an
+ENGINE, you have a guarantee that the ENGINE has been initialised and
+is ready to perform cryptographic operations, and will remain initialised
+until after you have released your reference.
+
+I<Structural references>
+
+This basic type of reference is used for instantiating new ENGINEs,
+iterating across OpenSSL's internal linked-list of loaded
+ENGINEs, reading information about an ENGINE, etc. Essentially a structural
+reference is sufficient if you only need to query or manipulate the data of
+an ENGINE implementation rather than use its functionality.
+
+The ENGINE_new() function returns a structural reference to a new (empty)
+ENGINE object. There are other ENGINE API functions that return structural
+references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(),
+ENGINE_get_next(), ENGINE_get_prev(). All structural references should be
+released by a corresponding to call to the ENGINE_free() function - the
+ENGINE object itself will only actually be cleaned up and deallocated when
+the last structural reference is released.
+
+It should also be noted that many ENGINE API function calls that accept a
+structural reference will internally obtain another reference - typically
+this happens whenever the supplied ENGINE will be needed by OpenSSL after
+the function has returned. Eg. the function to add a new ENGINE to
+OpenSSL's internal list is ENGINE_add() - if this function returns success,
+then OpenSSL will have stored a new structural reference internally so the
+caller is still responsible for freeing their own reference with
+ENGINE_free() when they are finished with it. In a similar way, some
+functions will automatically release the structural reference passed to it
+if part of the function's job is to do so. Eg. the ENGINE_get_next() and
+ENGINE_get_prev() functions are used for iterating across the internal
+ENGINE list - they will return a new structural reference to the next (or
+previous) ENGINE in the list or NULL if at the end (or beginning) of the
+list, but in either case the structural reference passed to the function is
+released on behalf of the caller.
+
+To clarify a particular function's handling of references, one should
+always consult that function's documentation "man" page, or failing that
+the openssl/engine.h header file includes some hints.
+
+I<Functional references>
+
+As mentioned, functional references exist when the cryptographic
+functionality of an ENGINE is required to be available. A functional
+reference can be obtained in one of two ways; from an existing structural
+reference to the required ENGINE, or by asking OpenSSL for the default
+operational ENGINE for a given cryptographic purpose.
+
+To obtain a functional reference from an existing structural reference,
+call the ENGINE_init() function. This returns zero if the ENGINE was not
+already operational and couldn't be successfully initialised (eg. lack of
+system drivers, no special hardware attached, etc), otherwise it will
+return non-zero to indicate that the ENGINE is now operational and will
+have allocated a new B<functional> reference to the ENGINE. All functional
+references are released by calling ENGINE_finish() (which removes the
+implicit structural reference as well).
+
+The second way to get a functional reference is by asking OpenSSL for a
+default implementation for a given task, eg. by ENGINE_get_default_RSA(),
+ENGINE_get_default_cipher_engine(), etc. These are discussed in the next
+section, though they are not usually required by application programmers as
+they are used automatically when creating and using the relevant
+algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc.
+
+=head2 Default implementations
+
+For each supported abstraction, the ENGINE code maintains an internal table
+of state to control which implementations are available for a given
+abstraction and which should be used by default. These implementations are
+registered in the tables and indexed by an 'nid' value, because
+abstractions like EVP_CIPHER and EVP_DIGEST support many distinct
+algorithms and modes, and ENGINEs can support arbitrarily many of them.
+In the case of other abstractions like RSA, DSA, etc, there is only one
+"algorithm" so all implementations implicitly register using the same 'nid'
+index.
+
+When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg.
+when calling RSA_new_method(NULL)), a "get_default" call will be made to the
+ENGINE subsystem to process the corresponding state table and return a
+functional reference to an initialised ENGINE whose implementation should be
+used. If no ENGINE should (or can) be used, it will return NULL and the caller
+will operate with a NULL ENGINE handle - this usually equates to using the
+conventional software implementation. In the latter case, OpenSSL will from
+then on behave the way it used to before the ENGINE API existed.
+
+Each state table has a flag to note whether it has processed this
+"get_default" query since the table was last modified, because to process
+this question it must iterate across all the registered ENGINEs in the
+table trying to initialise each of them in turn, in case one of them is
+operational. If it returns a functional reference to an ENGINE, it will
+also cache another reference to speed up processing future queries (without
+needing to iterate across the table). Likewise, it will cache a NULL
+response if no ENGINE was available so that future queries won't repeat the
+same iteration unless the state table changes. This behaviour can also be
+changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using
+ENGINE_set_table_flags()), no attempted initialisations will take place,
+instead the only way for the state table to return a non-NULL ENGINE to the
+"get_default" query will be if one is expressly set in the table. Eg.
+ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except
+that it also sets the state table's cached response for the "get_default"
+query. In the case of abstractions like EVP_CIPHER, where implementations are
+indexed by 'nid', these flags and cached-responses are distinct for each 'nid'
+value.
+
+=head2 Application requirements
+
+This section will explain the basic things an application programmer should
+support to make the most useful elements of the ENGINE functionality
+available to the user. The first thing to consider is whether the
+programmer wishes to make alternative ENGINE modules available to the
+application and user. OpenSSL maintains an internal linked list of
+"visible" ENGINEs from which it has to operate - at start-up, this list is
+empty and in fact if an application does not call any ENGINE API calls and
+it uses static linking against openssl, then the resulting application
+binary will not contain any alternative ENGINE code at all. So the first
+consideration is whether any/all available ENGINE implementations should be
+made visible to OpenSSL - this is controlled by calling the various "load"
+functions.
+
+Having called any of these functions, ENGINE objects would have been
+dynamically allocated and populated with these implementations and linked
+into OpenSSL's internal linked list. At this point it is important to
+mention an important API function;
+
+ void ENGINE_cleanup(void)
+
+If no ENGINE API functions are called at all in an application, then there
+are no inherent memory leaks to worry about from the ENGINE functionality.
+However, prior to OpenSSL 1.1.0 if any ENGINEs are loaded, even if they are
+never registered or used, it was necessary to use the ENGINE_cleanup() function
+to correspondingly cleanup before program exit, if the caller wishes to avoid
+memory leaks. This mechanism used an internal callback registration table
+so that any ENGINE API functionality that knows it requires cleanup can
+register its cleanup details to be called during ENGINE_cleanup(). This
+approach allowed ENGINE_cleanup() to clean up after any ENGINE functionality
+at all that your program uses, yet doesn't automatically create linker
+dependencies to all possible ENGINE functionality - only the cleanup
+callbacks required by the functionality you do use will be required by the
+linker. From OpenSSL 1.1.0 it is no longer necessary to explicitly call
+ENGINE_cleanup and this function is deprecated. Cleanup automatically takes
+place at program exit.
+
+The fact that ENGINEs are made visible to OpenSSL (and thus are linked into
+the program and loaded into memory at run-time) does not mean they are
+"registered" or called into use by OpenSSL automatically - that behaviour
+is something for the application to control. Some applications
+will want to allow the user to specify exactly which ENGINE they want used
+if any is to be used at all. Others may prefer to load all support and have
+OpenSSL automatically use at run-time any ENGINE that is able to
+successfully initialise - ie. to assume that this corresponds to
+acceleration hardware attached to the machine or some such thing. There are
+probably numerous other ways in which applications may prefer to handle
+things, so we will simply illustrate the consequences as they apply to a
+couple of simple cases and leave developers to consider these and the
+source code to openssl's builtin utilities as guides.
+
+I<Using a specific ENGINE implementation>
+
+Here we'll assume an application has been configured by its user or admin
+to want to use the "ACME" ENGINE if it is available in the version of
+OpenSSL the application was compiled with. If it is available, it should be
+used by default for all RSA, DSA, and symmetric cipher operations, otherwise
+OpenSSL should use its builtin software as per usual. The following code
+illustrates how to approach this;
+
+ ENGINE *e;
+ const char *engine_id = "ACME";
+ ENGINE_load_builtin_engines();
+ e = ENGINE_by_id(engine_id);
+ if(!e)
+ /* the engine isn't available */
+ return;
+ if(!ENGINE_init(e)) {
+ /* the engine couldn't initialise, release 'e' */
+ ENGINE_free(e);
+ return;
+ }
+ if(!ENGINE_set_default_RSA(e))
+ /* This should only happen when 'e' can't initialise, but the previous
+ * statement suggests it did. */
+ abort();
+ ENGINE_set_default_DSA(e);
+ ENGINE_set_default_ciphers(e);
+ /* Release the functional reference from ENGINE_init() */
+ ENGINE_finish(e);
+ /* Release the structural reference from ENGINE_by_id() */
+ ENGINE_free(e);
+
+I<Automatically using builtin ENGINE implementations>
+
+Here we'll assume we want to load and register all ENGINE implementations
+bundled with OpenSSL, such that for any cryptographic algorithm required by
+OpenSSL - if there is an ENGINE that implements it and can be initialised,
+it should be used. The following code illustrates how this can work;
+
+ /* Load all bundled ENGINEs into memory and make them visible */
+ ENGINE_load_builtin_engines();
+ /* Register all of them for every algorithm they collectively implement */
+ ENGINE_register_all_complete();
+
+That's all that's required. Eg. the next time OpenSSL tries to set up an
+RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to
+ENGINE_init() and if any of those succeed, that ENGINE will be set as the
+default for RSA use from then on.
+
+=head2 Advanced configuration support
+
+There is a mechanism supported by the ENGINE framework that allows each
+ENGINE implementation to define an arbitrary set of configuration
+"commands" and expose them to OpenSSL and any applications based on
+OpenSSL. This mechanism is entirely based on the use of name-value pairs
+and assumes ASCII input (no unicode or UTF for now!), so it is ideal if
+applications want to provide a transparent way for users to provide
+arbitrary configuration "directives" directly to such ENGINEs. It is also
+possible for the application to dynamically interrogate the loaded ENGINE
+implementations for the names, descriptions, and input flags of their
+available "control commands", providing a more flexible configuration
+scheme. However, if the user is expected to know which ENGINE device he/she
+is using (in the case of specialised hardware, this goes without saying)
+then applications may not need to concern themselves with discovering the
+supported control commands and simply prefer to pass settings into ENGINEs
+exactly as they are provided by the user.
+
+Before illustrating how control commands work, it is worth mentioning what
+they are typically used for. Broadly speaking there are two uses for
+control commands; the first is to provide the necessary details to the
+implementation (which may know nothing at all specific to the host system)
+so that it can be initialised for use. This could include the path to any
+driver or config files it needs to load, required network addresses,
+smart-card identifiers, passwords to initialise protected devices,
+logging information, etc etc. This class of commands typically needs to be
+passed to an ENGINE B<before> attempting to initialise it, ie. before
+calling ENGINE_init(). The other class of commands consist of settings or
+operations that tweak certain behaviour or cause certain operations to take
+place, and these commands may work either before or after ENGINE_init(), or
+in some cases both. ENGINE implementations should provide indications of
+this in the descriptions attached to builtin control commands and/or in
+external product documentation.
+
+I<Issuing control commands to an ENGINE>
+
+Let's illustrate by example; a function for which the caller supplies the
+name of the ENGINE it wishes to use, a table of string-pairs for use before
+initialisation, and another table for use after initialisation. Note that
+the string-pairs used for control commands consist of a command "name"
+followed by the command "parameter" - the parameter could be NULL in some
+cases but the name can not. This function should initialise the ENGINE
+(issuing the "pre" commands beforehand and the "post" commands afterwards)
+and set it as the default for everything except RAND and then return a
+boolean success or failure.
+
+ int generic_load_engine_fn(const char *engine_id,
+ const char **pre_cmds, int pre_num,
+ const char **post_cmds, int post_num)
+ {
+ ENGINE *e = ENGINE_by_id(engine_id);
+ if (!e) return 0;
+ while (pre_num--) {
+ if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {
+ fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
+ pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)");
+ ENGINE_free(e);
+ return 0;
+ }
+ pre_cmds += 2;
+ }
+ if (!ENGINE_init(e)) {
+ fprintf(stderr, "Failed initialisation\n");
+ ENGINE_free(e);
+ return 0;
+ }
+ /* ENGINE_init() returned a functional reference, so free the structural
+ * reference from ENGINE_by_id(). */
+ ENGINE_free(e);
+ while(post_num--) {
+ if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {
+ fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
+ post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)");
+ ENGINE_finish(e);
+ return 0;
+ }
+ post_cmds += 2;
+ }
+ ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
+ /* Success */
+ return 1;
+ }
+
+Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can
+relax the semantics of the function - if set non-zero it will only return
+failure if the ENGINE supported the given command name but failed while
+executing it, if the ENGINE doesn't support the command name it will simply
+return success without doing anything. In this case we assume the user is
+only supplying commands specific to the given ENGINE so we set this to
+FALSE.
+
+I<Discovering supported control commands>
+
+It is possible to discover at run-time the names, numerical-ids, descriptions
+and input parameters of the control commands supported by an ENGINE using a
+structural reference. Note that some control commands are defined by OpenSSL
+itself and it will intercept and handle these control commands on behalf of the
+ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command.
+openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands
+implemented by ENGINEs should be numbered from. Any command value lower than
+this symbol is considered a "generic" command is handled directly by the
+OpenSSL core routines.
+
+It is using these "core" control commands that one can discover the control
+commands implemented by a given ENGINE, specifically the commands:
+
+ ENGINE_HAS_CTRL_FUNCTION
+ ENGINE_CTRL_GET_FIRST_CMD_TYPE
+ ENGINE_CTRL_GET_NEXT_CMD_TYPE
+ ENGINE_CTRL_GET_CMD_FROM_NAME
+ ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
+ ENGINE_CTRL_GET_NAME_FROM_CMD
+ ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
+ ENGINE_CTRL_GET_DESC_FROM_CMD
+ ENGINE_CTRL_GET_CMD_FLAGS
+
+Whilst these commands are automatically processed by the OpenSSL framework code,
+they use various properties exposed by each ENGINE to process these
+queries. An ENGINE has 3 properties it exposes that can affect how this behaves;
+it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in
+the ENGINE's flags, and it can expose an array of control command descriptions.
+If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will
+simply pass all these "core" control commands directly to the ENGINE's ctrl()
+handler (and thus, it must have supplied one), so it is up to the ENGINE to
+reply to these "discovery" commands itself. If that flag is not set, then the
+OpenSSL framework code will work with the following rules;
+
+ if no ctrl() handler supplied;
+ ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),
+ all other commands fail.
+ if a ctrl() handler was supplied but no array of control commands;
+ ENGINE_HAS_CTRL_FUNCTION returns TRUE,
+ all other commands fail.
+ if a ctrl() handler and array of control commands was supplied;
+ ENGINE_HAS_CTRL_FUNCTION returns TRUE,
+ all other commands proceed processing ...
+
+If the ENGINE's array of control commands is empty then all other commands will
+fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of
+the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the
+identifier of a command supported by the ENGINE and returns the next command
+identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string
+name for a command and returns the corresponding identifier or fails if no such
+command name exists, and the remaining commands take a command identifier and
+return properties of the corresponding commands. All except
+ENGINE_CTRL_GET_FLAGS return the string length of a command name or description,
+or populate a supplied character buffer with a copy of the command name or
+description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following
+possible values:
+
+ ENGINE_CMD_FLAG_NUMERIC
+ ENGINE_CMD_FLAG_STRING
+ ENGINE_CMD_FLAG_NO_INPUT
+ ENGINE_CMD_FLAG_INTERNAL
+
+If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely
+informational to the caller - this flag will prevent the command being usable
+for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string().
+"INTERNAL" commands are not intended to be exposed to text-based configuration
+by applications, administrations, users, etc. These can support arbitrary
+operations via ENGINE_ctrl(), including passing to and/or from the control
+commands data of any arbitrary type. These commands are supported in the
+discovery mechanisms simply to allow applications to determine if an ENGINE
+supports certain specific commands it might want to use (eg. application "foo"
+might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" -
+and ENGINE could therefore decide whether or not to support this "foo"-specific
+extension).
+
+=head1 SEE ALSO
+
+L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<dsa(3)>, L<dh(3)>, L<rand(3)>
+
+=head1 HISTORY
+
+ENGINE_cleanup(), ENGINE_load_openssl(), ENGINE_load_dynamic(), and
+ENGINE_load_cryptodev() were deprecated in OpenSSL 1.1.0 by
+OPENSSL_init_crypto().
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and
+reason code
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ int ERR_GET_LIB(unsigned long e);
+
+ int ERR_GET_FUNC(unsigned long e);
+
+ int ERR_GET_REASON(unsigned long e);
+
+=head1 DESCRIPTION
+
+The error code returned by ERR_get_error() consists of a library
+number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC()
+and ERR_GET_REASON() can be used to extract these.
+
+The library number and function code describe where the error
+occurred, the reason code is the information about what went wrong.
+
+Each sub-library of OpenSSL has a unique library number; function and
+reason codes are unique within each sub-library. Note that different
+libraries may use the same value to signal different functions and
+reasons.
+
+B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally
+unique. However, when checking for sub-library specific reason codes,
+be sure to also compare the library number.
+
+ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros.
+
+=head1 RETURN VALUES
+
+The library number, function code and reason code respectively.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_get_error(3)>
+
+=head1 HISTORY
+
+ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in
+all versions of OpenSSL.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_clear_error - clear the error queue
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_clear_error(void);
+
+=head1 DESCRIPTION
+
+ERR_clear_error() empties the current thread's error queue.
+
+=head1 RETURN VALUES
+
+ERR_clear_error() has no return value.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
+ERR_func_error_string, ERR_reason_error_string - obtain human-readable
+error message
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ char *ERR_error_string(unsigned long e, char *buf);
+ void ERR_error_string_n(unsigned long e, char *buf, size_t len);
+
+ const char *ERR_lib_error_string(unsigned long e);
+ const char *ERR_func_error_string(unsigned long e);
+ const char *ERR_reason_error_string(unsigned long e);
+
+=head1 DESCRIPTION
+
+ERR_error_string() generates a human-readable string representing the
+error code I<e>, and places it at I<buf>. I<buf> must be at least 256
+bytes long. If I<buf> is B<NULL>, the error string is placed in a
+static buffer.
+Note that this function is not thread-safe and does no checks on the size
+of the buffer; use ERR_error_string_n() instead.
+
+ERR_error_string_n() is a variant of ERR_error_string() that writes
+at most I<len> characters (including the terminating 0)
+and truncates the string if necessary.
+For ERR_error_string_n(), I<buf> may not be B<NULL>.
+
+The string will have the following format:
+
+ error:[error code]:[library name]:[function name]:[reason string]
+
+I<error code> is an 8 digit hexadecimal number, I<library name>,
+I<function name> and I<reason string> are ASCII text.
+
+ERR_lib_error_string(), ERR_func_error_string() and
+ERR_reason_error_string() return the library name, function
+name and reason string respectively.
+
+If there is no text string registered for the given error code,
+the error string will contain the numeric code.
+
+L<ERR_print_errors(3)> can be used to print
+all error codes currently in the queue.
+
+=head1 RETURN VALUES
+
+ERR_error_string() returns a pointer to a static buffer containing the
+string if I<buf> B<== NULL>, I<buf> otherwise.
+
+ERR_lib_error_string(), ERR_func_error_string() and
+ERR_reason_error_string() return the strings, and B<NULL> if
+none is registered for the error code.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_get_error(3)>,
+L<ERR_print_errors(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_get_error, ERR_peek_error, ERR_peek_last_error,
+ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
+ERR_get_error_line_data, ERR_peek_error_line_data,
+ERR_peek_last_error_line_data - obtain error code and data
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ unsigned long ERR_get_error(void);
+ unsigned long ERR_peek_error(void);
+ unsigned long ERR_peek_last_error(void);
+
+ unsigned long ERR_get_error_line(const char **file, int *line);
+ unsigned long ERR_peek_error_line(const char **file, int *line);
+ unsigned long ERR_peek_last_error_line(const char **file, int *line);
+
+ unsigned long ERR_get_error_line_data(const char **file, int *line,
+ const char **data, int *flags);
+ unsigned long ERR_peek_error_line_data(const char **file, int *line,
+ const char **data, int *flags);
+ unsigned long ERR_peek_last_error_line_data(const char **file, int *line,
+ const char **data, int *flags);
+
+=head1 DESCRIPTION
+
+ERR_get_error() returns the earliest error code from the thread's error
+queue and removes the entry. This function can be called repeatedly
+until there are no more error codes to return.
+
+ERR_peek_error() returns the earliest error code from the thread's
+error queue without modifying it.
+
+ERR_peek_last_error() returns the latest error code from the thread's
+error queue without modifying it.
+
+See L<ERR_GET_LIB(3)> for obtaining information about
+location and reason of the error, and
+L<ERR_error_string(3)> for human-readable error
+messages.
+
+ERR_get_error_line(), ERR_peek_error_line() and
+ERR_peek_last_error_line() are the same as the above, but they
+additionally store the file name and line number where
+the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
+
+ERR_get_error_line_data(), ERR_peek_error_line_data() and
+ERR_peek_last_error_line_data() store additional data and flags
+associated with the error code in *B<data>
+and *B<flags>, unless these are B<NULL>. *B<data> contains a string
+if *B<flags>&B<ERR_TXT_STRING> is true.
+
+An application B<MUST NOT> free the *B<data> pointer (or any other pointers
+returned by these functions) with OPENSSL_free() as freeing is handled
+automatically by the error library.
+
+=head1 RETURN VALUES
+
+The error code, or 0 if there is no error in the queue.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_error_string(3)>,
+L<ERR_GET_LIB(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings -
+load and free error strings
+
+=head1 SYNOPSIS
+
+Deprecated:
+
+ #include <openssl/err.h>
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void ERR_load_crypto_strings(void);
+ void ERR_free_strings(void);
+ #endif
+
+ #include <openssl/ssl.h>
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void SSL_load_error_strings(void);
+ #endif
+
+=head1 DESCRIPTION
+
+All of the following functions are deprecated from OpenSSL 1.1.0. No explicit
+initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>
+and L<OPENSSL_init_ssl(3)>.
+
+ERR_load_crypto_strings() registers the error strings for all
+B<libcrypto> functions. SSL_load_error_strings() does the same,
+but also registers the B<libssl> error strings.
+
+In versions of OpenSSL prior to 1.1.0 ERR_free_strings() freed all previously
+loaded error strings. However from OpenSSL 1.1.0 it does nothing.
+
+=head1 RETURN VALUES
+
+ERR_load_crypto_strings(), SSL_load_error_strings() and
+ERR_free_strings() return no values.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_error_string(3)>
+
+=head1 HISTORY
+
+The ERR_load_crypto_strings(), SSL_load_error_strings(), and
+ERR_free_strings() functions were deprecated in OpenSSL 1.1.0 by
+OPENSSL_init_crypto() and OPENSSL_init_ssl().
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load
+arbitrary error strings
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_load_strings(int lib, ERR_STRING_DATA str[]);
+
+ int ERR_get_next_error_library(void);
+
+ unsigned long ERR_PACK(int lib, int func, int reason);
+
+=head1 DESCRIPTION
+
+ERR_load_strings() registers error strings for library number B<lib>.
+
+B<str> is an array of error string data:
+
+ typedef struct ERR_string_data_st
+ {
+ unsigned long error;
+ char *string;
+ } ERR_STRING_DATA;
+
+The error code is generated from the library number and a function and
+reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>).
+ERR_PACK() is a macro.
+
+The last entry in the array is {0,0}.
+
+ERR_get_next_error_library() can be used to assign library numbers
+to user libraries at runtime.
+
+=head1 RETURN VALUE
+
+ERR_load_strings() returns no value. ERR_PACK() return the error code.
+ERR_get_next_error_library() returns zero on failure, otherwise a new
+library number.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_load_strings(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb
+- print error messages
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_print_errors(BIO *bp);
+ void ERR_print_errors_fp(FILE *fp);
+ void ERR_print_errors_cb(int (*cb)(const char *str, size_t len, void *u),
+ void *u)
+
+
+=head1 DESCRIPTION
+
+ERR_print_errors() is a convenience function that prints the error
+strings for all errors that OpenSSL has recorded to B<bp>, thus
+emptying the error queue.
+
+ERR_print_errors_fp() is the same, except that the output goes to a
+B<FILE>.
+
+ERR_print_errors_cb() is the same, except that the callback function,
+B<cb>, is called for each error line with the string, length, and userdata
+B<u> as the callback parameters.
+
+The error strings will have the following format:
+
+ [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
+
+I<error code> is an 8 digit hexadecimal number. I<library name>,
+I<function name> and I<reason string> are ASCII text, as is I<optional
+text message> if one was set for the respective error code.
+
+If there is no text string registered for the given error code,
+the error string will contain the numeric code.
+
+=head1 RETURN VALUES
+
+ERR_print_errors() and ERR_print_errors_fp() return no values.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_error_string(3)>,
+L<ERR_get_error(3)>.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_put_error, ERR_add_error_data - record an error
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ void ERR_put_error(int lib, int func, int reason, const char *file,
+ int line);
+
+ void ERR_add_error_data(int num, ...);
+ void ERR_add_error_data(int num, va_list arg);
+
+=head1 DESCRIPTION
+
+ERR_put_error() adds an error code to the thread's error queue. It
+signals that the error of reason code B<reason> occurred in function
+B<func> of library B<lib>, in line number B<line> of B<file>.
+This function is usually called by a macro.
+
+ERR_add_error_data() associates the concatenation of its B<num> string
+arguments with the error code added last.
+ERR_add_error_vdata() is similar except the argument is a B<va_list>.
+
+L<ERR_load_strings(3)> can be used to register
+error strings so that the application can a generate human-readable
+error messages for the error code.
+
+=head2 Reporting errors
+
+Each sub-library has a specific macro XXXerr() that is used to report
+errors. Its first argument is a function code B<XXX_F_...>, the second
+argument is a reason code B<XXX_R_...>. Function codes are derived
+from the function names; reason codes consist of textual error
+descriptions. For example, the function ssl3_read_bytes() reports a
+"handshake failure" as follows:
+
+ SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
+
+Function and reason codes should consist of upper case characters,
+numbers and underscores only. The error file generation script translates
+function codes into function names by looking in the header files
+for an appropriate function name, if none is found it just uses
+the capitalized form such as "SSL3_READ_BYTES" in the above example.
+
+The trailing section of a reason code (after the "_R_") is translated
+into lower case and underscores changed to spaces.
+
+Although a library will normally report errors using its own specific
+XXXerr macro, another library's macro can be used. This is normally
+only done when a library wants to include ASN1 code which must use
+the ASN1err() macro.
+
+
+=head1 RETURN VALUES
+
+ERR_put_error() and ERR_add_error_data() return
+no values.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<ERR_load_strings(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_remove_thread_state, ERR_remove_state - DEPRECATED
+
+=head1 SYNOPSIS
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10000000L
+ void ERR_remove_state(unsigned long pid);
+ #endif
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void ERR_remove_thread_state(void *);
+ #endif
+
+=head1 DESCRIPTION
+
+The functions described here were used to free the error queue
+associated with the current or specified thread.
+
+They are now deprecated and do nothing, as the OpenSSL libraries now
+normally do all thread initialisation and deinitialisation
+automatically (see L<OPENSSL_init_crypto(3)>).
+
+=head1 RETURN VALUE
+
+The functions described here return no value.
+
+=head1 SEE ALSO
+
+L<err(3)>, L<OPENSSL_init_crypto(3)>
+
+=head1 HISTORY
+
+ERR_remove_state() was deprecated in OpenSSL 1.0.0 when
+ERR_remove_thread_state() was introduced.
+
+ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the
+thread handling functionality was entirely rewritten.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark
+
+=head1 SYNOPSIS
+
+ #include <openssl/err.h>
+
+ int ERR_set_mark(void);
+
+ int ERR_pop_to_mark(void);
+
+=head1 DESCRIPTION
+
+ERR_set_mark() sets a mark on the current topmost error record if there
+is one.
+
+ERR_pop_to_mark() will pop the top of the error stack until a mark is found.
+The mark is then removed. If there is no mark, the whole stack is removed.
+
+=head1 RETURN VALUES
+
+ERR_set_mark() returns 0 if the error stack is empty, otherwise 1.
+
+ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which
+implies that the stack became empty, otherwise 1.
+
+=head1 SEE ALSO
+
+L<err(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_BytesToKey - password based encryption routine
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
+ const unsigned char *salt,
+ const unsigned char *data, int datal, int count,
+ unsigned char *key, unsigned char *iv);
+
+=head1 DESCRIPTION
+
+EVP_BytesToKey() derives a key and IV from various parameters. B<type> is
+the cipher to derive the key and IV for. B<md> is the message digest to use.
+The B<salt> parameter is used as a salt in the derivation: it should point to
+an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing
+B<datal> bytes which is used to derive the keying data. B<count> is the
+iteration count to use. The derived key and IV will be written to B<key>
+and B<iv> respectively.
+
+=head1 NOTES
+
+A typical application of this function is to derive keying material for an
+encryption algorithm from a password in the B<data> parameter.
+
+Increasing the B<count> parameter slows down the algorithm which makes it
+harder for an attacker to perform a brute force attack using a large number
+of candidate passwords.
+
+If the total key and IV length is less than the digest length and
+B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5
+otherwise a non standard extension is used to derive the extra data.
+
+Newer applications should use a more modern algorithm such as PBKDF2 as
+defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC.
+
+=head1 KEY DERIVATION ALGORITHM
+
+The key and IV is derived by concatenating D_1, D_2, etc until
+enough data is available for the key and IV. D_i is defined as:
+
+ D_i = HASH^count(D_(i-1) || data || salt)
+
+where || denotes concatenation, D_0 is empty, HASH is the digest
+algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data)
+is HASH(HASH(data)) and so on.
+
+The initial bytes are used for the key and the subsequent bytes for
+the IV.
+
+=head1 RETURN VALUES
+
+If B<data> is NULL, then EVP_BytesToKey() returns the number of bytes
+needed to store the derived key.
+Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes,
+or 0 on error.
+
+=head1 SEE ALSO
+
+L<evp(3)>, L<rand(3)>,
+L<PKCS5_PBKDF2_HMAC(3)>,
+L<EVP_EncryptInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_CIPHER_CTX_get_cipher_data, EVP_CIPHER_CTX_set_cipher_data - Routines to
+inspect and modify EVP_CIPHER_CTX objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void *EVP_CIPHER_CTX_get_cipher_data(const EVP_CIPHER_CTX *ctx);
+ void *EVP_CIPHER_CTX_set_cipher_data(EVP_CIPHER_CTX *ctx, void *cipher_data);
+
+=head1 DESCRIPTION
+
+The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the cipher
+data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the
+particular implementation of the cipher. For example this data can be used by
+engines to store engine specific information. The data is automatically
+allocated and freed by OpenSSL, so applications and engines should not normally
+free this directly (but see below).
+
+The EVP_CIPHER_CTX_set_cipher_data() function allows an application or engine to
+replace the cipher data with new data. A pointer to any existing cipher data is
+returned from this function. If the old data is no longer required then it
+should be freed through a call to OPENSSL_free().
+
+=head1 RETURN VALUES
+
+The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the current
+cipher data for the EVP_CIPHER_CTX.
+
+The EVP_CIPHER_CTX_set_cipher_data() function returns a pointer to the old
+cipher data for the EVP_CIPHER_CTX.
+
+=head1 HISTORY
+
+The EVP_CIPHER_CTX_get_cipher_data() and EVP_CIPHER_CTX_set_cipher_data()
+functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free,
+EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags,
+EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init,
+EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup,
+EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params,
+EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init,
+EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup,
+EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params,
+EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);
+ EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);
+ void EVP_CIPHER_meth_free(EVP_CIPHER *cipher);
+
+ int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);
+ int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);
+ int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);
+ int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher,
+ int (*init) (EVP_CIPHER_CTX *ctx,
+ const unsigned char *key,
+ const unsigned char *iv,
+ int enc));
+ int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher,
+ int (*do_cipher) (EVP_CIPHER_CTX *ctx,
+ unsigned char *out,
+ const unsigned char *in,
+ size_t inl));
+ int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher,
+ int (*cleanup) (EVP_CIPHER_CTX *));
+ int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher,
+ int (*set_asn1_parameters) (EVP_CIPHER_CTX *,
+ ASN1_TYPE *));
+ int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher,
+ int (*get_asn1_parameters) (EVP_CIPHER_CTX *,
+ ASN1_TYPE *));
+ int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,
+ int (*ctrl) (EVP_CIPHER_CTX *, int type,
+ int arg, void *ptr));
+
+ int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
+ const unsigned char *key,
+ const unsigned char *iv,
+ int enc);
+ int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,
+ unsigned char *out,
+ const unsigned char *in,
+ size_t inl);
+ int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *);
+ int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
+ ASN1_TYPE *);
+ int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
+ ASN1_TYPE *);
+ int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,
+ int type, int arg,
+ void *ptr);
+
+=head1 DESCRIPTION
+
+The B<EVP_CIPHER> type is a structure for symmetric cipher method
+implementation.
+
+EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure.
+
+EVP_CIPHER_meth_dup() creates a copy of B<cipher>.
+
+EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure.
+
+EVP_CIPHER_meth_iv_length() sets the length of the IV.
+This is only needed when the implemented cipher mode requires it.
+
+EVP_CIPHER_meth_set_flags() sets the flags to describe optional
+behaviours in the particular B<cipher>.
+With the exception of cipher modes, of which only one may be present,
+several flags can be or'd together.
+The available flags are:
+
+=over
+
+=item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE,
+EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE,
+EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE,
+EVP_CIPH_OCB_MODE
+
+The cipher mode.
+
+=item EVP_CIPH_VARIABLE_LENGTH
+
+This cipher is of variable length.
+
+=item EVP_CIPH_CUSTOM_IV
+
+Storing and initialising the IV is left entirely to the
+implementation.
+
+=item EVP_CIPH_ALWAYS_CALL_INIT
+
+Set this if the implementation's init() function should be called even
+if B<key> is B<NULL>.
+
+=item EVP_CIPH_CTRL_INIT
+
+Set this to have the implementation's ctrl() function called with
+command code B<EVP_CTRL_INIT> early in its setup.
+
+=item EVP_CIPH_CUSTOM_KEY_LENGTH
+
+Checking and setting the key length after creating the B<EVP_CIPHER>
+is left to the implementation.
+Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a
+B<EVP_CIPHER> with this flag set, the implementation's ctrl() function
+will be called with the control code B<EVP_CTRL_SET_KEY_LENGTH> and
+the key length in B<arg>.
+
+=item EVP_CIPH_NO_PADDING
+
+Don't use standard block padding.
+
+=item EVP_CIPH_RAND_KEY
+
+Making a key with random content is left to the implementation.
+This is done by calling the implementation's ctrl() function with the
+control code B<EVP_CTRL_RAND_KEY> and the pointer to the key memory
+storage in B<ptr>.
+
+=item EVP_CIPH_CUSTOM_COPY
+
+Set this to have the implementation's ctrl() function called with
+command code B<EVP_CTRL_COPY> at the end of EVP_CIPHER_CTX_copy().
+The intended use is for further things to deal with after the
+implementation specific data block has been copied.
+The destination B<EVP_CIPHER_CTX> is passed to the control with the
+B<ptr> parameter.
+The implementation specific data block is reached with
+EVP_CIPHER_CTX_get_cipher_data().
+
+=item EVP_CIPH_FLAG_DEFAULT_ASN1
+
+Use the default EVP routines to pass IV to and from ASN.1.
+
+=item EVP_CIPH_FLAG_LENGTH_BITS
+
+Signals that the length of the input buffer for encryption /
+decryption is to be understood as the number of bits bits instead of
+bytes for this implementation.
+This is only useful for CFB1 ciphers.
+
+=begin comment
+The FIPS flags seem to be unused, so I'm hiding them until I get an
+explanation or they get removed. /RL
+
+=item EVP_CIPH_FLAG_FIPS
+
+=item EVP_CIPH_FLAG_NON_FIPS_ALLOW
+
+=end comment
+
+=item EVP_CIPH_FLAG_CUSTOM_CIPHER
+
+This indicates that the implementation takes care of everything,
+including padding, buffering and finalization.
+The EVP routines will simply give them control and do nothing more.
+
+=item EVP_CIPH_FLAG_AEAD_CIPHER
+
+This indicates that this is an AEAD cipher implementation.
+
+=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK
+
+Allow interleaving of crypto blocks, a particular optimization only applicable
+to certain TLS ciphers.
+
+=back
+
+EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's
+implementation context so that it can be automatically allocated.
+
+EVP_CIPHER_meth_set_init() sets the cipher init function for
+B<cipher>.
+The cipher init function is called by EVP_CipherInit(),
+EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(),
+EVP_DecryptInit(), EVP_DecryptInit_ex().
+
+EVP_CIPHER_meth_set_do_cipher() sets the cipher function for
+B<cipher>.
+The cipher function is called by EVP_CipherUpdate(),
+EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(),
+EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and
+EVP_DecryptFinal_ex().
+
+EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do
+extra cleanup before the method's private data structure is cleaned
+out and freed.
+Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the
+private data structure is then available with
+EVP_CIPHER_CTX_get_cipher_data().
+This cleanup function is called by EVP_CIPHER_CTX_reset() and
+EVP_CIPHER_CTX_free().
+
+EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>.
+
+=head1 RETURN VALUES
+
+EVP_CIPHER_meth_get_input_blocksize(), EVP_CIPHER_meth_get_result_size(),
+EVP_CIPHER_meth_get_app_datasize(), EVP_CIPHER_meth_get_flags(),
+EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_update(),
+EVP_CIPHER_meth_get_final(), EVP_CIPHER_meth_get_copy(),
+EVP_CIPHER_meth_get_cleanup() and EVP_CIPHER_meth_get_ctrl() are all used
+to retrieve the method data given with the EVP_CIPHER_meth_set_*()
+functions above.
+
+=head1 SEE ALSO
+
+L<EVP_EncryptInit>
+
+=head1 HISTORY
+
+The B<EVP_CIPHER> structure was openly available in OpenSSL before version
+1.1.
+The functions described here were added in OpenSSL version 1.1.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,
+EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex,
+EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type,
+EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
+EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha1,
+EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_mdc2,
+EVP_ripemd160, EVP_blake2b_512, EVP_blake2s_256, EVP_get_digestbyname,
+EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_MD_CTX *EVP_MD_CTX_new(void);
+ int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
+ void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
+
+ int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
+ int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
+ unsigned int *s);
+
+ int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);
+
+ int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+ int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
+ unsigned int *s);
+
+ int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
+
+ int EVP_MD_type(const EVP_MD *md);
+ int EVP_MD_pkey_type(const EVP_MD *md);
+ int EVP_MD_size(const EVP_MD *md);
+ int EVP_MD_block_size(const EVP_MD *md);
+
+ const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
+ int EVP_MD_CTX_size(const EVP_MD *ctx);
+ int EVP_MD_CTX_block_size(const EVP_MD *ctx);
+ int EVP_MD_CTX_type(const EVP_MD *ctx);
+
+ const EVP_MD *EVP_md_null(void);
+ const EVP_MD *EVP_md2(void);
+ const EVP_MD *EVP_md5(void);
+ const EVP_MD *EVP_sha1(void);
+ const EVP_MD *EVP_mdc2(void);
+ const EVP_MD *EVP_ripemd160(void);
+ const EVP_MD *EVP_blake2b_512(void);
+ const EVP_MD *EVP_blake2s_256(void);
+
+ const EVP_MD *EVP_sha224(void);
+ const EVP_MD *EVP_sha256(void);
+ const EVP_MD *EVP_sha384(void);
+ const EVP_MD *EVP_sha512(void);
+
+ const EVP_MD *EVP_get_digestbyname(const char *name);
+ const EVP_MD *EVP_get_digestbynid(int type);
+ const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);
+
+=head1 DESCRIPTION
+
+The EVP digest routines are a high level interface to message digests,
+and should be used instead of the cipher-specific functions.
+
+EVP_MD_CTX_new() allocates, initializes and returns a digest context.
+
+EVP_MD_CTX_reset() resets the digest context B<ctx>. This can be used
+to reuse an already existing context.
+
+EVP_MD_CTX_free() cleans up digest context B<ctx> and frees up the
+space allocated to it.
+
+EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest
+B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this
+function. B<type> will typically be supplied by a function such as EVP_sha1().
+If B<impl> is NULL then the default implementation of digest B<type> is used.
+
+EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
+digest context B<ctx>. This function can be called several times on the
+same B<ctx> to hash additional data.
+
+EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places
+it in B<md>. If the B<s> parameter is not NULL then the number of
+bytes of data written (i.e. the length of the digest) will be written
+to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
+After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate()
+can be made, but EVP_DigestInit_ex() can be called to initialize a new
+digest operation.
+
+EVP_MD_CTX_copy_ex() can be used to copy the message digest state from
+B<in> to B<out>. This is useful if large amounts of data are to be
+hashed which only differ in the last few bytes. B<out> must be initialized
+before calling this function.
+
+EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except
+the passed context B<ctx> does not have to be initialized, and it always
+uses the default digest implementation.
+
+EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest
+context B<ctx> is automatically cleaned up.
+
+EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination
+B<out> does not have to be initialized.
+
+EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest
+when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the
+hash.
+
+EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the
+message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure.
+
+EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER
+representing the given message digest when passed an B<EVP_MD> structure.
+For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is
+normally used when setting ASN1 OIDs.
+
+EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed
+B<EVP_MD_CTX>.
+
+EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated
+with this digest. For example EVP_sha1() is associated with RSA so this will
+return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms
+are no longer linked this function is only retained for compatibility
+reasons.
+
+EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(),
+EVP_sha384(), EVP_sha512(), EVP_mdc2(), EVP_ripemd160(), EVP_blake2b_512(), and
+EVP_blake2s_256() return B<EVP_MD> structures for the MD2, MD5, SHA1, SHA224,
+SHA256, SHA384, SHA512, MDC2, RIPEMD160, BLAKE2b-512, and BLAKE2s-256 digest
+algorithms respectively.
+
+EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it
+returns is of zero length.
+
+EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
+return an B<EVP_MD> structure when passed a digest name, a digest NID or
+an ASN1_OBJECT structure respectively.
+
+=head1 RETURN VALUES
+
+EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for
+success and 0 for failure.
+
+EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
+
+EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the
+corresponding OBJECT IDENTIFIER or NID_undef if none exists.
+
+EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and
+EVP_MD_CTX_block_size() return the digest or block size in bytes.
+
+EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(),
+EVP_mdc2(), EVP_ripemd160(), EVP_blake2b_512(), and EVP_blake2s_256() return
+pointers to the corresponding EVP_MD structures.
+
+EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
+return either an B<EVP_MD> structure or NULL if an error occurs.
+
+=head1 NOTES
+
+The B<EVP> interface to message digests should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the digest used and much more flexible.
+
+New applications should use the SHA2 digest algorithms such as SHA256.
+The other digest algorithms are still in common use.
+
+For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
+set to NULL to use the default digest implementation.
+
+The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
+obsolete but are retained to maintain compatibility with existing code. New
+applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
+EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
+instead of initializing and cleaning it up on each call and allow non default
+implementations of digests to be specified.
+
+If digest contexts are not cleaned up after use
+memory leaks will occur.
+
+EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(),
+EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as
+macros.
+
+
+=head1 EXAMPLE
+
+This example digests the data "Test Message\n" and "Hello World\n", using the
+digest name passed on the command line.
+
+ #include <stdio.h>
+ #include <openssl/evp.h>
+
+ main(int argc, char *argv[])
+ {
+ EVP_MD_CTX *mdctx;
+ const EVP_MD *md;
+ char mess1[] = "Test Message\n";
+ char mess2[] = "Hello World\n";
+ unsigned char md_value[EVP_MAX_MD_SIZE];
+ int md_len, i;
+
+ if(!argv[1]) {
+ printf("Usage: mdtest digestname\n");
+ exit(1);
+ }
+
+ md = EVP_get_digestbyname(argv[1]);
+
+ if(!md) {
+ printf("Unknown message digest %s\n", argv[1]);
+ exit(1);
+ }
+
+ mdctx = EVP_MD_CTX_new();
+ EVP_DigestInit_ex(mdctx, md, NULL);
+ EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
+ EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
+ EVP_DigestFinal_ex(mdctx, md_value, &md_len);
+ EVP_MD_CTX_free(mdctx);
+
+ printf("Digest is: ");
+ for (i = 0; i < md_len; i++)
+ printf("%02x", md_value[i]);
+ printf("\n");
+
+ exit(0);
+ }
+
+=head1 SEE ALSO
+
+L<dgst(1)>,
+L<evp(3)>
+
+=head1 HISTORY
+
+B<EVP_MD_CTX> became opaque in OpenSSL 1.1. Consequently, stack
+allocated B<EVP_MD_CTX>s are no longer supported.
+
+EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to
+EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.
+
+The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
+later, so now EVP_sha1() can be used with RSA and DSA. The legacy EVP_dss1()
+was removed in OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
+ const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
+ int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
+ int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
+
+=head1 DESCRIPTION
+
+The EVP signature routines are a high level interface to digital signatures.
+
+EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
+ENGINE B<impl> and private key B<pkey>. B<ctx> must be created with
+EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
+EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
+be used to set alternative signing options.
+
+EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
+signature context B<ctx>. This function can be called several times on the
+same B<ctx> to include additional data. This function is currently implemented
+using a macro.
+
+EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
+If B<sig> is B<NULL> then the maximum size of the output buffer is written to
+the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
+B<siglen> parameter should contain the length of the B<sig> buffer, if the
+call is successful the signature is written to B<sig> and the amount of data
+written to B<siglen>.
+
+=head1 RETURN VALUES
+
+EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return
+1 for success and 0 or a negative value for failure. In particular a return
+value of -2 indicates the operation is not supported by the public key
+algorithm.
+
+The error codes can be obtained from L<ERR_get_error(3)>.
+
+=head1 NOTES
+
+The B<EVP> interface to digital signatures should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the algorithm used and much more flexible.
+
+In previous versions of OpenSSL there was a link between message digest types
+and public key algorithms. This meant that "clone" digests such as EVP_dss1()
+needed to be used to sign using SHA1 and DSA. This is no longer necessary and
+the use of clone digest is now discouraged.
+
+For some key types and parameters the random number generator must be seeded
+or the operation will fail.
+
+The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
+context. This means that calls to EVP_DigestSignUpdate() and
+EVP_DigestSignFinal() can be called later to digest and sign additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
+The use of EVP_PKEY_size() with these functions is discouraged because some
+signature operations may have a signature length which depends on the
+parameters set. As a result EVP_PKEY_size() would have to return a value
+which indicates the maximum possible signature for any set of parameters.
+
+=head1 SEE ALSO
+
+L<EVP_DigestVerifyInit(3)>,
+L<EVP_DigestInit(3)>, L<err(3)>,
+L<evp(3)>, L<hmac(3)>, L<md2(3)>,
+L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
+L<sha(3)>, L<dgst(1)>
+
+=head1 HISTORY
+
+EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
+were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signature verification functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
+ const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
+ int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
+ int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen);
+
+=head1 DESCRIPTION
+
+The EVP signature routines are a high level interface to digital signatures.
+
+EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest
+B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be created
+with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
+EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this
+can be used to set alternative verification options.
+
+EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
+verification context B<ctx>. This function can be called several times on the
+same B<ctx> to include additional data. This function is currently implemented
+using a macro.
+
+EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in
+B<sig> of length B<siglen>.
+
+=head1 RETURN VALUES
+
+EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0
+for failure.
+
+EVP_DigestVerifyFinal() returns 1 for success; any other value indicates
+failure. A return value of zero indicates that the signature did not verify
+successfully (that is, tbs did not match the original data or the signature had
+an invalid form), while other values indicate a more serious error (and
+sometimes also indicate an invalid signature form).
+
+The error codes can be obtained from L<ERR_get_error(3)>.
+
+=head1 NOTES
+
+The B<EVP> interface to digital signatures should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the algorithm used and much more flexible.
+
+In previous versions of OpenSSL there was a link between message digest types
+and public key algorithms. This meant that "clone" digests such as EVP_dss1()
+needed to be used to sign using SHA1 and DSA. This is no longer necessary and
+the use of clone digest is now discouraged.
+
+For some key types and parameters the random number generator must be seeded
+or the operation will fail.
+
+The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
+context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
+be called later to digest and verify additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
+=head1 SEE ALSO
+
+L<EVP_DigestSignInit(3)>,
+L<EVP_DigestInit(3)>, L<err(3)>,
+L<evp(3)>, L<hmac(3)>, L<md2(3)>,
+L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
+L<sha(3)>, L<dgst(1)>
+
+=head1 HISTORY
+
+EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal()
+were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy,
+EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal,
+EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal,
+EVP_DecodeBlock - EVP base 64 encode/decode routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void);
+ void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx);
+ int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx);
+ int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx);
+ void EVP_EncodeInit(EVP_ENCODE_CTX *ctx);
+ int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,
+ const unsigned char *in, int inl);
+ void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl);
+ int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n);
+
+ void EVP_DecodeInit(EVP_ENCODE_CTX *ctx);
+ int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl,
+ const unsigned char *in, int inl);
+ int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned
+ char *out, int *outl);
+ int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n);
+
+=head1 DESCRIPTION
+
+The EVP encode routines provide a high level interface to base 64 encoding and
+decoding. Base 64 encoding converts binary data into a printable form that uses
+the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3
+bytes of binary data provided 4 bytes of base 64 encoded data will be produced
+plus some occasional newlines (see below). If the input data length is not a
+multiple of 3 then the output data will be padded at the end using the "="
+character.
+
+EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for
+the encode/decode functions.
+
+EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the
+space allocated to it.
+
+Encoding of binary data is performed in blocks of 48 input bytes (or less for
+the final block). For each 48 byte input block encoded 64 bytes of base 64 data
+is output plus an additional newline character (i.e. 65 bytes in total). The
+final block (which may be less than 48 bytes) will output 4 bytes for every 3
+bytes of input. If the data length is not divisible by 3 then a full 4 bytes is
+still output for the final 1 or 2 bytes of input. Similarly a newline character
+will also be output.
+
+EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation.
+
+EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by
+B<in>. The output is stored in the buffer B<out> and the number of bytes output
+is stored in B<*outl>. It is the caller's responsibility to ensure that the
+buffer at B<out> is sufficiently large to accommodate the output data. Only full
+blocks of data (48 bytes) will be immediately processed and output by this
+function. Any remainder is held in the B<ctx> object and will be processed by a
+subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the
+required size of the output buffer add together the value of B<inl> with the
+amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore
+any remainder). This gives the number of blocks of data that will be processed.
+Ensure the output buffer contains 65 bytes of storage for each block, plus an
+additional byte for a NUL terminator. EVP_EncodeUpdate() may be called
+repeatedly to process large amounts of input data. In the event of an error
+EVP_EncodeUpdate() will set B<*outl> to 0 and return 0. On success 1 will be
+returned.
+
+EVP_EncodeFinal() must be called at the end of an encoding operation. It will
+process any partial block of data remaining in the B<ctx> object. The output
+data will be stored in B<out> and the length of the data written will be stored
+in B<*outl>. It is the caller's responsibility to ensure that B<out> is
+sufficiently large to accommodate the output data which will never be more than
+65 bytes plus an additional NUL terminator (i.e. 66 bytes in total).
+
+EVP_ENCODE_CTX_copy() can be used to copy a context B<sctx> to a context
+B<dctx>. B<dctx> must be initialized before calling this function.
+
+EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to
+be encoded or decoded that are pending in the B<ctx> object.
+
+EVP_EncodeBlock() encodes a full block of input data in B<f> and of length
+B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of
+output data will be produced. If B<dlen> is not divisible by 3 then the block is
+encoded as a final block of data and the output is padded such that it is always
+divisible by 4. Additionally a NUL terminator character will be added. For
+example if 16 bytes of input data is provided then 24 bytes of encoded data is
+created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of
+the data generated I<without> the NUL terminator is returned from the function.
+
+EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation.
+
+EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed
+to by B<in>. The output is stored in the buffer B<out> and the number of bytes
+output is stored in B<*outl>. It is the caller's responsibility to ensure that
+the buffer at B<out> is sufficiently large to accommodate the output data. This
+function will attempt to decode as much data as possible in 4 byte chunks. Any
+whitespace, newline or carriage return characters are ignored. Any partial chunk
+of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in
+the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If
+any illegal base 64 characters are encountered or if the base 64 padding
+character "=" is encountered in the middle of the data then the function returns
+-1 to indicate an error. A return value of 0 or 1 indicates successful
+processing of the data. A return value of 0 additionally indicates that the last
+input data characters processed included the base 64 padding character "=" and
+therefore no more non-padding character data is expected to be processed. For
+every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and
+line feeds), 3 bytes of binary output data will be produced (or less at the end
+of the data where the padding character "=" has been used).
+
+EVP_DecodeFinal() must be called at the end of a decoding operation. If there
+is any unprocessed data still in B<ctx> then the input data must not have been
+a multiple of 4 and therefore an error has occurred. The function will return -1
+in this case. Otherwise the function returns 1 on success.
+
+EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data
+contained in B<f> and store the result in B<t>. Any leading whitespace will be
+trimmed as will any trailing whitespace, newlines, carriage returns or EOF
+characters. After such trimming the length of the data in B<f> must be divisible
+by 4. For every 4 input bytes exactly 3 output bytes will be produced. The
+output will be padded with 0 bits if necessary to ensure that the output is
+always 3 bytes for every 4 input bytes. This function will return the length of
+the data decoded or -1 on error.
+
+=head1 RETURN VALUES
+
+EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX
+object or NULL on error.
+
+EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in
+B<ctx>.
+
+EVP_EncodeUpdate() returns 0 on error or 1 on success.
+
+EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL
+terminator.
+
+EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned
+then no more non-padding base 64 characters are expected.
+
+EVP_DecodeFinal() returns -1 on error or 1 on success.
+
+EVP_DecodeBlock() returns the length of the data decoded or -1 on error.
+
+=head1 SEE ALSO
+
+L<evp(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free,
+EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex,
+EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex,
+EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex,
+EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit,
+EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal,
+EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
+EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid,
+EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length,
+EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher,
+EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
+EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
+EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
+EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
+EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb,
+EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb,
+EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb,
+EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc,
+EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc,
+EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc,
+EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc,
+EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc,
+EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb,
+EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb,
+EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb,
+EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb,
+EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm,
+EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
+ int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
+
+ int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ ENGINE *impl, unsigned char *key, unsigned char *iv);
+ int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+ int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ ENGINE *impl, unsigned char *key, unsigned char *iv);
+ int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
+ int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char *key, unsigned char *iv);
+ int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+ int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char *key, unsigned char *iv);
+ int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char *key, unsigned char *iv, int enc);
+ int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
+ int *outl);
+
+ int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
+ int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
+ int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
+
+ const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
+ const EVP_CIPHER *EVP_get_cipherbynid(int nid);
+ const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);
+
+ int EVP_CIPHER_nid(const EVP_CIPHER *e);
+ int EVP_CIPHER_block_size(const EVP_CIPHER *e);
+ int EVP_CIPHER_key_length(const EVP_CIPHER *e)
+ int EVP_CIPHER_key_length(const EVP_CIPHER *e);
+ int EVP_CIPHER_iv_length(const EVP_CIPHER *e);
+ unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e);
+ unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e);
+ int EVP_CIPHER_type(const EVP_CIPHER *ctx);
+
+ const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
+ void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);
+ int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx);
+
+ int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
+ int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
+
+=head1 DESCRIPTION
+
+The EVP cipher routines are a high level interface to certain
+symmetric ciphers.
+
+EVP_CIPHER_CTX_new() creates a cipher context.
+
+EVP_CIPHER_CTX_free() clears all information from a cipher context
+and free up any allocated memory associate with it, including B<ctx>
+itself. This function should be called after all operations using a
+cipher are complete so sensitive information does not remain in
+memory.
+
+EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
+with cipher B<type> from ENGINE B<impl>. B<ctx> must be created
+before calling this function. B<type> is normally supplied
+by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
+default implementation is used. B<key> is the symmetric key to use
+and B<iv> is the IV to use (if necessary), the actual number of bytes
+used for the key and IV depends on the cipher. It is possible to set
+all parameters to NULL except B<type> in an initial call and supply
+the remaining parameters in subsequent calls, all of which have B<type>
+set to NULL. This is done when the default cipher parameters are not
+appropriate.
+
+EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
+writes the encrypted version to B<out>. This function can be called
+multiple times to encrypt successive blocks of data. The amount
+of data written depends on the block alignment of the encrypted data:
+as a result the amount of data written may be anything from zero bytes
+to (inl + cipher_block_size - 1) so B<out> should contain sufficient
+room. The actual number of bytes written is placed in B<outl>. It also
+checks if B<in> and B<out> are partially overlapping, and if they are
+0 is returned to indicate failure.
+
+If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
+the "final" data, that is any data that remains in a partial block.
+It uses standard block padding (aka PKCS padding) as described in
+the NOTES section, below. The encrypted
+final data is written to B<out> which should have sufficient space for
+one cipher block. The number of bytes written is placed in B<outl>. After
+this function is called the encryption operation is finished and no further
+calls to EVP_EncryptUpdate() should be made.
+
+If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
+data and it will return an error if any data remains in a partial block:
+that is if the total data length is not a multiple of the block size.
+
+EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the
+corresponding decryption operations. EVP_DecryptFinal() will return an
+error code if padding is enabled and the final block is not correctly
+formatted. The parameters and restrictions are identical to the encryption
+operations except that if padding is enabled the decrypted data buffer B<out>
+passed to EVP_DecryptUpdate() should have sufficient room for
+(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in
+which case B<inl> bytes is sufficient.
+
+EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are
+functions that can be used for decryption or encryption. The operation
+performed depends on the value of the B<enc> parameter. It should be set
+to 1 for encryption, 0 for decryption and -1 to leave the value unchanged
+(the actual value of 'enc' being supplied in a previous call).
+
+EVP_CIPHER_CTX_reset() clears all information from a cipher context
+and free up any allocated memory associate with it, except the B<ctx>
+itself. This function should be called anytime B<ctx> is to be reused
+for another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal()
+series of calls.
+
+EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
+similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
+EVP_CipherInit_ex() except the B<ctx> parameter does not need to be
+initialized and they always use the default cipher implementation.
+
+EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are
+identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
+EVP_CipherFinal_ex(). In previous releases they also cleaned up
+the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean()
+must be called to free any context resources.
+
+EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+return an EVP_CIPHER structure when passed a cipher name, a NID or an
+ASN1_OBJECT structure.
+
+EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when
+passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID
+value is an internal value which may not have a corresponding OBJECT
+IDENTIFIER.
+
+EVP_CIPHER_CTX_set_padding() enables or disables padding. This
+function should be called after the context is set up for encryption
+or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or
+EVP_CipherInit_ex(). By default encryption operations are padded using
+standard block padding and the padding is checked and removed when
+decrypting. If the B<pad> parameter is zero then no padding is
+performed, the total amount of data encrypted or decrypted must then
+be a multiple of the block size or an error will occur.
+
+EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
+length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
+structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
+for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
+given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
+for variable key length ciphers.
+
+EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
+If the cipher is a fixed length cipher then attempting to set the key
+length to any value other than the fixed value is an error.
+
+EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
+length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
+It will return zero if the cipher does not use an IV. The constant
+B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
+
+EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
+size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
+structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the maximum block
+length for all ciphers.
+
+EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
+cipher or context. This "type" is the actual NID of the cipher OBJECT
+IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
+128 bit RC2 have the same NID. If the cipher does not have an object
+identifier or does not have ASN1 support this function will return
+B<NID_undef>.
+
+EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
+an B<EVP_CIPHER_CTX> structure.
+
+EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
+EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
+EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
+EVP_CIPH_STREAM_CIPHER is returned.
+
+EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
+on the passed cipher. This will typically include any parameters and an
+IV. The cipher IV (if any) must be set when this call is made. This call
+should be made before the cipher is actually "used" (before any
+EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function
+may fail if the cipher does not have any ASN1 support.
+
+EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
+AlgorithmIdentifier "parameter". The precise effect depends on the cipher
+In the case of RC2, for example, it will set the IV and effective key length.
+This function should be called after the base cipher type is set but before
+the key is set. For example EVP_CipherInit() will be called with the IV and
+key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
+EVP_CipherInit() again with all parameters except the key set to NULL. It is
+possible for this function to fail if the cipher does not have any ASN1 support
+or the parameters cannot be set (for example the RC2 effective key length
+is not supported.
+
+EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
+and set.
+
+=head1 RETURN VALUES
+
+EVP_CIPHER_CTX_new() returns a pointer to a newly created
+B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
+
+EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
+return 1 for success and 0 for failure.
+
+EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
+EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
+
+EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
+EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
+
+EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
+
+EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+return an B<EVP_CIPHER> structure or NULL on error.
+
+EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
+
+EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
+size.
+
+EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
+length.
+
+EVP_CIPHER_CTX_set_padding() always returns 1.
+
+EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
+length or zero if the cipher does not use an IV.
+
+EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
+OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
+
+EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
+
+EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater
+than zero for success and zero or a negative number.
+
+=head1 CIPHER LISTING
+
+All algorithms have a fixed key length unless otherwise stated.
+
+=over 4
+
+=item EVP_enc_null()
+
+Null cipher: does nothing.
+
+=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb()
+
+AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb()
+
+AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb()
+
+AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb()
+
+DES in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(), EVP_des_ede_cfb()
+
+Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(), EVP_des_ede3_cfb()
+
+Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_desx_cbc()
+
+DESX algorithm in CBC mode.
+
+=item EVP_rc4()
+
+RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
+
+=item EVP_rc4_40()
+
+RC4 stream cipher with 40 bit key length.
+This is obsolete and new code should use EVP_rc4()
+and the EVP_CIPHER_CTX_set_key_length() function.
+
+=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb()
+
+IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+
+=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb()
+
+RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
+length cipher with an additional parameter called "effective key bits" or "effective key length".
+By default both are set to 128 bits.
+
+=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc()
+
+RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
+These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
+EVP_CIPHER_CTX_ctrl() to set the key length and effective key length.
+
+=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb()
+
+Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
+length cipher.
+
+=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb()
+
+CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
+length cipher.
+
+=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb()
+
+RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length
+cipher with an additional "number of rounds" parameter. By default the key length is set to 128
+bits and 12 rounds.
+
+=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm()
+
+AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
+These ciphers require additional control operations to function correctly: see
+the L</GCM and OCB Modes> section below for details.
+
+=item EVP_aes_128_ocb(void), EVP_aes_192_ocb(void), EVP_aes_256_ocb(void)
+
+Offset Codebook Mode (OCB) for 128, 192 and 256 bit keys respectively.
+These ciphers require additional control operations to function correctly: see
+the L</GCM and OCB Modes> section below for details.
+
+=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm()
+
+AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively.
+These ciphers require additional control operations to function correctly: see
+CCM mode section below for details.
+
+=back
+
+=head1 GCM and OCB Modes
+
+For GCM and OCB mode ciphers the behaviour of the EVP interface is subtly
+altered and several additional ctrl operations are supported.
+
+To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(),
+EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
+parameter B<out> set to B<NULL>.
+
+When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal()
+indicates if the operation was successful. If it does not indicate success
+the authentication operation has failed and any output data B<MUST NOT>
+be used as it is corrupted.
+
+The following ctrls are supported in both GCM and OCB modes:
+
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
+
+Sets the IV length: this call can only be made before specifying an IV. If
+not called a default IV length is used. For GCM AES and OCB AES the default is
+12 (i.e. 96 bits). For OCB mode the maximum is 15.
+
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
+
+Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
+This call can only be made when encrypting data and B<after> all data has been
+processed (e.g. after an EVP_EncryptFinal() call). For OCB mode the taglen must
+either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
+
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
+
+Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
+when decrypting data and must be made B<before> any data is processed (e.g.
+before any EVP_DecryptUpdate() call). For OCB mode the taglen must
+either be 16 or the value previously set via EVP_CTRL_AEAD_SET_TAG.
+
+In OCB mode calling this with B<tag> set to NULL sets the tag length. The tag
+length can only be set before specifying an IV. If not called a default tag
+length is used. For OCB AES the default is 16 (i.e. 128 bits). This is also the
+maximum tag length for OCB.
+
+See L</EXAMPLES> below for an example of the use of GCM mode.
+
+=head1 CCM Mode
+
+The behaviour of CCM mode ciphers is similar to GCM mode but with a few
+additional requirements and different ctrl values.
+
+Like GCM and OCB modes any additional authenticated data (AAD) is passed by calling
+EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
+parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext
+length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or
+EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>)
+set to B<NULL> and the length passed in the B<inl> parameter.
+
+The following ctrls are supported in CCM mode:
+
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
+
+This call is made to set the expected B<CCM> tag value when decrypting or
+the length of the tag (with the B<tag> parameter set to NULL) when encrypting.
+The tag length is often referred to as B<M>. If not set a default value is
+used (12 for AES).
+
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);
+
+Sets the CCM B<L> value. If not set a default is used (8 for AES).
+
+ EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
+
+Sets the CCM nonce (IV) length: this call can only be made before specifying
+an nonce value. The nonce length is given by B<15 - L> so it is 7 by default
+for AES.
+
+=head1 NOTES
+
+Where possible the B<EVP> interface to symmetric ciphers should be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the cipher used and much more flexible. Additionally, the
+B<EVP> interface will ensure the use of platform specific cryptographic
+acceleration such as AES-NI (the low level interfaces do not provide the
+guarantee).
+
+PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
+length of the encrypted data a multiple of the block size. Padding is always
+added so if the data is already a multiple of the block size B<n> will equal
+the block size. For example if the block size is 8 and 11 bytes are to be
+encrypted then 5 padding bytes of value 5 will be added.
+
+When decrypting the final block is checked to see if it has the correct form.
+
+Although the decryption operation can produce an error if padding is enabled,
+it is not a strong test that the input data or key is correct. A random block
+has better than 1 in 256 chance of being of the correct format and problems with
+the input data earlier on will not produce a final decrypt error.
+
+If padding is disabled then the decryption operation will always succeed if
+the total amount of data decrypted is a multiple of the block size.
+
+The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
+EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
+compatibility with existing code. New code should use EVP_EncryptInit_ex(),
+EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
+EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
+existing context without allocating and freeing it up on each call.
+
+EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.
+
+=head1 BUGS
+
+For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
+a limitation of the current RC5 code rather than the EVP interface.
+
+EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
+default key lengths. If custom ciphers exceed these values the results are
+unpredictable. This is because it has become standard practice to define a
+generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
+
+The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
+for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
+
+=head1 EXAMPLES
+
+Encrypt a string using IDEA:
+
+ int do_crypt(char *outfile)
+ {
+ unsigned char outbuf[1024];
+ int outlen, tmplen;
+ /* Bogus key and IV: we'd normally set these from
+ * another source.
+ */
+ unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
+ unsigned char iv[] = {1,2,3,4,5,6,7,8};
+ char intext[] = "Some Crypto Text";
+ EVP_CIPHER_CTX ctx;
+ FILE *out;
+
+ ctx = EVP_CIPHER_CTX_new();
+ EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv);
+
+ if(!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext)))
+ {
+ /* Error */
+ return 0;
+ }
+ /* Buffer passed to EVP_EncryptFinal() must be after data just
+ * encrypted to avoid overwriting it.
+ */
+ if(!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen))
+ {
+ /* Error */
+ return 0;
+ }
+ outlen += tmplen;
+ EVP_CIPHER_CTX_free(ctx);
+ /* Need binary mode for fopen because encrypted data is
+ * binary data. Also cannot use strlen() on it because
+ * it won't be null terminated and may contain embedded
+ * nulls.
+ */
+ out = fopen(outfile, "wb");
+ fwrite(outbuf, 1, outlen, out);
+ fclose(out);
+ return 1;
+ }
+
+The ciphertext from the above example can be decrypted using the B<openssl>
+utility with the command line (shown on two lines for clarity):
+
+ openssl idea -d <filename
+ -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
+
+General encryption and decryption function example using FILE I/O and AES128
+with a 128-bit key:
+
+ int do_crypt(FILE *in, FILE *out, int do_encrypt)
+ {
+ /* Allow enough space in output buffer for additional block */
+ unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
+ int inlen, outlen;
+ EVP_CIPHER_CTX *ctx;
+ /* Bogus key and IV: we'd normally set these from
+ * another source.
+ */
+ unsigned char key[] = "0123456789abcdeF";
+ unsigned char iv[] = "1234567887654321";
+
+ /* Don't set key or IV right away; we want to check lengths */
+ ctx = EVP_CIPHER_CTX_new();
+ EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
+ do_encrypt);
+ OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
+ OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
+
+ /* Now we can set key and IV */
+ EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt);
+
+ for(;;)
+ {
+ inlen = fread(inbuf, 1, 1024, in);
+ if (inlen <= 0) break;
+ if(!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen))
+ {
+ /* Error */
+ EVP_CIPHER_CTX_free(ctx);
+ return 0;
+ }
+ fwrite(outbuf, 1, outlen, out);
+ }
+ if(!EVP_CipherFinal_ex(ctx, outbuf, &outlen))
+ {
+ /* Error */
+ EVP_CIPHER_CTX_free(ctx);
+ return 0;
+ }
+ fwrite(outbuf, 1, outlen, out);
+
+ EVP_CIPHER_CTX_free(ctx);
+ return 1;
+ }
+
+
+=head1 SEE ALSO
+
+L<evp(3)>
+
+=head1 HISTORY
+
+Support for OCB mode was added in OpenSSL 1.1.0
+
+B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result,
+EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
+disappeared. EVP_CIPHER_CTX_init() remains as an alias for
+EVP_CIPHER_CTX_reset().
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_MD_meth_dup,
+EVP_MD_meth_new, EVP_MD_meth_free, EVP_MD_meth_set_input_blocksize,
+EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize,
+EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update,
+EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup,
+EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
+EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
+EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
+EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
+EVP_MD_meth_get_ctrl, EVP_MD_CTX_md_data
+- Routines to build up EVP_MD methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type);
+ void EVP_MD_meth_free(EVP_MD *md);
+ EVP_MD *EVP_MD_meth_dup(const EVP_MD *md);
+
+ int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize);
+ int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize);
+ int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize);
+ int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags);
+ int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx));
+ int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx,
+ const void *data,
+ size_t count));
+ int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx,
+ unsigned char *md));
+ int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to,
+ const EVP_MD_CTX *from));
+ void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
+ int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx));
+ int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd,
+ int p1, void *p2));
+
+ int EVP_MD_meth_get_input_blocksize(const EVP_MD *md);
+ int EVP_MD_meth_get_result_size(const EVP_MD *md);
+ int EVP_MD_meth_get_app_datasize(const EVP_MD *md);
+ unsigned long EVP_MD_meth_get_flags(const EVP_MD *md);
+ int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx);
+ int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx,
+ const void *data,
+ size_t count);
+ int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx,
+ unsigned char *md);
+ int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to,
+ const EVP_MD_CTX *from);
+ int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx);
+ int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
+ int p1, void *p2);
+
+=head1 DESCRIPTION
+
+The B<EVP_MD> type is a structure for digest method implementation.
+It can also have associated public/private key signing and verifying
+routines.
+
+EVP_MD_meth_new() creates a new B<EVP_MD> structure.
+
+EVP_MD_meth_dup() creates a copy of B<md>.
+
+EVP_MD_meth_free() destroys a B<EVP_MD> structure.
+
+EVP_MD_meth_set_input_blocksize() sets the internal input block size
+for the method B<md> to B<blocksize> bytes.
+
+EVP_MD_meth_set_result_size() sets the size of the result that the
+digest method in B<md> is expected to produce to B<resultsize> bytes.
+
+The digest method may have its own private data, which OpenSSL will
+allocate for it. EVP_MD_meth_set_app_datasize() should be used to
+set the size for it to B<datasize>.
+
+EVP_MD_meth_set_flags() sets the flags to describe optional
+behaviours in the particular B<md>. Several flags can be or'd
+together. The available flags are:
+
+=over 4
+
+=item EVP_MD_FLAG_ONESHOT
+
+This digest method can only handles one block of input.
+
+=item EVP_MD_FLAG_DIGALGID_NULL
+
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter set to NULL by default. Use this for PKCS#1. I<Note: if
+combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
+
+=item EVP_MD_FLAG_DIGALGID_ABSENT
+
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter be left absent by default. I<Note: if combined with
+EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
+
+=item EVP_MD_FLAG_DIGALGID_CUSTOM
+
+Custom DigestAlgorithmIdentifier handling via ctrl, with
+B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
+EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
+Currently unused.
+
+=back
+
+EVP_MD_meth_set_init() sets the digest init function for B<md>.
+The digest init function is called by EVP_DigestInit(),
+EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
+and EVP_VerifyInit_ex().
+
+EVP_MD_meth_set_update() sets the digest update function for B<md>.
+The digest update function is called by EVP_DigestUpdate(),
+EVP_SignUpdate().
+
+EVP_MD_meth_set_final() sets the digest final function for B<md>.
+The digest final function is called by EVP_DigestFinal(),
+EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
+
+EVP_MD_meth_set_copy() sets the function for B<md> to do extra
+computations after the method's private data structure has been copied
+from one B<EVP_MD_CTX> to another. If all that's needed is to copy
+the data, there is no need for this copy function.
+Note that the copy function is passed two B<EVP_MD_CTX *>, the private
+data structure is then available with EVP_MD_CTX_md_data().
+This copy function is called by EVP_MD_CTX_copy() and
+EVP_MD_CTX_copy_ex().
+
+EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra
+cleanup before the method's private data structure is cleaned out and
+freed.
+Note that the cleanup function is passed a B<EVP_MD_CTX *>, the
+private data structure is then available with EVP_MD_CTX_md_data().
+This cleanup function is called by EVP_MD_CTX_reset() and
+EVP_MD_CTX_free().
+
+EVP_MD_meth_set_ctrl() sets the control function for B<md>.
+
+
+EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
+EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
+EVP_MD_meth_get_init(), EVP_MD_meth_get_update(),
+EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(),
+EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
+to retrieve the method data given with the EVP_MD_meth_set_*()
+functions above.
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
+
+=head1 HISTORY
+
+The B<EVP_MD> structure was openly available in OpenSSL before version
+1.1. The functions described here were added in OpenSSL version 1.1.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_OpenInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *ek,
+ int ekl, unsigned char *iv, EVP_PKEY *priv);
+ int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+=head1 DESCRIPTION
+
+The EVP envelope routines are a high level interface to envelope
+decryption. They decrypt a public key encrypted symmetric key and
+then decrypt data using it.
+
+EVP_OpenInit() initializes a cipher context B<ctx> for decryption
+with cipher B<type>. It decrypts the encrypted symmetric key of length
+B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>.
+The IV is supplied in the B<iv> parameter.
+
+EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties
+as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as
+documented on the L<EVP_EncryptInit(3)> manual
+page.
+
+=head1 NOTES
+
+It is possible to call EVP_OpenInit() twice in the same way as
+EVP_DecryptInit(). The first call should have B<priv> set to NULL
+and (after setting any cipher parameters) it should be called again
+with B<type> set to NULL.
+
+If the cipher passed in the B<type> parameter is a variable length
+cipher then the key length will be set to the value of the recovered
+key length. If the cipher is a fixed length cipher then the recovered
+key length must match the fixed cipher length.
+
+=head1 RETURN VALUES
+
+EVP_OpenInit() returns 0 on error or a non zero integer (actually the
+recovered secret key size) if successful.
+
+EVP_OpenUpdate() returns 1 for success or 0 for failure.
+
+EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success.
+
+=head1 SEE ALSO
+
+L<evp(3)>, L<rand(3)>,
+L<EVP_EncryptInit(3)>,
+L<EVP_SealInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str,
+EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding,
+EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits,
+EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits,
+EVP_PKEY_CTX_set_dh_paramgen_prime_len,
+EVP_PKEY_CTX_set_dh_paramgen_generator,
+EVP_PKEY_CTX_set_ec_paramgen_curve_nid,
+EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
+ int cmd, int p1, void *p2);
+ int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,
+ const char *value);
+
+ #include <openssl/rsa.h>
+
+ int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
+
+ int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
+ int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
+ int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
+ int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
+
+ #include <openssl/dsa.h>
+ int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
+
+ #include <openssl/dh.h>
+ int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
+ int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
+
+ #include <openssl/ec.h>
+ int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
+ int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
+
+=head1 DESCRIPTION
+
+The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
+B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter
+B<optype> is a mask indicating which operations the control can be applied to.
+The control command is indicated in B<cmd> and any additional arguments in
+B<p1> and B<p2>.
+
+Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will
+instead call one of the algorithm specific macros below.
+
+The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm
+specific control operation to a context B<ctx> in string form. This is
+intended to be used for options specified on the command line or in text
+files. The commands supported are documented in the openssl utility
+command line pages for the option B<-pkeyopt> which is supported by the
+B<pkeyutl>, B<genpkey> and B<req> commands.
+
+All the remaining "functions" are implemented as macros.
+
+The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used
+in a signature. It can be used with any public key algorithm supporting
+signature operations.
+
+The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>.
+The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding,
+RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding,
+RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only),
+RSA_X931_PADDING for X9.31 padding (signature operations only) and
+RSA_PKCS1_PSS_PADDING (sign and verify only).
+
+Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md()
+is used. If this macro is called for PKCS#1 padding the plaintext buffer is
+an actual digest value and is encapsulated in a DigestInfo structure according
+to PKCS#1 when signing and this structure is expected (and stripped off) when
+verifying. If this control is not used with RSA and PKCS#1 padding then the
+supplied data is used directly and not encapsulated. In the case of X9.31
+padding for RSA the algorithm identifier byte is added or checked and removed
+if this control is called. If it is not called then the first byte of the plaintext
+buffer is expected to be the algorithm identifier byte.
+
+The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to
+B<len> as its name implies it is only supported for PSS padding. Two special
+values are supported: -1 sets the salt length to the digest length. When
+signing -2 sets the salt length to the maximum permissible value. When
+verifying -2 causes the salt length to be automatically determined based on the
+B<PSS> block structure. If this macro is not called a salt length value of -2
+is used by default.
+
+The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for
+RSA key generation to B<bits>. If not specified 1024 bits is used.
+
+The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value
+for RSA key generation to B<pubexp> currently it should be an odd integer. The
+B<pubexp> pointer is used internally by this function so it should not be
+modified or free after the call. If this macro is not called then 65537 is used.
+
+The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used
+for DSA parameter generation to B<bits>. If not specified 1024 is used.
+
+The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH
+prime parameter B<p> for DH parameter generation. If this macro is not called
+then 1024 is used.
+
+The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen>
+for DH parameter generation. If not specified 2 is used.
+
+The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
+generation to B<nid>. For EC parameter generation this macro must be called
+or an error occurs because there is no default curve.
+This function can also be called to set the curve explicitly when
+generating an EC key.
+
+The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to
+B<param_enc> when generating EC parameters or an EC key. The encoding can be
+B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions
+of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form.
+For maximum compatibility the named curve form should be used. Note: the
+B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous
+versions should use 0 instead.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0
+or a negative value for failure. In particular a return value of -2
+indicates the operation is not supported by the public key algorithm.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>
+L<EVP_PKEY_keygen(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
+ EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
+ EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx);
+ void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_CTX_new() function allocates public key algorithm context using
+the algorithm specified in B<pkey> and ENGINE B<e>.
+
+The EVP_PKEY_CTX_new_id() function allocates public key algorithm context
+using the algorithm specified by B<id> and ENGINE B<e>. It is normally used
+when no B<EVP_PKEY> structure is associated with the operations, for example
+during parameter generation of key generation for some algorithms.
+
+EVP_PKEY_CTX_dup() duplicates the context B<ctx>.
+
+EVP_PKEY_CTX_free() frees up the context B<ctx>.
+If B<ctx> is NULL, nothing is done.
+
+=head1 NOTES
+
+The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used
+by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between
+threads: that is it is not permissible to use the same context simultaneously
+in two threads.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either
+the newly allocated B<EVP_PKEY_CTX> structure of B<NULL> if an error occurred.
+
+EVP_PKEY_CTX_free() does not return a value.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_new(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt,
+EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info -
+HMAC-based Extract-and-Expand key derivation algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/kdf.h>
+
+ int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
+
+ int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
+ int saltlen);
+
+ int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key,
+ int keylen);
+
+ int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info,
+ int infolen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function.
+HKDF follows the "extract-then-expand" paradigm, where the KDF logically
+consists of two modules. The first stage takes the input keying material
+and "extracts" from it a fixed-length pseudorandom key K. The second stage
+"expands" the key K into several additional pseudorandom keys (the output
+of the KDF).
+
+EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF.
+
+EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the
+buffer B<salt>. Any existing value is replaced.
+
+EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer
+B<key>. Any existing value is replaced.
+
+EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the
+buffer B<info>. If a value is already set, it is appended to the existing
+value.
+
+=head1 STRING CTRLS
+
+HKDF also supports string based control operations via
+L<EVP_PKEY_CTX_ctrl_str(3)>.
+The B<type> parameter "md" uses the supplied B<value> as the name of the digest
+algorithm to use.
+The B<type> parameters "salt", "key" and "info" use the supplied B<value>
+parameter as a B<seed>, B<key> or B<info> value.
+The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex
+string which is converted to binary.
+
+=head1 NOTES
+
+All these functions are implemented as macros.
+
+A context for HKDF can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_HKDF, NULL);
+
+The digest, key, salt and info values must be set before a key is derived or
+an error occurs.
+
+The total length of the info buffer cannot exceed 1024 bytes in length: this
+should be more than enough for any normal use of HKDF.
+
+The output length of the KDF is specified via the length parameter to the
+L<EVP_PKEY_derive(3)> function.
+Since the HKDF output length is variable, passing a B<NULL> buffer as a means
+to obtain the requisite length is not meaningful with HKDF.
+Instead, the caller must allocate a buffer of the desired length, and pass that
+buffer to L<EVP_PKEY_derive(3)> along with (a pointer initialized to) the
+desired length.
+
+Optimised versions of HKDF can be implemented in an ENGINE.
+
+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 or a negative value for failure.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using SHA-256 with the secret key "secret",
+salt value "salt" and info value "label":
+
+ EVP_PKEY_CTX *pctx;
+ unsigned char out[10];
+ size_t outlen = sizeof(out);
+ pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
+
+ if (EVP_PKEY_derive_init(pctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set1_salt(pctx, "salt", 4) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set1_key(pctx, "secret", 6) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 6) <= 0)
+ /* Error */
+ if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
+ /* Error */
+
+=head1 CONFORMING TO
+
+RFC 5869
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_set_tls1_prf_md,
+EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed -
+TLS PRF key derivation algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/kdf.h>
+
+ int EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
+ int EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx,
+ unsigned char *sec, int seclen);
+ int EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx, seed, seedlen)
+ unsigned char *seed, int seedlen);
+
+=head1 DESCRIPTION
+
+The B<EVP_PKEY_TLS1_PRF> algorithm implements the PRF key derivation function for
+TLS. It has no associated private key and only implements key derivation
+using EVP_PKEY_derive().
+
+EVP_PKEY_set_tls1_prf_md() sets the message digest associated with the
+TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF
+algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
+
+EVP_PKEY_CTX_set_tls1_prf_secret() sets the secret value of the TLS PRF
+to B<seclen> bytes of the buffer B<sec>. Any existing secret value is replaced
+and any seed is reset.
+
+EVP_PKEY_CTX_add1_tls1_prf_seed() sets the seed to B<seedlen> bytes of B<seed>.
+If a seed is already set it is appended to the existing value.
+
+=head1 STRING CTRLS
+
+The TLS PRF also supports string based control operations using
+L<EVP_PKEY_CTX_ctrl_str(3)>.
+The B<type> parameter "md" uses the supplied B<value> as the name of the digest
+algorithm to use.
+The B<type> parameters "secret" and "seed" use the supplied B<value> parameter
+as a secret or seed value.
+The names "hexsecret" and "hexseed" are similar except they take a hex string
+which is converted to binary.
+
+=head1 NOTES
+
+All these functions are implemented as macros.
+
+A context for the TLS PRF can be obtained by calling:
+
+ EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_TLS1_PRF, NULL);
+
+The digest, secret value and seed must be set before a key is derived or an
+error occurs.
+
+The total length of all seeds cannot exceed 1024 bytes in length: this should
+be more than enough for any normal use of the TLS PRF.
+
+The output length of the PRF is specified by the length parameter in the
+EVP_PKEY_derive() function. Since the output length is variable, setting
+the buffer to B<NULL> is not meaningful for the TLS PRF.
+
+Optimised versions of the TLS PRF can be implemented in an ENGINE.
+
+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 or a negative value for failure.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using SHA-256 with the secret key "secret"
+and seed value "seed":
+
+ EVP_PKEY_CTX *pctx;
+ unsigned char out[10];
+ size_t outlen = sizeof(out);
+ pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL);
+ if (EVP_PKEY_derive_init(pctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0)
+ /* Error */
+ if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
+ /* Error */
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters,
+EVP_PKEY_cmp - public key parameter and comparison functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey);
+ int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from);
+
+ int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b);
+ int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b);
+
+=head1 DESCRIPTION
+
+The function EVP_PKEY_missing_parameters() returns 1 if the public key
+parameters of B<pkey> are missing and 0 if they are present or the algorithm
+doesn't use parameters.
+
+The function EVP_PKEY_copy_parameters() copies the parameters from key
+B<from> to key B<to>. An error is returned if the parameters are missing in
+B<from> or present in both B<from> and B<to> and mismatch. If the parameters
+in B<from> and B<to> are both present and match this function has no effect.
+
+The function EVP_PKEY_cmp_parameters() compares the parameters of keys
+B<a> and B<b>.
+
+The function EVP_PKEY_cmp() compares the public key components and parameters
+(if present) of keys B<a> and B<b>.
+
+=head1 NOTES
+
+The main purpose of the functions EVP_PKEY_missing_parameters() and
+EVP_PKEY_copy_parameters() is to handle public keys in certificates where the
+parameters are sometimes omitted from a public key if they are inherited from
+the CA that signed it.
+
+Since OpenSSL private keys contain public key components too the function
+EVP_PKEY_cmp() can also be used to determine if a private key matches
+a public key.
+
+=head1 RETURN VALUES
+
+The function EVP_PKEY_missing_parameters() returns 1 if the public key
+parameters of B<pkey> are missing and 0 if they are present or the algorithm
+doesn't use parameters.
+
+These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for
+failure.
+
+The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the
+keys match, 0 if they don't match, -1 if the key types are different and
+-2 if the operation is not supported.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_keygen(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx,
+ unsigned char *out, size_t *outlen,
+ const unsigned char *in, size_t inlen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_decrypt_init() function initializes a public key algorithm
+context using key B<pkey> for a decryption operation.
+
+The EVP_PKEY_decrypt() function performs a public key decryption operation
+using B<ctx>. The data to be decrypted is specified using the B<in> and
+B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output
+buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then
+before the call the B<outlen> parameter should contain the length of the
+B<out> buffer, if the call is successful the decrypted data is written to
+B<out> and the amount of data written to B<outlen>.
+
+=head1 NOTES
+
+After the call to EVP_PKEY_decrypt_init() algorithm specific control
+operations can be performed to set any appropriate parameters for the
+operation.
+
+The function EVP_PKEY_decrypt() can be called more than once on the same
+context if several operations are performed using the same parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0
+or a negative value for failure. In particular a return value of -2
+indicates the operation is not supported by the public key algorithm.
+
+=head1 EXAMPLE
+
+Decrypt data using OAEP (for RSA keys):
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ unsigned char *out, *in;
+ size_t outlen, inlen;
+ EVP_PKEY *key;
+ /* NB: assumes key in, inlen are already set up
+ * and that key is an RSA private key
+ */
+ ctx = EVP_PKEY_CTX_new(key);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_decrypt_init(ctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0)
+ /* Error */
+
+ /* Determine buffer length */
+ if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0)
+ /* Error */
+
+ out = OPENSSL_malloc(outlen);
+
+ if (!out)
+ /* malloc failure */
+
+ if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0)
+ /* Error */
+
+ /* Decrypted data is outlen bytes written to buffer out */
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
+ int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_derive_init() function initializes a public key algorithm
+context using key B<pkey> for shared secret derivation.
+
+The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
+be a public key.
+
+The EVP_PKEY_derive() derives a shared secret using B<ctx>.
+If B<key> is B<NULL> then the maximum size of the output buffer is written to
+the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
+B<keylen> parameter should contain the length of the B<key> buffer, if the call
+is successful the shared secret is written to B<key> and the amount of data
+written to B<keylen>.
+
+=head1 NOTES
+
+After the call to EVP_PKEY_derive_init() algorithm specific control
+operations can be performed to set any appropriate parameters for the
+operation.
+
+The function EVP_PKEY_derive() can be called more than once on the same
+context if several operations are performed using the same parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
+or a negative value for failure. In particular a return value of -2
+indicates the operation is not supported by the public key algorithm.
+
+=head1 EXAMPLE
+
+Derive shared secret (for example DH or EC keys):
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ unsigned char *skey;
+ size_t skeylen;
+ EVP_PKEY *pkey, *peerkey;
+ /* NB: assumes pkey, peerkey have been already set up */
+
+ ctx = EVP_PKEY_CTX_new(pkey);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_derive_init(ctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
+ /* Error */
+
+ /* Determine buffer length */
+ if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
+ /* Error */
+
+ skey = OPENSSL_malloc(skeylen);
+
+ if (!skey)
+ /* malloc failure */
+
+ if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
+ /* Error */
+
+ /* Shared secret is skey bytes written to buffer skey */
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx,
+ unsigned char *out, size_t *outlen,
+ const unsigned char *in, size_t inlen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_encrypt_init() function initializes a public key algorithm
+context using key B<pkey> for an encryption operation.
+
+The EVP_PKEY_encrypt() function performs a public key encryption operation
+using B<ctx>. The data to be encrypted is specified using the B<in> and
+B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output
+buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then
+before the call the B<outlen> parameter should contain the length of the
+B<out> buffer, if the call is successful the encrypted data is written to
+B<out> and the amount of data written to B<outlen>.
+
+=head1 NOTES
+
+After the call to EVP_PKEY_encrypt_init() algorithm specific control
+operations can be performed to set any appropriate parameters for the
+operation.
+
+The function EVP_PKEY_encrypt() can be called more than once on the same
+context if several operations are performed using the same parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0
+or a negative value for failure. In particular a return value of -2
+indicates the operation is not supported by the public key algorithm.
+
+=head1 EXAMPLE
+
+Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or
+L<d2i_X509(3)> for means to load a public key. You may also simply
+set 'eng = NULL;' to start with the default OpenSSL RSA implementation:
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+ #include <openssl/engine.h>
+
+ EVP_PKEY_CTX *ctx;
+ ENGINE *eng;
+ unsigned char *out, *in;
+ size_t outlen, inlen;
+ EVP_PKEY *key;
+ /* NB: assumes eng, key, in, inlen are already set up,
+ * and that key is an RSA public key
+ */
+ ctx = EVP_PKEY_CTX_new(key, eng);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_encrypt_init(ctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0)
+ /* Error */
+
+ /* Determine buffer length */
+ if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0)
+ /* Error */
+
+ out = OPENSSL_malloc(outlen);
+
+ if (!out)
+ /* malloc failure */
+
+ if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0)
+ /* Error */
+
+ /* Encrypted data is outlen bytes written to buffer out */
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<engine(3)>,
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_get_default_digest_nid - get default signature digest
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+ int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_get_default_digest_nid() function sets B<pnid> to the default
+message digest NID for the public key signature operations associated with key
+B<pkey>.
+
+=head1 NOTES
+
+For all current standard OpenSSL public key algorithms SHA1 is returned.
+
+=head1 RETURN VALUES
+
+The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest
+is advisory (that is other digests can be used) and 2 if it is mandatory (other
+digests can not be used). It returns 0 or a negative value for failure. In
+particular a return value of -2 indicates the operation is not supported by the
+public key algorithm.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+
+=head1 HISTORY
+
+This function was first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
+EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
+EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
+EVP_PKEY_CTX_get_app_data - key and parameter generation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
+ int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
+
+ typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
+
+ void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
+ EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
+
+ int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
+
+ void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
+ void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_keygen_init() function initializes a public key algorithm
+context using key B<pkey> for a key generation operation.
+
+The EVP_PKEY_keygen() function performs a key generation operation, the
+generated key is written to B<ppkey>.
+
+The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar
+except parameters are generated.
+
+The function EVP_PKEY_set_cb() sets the key or parameter generation callback
+to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
+generation callback.
+
+The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated
+with the generation operation. If B<idx> is -1 the total number of
+parameters available is returned. Any non negative value returns the value of
+that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
+B<idx> should only be called within the generation callback.
+
+If the callback returns 0 then the key generation operation is aborted and an
+error occurs. This might occur during a time consuming operation where
+a user clicks on a "cancel" button.
+
+The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set
+and retrieve an opaque pointer. This can be used to set some application
+defined value which can be retrieved in the callback: for example a handle
+which is used to update a "progress dialog".
+
+=head1 NOTES
+
+After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
+specific control operations can be performed to set any appropriate parameters
+for the operation.
+
+The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than
+once on the same context if several operations are performed using the same
+parameters.
+
+The meaning of the parameters passed to the callback will depend on the
+algorithm and the specific implementation of the algorithm. Some might not
+give any useful information at all during key or parameter generation. Others
+might not even call the callback.
+
+The operation performed by key or parameter generation depends on the algorithm
+used. In some cases (e.g. EC with a supplied named curve) the "generation"
+option merely sets the appropriate fields in an EVP_PKEY structure.
+
+In OpenSSL an EVP_PKEY structure containing a private key also contains the
+public key components and parameters (if any). An OpenSSL private key is
+equivalent to what some libraries call a "key pair". A private key can be used
+in functions which require the use of a public key or parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
+EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
+
+=head1 EXAMPLES
+
+Generate a 2048 bit RSA key:
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ EVP_PKEY *pkey = NULL;
+ ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_keygen_init(ctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
+ /* Error */
+
+ /* Generate key */
+ if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
+ /* Error */
+
+Generate a key from a set of parameters:
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ EVP_PKEY *pkey = NULL, *param;
+ /* Assumed param is set up already */
+ ctx = EVP_PKEY_CTX_new(param);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_keygen_init(ctx) <= 0)
+ /* Error */
+
+ /* Generate key */
+ if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
+ /* Error */
+
+Example of generation callback for OpenSSL public key implementations:
+
+ /* Application data is a BIO to output status to */
+
+ EVP_PKEY_CTX_set_app_data(ctx, status_bio);
+
+ static int genpkey_cb(EVP_PKEY_CTX *ctx)
+ {
+ char c = '*';
+ BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
+ int p;
+ p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
+ if (p == 0) c = '.';
+ if (p == 1) c = '+';
+ if (p == 2) c = '*';
+ if (p == 3) c = '\n';
+ BIO_write(b, &c, 1);
+ (void)BIO_flush(b);
+ return 1;
+ }
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_free - private key allocation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_PKEY *EVP_PKEY_new(void);
+ int EVP_PKEY_up_ref(EVP_PKEY *key);
+ void EVP_PKEY_free(EVP_PKEY *key);
+
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is
+used by OpenSSL to store private keys. The reference count is set to B<1>.
+
+EVP_PKEY_up_ref() increments the reference count of B<key>.
+
+EVP_PKEY_free() decrements the reference count of B<key> and, if the reference
+count is zero, frees it up. If B<key> is NULL, nothing is done.
+
+=head1 NOTES
+
+The B<EVP_PKEY> structure is used by various OpenSSL functions which require a
+general private key without reference to any particular algorithm.
+
+The structure returned by EVP_PKEY_new() is empty. To add a private key to this
+empty structure the functions described in L<EVP_PKEY_set1_RSA(3)> should be
+used.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> structure or
+B<NULL> if an error occurred.
+
+EVP_PKEY_up_ref() returns 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_set1_RSA(3)>
+
+=head1 HISTORY
+
+EVP_PKEY_new() and EVP_PKEY_free() exist in all versions of OpenSSL.
+
+EVP_PKEY_up_ref() was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public key algorithm printing routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey,
+ int indent, ASN1_PCTX *pctx);
+ int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey,
+ int indent, ASN1_PCTX *pctx);
+ int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey,
+ int indent, ASN1_PCTX *pctx);
+
+=head1 DESCRIPTION
+
+The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and
+EVP_PKEY_print_params() print out the public, private or parameter components
+of key B<pkey> respectively. The key is sent to BIO B<out> in human readable
+form. The parameter B<indent> indicated how far the printout should be indented.
+
+The B<pctx> parameter allows the print output to be finely tuned by using
+ASN1 printing options. If B<pctx> is set to NULL then default values will
+be used.
+
+=head1 NOTES
+
+Currently no public key algorithms include any options in the B<pctx> parameter
+parameter.
+
+If the key does not include all the components indicated by the function then
+only those contained in the key will be printed. For example passing a public
+key to EVP_PKEY_print_private() will only print the public components.
+
+=head1 RETURN VALUES
+
+These functions all return 1 for success and 0 or a negative value for failure.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_keygen(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
+EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
+EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
+EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY,
+EVP_PKEY_get0_hmac,
+EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id
+- EVP_PKEY assignment functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
+ int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
+ int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
+ int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
+
+ RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
+ DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
+ DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
+ EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
+
+ const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
+ RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey);
+ DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey);
+ DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey);
+ EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey);
+
+ int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
+ int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
+ int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
+ int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
+
+ int EVP_PKEY_id(const EVP_PKEY *pkey);
+ int EVP_PKEY_base_id(const EVP_PKEY *pkey);
+ int EVP_PKEY_type(int type);
+
+=head1 DESCRIPTION
+
+EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
+EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>.
+
+EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
+EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
+B<NULL> if the key is not of the correct type.
+
+EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(),
+EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the
+referenced key in B<pkey> or B<NULL> if the key is not of the
+correct type but the reference count of the returned key is
+B<not> incremented and so must not be freed up after use.
+
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
+however these use the supplied B<key> internally and so B<key>
+will be freed when the parent B<pkey> is freed.
+
+EVP_PKEY_base_id() returns the type of B<pkey>. For example
+an RSA key will return B<EVP_PKEY_RSA>.
+
+EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys
+using the same algorithm could use different OIDs. For example an RSA key could
+use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to
+B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of
+alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not
+often seen in practice.
+
+EVP_PKEY_type() returns the underlying type of the NID B<type>. For example
+EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
+
+=head1 NOTES
+
+In accordance with the OpenSSL naming convention the key obtained
+from or assigned to the B<pkey> using the B<1> functions must be
+freed as well as B<pkey>.
+
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+and EVP_PKEY_assign_EC_KEY() are implemented as macros.
+
+Most applications wishing to know a key type will simply call
+EVP_PKEY_base_id() and will not care about the actual type:
+which will be identical in almost all cases.
+
+Previous versions of this document suggested using EVP_PKEY_type(pkey->type)
+to determine the type of a key. Since B<EVP_PKEY> is now opaque this
+is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
+
+=head1 RETURN VALUES
+
+EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
+EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
+
+EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
+EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
+an error occurred.
+
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
+
+EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key
+type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
+ unsigned char *sig, size_t *siglen,
+ const unsigned char *tbs, size_t tbslen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_sign_init() function initializes a public key algorithm
+context using key B<pkey> for a signing operation.
+
+The EVP_PKEY_sign() function performs a public key signing operation
+using B<ctx>. The data to be signed is specified using the B<tbs> and
+B<tbslen> parameters. If B<sig> is B<NULL> then the maximum size of the output
+buffer is written to the B<siglen> parameter. If B<sig> is not B<NULL> then
+before the call the B<siglen> parameter should contain the length of the
+B<sig> buffer, if the call is successful the signature is written to
+B<sig> and the amount of data written to B<siglen>.
+
+=head1 NOTES
+
+EVP_PKEY_sign() does not hash the data to be signed, and therefore is
+normally used to sign digests. For signing arbitrary messages, see the
+L<EVP_DigestSignInit(3)> and
+L<EVP_SignInit(3)> signing interfaces instead.
+
+After the call to EVP_PKEY_sign_init() algorithm specific control
+operations can be performed to set any appropriate parameters for the
+operation (see L<EVP_PKEY_CTX_ctrl(3)>).
+
+The function EVP_PKEY_sign() can be called more than once on the same
+context if several operations are performed using the same parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0
+or a negative value for failure. In particular a return value of -2
+indicates the operation is not supported by the public key algorithm.
+
+=head1 EXAMPLE
+
+Sign data using RSA with PKCS#1 padding and SHA256 digest:
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ /* md is a SHA-256 digest in this example. */
+ unsigned char *md, *sig;
+ size_t mdlen = 32, siglen;
+ EVP_PKEY *signing_key;
+
+ /*
+ * NB: assumes signing_key and md are set up before the next
+ * step. signing_key must be an RSA private key and md must
+ * point to the SHA-256 digest to be signed.
+ */
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_sign_init(ctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
+ /* Error */
+
+ /* Determine buffer length */
+ if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)
+ /* Error */
+
+ sig = OPENSSL_malloc(siglen);
+
+ if (!sig)
+ /* malloc failure */
+
+ if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)
+ /* Error */
+
+ /* Signature is siglen bytes written to buffer sig */
+
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
+ const unsigned char *sig, size_t siglen,
+ const unsigned char *tbs, size_t tbslen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_verify_init() function initializes a public key algorithm
+context using key B<pkey> for a signature verification operation.
+
+The EVP_PKEY_verify() function performs a public key verification operation
+using B<ctx>. The signature is specified using the B<sig> and
+B<siglen> parameters. The verified data (i.e. the data believed originally
+signed) is specified using the B<tbs> and B<tbslen> parameters.
+
+=head1 NOTES
+
+After the call to EVP_PKEY_verify_init() algorithm specific control
+operations can be performed to set any appropriate parameters for the
+operation.
+
+The function EVP_PKEY_verify() can be called more than once on the same
+context if several operations are performed using the same parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was
+successful and 0 if it failed. Unlike other functions the return value 0 from
+EVP_PKEY_verify() only indicates that the signature did not not verify
+successfully (that is tbs did not match the original data or the signature was
+of invalid form) it is not an indication of a more serious error.
+
+A negative value indicates an error other that signature verification failure.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
+
+=head1 EXAMPLE
+
+Verify signature using PKCS#1 and SHA256 digest:
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ unsigned char *md, *sig;
+ size_t mdlen, siglen;
+ EVP_PKEY *verify_key;
+ /* NB: assumes verify_key, sig, siglen md and mdlen are already set up
+ * and that verify_key is an RSA public key
+ */
+ ctx = EVP_PKEY_CTX_new(verify_key);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_verify_init(ctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
+ /* Error */
+
+ /* Perform operation */
+ ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);
+
+ /* ret == 1 indicates success, 0 verify failure and < 0 for some
+ * other error.
+ */
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
+ unsigned char *rout, size_t *routlen,
+ const unsigned char *sig, size_t siglen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
+context using key B<pkey> for a verify recover operation.
+
+The EVP_PKEY_verify_recover() function recovers signed data
+using B<ctx>. The signature is specified using the B<sig> and
+B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output
+buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then
+before the call the B<routlen> parameter should contain the length of the
+B<rout> buffer, if the call is successful recovered data is written to
+B<rout> and the amount of data written to B<routlen>.
+
+=head1 NOTES
+
+Normally an application is only interested in whether a signature verification
+operation is successful in those cases the EVP_verify() function should be
+used.
+
+Sometimes however it is useful to obtain the data originally signed using a
+signing operation. Only certain public key algorithms can recover a signature
+in this way (for example RSA in PKCS padding mode).
+
+After the call to EVP_PKEY_verify_recover_init() algorithm specific control
+operations can be performed to set any appropriate parameters for the
+operation.
+
+The function EVP_PKEY_verify_recover() can be called more than once on the same
+context if several operations are performed using the same parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for success
+and 0 or a negative value for failure. In particular a return value of -2
+indicates the operation is not supported by the public key algorithm.
+
+=head1 EXAMPLE
+
+Recover digest originally signed using PKCS#1 and SHA256 digest:
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ unsigned char *rout, *sig;
+ size_t routlen, siglen;
+ EVP_PKEY *verify_key;
+ /* NB: assumes verify_key, sig and siglen are already set up
+ * and that verify_key is an RSA public key
+ */
+ ctx = EVP_PKEY_CTX_new(verify_key);
+ if (!ctx)
+ /* Error occurred */
+ if (EVP_PKEY_verify_recover_init(ctx) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
+ /* Error */
+ if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
+ /* Error */
+
+ /* Determine buffer length */
+ if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0)
+ /* Error */
+
+ rout = OPENSSL_malloc(routlen);
+
+ if (!rout)
+ /* malloc failure */
+
+ if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0)
+ /* Error */
+
+ /* Recovered data is routlen bytes written to buffer rout */
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_derive(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+ unsigned char **ek, int *ekl, unsigned char *iv,
+ EVP_PKEY **pubk, int npubk);
+ int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl, unsigned char *in, int inl);
+ int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int *outl);
+
+=head1 DESCRIPTION
+
+The EVP envelope routines are a high level interface to envelope
+encryption. They generate a random key and IV (if required) then
+"envelope" it by using public key encryption. Data can then be
+encrypted using this key.
+
+EVP_SealInit() initializes a cipher context B<ctx> for encryption
+with cipher B<type> using a random secret key and IV. B<type> is normally
+supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted
+using one or more public keys, this allows the same encrypted data to be
+decrypted using any of the corresponding private keys. B<ek> is an array of
+buffers where the public key encrypted secret key will be written, each buffer
+must contain enough room for the corresponding encrypted key: that is
+B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual
+size of each encrypted secret key is written to the array B<ekl>. B<pubk> is
+an array of B<npubk> public keys.
+
+The B<iv> parameter is a buffer where the generated IV is written to. It must
+contain enough room for the corresponding cipher's IV, as determined by (for
+example) EVP_CIPHER_iv_length(type).
+
+If the cipher does not require an IV then the B<iv> parameter is ignored
+and can be B<NULL>.
+
+EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties
+as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as
+documented on the L<EVP_EncryptInit(3)> manual
+page.
+
+=head1 RETURN VALUES
+
+EVP_SealInit() returns 0 on error or B<npubk> if successful.
+
+EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for
+failure.
+
+=head1 NOTES
+
+Because a random secret key is generated the random number generator
+must be seeded before calling EVP_SealInit().
+
+The public key must be RSA because it is the only OpenSSL public key
+algorithm that supports key transport.
+
+Envelope encryption is the usual method of using public key encryption
+on large amounts of data, this is because public key encryption is slow
+but symmetric encryption is fast. So symmetric encryption is used for
+bulk encryption and the small random symmetric key used is transferred
+using public key encryption.
+
+It is possible to call EVP_SealInit() twice in the same way as
+EVP_EncryptInit(). The first call should have B<npubk> set to 0
+and (after setting any cipher parameters) it should be called again
+with B<type> set to NULL.
+
+=head1 SEE ALSO
+
+L<evp(3)>, L<rand(3)>,
+L<EVP_EncryptInit(3)>,
+L<EVP_OpenInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_PKEY_size,
+EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing
+functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s, EVP_PKEY *pkey);
+
+ void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+
+ int EVP_PKEY_size(EVP_PKEY *pkey);
+
+=head1 DESCRIPTION
+
+The EVP signature routines are a high level interface to digital
+signatures.
+
+EVP_SignInit_ex() sets up signing context B<ctx> to use digest
+B<type> from ENGINE B<impl>. B<ctx> must be created with
+EVP_MD_CTX_new() before calling this function.
+
+EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
+signature context B<ctx>. This function can be called several times on the
+same B<ctx> to include additional data.
+
+EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
+places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey)
+bytes in size. B<s> is an OUT parameter, and not used as an IN parameter.
+The number of bytes of data written (i.e. the length of the signature)
+will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
+will be written.
+
+EVP_SignInit() initializes a signing context B<ctx> to use the default
+implementation of digest B<type>.
+
+EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
+signature returned by EVP_SignFinal() may be smaller.
+
+=head1 RETURN VALUES
+
+EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
+for success and 0 for failure.
+
+EVP_PKEY_size() returns the maximum size of a signature in bytes.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 NOTES
+
+The B<EVP> interface to digital signatures should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the algorithm used and much more flexible.
+
+Due to the link between message digests and public key algorithms the correct
+digest algorithm must be used with the correct public key type. A list of
+algorithms and associated public key algorithms appears in
+L<EVP_DigestInit(3)>.
+
+When signing with DSA private keys the random number generator must be seeded
+or the operation will fail. The random number generator does not need to be
+seeded for RSA signatures.
+
+The call to EVP_SignFinal() internally finalizes a copy of the digest context.
+This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called
+later to digest and sign additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
+=head1 BUGS
+
+Older versions of this documentation wrongly stated that calls to
+EVP_SignUpdate() could not be made after calling EVP_SignFinal().
+
+Since the private key is passed in the call to EVP_SignFinal() any error
+relating to the private key (for example an unsuitable key and digest
+combination) will not be indicated until after potentially large amounts of
+data have been passed through EVP_SignUpdate().
+
+It is not possible to change the signing parameters using these function.
+
+The previous two bugs are fixed in the newer EVP_SignDigest*() function.
+
+=head1 SEE ALSO
+
+L<EVP_VerifyInit(3)>,
+L<EVP_DigestInit(3)>, L<err(3)>,
+L<evp(3)>, L<hmac(3)>, L<md2(3)>,
+L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
+L<sha(3)>, L<dgst(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_VerifyInit_ex,
+EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal
+- EVP signature verification functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen, EVP_PKEY *pkey);
+
+ int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+
+=head1 DESCRIPTION
+
+The EVP signature verification routines are a high level interface to digital
+signatures.
+
+EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest
+B<type> from ENGINE B<impl>. B<ctx> must be created by calling
+EVP_MD_CTX_new() before calling this function.
+
+EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
+verification context B<ctx>. This function can be called several times on the
+same B<ctx> to include additional data.
+
+EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey>
+and against the B<siglen> bytes at B<sigbuf>.
+
+EVP_VerifyInit() initializes verification context B<ctx> to use the default
+implementation of digest B<type>.
+
+=head1 RETURN VALUES
+
+EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for
+failure.
+
+EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some
+other error occurred.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 NOTES
+
+The B<EVP> interface to digital signatures should almost always be used in
+preference to the low level interfaces. This is because the code then becomes
+transparent to the algorithm used and much more flexible.
+
+Due to the link between message digests and public key algorithms the correct
+digest algorithm must be used with the correct public key type. A list of
+algorithms and associated public key algorithms appears in
+L<EVP_DigestInit(3)>.
+
+The call to EVP_VerifyFinal() internally finalizes a copy of the digest context.
+This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called
+later to digest and verify additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
+
+=head1 BUGS
+
+Older versions of this documentation wrongly stated that calls to
+EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().
+
+Since the public key is passed in the call to EVP_SignFinal() any error
+relating to the private key (for example an unsuitable key and digest
+combination) will not be indicated until after potentially large amounts of
+data have been passed through EVP_SignUpdate().
+
+It is not possible to change the signing parameters using these function.
+
+The previous two bugs are fixed in the newer EVP_VerifyDigest*() function.
+
+=head1 SEE ALSO
+
+L<evp(3)>,
+L<EVP_SignInit(3)>,
+L<EVP_DigestInit(3)>, L<err(3)>,
+L<evp(3)>, L<hmac(3)>, L<md2(3)>,
+L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
+L<sha(3)>, L<dgst(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+HMAC,
+HMAC_CTX_new,
+HMAC_CTX_reset,
+HMAC_CTX_free,
+HMAC_Init,
+HMAC_Init_ex,
+HMAC_Update,
+HMAC_Final,
+HMAC_CTX_copy,
+HMAC_CTX_set_flags,
+HMAC_CTX_get_md
+- HMAC message authentication code
+
+=head1 SYNOPSIS
+
+ #include <openssl/hmac.h>
+
+ unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
+ int key_len, const unsigned char *d, int n,
+ unsigned char *md, unsigned int *md_len);
+
+ HMAC_CTX *HMAC_CTX_new(void);
+ int HMAC_CTX_reset(HMAC_CTX *ctx);
+
+ int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
+ const EVP_MD *md, ENGINE *impl);
+ int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);
+ int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
+
+ void HMAC_CTX_free(HMAC_CTX *ctx);
+
+ int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx);
+ void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags);
+ const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
+ const EVP_MD *md);
+ #endif
+
+=head1 DESCRIPTION
+
+HMAC is a MAC (message authentication code), i.e. a keyed hash
+function used for message authentication, which is based on a hash
+function.
+
+HMAC() computes the message authentication code of the B<n> bytes at
+B<d> using the hash function B<evp_md> and the key B<key> which is
+B<key_len> bytes long.
+
+It places the result in B<md> (which must have space for the output of
+the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes).
+If B<md> is NULL, the digest is placed in a static array. The size of
+the output is placed in B<md_len>, unless it is B<NULL>.
+
+B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
+
+HMAC_CTX_new() creates a new HMAC_CTX in heap memory.
+
+HMAC_CTX_reset() zeroes an existing B<HMAC_CTX> and associated
+resources, making it suitable for new computations as if it was newly
+created with HMAC_CTX_new().
+
+HMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>,
+releases any associated resources and finally frees the B<HMAC_CTX>
+itself.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
+function B<evp_md> and the key B<key> which is B<key_len> bytes
+long. It is deprecated and only included for backward compatibility
+with OpenSSL 0.9.6b.
+
+HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash
+function B<evp_md> and key B<key>. If both are NULL (or B<evp_md> is the same
+as the previous digest used by B<ctx> and B<key> is NULL) the existing key is
+reused. B<ctx> must have been created with HMAC_CTX_new() before the first use
+of an B<HMAC_CTX> in this function. B<N.B. HMAC_Init() had this undocumented
+behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex()
+in programs that expect it will cause them to stop working>.
+
+B<NOTE:> If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the
+same as the previous digest used by B<ctx> then an error is returned
+because reuse of an existing key with a different digest is not supported.
+
+HMAC_Update() can be called repeatedly with chunks of the message to
+be authenticated (B<len> bytes at B<data>).
+
+HMAC_Final() places the message authentication code in B<md>, which
+must have space for the hash function output.
+
+HMAC_CTX_copy() copies all of the internal state from B<sctx> into B<dctx>.
+
+HMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTXs.
+These flags have the same meaning as for L<EVP_MD_CTX_set_flags(3)>.
+
+HMAC_CTX_get_md() returns the EVP_MD that has previously been set for the
+supplied HMAC_CTX.
+
+=head1 RETURN VALUES
+
+HMAC() returns a pointer to the message authentication code or NULL if
+an error occurred.
+
+HMAC_CTX_new() returns a pointer to a new B<HMAC_CTX> on success or
+B<NULL> if an error occurred.
+
+HMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and
+HMAC_CTX_copy() return 1 for success or 0 if an error occurred.
+
+HMAC_CTX_get_md() return the EVP_MD previously set for the supplied HMAC_CTX or
+NULL if no EVP_MD has been set.
+
+=head1 CONFORMING TO
+
+RFC 2104
+
+=head1 SEE ALSO
+
+L<sha(3)>, L<evp(3)>
+
+=head1 HISTORY
+
+HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL versions 1.1.0.
+
+HMAC_CTX_cleanup() existed in OpenSSL versions before 1.1.0.
+
+HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL version
+1.1.0.
+
+HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in
+versions of OpenSSL before 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update,
+MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/md2.h>
+
+ unsigned char *MD2(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MD2_Init(MD2_CTX *c);
+ int MD2_Update(MD2_CTX *c, const unsigned char *data,
+ unsigned long len);
+ int MD2_Final(unsigned char *md, MD2_CTX *c);
+
+
+ #include <openssl/md4.h>
+
+ unsigned char *MD4(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MD4_Init(MD4_CTX *c);
+ int MD4_Update(MD4_CTX *c, const void *data,
+ unsigned long len);
+ int MD4_Final(unsigned char *md, MD4_CTX *c);
+
+
+ #include <openssl/md5.h>
+
+ unsigned char *MD5(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MD5_Init(MD5_CTX *c);
+ int MD5_Update(MD5_CTX *c, const void *data,
+ unsigned long len);
+ int MD5_Final(unsigned char *md, MD5_CTX *c);
+
+=head1 DESCRIPTION
+
+MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output.
+
+MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest
+of the B<n> bytes at B<d> and place it in B<md> (which must have space
+for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16
+bytes of output). If B<md> is NULL, the digest is placed in a static
+array.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+MD2_Init() initializes a B<MD2_CTX> structure.
+
+MD2_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+MD2_Final() places the message digest in B<md>, which must have space
+for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>.
+
+MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and
+MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure.
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)>
+etc. instead of calling the hash functions directly.
+
+=head1 NOTE
+
+MD2, MD4, and MD5 are recommended only for compatibility with existing
+applications. In new applications, SHA-1 or RIPEMD-160 should be
+preferred.
+
+=head1 RETURN VALUES
+
+MD2(), MD4(), and MD5() return pointers to the hash value.
+
+MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(),
+MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for
+success, 0 otherwise.
+
+=head1 CONFORMING TO
+
+RFC 1319, RFC 1320, RFC 1321
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function
+
+=head1 SYNOPSIS
+
+ #include <openssl/mdc2.h>
+
+ unsigned char *MDC2(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int MDC2_Init(MDC2_CTX *c);
+ int MDC2_Update(MDC2_CTX *c, const unsigned char *data,
+ unsigned long len);
+ int MDC2_Final(unsigned char *md, MDC2_CTX *c);
+
+=head1 DESCRIPTION
+
+MDC2 is a method to construct hash functions with 128 bit output from
+block ciphers. These functions are an implementation of MDC2 with
+DES.
+
+MDC2() computes the MDC2 message digest of the B<n>
+bytes at B<d> and places it in B<md> (which must have space for
+MDC2_DIGEST_LENGTH == 16 bytes of output). If B<md> is NULL, the digest
+is placed in a static array.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+MDC2_Init() initializes a B<MDC2_CTX> structure.
+
+MDC2_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+MDC2_Final() places the message digest in B<md>, which must have space
+for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MDC2_CTX>.
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)> etc. instead of calling the
+hash functions directly.
+
+=head1 RETURN VALUES
+
+MDC2() returns a pointer to the hash value.
+
+MDC2_Init(), MDC2_Update() and MDC2_Final() return 1 for success, 0 otherwise.
+
+=head1 CONFORMING TO
+
+ISO/IEC 10118-2, with DES
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+i2t_ASN1_OBJECT,
+OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln,
+OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp,
+OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup
+- ASN1 object utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/objects.h>
+
+ ASN1_OBJECT *OBJ_nid2obj(int n);
+ const char *OBJ_nid2ln(int n);
+ const char *OBJ_nid2sn(int n);
+
+ int OBJ_obj2nid(const ASN1_OBJECT *o);
+ int OBJ_ln2nid(const char *ln);
+ int OBJ_sn2nid(const char *sn);
+
+ int OBJ_txt2nid(const char *s);
+
+ ASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name);
+ int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
+
+ int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a);
+
+ int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b);
+ ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o);
+
+ int OBJ_create(const char *oid, const char *sn, const char *ln);
+
+ size_t OBJ_length(const ASN1_OBJECT *obj);
+ const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void OBJ_cleanup(void)
+ #endif
+
+=head1 DESCRIPTION
+
+The ASN1 object utility functions process ASN1_OBJECT structures which are
+a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
+For convenience, OIDs are usually represented in source code as numeric
+identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that
+are generated when the library is built, and their corresponding NIDs
+are available as defined constants. For the functions below, application
+code should treat all returned values -- OIDs, NIDs, or names -- as
+constants.
+
+OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
+an ASN1_OBJECT structure, its long name and its short name respectively,
+or B<NULL> is an error occurred.
+
+OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
+for the object B<o>, the long name <ln> or the short name <sn> respectively
+or NID_undef if an error occurred.
+
+OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
+a long name, a short name or the numerical representation of an object.
+
+OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
+If B<no_name> is 0 then long names and short names will be interpreted
+as well as numerical forms. If B<no_name> is 1 only the numerical form
+is acceptable.
+
+OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.
+The representation is written as a null terminated string to B<buf>
+at most B<buf_len> bytes are written, truncating the result if necessary.
+The total amount of space required is returned. If B<no_name> is 0 then
+if the object has a long or short name then that will be used, otherwise
+the numerical form will be used. If B<no_name> is 1 then the numerical
+form will always be used.
+
+i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero.
+
+OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
+
+OBJ_dup() returns a copy of B<o>.
+
+OBJ_create() adds a new object to the internal table. B<oid> is the
+numerical form of the object, B<sn> the short name and B<ln> the
+long name. A new NID is returned for the created object.
+
+OBJ_length() returns the size of the content octets of B<obj>.
+
+OBJ_get0_data() returns a pointer to the content octets of B<obj>.
+The returned pointer is an internal pointer which B<must not> be freed.
+
+In OpenSSL versions prior to 1.1.0 OBJ_cleanup() cleaned up OpenSSLs internal
+object table and was called before an application exits if any new objects were
+added using OBJ_create(). This function is deprecated in version 1.1.0 and now
+does nothing if called. No explicit de-initialisation is now required. See
+L<OPENSSL_init_crypto(3)> for further information.
+
+=head1 NOTES
+
+Objects in OpenSSL can have a short name, a long name and a numerical
+identifier (NID) associated with them. A standard set of objects is
+represented in an internal table. The appropriate values are defined
+in the header file B<objects.h>.
+
+For example the OID for commonName has the following definitions:
+
+ #define SN_commonName "CN"
+ #define LN_commonName "commonName"
+ #define NID_commonName 13
+
+New objects can be added by calling OBJ_create().
+
+Table objects have certain advantages over other objects: for example
+their NIDs can be used in a C language switch statement. They are
+also static constant structures which are shared: that is there
+is only a single constant structure for each table object.
+
+Objects which are not in the table have the NID value NID_undef.
+
+Objects do not need to be in the internal tables to be processed,
+the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical
+form of an OID.
+
+Some objects are used to represent algorithms which do not have a
+corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently
+exists for a particular algorithm). As a result they B<cannot> be encoded or
+decoded as part of ASN.1 structures. Applications can determine if there
+is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.
+
+These functions cannot return B<const> because an B<ASN1_OBJECT> can
+represent both an internal, constant, OID and a dynamically-created one.
+The latter cannot be constant because it needs to be freed after use.
+
+=head1 EXAMPLES
+
+Create an object for B<commonName>:
+
+ ASN1_OBJECT *o;
+ o = OBJ_nid2obj(NID_commonName);
+
+Check if an object is B<commonName>
+
+ if (OBJ_obj2nid(obj) == NID_commonName)
+ /* Do something */
+
+Create a new NID and initialize an object from it:
+
+ int new_nid;
+ ASN1_OBJECT *obj;
+
+ new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
+
+ obj = OBJ_nid2obj(new_nid);
+
+Create a new object directly:
+
+ obj = OBJ_txt2obj("1.2.3.4", 1);
+
+=head1 BUGS
+
+OBJ_obj2txt() is awkward and messy to use: it doesn't follow the
+convention of other OpenSSL functions where the buffer can be set
+to B<NULL> to determine the amount of data that should be written.
+Instead B<buf> must point to a valid buffer and B<buf_len> should
+be set to a positive value. A buffer length of 80 should be more
+than enough to handle any OID encountered in practice.
+
+=head1 RETURN VALUES
+
+OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
+error occurred.
+
+OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
+on error.
+
+OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
+a NID or B<NID_undef> on error.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+
+=head1 HISTORY
+
+OBJ_cleanup() was deprecated in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign,
+OCSP_request_add1_cert, OCSP_request_onereq_count,
+OCSP_request_onereq_get0 - OCSP request functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ocsp.h>
+
+ OCSP_REQUEST *OCSP_REQUEST_new(void);
+ void OCSP_REQUEST_free(OCSP_REQUEST *req);
+
+ OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid);
+
+ int OCSP_request_sign(OCSP_REQUEST *req,
+ X509 *signer, EVP_PKEY *key, const EVP_MD *dgst,
+ STACK_OF(X509) *certs, unsigned long flags);
+
+ int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert);
+
+ int OCSP_request_onereq_count(OCSP_REQUEST *req);
+ OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i);
+
+=head1 DESCRIPTION
+
+OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure.
+
+OCSP_REQUEST_free() frees up the request structure B<req>.
+
+OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns
+the B<OCSP_ONEREQ> structure added so an application can add additional
+extensions to the request. The B<id> parameter B<MUST NOT> be freed up after
+the operation.
+
+OCSP_request_sign() signs OCSP request B<req> using certificate
+B<signer>, private key B<key>, digest B<dgst> and additional certificates
+B<certs>. If the B<flags> option B<OCSP_NOCERTS> is set then no certificates
+will be included in the request.
+
+OCSP_request_add1_cert() adds certificate B<cert> to request B<req>. The
+application is responsible for freeing up B<cert> after use.
+
+OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
+structures in B<req>.
+
+OCSP_request_onereq_get0() returns an internal pointer to the B<OCSP_ONEREQ>
+contained in B<req> of index B<i>. The index value B<i> runs from 0 to
+OCSP_request_onereq_count(req) - 1.
+
+=head1 RETURN VALUES
+
+OCSP_REQUEST_new() returns an empty B<OCSP_REQUEST> structure or B<NULL> if
+an error occurred.
+
+OCSP_request_add0_id() returns the B<OCSP_ONEREQ> structure containing B<cid>
+or B<NULL> if an error occurred.
+
+OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0
+for failure.
+
+OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ>
+structures in B<req>.
+
+OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure
+or B<NULL> if the index value is out or range.
+
+=head1 NOTES
+
+An OCSP request structure contains one or more B<OCSP_ONEREQ> structures
+corresponding to each certificate.
+
+OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
+OCSP responders.
+
+=head1 EXAMPLE
+
+Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
+B<issuer>:
+
+ OCSP_REQUEST *req;
+ OCSP_ID *cid;
+
+ req = OCSP_REQUEST_new();
+ if (req == NULL)
+ /* error */
+ cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);
+ if (cid == NULL)
+ /* error */
+
+ if (OCSP_REQUEST_add0_id(req, cid) == NULL)
+ /* error */
+
+ /* Do something with req, e.g. query responder */
+
+ OCSP_REQUEST_free(req);
+
+=head1 SEE ALSO
+
+L<crypto(3)>,
+L<OCSP_cert_to_id(3)>,
+L<OCSP_request_add1_nonce(3)>,
+L<OCSP_response_find_status(3)>,
+L<OCSP_response_status(3)>,
+L<OCSP_sendreq_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OCSP_cert_to_id, OCSP_cert_id_new, OCSP_CERTID_free, OCSP_id_issuer_cmp,
+OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ocsp.h>
+
+ OCSP_CERTID *OCSP_cert_to_id(const EVP_MD *dgst,
+ X509 *subject, X509 *issuer);
+
+ OCSP_CERTID *OCSP_cert_id_new(const EVP_MD *dgst,
+ X509_NAME *issuerName,
+ ASN1_BIT_STRING *issuerKey,
+ ASN1_INTEGER *serialNumber);
+
+ void OCSP_CERTID_free(OCSP_CERTID *id);
+
+ int OCSP_id_issuer_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
+ int OCSP_id_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
+
+ int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd,
+ ASN1_OCTET_STRING **pikeyHash,
+ ASN1_INTEGER **pserial, OCSP_CERTID *cid);
+
+
+=head1 DESCRIPTION
+
+OCSP_cert_to_id() creates and returns a new B<OCSP_CERTID> structure using
+message digest B<dgst> for certificate B<subject> with issuer B<issuer>. If
+B<dgst> is B<NULL> then SHA1 is used.
+
+OCSP_cert_id_new() creates and returns a new B<OCSP_CERTID> using B<dgst> and
+issuer name B<issuerName>, issuer key hash B<issuerKey> and serial number
+B<serialNumber>.
+
+OCSP_CERTID_free() frees up B<id>.
+
+OCSP_id_cmp() compares B<OCSP_CERTID> B<a> and B<b>.
+
+OCSP_id_issuer_cmp() compares only the issuer name of B<OCSP_CERTID> B<a> and B<b>.
+
+OCSP_id_get0_info() returns the issuer name hash, hash OID, issuer key hash and
+serial number contained in B<cid>. If any of the values are not required the
+corresponding parameter can be set to B<NULL>.
+
+=head1 RETURN VALUES
+
+OCSP_cert_to_id() and OCSP_cert_id_new() return either a pointer to a valid
+B<OCSP_CERTID> structure or B<NULL> if an error occurred.
+
+OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and non-zero
+otherwise.
+
+OCSP_CERTID_free() does not return a value.
+
+OCSP_id_get0_info() returns 1 for success and 0 for failure.
+
+=head1 NOTES
+
+OCSP clients will typically only use OCSP_cert_to_id() or OCSP_cert_id_new():
+the other functions are used by responder applications.
+
+The values returned by OCSP_id_get0_info() are internal pointers and B<MUST
+NOT> be freed up by an application: they will be freed when the corresponding
+B<OCSP_CERTID> structure is freed.
+
+=head1 SEE ALSO
+
+L<crypto(3)>,
+L<OCSP_request_add1_nonce(3)>,
+L<OCSP_REQUEST_new(3)>,
+L<OCSP_response_find_status(3)>,
+L<OCSP_response_status(3)>,
+L<OCSP_sendreq_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce - OCSP nonce functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ocsp.h>
+
+ int OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len);
+ int OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len);
+ int OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req);
+ int OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp);
+
+=head1 DESCRIPTION
+
+OCSP_request_add1_nonce() adds a nonce of value B<val> and length B<len> to
+OCSP request B<req>. If B<val> is B<NULL> a random nonce is used. If B<len>
+is zero or negative a default length will be used (currently 16 bytes).
+
+OCSP_basic_add1_nonce() is identical to OCSP_request_add1_nonce() except
+it adds a nonce to OCSP basic response B<resp>.
+
+OCSP_check_nonce() compares the nonce value in B<req> and B<resp>.
+
+OCSP_copy_nonce() copys any nonce value present in B<req> to B<resp>.
+
+=head1 RETURN VALUES
+
+OCSP_request_add1_nonce() and OCSP_basic_add1_nonce() return 1 for success
+and 0 for failure.
+
+OCSP_copy_nonce() returns 1 if a nonce was successfully copied, 2 if no nonce
+was present in B<req> and 0 if an error occurred.
+
+OCSP_check_nonce() returns the result of the nonce comparison between B<req>
+and B<resp>. The return value indicates the result of the comparison. If
+nonces are present and equal 1 is returned. If the nonces are absent 2 is
+returned. If a nonce is present in the response only 3 is returned. If nonces
+are present and unequal 0 is returned. If the nonce is present in the request
+only then -1 is returned.
+
+=head1 NOTES
+
+For most purposes the nonce value in a request is set to a random value so
+the B<val> parameter in OCSP_request_add1_nonce() is usually NULL.
+
+An OCSP nonce is typically added to an OCSP request to thwart replay attacks
+by checking the same nonce value appears in the response.
+
+Some responders may include a nonce in all responses even if one is not
+supplied.
+
+Some responders cache OCSP responses and do not sign each response for
+performance reasons. As a result they do not support nonces.
+
+The return values of OCSP_check_nonce() can be checked to cover each case. A
+positive return value effectively indicates success: nonces are both present
+and match, both absent or present in the response only. A non-zero return
+additionally covers the case where the nonce is present in the request only:
+this will happen if the responder doesn't support nonces. A zero return value
+indicates present and mismatched nonces: this should be treated as an error
+condition.
+
+=head1 SEE ALSO
+
+L<crypto(3)>,
+L<OCSP_cert_to_id(3)>,
+L<OCSP_REQUEST_new(3)>,
+L<OCSP_response_find_status(3)>,
+L<OCSP_response_status(3)>,
+L<OCSP_sendreq_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OCSP_resp_get0_certs,
+OCSP_resp_get0_id,
+OCSP_resp_get0_produced_at,
+OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find,
+OCSP_single_get0_status, OCSP_check_validity
+- OCSP response utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ocsp.h>
+
+ int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,
+ int *reason,
+ ASN1_GENERALIZEDTIME **revtime,
+ ASN1_GENERALIZEDTIME **thisupd,
+ ASN1_GENERALIZEDTIME **nextupd);
+
+ int OCSP_resp_count(OCSP_BASICRESP *bs);
+ OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx);
+ int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last);
+ int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,
+ ASN1_GENERALIZEDTIME **revtime,
+ ASN1_GENERALIZEDTIME **thisupd,
+ ASN1_GENERALIZEDTIME **nextupd);
+
+ const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(
+ const OCSP_BASICRESP* single);
+
+ const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs);
+
+ int OCSP_resp_get0_id(const OCSP_BASICRESP *bs,
+ const ASN1_OCTET_STRING **pid,
+ const X509_NAME **pname);
+
+ int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,
+ ASN1_GENERALIZEDTIME *nextupd,
+ long sec, long maxsec);
+
+=head1 DESCRIPTION
+
+OCSP_resp_find_status() searches B<bs> for an OCSP response for B<id>. If it is
+successful the fields of the response are returned in B<*status>, B<*reason>,
+B<*revtime>, B<*thisupd> and B<*nextupd>. The B<*status> value will be one of
+B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or
+B<V_OCSP_CERTSTATUS_UNKNOWN>. The B<*reason> and B<*revtime> fields are only
+set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the B<*reason> field
+will be set to the revocation reason which will be one of
+B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>,
+B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>,
+B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>,
+B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>,
+B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>.
+
+OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in B<bs>.
+
+OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in B<bs>
+corresponding to index B<idx>. Where B<idx> runs from 0 to
+OCSP_resp_count(bs) - 1.
+
+OCSP_resp_find() searches B<bs> for B<id> and returns the index of the first
+matching entry after B<last> or starting from the beginning if B<last> is -1.
+
+OCSP_single_get0_status() extracts the fields of B<single> in B<*reason>,
+B<*revtime>, B<*thisupd> and B<*nextupd>.
+
+OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the
+single response B<bs>.
+
+OCSP_resp_get0_certs() returns any certificates included in B<bs>.
+
+OCSP_resp_get0_id() gets the responder id of <bs>. If the responder ID is
+a name then <*pname> is set to the name and B<*pid> is set to NULL. If the
+responder ID is by key ID then B<*pid> is set to the key ID and B<*pname>
+is set to NULL.
+
+OCSP_check_validity() checks the validity of B<thisupd> and B<nextupd> values
+which will be typically obtained from OCSP_resp_find_status() or
+OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds
+leeway should be allowed in the check. If B<maxsec> is positive it indicates
+the maximum age of B<thisupd> in seconds.
+
+=head1 RETURN VALUES
+
+OCSP_resp_find_status() returns 1 if B<id> is found in B<bs> and 0 otherwise.
+
+OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in
+B<bs>.
+
+OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or
+B<NULL> if B<idx> is out of range.
+
+OCSP_resp_find() returns the index of B<id> in B<bs> (which may be 0) or -1 if
+B<id> was not found.
+
+OCSP_single_get0_status() returns the status of B<single> or -1 if an error
+occurred.
+
+=head1 NOTES
+
+Applications will typically call OCSP_resp_find_status() using the certificate
+ID of interest and then check its validity using OCSP_check_validity(). They
+can then take appropriate action based on the status of the certificate.
+
+An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate>
+fields. Normally the current time should be between these two values. To
+account for clock skew the B<maxsec> field can be set to non-zero in
+OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this
+would otherwise mean an ancient response would be considered valid: the
+B<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted
+age of responses.
+
+The values written to B<*revtime>, B<*thisupd> and B<*nextupd> by
+OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers
+which B<MUST NOT> be freed up by the calling application. Any or all of these
+parameters can be set to NULL if their value is not required.
+
+=head1 SEE ALSO
+
+L<crypto(3)>,
+L<OCSP_cert_to_id(3)>,
+L<OCSP_request_add1_nonce(3)>,
+L<OCSP_REQUEST_new(3)>,
+L<OCSP_response_status(3)>,
+L<OCSP_sendreq_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create,
+OCSP_RESPONSE_free, OCSP_RESPID_set_by_name,
+OCSP_RESPID_set_by_key, OCSP_RESPID_match - OCSP response functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ocsp.h>
+
+ int OCSP_response_status(OCSP_RESPONSE *resp);
+ OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp);
+ OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs);
+ void OCSP_RESPONSE_free(OCSP_RESPONSE *resp);
+
+ int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert);
+ int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert);
+ int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert);
+
+=head1 DESCRIPTION
+
+OCSP_response_status() returns the OCSP response status of B<resp>. It returns
+one of the values: B<OCSP_RESPONSE_STATUS_SUCCESSFUL>,
+B<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>,
+B<OCSP_RESPONSE_STATUS_INTERNALERROR>, B<OCSP_RESPONSE_STATUS_TRYLATER>
+B<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or B<OCSP_RESPONSE_STATUS_UNAUTHORIZED>.
+
+OCSP_response_get1_basic() decodes and returns the B<OCSP_BASICRESP> structure
+contained in B<resp>.
+
+OCSP_response_create() creates and returns an B<OCSP_RESPONSE> structure for
+B<status> and optionally including basic response B<bs>.
+
+OCSP_RESPONSE_free() frees up OCSP response B<resp>.
+
+OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the
+subject name in the supplied X509 certificate B<cert> for the OCSP responder.
+
+OCSP_RESPID_set_by_key() sets the key of the OCSP_RESPID to be the same as the
+key in the supplied X509 certificate B<cert> for the OCSP responder. The key is
+stored as a SHA1 hash.
+
+Note that an OCSP_RESPID can only have one of the name, or the key set. Calling
+OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing
+setting.
+
+OCSP_RESPID_match() tests whether the OCSP_RESPID given in B<respid> matches
+with the X509 certificate B<cert>.
+
+=head1 RETURN VALUES
+
+OCSP_RESPONSE_status() returns a status value.
+
+OCSP_response_get1_basic() returns an B<OCSP_BASICRESP> structure pointer or
+B<NULL> if an error occurred.
+
+OCSP_response_create() returns an B<OCSP_RESPONSE> structure pointer or B<NULL>
+if an error occurred.
+
+OCSP_RESPONSE_free() does not return a value.
+
+OCSP_RESPID_set_by_name() and OCSP_RESPID_set_by_key() return 1 on success or 0
+on failure.
+
+OCSP_RESPID_match() returns 1 if the OCSP_RESPID and the X509 certificate match
+or 0 otherwise.
+
+=head1 NOTES
+
+OCSP_response_get1_basic() is only called if the status of a response is
+B<OCSP_RESPONSE_STATUS_SUCCESSFUL>.
+
+=head1 SEE ALSO
+
+L<crypto(3)>
+L<OCSP_cert_to_id(3)>
+L<OCSP_request_add1_nonce(3)>
+L<OCSP_REQUEST_new(3)>
+L<OCSP_response_find_status(3)>
+L<OCSP_sendreq_new(3)>
+L<OCSP_RESPID_new(3)>
+L<OCSP_RESPID_free(3)>
+
+=head1 HISTORY
+
+The OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key() and OCSP_RESPID_match()
+functions were added in OpenSSL version 1.1.0a.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_REQ_CTX_free,
+OCSP_set_max_response_length, OCSP_REQ_CTX_add1_header,
+OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ocsp.h>
+
+ OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req,
+ int maxline);
+
+ int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx);
+
+ void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx);
+
+ void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len);
+
+ int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx,
+ const char *name, const char *value);
+
+ int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req);
+
+ OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req,
+ int maxline);
+
+=head1 DESCRIPTION
+
+The function OCSP_sendreq_new() returns an B<OCSP_CTX> structure using the
+responder B<io>, the URL path B<path>, the OCSP request B<req> and with a
+response header maximum line length of B<maxline>. If B<maxline> is zero a
+default value of 4k is used. The OCSP request B<req> may be set to B<NULL>
+and provided later if required.
+
+OCSP_sendreq_nbio() performs non-blocking I/O on the OCSP request context
+B<rctx>. When the operation is complete it returns the response in B<*presp>.
+
+OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>.
+
+OCSP_set_max_response_length() sets the maximum response length for B<rctx>
+to B<len>. If the response exceeds this length an error occurs. If not
+set a default value of 100k is used.
+
+OCSP_REQ_CTX_add1_header() adds header B<name> with value B<value> to the
+context B<rctx>. It can be called more than once to add multiple headers.
+It B<MUST> be called before any calls to OCSP_sendreq_nbio(). The B<req>
+parameter in the initial to OCSP_sendreq_new() call MUST be set to B<NULL> if
+additional headers are set.
+
+OCSP_REQ_CTX_set1_req() sets the OCSP request in B<rctx> to B<req>. This
+function should be called after any calls to OCSP_REQ_CTX_add1_header().
+
+OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL
+path B<path>, the OCSP request B<req> and with a response header maximum line
+length of B<maxline>. If B<maxline> is zero a default value of 4k is used.
+
+=head1 RETURN VALUES
+
+OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL> if
+an error occurred.
+
+OCSP_sendreq_nbio() returns B<1> if the operation was completed successfully,
+B<-1> if the operation should be retried and B<0> if an error occurred.
+
+OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req() return B<1> for success
+and B<0> for failure.
+
+OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the
+responder or B<NULL> if an error occurred.
+
+OCSP_REQ_CTX_free() and OCSP_set_max_response_length() do not return values.
+
+=head1 NOTES
+
+These functions only perform a minimal HTTP query to a responder. If an
+application wishes to support more advanced features it should use an
+alternative more complete HTTP library.
+
+Currently only HTTP POST queries to responders are supported.
+
+The arguments to OCSP_sendreq_new() correspond to the components of the URL.
+For example if the responder URL is B<http://ocsp.com/ocspreq> the BIO
+B<io> should be connected to host B<ocsp.com> on port 80 and B<path>
+should be set to B<"/ocspreq">
+
+The headers added with OCSP_REQ_CTX_add1_header() are of the form
+"B<name>: B<value>" or just "B<name>" if B<value> is B<NULL>. So to add
+a Host header for B<ocsp.com> you would call:
+
+ OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
+
+If OCSP_sendreq_nbio() indicates an operation should be retried the
+corresponding BIO can be examined to determine which operation (read or
+write) should be retried and appropriate action taken (for example a select()
+call on the underlying socket).
+
+OCSP_sendreq_bio() does not support retries and so cannot handle non-blocking
+I/O efficiently. It is retained for compatibility and its use in new
+applications is not recommended.
+
+=head1 SEE ALSO
+
+L<crypto(3)>,
+L<OCSP_cert_to_id(3)>,
+L<OCSP_request_add1_nonce(3)>,
+L<OCSP_REQUEST_new(3)>,
+L<OCSP_response_find_status(3)>,
+L<OCSP_response_status(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_Applink - glue between OpenSSL BIO and Win32 compiler run-time
+
+=head1 SYNOPSIS
+
+ __declspec(dllexport) void **OPENSSL_Applink();
+
+=head1 DESCRIPTION
+
+OPENSSL_Applink is application-side interface which provides a glue
+between OpenSSL BIO layer and Win32 compiler run-time environment.
+Even though it appears at application side, it's essentially OpenSSL
+private interface. For this reason application developers are not
+expected to implement it, but to compile provided module with
+compiler of their choice and link it into the target application.
+The referred module is available as F<applink.c>, located alongside
+the public header files (only on the platforms where applicable).
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DECLARE_LHASH_OF,
+OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC,
+LHASH_DOALL_ARG_FN_TYPE,
+IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN,
+lh_TYPE_new, lh_TYPE_free,
+lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve,
+lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ #include <openssl/lhash.h>
+
+ DECLARE_LHASH_OF(TYPE);
+
+ LHASH *lh_TYPE_new();
+ void lh_TYPE_free(LHASH_OF(TYPE *table);
+
+ TYPE *lh_TYPE_insert(LHASH_OF(TYPE *table, TYPE *data);
+ TYPE *lh_TYPE_delete(LHASH_OF(TYPE *table, TYPE *data);
+ TYPE *lh_retrieve(LHASH_OFTYPE *table, TYPE *data);
+
+ void lh_TYPE_doall(LHASH_OF(TYPE *table, OPENSSL_LH_DOALL_FUNC func);
+ void lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func,
+ TYPE, TYPE *arg);
+
+ int lh_TYPE_error(LHASH_OF(TYPE) *table);
+
+ typedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *);
+ typedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *);
+ typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *);
+ typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *);
+
+=head1 DESCRIPTION
+
+This library implements type-checked dynamic hash tables. The hash
+table entries can be arbitrary structures. Usually they consist of key
+and value fields. In the description here, I<TYPE> is used a placeholder
+for any of the OpenSSL datatypes, such as I<SSL_SESSION>.
+
+lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store
+arbitrary data entries, and specifies the 'hash' and 'compare'
+callbacks to be used in organising the table's entries. The B<hash>
+callback takes a pointer to a table entry as its argument and returns
+an unsigned long hash value for its key field. The hash value is
+normally truncated to a power of 2, so make sure that your hash
+function returns well mixed low order bits. The B<compare> callback
+takes two arguments (pointers to two hash table entries), and returns
+0 if their keys are equal, non-zero otherwise.
+
+If your hash table
+will contain items of some particular type and the B<hash> and
+B<compare> callbacks hash/compare these types, then the
+B<IMPLEMENT_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be
+used to create callback wrappers of the prototypes required by
+lh_TYPE_new() as shown in this example:
+
+ /*
+ * Implement the hash and compare functions; "stuff" can be any word.
+ */
+ static unsigned long stuff_hash(const TYPE *a)
+ {
+ ...
+ }
+ static int stuff_cmp(const TYPE *a, const TYPE *b)
+ {
+ ...
+ }
+
+ /*
+ * Implement the wrapper functions.
+ */
+ static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE)
+ static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE)
+
+If the type is going to be used in several places, the following macros
+can be used in a common header file to declare the function wrappers:
+
+ DECLARE_LHASH_HASH_FN(stuff, TYPE)
+ DECLARE_LHASH_COMP_FN(stuff, TYPE)
+
+Then a hash table of TYPE objects can be created using this:
+
+ LHASH_OF(TYPE) *htable;
+
+ htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
+
+lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure
+B<table>. Allocated hash table entries will not be freed; consider
+using lh_TYPE_doall() to deallocate any remaining entries in the
+hash table (see below).
+
+lh_TYPE_insert() inserts the structure pointed to by B<data> into
+B<table>. If there already is an entry with the same key, the old
+value is replaced. Note that lh_TYPE_insert() stores pointers, the
+data are not copied.
+
+lh_TYPE_delete() deletes an entry from B<table>.
+
+lh_TYPE_retrieve() looks up an entry in B<table>. Normally, B<data>
+is a structure with the key field(s) set; the function will return a
+pointer to a fully populated structure.
+
+lh_TYPE_doall() will, for every entry in the hash table, call
+B<func> with the data item as its parameter.
+For example:
+
+ /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */
+ void TYPE_cleanup_doall(TYPE *a);
+
+ /* Implement a prototype-compatible wrapper for "TYPE_cleanup" */
+ IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE)
+
+ /* Call "TYPE_cleanup" against all items in a hash table. */
+ lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup));
+
+ /* Then the hash table itself can be deallocated */
+ lh_TYPE_free(hashtable);
+
+When doing this, be careful if you delete entries from the hash table
+in your callbacks: the table may decrease in size, moving the item
+that you are currently on down lower in the hash table - this could
+cause some entries to be skipped during the iteration. The second
+best solution to this problem is to set hash-E<gt>down_load=0 before
+you start (which will stop the hash table ever decreasing in size).
+The best solution is probably to avoid deleting items from the hash
+table inside a "doall" callback!
+
+lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that
+B<func> will be called with B<arg> as the second argument and B<func>
+should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype
+that is passed both the table entry and an extra argument). As with
+lh_doall(), you can instead choose to declare your callback with a
+prototype matching the types you are dealing with and use the
+declare/implement macros to create compatible wrappers that cast
+variables before calling your type-specific callbacks. An example of
+this is demonstrated here (printing all hash table entries to a BIO
+that is provided by the caller):
+
+ /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */
+ void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio);
+
+ /* Implement a prototype-compatible wrapper for "TYPE_print" */
+ static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO)
+
+ /* Print out the entire hashtable to a particular BIO */
+ lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO,
+ logging_bio);
+
+
+lh_TYPE_error() can be used to determine if an error occurred in the last
+operation.
+
+=head1 RETURN VALUES
+
+lh_TYPE_new() returns B<NULL> on error, otherwise a pointer to the new
+B<LHASH> structure.
+
+When a hash table entry is replaced, lh_TYPE_insert() returns the value
+being replaced. B<NULL> is returned on normal operation and on error.
+
+lh_TYPE_delete() returns the entry being deleted. B<NULL> is returned if
+there is no such value in the hash table.
+
+lh_TYPE_retrieve() returns the hash table entry if it has been found,
+B<NULL> otherwise.
+
+lh_TYPE_error() returns 1 if an error occurred in the last operation, 0
+otherwise.
+
+lh_TYPE_free(), lh_TYPE_doall() and lh_TYPE_doall_arg() return no values.
+
+=head1 NOTE
+
+The various LHASH macros and callback types exist to make it possible
+to write type-checked code without resorting to function-prototype
+casting - an evil that makes application code much harder to
+audit/verify and also opens the window of opportunity for stack
+corruption and other hard-to-find bugs. It also, apparently, violates
+ANSI-C.
+
+The LHASH code regards table entries as constant data. As such, it
+internally represents lh_insert()'d items with a "const void *"
+pointer type. This is why callbacks such as those used by lh_doall()
+and lh_doall_arg() declare their prototypes with "const", even for the
+parameters that pass back the table items' data pointers - for
+consistency, user-provided data is "const" at all times as far as the
+LHASH code is concerned. However, as callers are themselves providing
+these pointers, they can choose whether they too should be treating
+all such parameters as constant.
+
+As an example, a hash table may be maintained by code that, for
+reasons of encapsulation, has only "const" access to the data being
+indexed in the hash table (ie. it is returned as "const" from
+elsewhere in their code) - in this case the LHASH prototypes are
+appropriate as-is. Conversely, if the caller is responsible for the
+life-time of the data in question, then they may well wish to make
+modifications to table item passed back in the lh_doall() or
+lh_doall_arg() callbacks (see the "TYPE_cleanup" example above). If
+so, the caller can either cast the "const" away (if they're providing
+the raw callbacks themselves) or use the macros to declare/implement
+the wrapper functions without "const" types.
+
+Callers that only have "const" access to data they're indexing in a
+table, yet declare callbacks without constant types (or cast the
+"const" away themselves), are therefore creating their own risks/bugs
+without being encouraged to do so by the API. On a related note,
+those auditing code should pay special attention to any instances of
+DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types
+without any "const" qualifiers.
+
+=head1 BUGS
+
+lh_TYPE_insert() returns B<NULL> both for success and error.
+
+=head1 SEE ALSO
+
+L<lh_stats(3)>
+
+=head1 HISTORY
+
+In OpenSSL 1.0.0, the lhash interface was revamped for better
+type checking.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_LH_stats, OPENSSL_LH_node_stats, OPENSSL_LH_node_usage_stats,
+OPENSSL_LH_stats_bio,
+OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics
+
+=head1 SYNOPSIS
+
+ #include <openssl/lhash.h>
+
+ void OPENSSL_LH_stats(LHASH *table, FILE *out);
+ void OPENSSL_LH_node_stats(LHASH *table, FILE *out);
+ void OPENSSL_LH_node_usage_stats(LHASH *table, FILE *out);
+
+ void OPENSSL_LH_stats_bio(LHASH *table, BIO *out);
+ void OPENSSL_LH_node_stats_bio(LHASH *table, BIO *out);
+ void OPENSSL_LH_node_usage_stats_bio(LHASH *table, BIO *out);
+
+=head1 DESCRIPTION
+
+The B<LHASH> structure records statistics about most aspects of
+accessing the hash table. This is mostly a legacy of Eric Young
+writing this library for the reasons of implementing what looked like
+a nice algorithm rather than for a particular software product.
+
+OPENSSL_LH_stats() prints out statistics on the size of the hash table, how
+many entries are in it, and the number and result of calls to the
+routines in this library.
+
+OPENSSL_LH_node_stats() prints the number of entries for each 'bucket' in the
+hash table.
+
+OPENSSL_LH_node_usage_stats() prints out a short summary of the state of the
+hash table. It prints the 'load' and the 'actual load'. The load is
+the average number of data items per 'bucket' in the hash table. The
+'actual load' is the average number of items per 'bucket', but only
+for buckets which contain entries. So the 'actual load' is the
+average number of searches that will need to find an item in the hash
+table, while the 'load' is the average number that will be done to
+record a miss.
+
+OPENSSL_LH_stats_bio(), OPENSSL_LH_node_stats_bio() and OPENSSL_LH_node_usage_stats_bio()
+are the same as the above, except that the output goes to a B<BIO>.
+
+=head1 RETURN VALUES
+
+These functions do not return values.
+
+=head1 SEE ALSO
+
+L<bio(3)>, L<lhash(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_VERSION_NUMBER, OpenSSL_version,
+OpenSSL_version_num - get OpenSSL version number
+
+=head1 SYNOPSIS
+
+ #include <openssl/opensslv.h>
+ #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL
+
+ #include <openssl/crypto.h>
+
+ unsigned long OpenSSL_version_num();
+ const char *OpenSSL_version(int t);
+
+=head1 DESCRIPTION
+
+OPENSSL_VERSION_NUMBER is a numeric release version identifier:
+
+ MNNFFPPS: major minor fix patch status
+
+The status nibble has one of the values 0 for development, 1 to e for betas
+1 to 14, and f for release.
+
+for example
+
+ 0x000906000 == 0.9.6 dev
+ 0x000906023 == 0.9.6b beta 3
+ 0x00090605f == 0.9.6e release
+
+Versions prior to 0.9.3 have identifiers E<lt> 0x0930.
+Versions between 0.9.3 and 0.9.5 had a version identifier with this
+interpretation:
+
+ MMNNFFRBB major minor fix final beta/patch
+
+for example
+
+ 0x000904100 == 0.9.4 release
+ 0x000905000 == 0.9.5 dev
+
+Version 0.9.5a had an interim interpretation that is like the current one,
+except the patch level got the highest bit set, to keep continuity. The
+number was therefore 0x0090581f.
+
+OpenSSL_version_num() returns the version number.
+
+OpenSSL_version() returns different strings depending on B<t>:
+
+=over 4
+
+=item OPENSSL_VERSION
+
+The text variant of the version number and the release date. For example,
+"OpenSSL 1.0.1a 15 Oct 2015".
+
+=item OPENSSL_CFLAGS
+
+The compiler flags set for the compilation process in the form
+"compiler: ..." if available or "compiler: information not available"
+otherwise.
+
+=item OPENSSL_BUILT_ON
+
+The date of the build process in the form "built on: ..." if available
+or "built on: date not available" otherwise.
+
+=item OPENSSL_PLATFORM
+
+The "Configure" target of the library build in the form "platform: ..."
+if available or "platform: information not available" otherwise.
+
+=item OPENSSL_DIR
+
+The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "...""
+if available or "OPENSSLDIR: N/A" otherwise.
+
+=item OPENSSL_ENGINES_DIR
+
+The "ENGINESDIR" setting of the library build in the form "ENGINESDIR: "...""
+if available or "ENGINESDIR: N/A" otherwise.
+
+=back
+
+For an unknown B<t>, the text "not available" is returned.
+
+=head1 RETURN VALUE
+
+The version number.
+
+=head1 SEE ALSO
+
+L<crypto(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void OPENSSL_config(const char *appname);
+ void OPENSSL_no_config(void);
+ #endif
+
+=head1 DESCRIPTION
+
+OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> and
+reads from the application section B<appname>. If B<appname> is NULL then
+the default section, B<openssl_conf>, will be used.
+Errors are silently ignored.
+Multiple calls have no effect.
+
+OPENSSL_no_config() disables configuration. If called before OPENSSL_config()
+no configuration takes place.
+
+If the application is built with B<OPENSSL_LOAD_CONF> defined, then a
+call to OpenSSL_add_all_algorithms() will implicitly call OPENSSL_config()
+first.
+
+=head1 NOTES
+
+The OPENSSL_config() function is designed to be a very simple "call it and
+forget it" function.
+It is however B<much> better than nothing. Applications which need finer
+control over their configuration functionality should use the configuration
+functions such as CONF_modules_load() directly. This function is deprecated
+and its use should be avoided.
+Applications should instead call CONF_modules_load() during
+initialization (that is before starting any threads).
+
+There are several reasons why calling the OpenSSL configuration routines is
+advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs).
+However very few applications currently support the control interface and so
+very few can load and use dynamic ENGINEs. Equally in future more sophisticated
+ENGINEs will require certain control operations to customize them. If an
+application calls OPENSSL_config() it doesn't need to know or care about
+ENGINE control operations because they can be performed by editing a
+configuration file.
+
+=head1 RETURN VALUES
+
+Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
+
+=head1 SEE ALSO
+
+L<conf(5)>,
+L<CONF_modules_load_file(3)>
+
+=head1 HISTORY
+
+The OPENSSL_no_config() and OPENSSL_config() functions were
+deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto().
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_ia32cap - the x86[_64] processor capabilities vector
+
+=head1 SYNOPSIS
+
+ env OPENSSL_ia32cap=... <application>
+
+=head1 DESCRIPTION
+
+OpenSSL supports a range of x86[_64] instruction set extensions. These
+extensions are denoted by individual bits in capability vector returned
+by processor in EDX:ECX register pair after executing CPUID instruction
+with EAX=1 input value (see Intel Application Note #241618). This vector
+is copied to memory upon toolkit initialization and used to choose
+between different code paths to provide optimal performance across wide
+range of processors. For the moment of this writing following bits are
+significant:
+
+=over
+
+=item bit #4 denoting presence of Time-Stamp Counter.
+
+=item bit #19 denoting availability of CLFLUSH instruction;
+
+=item bit #20, reserved by Intel, is used to choose among RC4 code paths;
+
+=item bit #23 denoting MMX support;
+
+=item bit #24, FXSR bit, denoting availability of XMM registers;
+
+=item bit #25 denoting SSE support;
+
+=item bit #26 denoting SSE2 support;
+
+=item bit #28 denoting Hyperthreading, which is used to distinguish
+cores with shared cache;
+
+=item bit #30, reserved by Intel, denotes specifically Intel CPUs;
+
+=item bit #33 denoting availability of PCLMULQDQ instruction;
+
+=item bit #41 denoting SSSE3, Supplemental SSE3, support;
+
+=item bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs);
+
+=item bit #54 denoting availability of MOVBE instruction;
+
+=item bit #57 denoting AES-NI instruction set extension;
+
+=item bit #58, XSAVE bit, lack of which in combination with MOVBE is used
+to identify Atom Silvermont core;
+
+=item bit #59, OSXSAVE bit, denoting availability of YMM registers;
+
+=item bit #60 denoting AVX extension;
+
+=item bit #62 denoting availability of RDRAND instruction;
+
+=back
+
+For example, in 32-bit application context clearing bit #26 at run-time
+disables high-performance SSE2 code present in the crypto library, while
+clearing bit #24 disables SSE2 code operating on 128-bit XMM register
+bank. You might have to do the latter if target OpenSSL application is
+executed on SSE2 capable CPU, but under control of OS that does not
+enable XMM registers. Historically address of the capability vector copy
+was exposed to application through OPENSSL_ia32cap_loc(), but not
+anymore. Now the only way to affect the capability detection is to set
+OPENSSL_ia32cap environment variable prior target application start. To
+give a specific example, on Intel P4 processor 'env
+OPENSSL_ia32cap=0x16980010 apps/openssl', or better yet 'env
+OPENSSL_ia32cap=~0x1000000 apps/openssl' would achieve the desired
+effect. Alternatively you can reconfigure the toolkit with no-sse2
+option and recompile.
+
+Less intuitive is clearing bit #28, or ~0x10000000 in the "environment
+variable" terms. The truth is that it's not copied from CPUID output
+verbatim, but is adjusted to reflect whether or not the data cache is
+actually shared between logical cores. This in turn affects the decision
+on whether or not expensive countermeasures against cache-timing attacks
+are applied, most notably in AES assembler module.
+
+The capability vector is further extended with EBX value returned by
+CPUID with EAX=7 and ECX=0 as input. Following bits are significant:
+
+=over
+
+=item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;
+
+=item bit #64+5 denoting availability of AVX2 instructions;
+
+=item bit #64+8 denoting availability of BMI2 instructions, e.g. MULX
+and RORX;
+
+=item bit #64+16 denoting availability of AVX512F extension;
+
+=item bit #64+18 denoting availability of RDSEED instruction;
+
+=item bit #64+19 denoting availability of ADCX and ADOX instructions;
+
+=item bit #64+29 denoting availability of SHA extension;
+
+=item bit #64+30 denoting availability of AVX512BW extension;
+
+=item bit #64+31 denoting availability of AVX512VL extension;
+
+=back
+
+To control this extended capability word use ':' as delimiter when
+setting up OPENSSL_ia32cap environment variable. For example assigning
+':~0x20' would disable AVX2 code paths, and ':0' - all post-AVX
+extensions.
+
+It should be noted that whether or not some of the most "fancy"
+extension code paths are actually assembled depends on current assembler
+version. Base minimum of AES-NI/PCLMULQDQ, SSSE3 and SHA extension code
+paths are always assembled. Besides that, minimum assembler version
+requirements are summarized in below table:
+
+ Extension | GNU as | nasm | llvm
+ ------------+--------+--------+--------
+ AVX | 2.19 | 2.09 | 3.0
+ AVX2 | 2.22 | 2.10 | 3.1
+ ADCX/ADOX | 2.23 | 2.10 | 3.3
+ AVX512 | 2.25 | 2.11.8 | 3.6
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_init_new, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_free,
+OPENSSL_init_crypto, OPENSSL_cleanup,
+OPENSSL_atexit, OPENSSL_thread_stop - OpenSSL
+initialisation and deinitialisation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ void OPENSSL_cleanup(void);
+ int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
+ int OPENSSL_atexit(void (*handler)(void));
+ void OPENSSL_thread_stop(void);
+
+ OPENSSL_INIT_SETTINGS *OPENSSL_init_new(void);
+ int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,
+ const char* name);
+ void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);
+
+=head1 DESCRIPTION
+
+During normal operation OpenSSL (libcrypto) will allocate various resources at
+start up that must, subsequently, be freed on close down of the library.
+Additionally some resources are allocated on a per thread basis (if the
+application is multi-threaded), and these resources must be freed prior to the
+thread closing.
+
+As of version 1.1.0 OpenSSL will automatically allocate all resources that it
+needs so no explicit initialisation is required. Similarly it will also
+automatically deinitialise as required.
+
+However, there way be situations when explicit initialisation is desirable or
+needed, for example when some non-default initialisation is required. The
+function OPENSSL_init_crypto() can be used for this purpose for
+libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl
+equivalent).
+
+Numerous internal OpenSSL functions call OPENSSL_init_crypto().
+Therefore, in order to perform non-default initialisation,
+OPENSSL_init_crypto() MUST be called by application code prior to
+any other OpenSSL function calls.
+
+The B<opts> parameter specifies which aspects of libcrypto should be
+initialised. Valid options are:
+
+=over 4
+
+=item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS
+
+Suppress automatic loading of the libcrypto error strings. This option is
+not a default option. Once selected subsequent calls to
+OPENSSL_init_crypto() with the option
+B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored.
+
+=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS
+
+Automatic loading of the libcrypto error strings. With this option the
+library will automatically load the libcrypto error strings.
+This option is a default option. Once selected subsequent calls to
+OPENSSL_init_crypto() with the option
+B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> will be ignored.
+
+=item OPENSSL_INIT_ADD_ALL_CIPHERS
+
+With this option the library will automatically load and make available all
+libcrypto ciphers. This option is a default option. Once selected subsequent
+calls to OPENSSL_init_crypto() with the option
+B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
+
+=item OPENSSL_INIT_ADD_ALL_DIGESTS
+
+With this option the library will automatically load and make available all
+libcrypto digests. This option is a default option. Once selected subsequent
+calls to OPENSSL_init_crypto() with the option
+B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
+
+=item OPENSSL_INIT_NO_ADD_ALL_CIPHERS
+
+With this option the library will suppress automatic loading of libcrypto
+ciphers. This option is not a default option. Once selected subsequent
+calls to OPENSSL_init_crypto() with the option
+B<OPENSSL_INIT_ADD_ALL_CIPHERS> will be ignored.
+
+=item OPENSSL_INIT_NO_ADD_ALL_DIGESTS
+
+With this option the library will suppress automatic loading of libcrypto
+digests. This option is not a default option. Once selected subsequent
+calls to OPENSSL_init_crypto() with the option
+B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored.
+
+=item OPENSSL_INIT_LOAD_CONFIG
+
+With this option an OpenSSL configuration file will be automatically loaded and
+used by calling OPENSSL_config(). This is not a default option.
+See the description of OPENSSL_init_new(), below.
+
+=item OPENSSL_INIT_NO_LOAD_CONFIG
+
+With this option the loading of OpenSSL configuration files will be suppressed.
+It is the equivalent of calling OPENSSL_no_config(). This is not a default
+option.
+
+=item OPENSSL_INIT_ASYNC
+
+With this option the library with automatically initialise the libcrypto async
+sub-library (see L<ASYNC_start_job(3)>). This is a default option.
+
+=item OPENSSL_INIT_ENGINE_RDRAND
+
+With this option the library will automatically load and initialise the
+RDRAND engine (if available). This not a default option.
+
+=item OPENSSL_INIT_ENGINE_DYNAMIC
+
+With this option the library will automatically load and initialise the
+dynamic engine. This not a default option.
+
+=item OPENSSL_INIT_ENGINE_OPENSSL
+
+With this option the library will automatically load and initialise the
+openssl engine. This not a default option.
+
+=item OPENSSL_INIT_ENGINE_CRYPTODEV
+
+With this option the library will automatically load and initialise the
+cryptodev engine (if available). This not a default option.
+
+=item OPENSSL_INIT_ENGINE_CAPI
+
+With this option the library will automatically load and initialise the
+CAPI engine (if available). This not a default option.
+
+=item OPENSSL_INIT_ENGINE_PADLOCK
+
+With this option the library will automatically load and initialise the
+padlock engine (if available). This not a default option.
+
+=item OPENSSL_INIT_ENGINE_DASYNC
+
+With this option the library will automatically load and initialise the
+DASYNC engine. This not a default option.
+
+=item OPENSSL_INIT_ENGINE_ALL_BUILTIN
+
+With this option the library will automatically load and initialise all the
+built in engines listed above with the exception of the openssl and dasync
+engines. This not a default option.
+
+=back
+
+Multiple options may be combined together in a single call to
+OPENSSL_init_crypto(). For example:
+
+ OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
+ | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
+
+The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto
+and libssl). All resources allocated by OpenSSL are freed. Typically there
+should be no need to call this function directly as it is initiated
+automatically on application exit. This is done via the standard C library
+L<atexit(3)> function. In the event that the application will close in a manner
+that will not call the registered atexit() handlers then the application should
+call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL
+are discouraged from calling this function and should instead, typically, rely
+on auto-deinitialisation. This is to avoid error conditions where both an
+application and a library it depends on both use OpenSSL, and the library
+deinitialises it before the application has finished using it.
+
+Once OPENSSL_cleanup() has been called the library cannot be reinitialised.
+Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error
+will be added to the error stack. Note that because initialisation has failed
+OpenSSL error strings will not be available, only an error code. This code can
+be put through the openssl errstr command line application to produce a human
+readable error (see L<errstr(1)>).
+
+The OPENSSL_atexit() function enables the registration of a
+function to be called during OPENSSL_cleanup(). Stop handlers are
+called after deinitialisation of resources local to a thread, but before other
+process wide resources are freed. In the event that multiple stop handlers are
+registered, no guarantees are made about the order of execution.
+
+The OPENSSL_thread_stop() function deallocates resources associated
+with the current thread. Typically this function will be called automatically by
+the library when the thread exits. This should only be called directly if
+resources should be freed at an earlier time, or under the circumstances
+described in the NOTES section below.
+
+The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a default configuration
+file. To specify a different file, an B<OPENSSL_INIT_SETTINGS> must
+be created and used. The routines
+OPENSSL_init_new() and OPENSSL_INIT_set_config_appname() can be used to
+allocate the object and set the application name, and then the
+object can be released with OPENSSL_INIT_free() when done.
+
+=head1 NOTES
+
+Resources local to a thread are deallocated automatically when the thread exits
+(e.g. in a pthreads environment, when pthread_exit() is called). On Windows
+platforms this is done in response to a DLL_THREAD_DETACH message being sent to
+the libcrypto32.dll entry point. Some windows functions may cause threads to exit
+without sending this message (for example ExitProcess()). If the application
+uses such functions, then the application must free up OpenSSL resources
+directly via a call to OPENSSL_thread_stop() on each thread. Similarly this
+message will also not be sent if OpenSSL is linked statically, and therefore
+applications using static linking should also call OPENSSL_thread_stop() on each
+thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the
+threads are not destroyed until after FreeLibrary() is called then each thread
+should call OPENSSL_thread_stop() prior to the FreeLibrary() call.
+
+On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is
+multi-threaded and if dlclose() is subsequently called prior to the threads
+being destroyed then OpenSSL will not be able to deallocate resources associated
+with those threads. The application should either call OPENSSL_thread_stop() on
+each thread prior to the dlclose() call, or alternatively the original dlopen()
+call should use the RTLD_NODELETE flag (where available on the platform).
+
+=head1 RETURN VALUES
+
+The functions OPENSSL_init_crypto, OPENSSL_atexit() and
+OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error.
+
+=head1 SEE ALSO
+
+L<OPENSSL_init_ssl(3)>
+
+=head1 HISTORY
+
+The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(),
+OPENSSL_thread_stop(), OPENSSL_init_new(), OPENSSL_INIT_set_config_appname()
+and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
+
+=head1 DESCRIPTION
+
+During normal operation OpenSSL (libssl and libcrypto) will allocate various
+resources at start up that must, subsequently, be freed on close down of the
+library. Additionally some resources are allocated on a per thread basis (if the
+application is multi-threaded), and these resources must be freed prior to the
+thread closing.
+
+As of version 1.1.0 OpenSSL will automatically allocate all resources that it
+needs so no explicit initialisation is required. Similarly it will also
+automatically deinitialise as required.
+
+However, there may be situations when explicit initialisation is desirable or
+needed, for example when some non-default initialisation is required. The
+function OPENSSL_init_ssl() can be used for this purpose. Calling
+this function will explicitly initialise BOTH libcrypto and libssl. To
+explicitly initialise ONLY libcrypto see the
+L<OPENSSL_init_crypto(3)> function.
+
+Numerous internal OpenSSL functions call OPENSSL_init_ssl().
+Therefore, in order to perform non-default initialisation,
+OPENSSL_init_ssl() MUST be called by application code prior to
+any other OpenSSL function calls.
+
+The B<opts> parameter specifies which aspects of libssl and libcrypto should be
+initialised. Valid options for libcrypto are described on the
+L<OPENSSL_init_crypto(3)> page. In addition to any libcrypto
+specific option the following libssl options can also be used:
+
+=over 4
+
+=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS
+
+Suppress automatic loading of the libssl error strings. This option is
+not a default option. Once selected subsequent calls to
+OPENSSL_init_ssl() with the option
+B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.
+
+=item OPENSSL_INIT_LOAD_SSL_STRINGS
+
+Automatic loading of the libssl error strings. This option is a
+default option. Once selected subsequent calls to
+OPENSSL_init_ssl() with the option
+B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.
+
+=back
+
+OPENSSL_init_ssl() takes a B<settings> parameter which can be used to
+set parameter values. See L<OPENSSL_init_crypto(3)> for details.
+
+=head1 RETURN VALUES
+
+The function OPENSSL_init_ssl() returns 1 on success or 0 on error.
+
+=head1 SEE ALSO
+
+L<OPENSSL_init_crypto(3)>
+
+=head1 HISTORY
+
+The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memory bus
+
+=head1 SYNOPSIS
+
+ #ifdef OPENSSL_CPUID_OBJ
+ size_t OPENSSL_instrument_bus(int *vector, size_t num);
+ size_t OPENSSL_instrument_bus2(int *vector, size_t num, size_t max);
+ #endif
+
+=head1 DESCRIPTION
+
+It was empirically found that timings of references to primary memory
+are subject to irregular, apparently non-deterministic variations. The
+subroutines in question instrument these references for purposes of
+gathering entropy for random number generator. In order to make it
+bus-bound a 'flush cache line' instruction is used between probes. In
+addition probes are added to B<vector> elements in atomic or
+interlocked manner, which should contribute additional noise on
+multi-processor systems. This also means that B<vector[num]> should be
+zeroed upon invocation (if you want to retrieve actual probe values).
+
+OPENSSL_instrument_bus() performs B<num> probes and records the number of
+oscillator cycles every probe took.
+
+OPENSSL_instrument_bus2() on the other hand B<accumulates> consecutive
+probes with the same value, i.e. in a way it records duration of
+periods when probe values appeared deterministic. The subroutine
+performs at most B<max> probes in attempt to fill the B<vector[num]>,
+with B<max> value of 0 meaning "as many as it takes."
+
+=head1 RETURN VALUE
+
+Return value of 0 indicates that CPU is not capable of performing the
+benchmark, either because oscillator counter or 'flush cache line' is
+not available on current platform. For reference, on x86 'flush cache
+line' was introduced with the SSE2 extensions.
+
+Otherwise number of recorded values is returned.
+
+=head1 COPYRIGHT
+
+Copyright 2011-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules
+
+=head1 SYNOPSIS
+
+ #include <openssl/conf.h>
+
+ void OPENSSL_load_builtin_modules(void);
+ void ASN1_add_oid_module(void);
+ ENGINE_add_conf_module();
+
+=head1 DESCRIPTION
+
+The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL
+configuration modules to the internal list. They can then be used by the
+OpenSSL configuration code.
+
+ASN1_add_oid_module() adds just the ASN1 OBJECT module.
+
+ENGINE_add_conf_module() adds just the ENGINE configuration module.
+
+=head1 NOTES
+
+If the simple configuration function OPENSSL_config() is called then
+OPENSSL_load_builtin_modules() is called automatically.
+
+Applications which use the configuration functions directly will need to
+call OPENSSL_load_builtin_modules() themselves I<before> any other
+configuration code.
+
+Applications should call OPENSSL_load_builtin_modules() to load all
+configuration modules instead of adding modules selectively: otherwise
+functionality may be missing from the application if an when new
+modules are added.
+
+=head1 RETURN VALUE
+
+None of the functions return a value.
+
+=head1 SEE ALSO
+
+L<conf(3)>, L<OPENSSL_config(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OPENSSL_malloc_init,
+OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
+OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
+CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
+OPENSSL_strdup, OPENSSL_strndup,
+OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat,
+OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int,
+CRYPTO_strdup, CRYPTO_strndup,
+OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
+CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
+CRYPTO_clear_realloc, CRYPTO_clear_free,
+CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
+CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
+CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ int OPENSSL_malloc_init(void)
+
+ void *OPENSSL_malloc(size_t num)
+ void *OPENSSL_zalloc(size_t num)
+ void *OPENSSL_realloc(void *addr, size_t num)
+ void OPENSSL_free(void *addr)
+ char *OPENSSL_strdup(const char *str)
+ char *OPENSSL_strndup(const char *str, size_t s)
+ size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
+ size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
+ void *OPENSSL_memdup(void *data, size_t s)
+ void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num)
+ void OPENSSL_clear_free(void *str, size_t num)
+ void OPENSSL_cleanse(void *ptr, size_t len);
+
+ unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
+ char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len);
+ int OPENSSL_hexchar2int(unsigned char c);
+
+ void *CRYPTO_malloc(size_t num, const char *file, int line)
+ void *CRYPTO_zalloc(size_t num, const char *file, int line)
+ void *CRYPTO_realloc(void *p, size_t num, const char *file, int line)
+ void CRYPTO_free(void *str, const char *, int)
+ char *CRYPTO_strdup(const char *p, const char *file, int line)
+ char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line)
+ void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, const char *file, int line)
+ void CRYPTO_clear_free(void *str, size_t num, const char *, int)
+
+ void CRYPTO_get_mem_functions(
+ void *(**m)(size_t, const char *, int),
+ void *(**r)(void *, size_t, const char *, int),
+ void (**f)(void *, const char *, int))
+ int CRYPTO_set_mem_functions(
+ void *(*m)(size_t, const char *, int),
+ void *(*r)(void *, size_t, const char *, int),
+ void (*f)(void *, const char *, int))
+
+ int CRYPTO_set_mem_debug(int onoff)
+
+ int CRYPTO_mem_ctrl(int mode);
+
+ int OPENSSL_mem_debug_push(const char *info)
+ int OPENSSL_mem_debug_pop(void);
+
+ int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
+ int CRYPTO_mem_debug_pop(void);
+
+ void CRYPTO_mem_leaks(BIO *b);
+ void CRYPTO_mem_leaks_fp(FILE *fp);
+
+=head1 DESCRIPTION
+
+OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are
+generally macro's that add the standard C B<__FILE__> and B<__LINE__>
+parameters and call a lower-level B<CRYPTO_xxx> API.
+Some functions do not add those parameters, but exist for consistency.
+
+OPENSSL_malloc_init() sets the lower-level memory allocation functions
+to their default implementation.
+It is generally not necessary to call this, except perhaps in certain
+shared-library situations.
+
+OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the
+C malloc(), realloc(), and free() functions.
+OPENSSL_zalloc() calls memset() to zero the memory before returning.
+
+OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used
+when the buffer at B<addr> holds sensitive information.
+The old buffer is filled with zero's by calling OPENSSL_cleanse()
+before ultimately calling OPENSSL_free().
+
+OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's.
+Use OPENSSL_cleanse() with care if the memory is a mapping of a file.
+If the storage controller uses write compression, then its possible
+that sensitive tail bytes will survive zeroization because the block of
+zeros will be compressed. If the storage controller uses wear leveling,
+then the old sensitive data will not be overwritten; rather, a block of
+0's will be written at a new physical location.
+
+OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the
+equivalent C functions, except that memory is allocated by calling the
+OPENSSL_malloc() and should be released by calling OPENSSL_free().
+
+OPENSSL_strlcpy(),
+OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C
+library functions and are provided for portability.
+
+OPENSSL_hexstr2buf() parses B<str> as a hex string and returns a
+pointer to the parsed value. The memory is allocated by calling
+OPENSSL_malloc() and should be released by calling OPENSSL_free().
+If B<len> is not NULL, it is filled in with the output length.
+Colons between two-character hex "bytes" are ignored.
+An odd number of hex digits is an error.
+
+OPENSSL_buf2hexstr() takes the specified buffer and length, and returns
+a hex string for value, or NULL on error.
+B<Buffer> cannot be NULL; if B<len> is 0 an empty string is returned.
+
+OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent,
+or returns -1 on error.
+
+If no allocations have been done, it is possible to "swap out" the default
+implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free()
+and replace them with alternate versions (hooks).
+CRYPTO_get_mem_functions() function fills in the given arguments with the
+function pointers for the current implementations.
+With CRYPTO_set_mem_functions(), you can specify a different set of functions.
+If any of B<m>, B<r>, or B<f> are NULL, then the function is not changed.
+
+The default implementation can include some debugging capability (if enabled
+at build-time).
+This adds some overhead by keeping a list of all memory allocations, and
+removes items from the list when they are free'd.
+This is most useful for identifying memory leaks.
+CRYPTO_set_mem_debug() turns this tracking on and off. It is normally
+called at startup, but can be called at any time.
+
+CRYPTO_mem_ctrl() provides fine-grained control of memory leak tracking.
+To enable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
+the B<CRYPTO_MEM_CHECK_ON>.
+To disable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
+the B<CRYPTO_MEM_CHECK_OFF>.
+
+While checking memory, it can be useful to store additional context
+about what is being done.
+For example, identifying the field names when parsing a complicated
+data structure.
+OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push())
+attachs an identifying string to the allocation stack.
+This must be a global or other static string; it is not copied.
+OPENSSL_mem_debug_pop() removes identifying state from the stack.
+
+At the end of the program, calling CRYPTO_mem_leaks() or
+CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it
+to the specified BIO B<b> or FILE B<fp>. These functions return 1 if
+there are no leaks, 0 if there are leaks and -1 if an error occurred.
+
+=head1 RETURN VALUES
+
+OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
+CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
+return no value.
+
+CRYPTO_mem_leaks() and CRYPTO_mem_leaks_fp() return 1 if there
+are no leaks, 0 if there are leaks and -1 if an error occurred.
+
+OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
+OPENSSL_clear_realloc(),
+CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(),
+CRYPTO_clear_realloc(),
+OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(),
+OPENSSL_strdup(), and OPENSSL_strndup()
+return a pointer to allocated memory or NULL on error.
+
+CRYPTO_set_mem_functions() and CRYPTO_set_mem_debug()
+return 1 on success or 0 on failure (almost
+always because allocations have already happened).
+
+CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the
+previous value of the mode.
+
+OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop()
+return 1 on success or 0 on failure.
+
+=head1 NOTES
+
+While it's permitted to swap out only a few and not all the functions
+with CRYPTO_set_mem_functions(), it's recommended to swap them all out
+at once. I<This applies specially if OpenSSL was built with the
+configuration option> C<crypto-mdebug> I<enabled. In case, swapping out
+only, say, the malloc() implementation is outright dangerous.>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized,
+CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc,
+OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free,
+CRYPTO_secure_free, OPENSSL_secure_actual_size, OPENSSL_secure_allocated,
+CYRPTO_secure_used - secure heap storage
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ int CRYPTO_secure_malloc_init(size_t size, int minsize);
+
+ int CRYPTO_secure_malloc_initialized();
+
+ int CRYPTO_secure_malloc_done();
+
+ void *OPENSSL_secure_malloc(size_t num);
+ void *CRYPTO_secure_malloc(size_t num, const char *file, int line);
+
+ void *OPENSSL_secure_zalloc(size_t num);
+ void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);
+
+ void OPENSSL_secure_free(void* ptr);
+ void CRYPTO_secure_free(void *ptr, const char *, int);
+
+ size_t OPENSSL_secure_actual_size(const void *ptr);
+ int OPENSSL_secure_allocated(const void *ptr);
+
+ size_t CYRPTO_secure_used();
+
+=head1 DESCRIPTION
+
+In order to help protect applications (particularly long-running servers)
+from pointer overruns or underruns that could return arbitrary data from
+the program's dynamic memory area, where keys and other sensitive
+information might be stored, OpenSSL supports the concept of a "secure heap."
+The level and type of security guarantees depend on the operating system.
+It is a good idea to review the code and see if it addresses your
+threat model and concerns.
+
+If a secure heap is used, then private key B<BIGNUM> values are stored there.
+This protects long-term storage of private keys, but will not necessarily
+put all intermediate values and computations there.
+
+CRYPTO_secure_malloc_init() creates the secure heap, with the specified
+C<size> in bytes. The C<minsize> parameter is the minimum size to
+allocate from the heap. Both C<size> and C<minsize> must be a power
+of two.
+
+CRYPTO_secure_malloc_initialized() indicates whether or not the secure
+heap as been initialized and is available.
+
+CRYPTO_secure_malloc_done() releases the heap and makes the memory unavailable
+to the process if all secure memory has been freed.
+It can take noticeably long to complete.
+
+OPENSSL_secure_malloc() allocates C<num> bytes from the heap.
+If CRYPTO_secure_malloc_init() is not called, this is equivalent to
+calling OPENSSL_malloc().
+It is a macro that expands to
+CRYPTO_secure_malloc() and adds the C<__FILE__> and C<__LINE__> parameters.
+
+OPENSSL_secure_zalloc() and CRYPTO_secure_zalloc() are like
+OPENSSL_secure_malloc() and CRYPTO_secure_malloc(), respectively,
+except that they call memset() to zero the memory before returning.
+
+OPENSSL_secure_free() releases the memory at C<ptr> back to the heap.
+It must be called with a value previously obtained from
+OPENSSL_secure_malloc().
+If CRYPTO_secure_malloc_init() is not called, this is equivalent to
+calling OPENSSL_free().
+It exists for consistency with OPENSSL_secure_malloc() , and
+is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__>
+and C<__LINE__> parameters..
+
+OPENSSL_secure_allocated() tells whether or not a pointer is within
+the secure heap.
+OPENSSL_secure_actual_size() tells the actual size allocated to the
+pointer; implementations may allocate more space than initially
+requested, in order to "round up" and reduce secure heap fragmentation.
+
+CRYPTO_secure_used() returns the number of bytes allocated in the
+secure heap.
+
+=head1 RETURN VALUES
+
+CRYPTO_secure_malloc_init() returns 0 on failure, 1 if successful,
+and 2 if successful but the heap could not be protected by memory
+mapping.
+
+CRYPTO_secure_malloc_initialized() returns 1 if the secure heap is
+available (that is, if CRYPTO_secure_malloc_init() has been called,
+but CRYPTO_secure_malloc_done() has not been called or failed) or 0 if not.
+
+OPENSSL_secure_malloc() and OPENSSL_secure_zalloc() return a pointer into
+the secure heap of the requested size, or C<NULL> if memory could not be
+allocated.
+
+CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 if not.
+
+CRYPTO_secure_malloc_done() returns 1 if the secure memory area is released, or 0 if not.
+
+OPENSSL_secure_free() returns no values.
+
+=head1 SEE ALSO
+
+L<OPENSSL_malloc(3)>,
+L<BN_new(3)>,
+L<bn_internal(3)>.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup -
+add algorithms to internal table
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+Deprecated:
+
+ # if OPENSSL_API_COMPAT < 0x10100000L
+ void OpenSSL_add_all_algorithms(void);
+ void OpenSSL_add_all_ciphers(void);
+ void OpenSSL_add_all_digests(void);
+
+ void EVP_cleanup(void)
+# endif
+
+=head1 DESCRIPTION
+
+OpenSSL keeps an internal table of digest algorithms and ciphers. It uses
+this table to lookup ciphers via functions such as EVP_get_cipher_byname(). In
+OpenSSL versions prior to 1.1.0 these functions initialised and de-initialised
+this table. From OpenSSL 1.1.0 they are deprecated. No explicit initialisation
+or de-initialisation is required. See L<OPENSSL_init_crypto(3)> for further
+information.
+
+OpenSSL_add_all_digests() adds all digest algorithms to the table.
+
+OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and
+ciphers).
+
+OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including
+password based encryption algorithms.
+
+In versions prior to 1.1.0 EVP_cleanup() removed all ciphers and digests from
+the table. It no longer has any effect in OpenSSL 1.1.0.
+
+=head1 RETURN VALUES
+
+None of the functions return a value.
+
+=head1 NOTES
+
+A typical application will call OpenSSL_add_all_algorithms() initially and
+EVP_cleanup() before exiting.
+
+An application does not need to add algorithms to use them explicitly, for example
+by EVP_sha1(). It just needs to add them if it (or any of the functions it calls)
+needs to lookup algorithms.
+
+The cipher and digest lookup functions are used in many parts of the library. If
+the table is not initialized several functions will misbehave and complain they
+cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries.
+This is a common query in the OpenSSL mailing lists.
+
+Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a
+statically linked executable can be quite large. If this is important it is possible
+to just add the required ciphers and digests.
+
+=head1 BUGS
+
+Although the functions do not return error codes it is possible for them to fail.
+This will only happen as a result of a memory allocation failure so this is not
+too much of a problem in practice.
+
+=head1 SEE ALSO
+
+L<evp(3)>, L<EVP_DigestInit(3)>,
+L<EVP_EncryptInit(3)>
+
+=head1 HISTORY
+
+The OpenSSL_add_all_algorithms(), OpenSSL_add_all_ciphers(),
+OpenSSL_add_all_digests(), and EVP_cleanup(), functions
+were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto().
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PEM_write, PEM_write_bio,
+PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO
+- PEM encoding routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/pem.h>
+
+ int PEM_write(FILE *fp, const char *name, const char *header,
+ const unsigned char *data, long len)
+ int PEM_write_bio(BIO *bp, const char *name, const char *header,
+ const unsigned char *data, long len)
+
+ int PEM_read(FILE *fp, char **name, char **header,
+ unsigned char **data, long *len);
+ int PEM_read_bio(BIO *bp, char **name, char **header,
+ unsigned char **data, long *len);
+
+ int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo);
+ int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len,
+ pem_password_cb *cb, void *u);
+
+=head1 DESCRIPTION
+
+These functions read and write PEM-encoded objects, using the PEM
+type B<name>, any additional B<header> information, and the raw
+B<data> of length B<len>.
+
+PEM is the term used for binary content encoding first defined in IETF
+RFC 1421. The content is a series of base64-encoded lines, surrounded
+by begin/end markers each on their own line. For example:
+
+ -----BEGIN PRIVATE KEY-----
+ MIICdg....
+ ... bhTQ==
+ -----END PRIVATE KEY-----
+
+Optional header line(s) may appear after the begin line, and their
+existence depends on the type of object being written or read.
+
+PEM_write() writes to the file B<fp>, while PEM_write_bio() writes to
+the BIO B<bp>. The B<name> is the name to use in the marker, the
+B<header> is the header value or NULL, and B<data> and B<len> specify
+the data and its length.
+
+The final B<data> buffer is typically an ASN.1 object which can be decoded with
+the B<d2i> function appropriate to the type B<name>; see L<d2i_X509(3)>
+for examples.
+
+PEM_read() reads from the file B<fp>, while PEM_read_bio() reads
+from the BIO B<bp>.
+Both skip any non-PEM data that precedes the start of the next PEM object.
+When an object is successfully retrieved, the type name from the "----BEGIN
+<type>-----" is returned via the B<name> argument, any encapsulation headers
+are returned in B<header> and the base64-decoded content and its length are
+returned via B<data> and B<len> respectively.
+The B<name>, B<header> and B<data> pointers are allocated via OPENSSL_malloc()
+and should be freed by the caller via OPENSSL_free() when no longer needed.
+
+PEM_get_EVP_CIPHER_INFO() can be used to determine the B<data> returned by
+PEM_read() or PEM_read_bio() is encrypted and to retrieve the associated cipher
+and IV.
+The caller passes a pointer to structure of type B<EVP_CIPHER_INFO> via the
+B<cinfo> argument and the B<header> returned via PEM_read() or PEM_read_bio().
+If the call is successful 1 is returned and the cipher and IV are stored at the
+address pointed to by B<cinfo>.
+When the header is malformed, or not supported or when the cipher is unknown
+or some internal error happens 0 is returned.
+This function is deprecated, see B<NOTES> below.
+
+PEM_do_header() can then be used to decrypt the data if the header
+indicates encryption.
+The B<cinfo> argument is a pointer to the structure initialized by the previous
+call to PEM_get_EVP_CIPHER_INFO().
+The B<data> and B<len> arguments are those returned by the previous call to
+PEM_read() or PEM_read_bio().
+The B<cb> and B<u> arguments make it possible to override the default password
+prompt function as described in L<PEM_read_PrivateKey(3)>.
+On successful completion the B<data> is decrypted in place, and B<len> is
+updated to indicate the plaintext length.
+This function is deprecated, see B<NOTES> below.
+
+If the data is a priori known to not be encrypted, then neither PEM_do_header()
+nor PEM_get_EVP_CIPHER_INFO() need be called.
+
+=head1 RETURN VALUES
+
+PEM_read() and PEM_read_bio() return 1 on success and 0 on failure, the latter
+includes the case when no more PEM objects remain in the input file.
+To distinguish end of file from more serious errors the caller must peek at the
+error stack and check for B<PEM_R_NO_START_LINE>, which indicates that no more
+PEM objects were found. See L<ERR_peek_last_error(3)>, L<ERR_GET_REASON(3)>.
+
+PEM_get_EVP_CIPHER_INFO() and PEM_do_header() return 1 on success, and 0 on
+failure.
+The B<data> is likely meaningless if these functions fail.
+
+=head1 NOTES
+
+The PEM_get_EVP_CIPHER_INFO() and PEM_do_header() functions are deprecated.
+This is because the underlying PEM encryption format is obsolete, and should
+be avoided.
+It uses an encryption format with an OpenSSL-specific key-derivation function,
+which employs MD5 with an iteration count of 1!
+Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5
+v2.0 PBE.
+See L<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>.
+
+=head1 SEE ALSO
+
+L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>,
+L<d2i_PKCS8PrivateKey_bio(3)>.
+
+=head1 COPYRIGHT
+
+Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DECLARE_PEM_rw,
+PEM_read_CMS,
+PEM_read_bio_CMS,
+PEM_write_CMS,
+PEM_write_bio_CMS,
+PEM_write_DHxparams,
+PEM_write_bio_DHxparams,
+PEM_read_ECPKParameters,
+PEM_read_bio_ECPKParameters,
+PEM_write_ECPKParameters,
+PEM_write_bio_ECPKParameters,
+PEM_read_ECPrivateKey,
+PEM_write_ECPrivateKey,
+PEM_write_bio_ECPrivateKey,
+PEM_read_EC_PUBKEY,
+PEM_read_bio_EC_PUBKEY,
+PEM_write_EC_PUBKEY,
+PEM_write_bio_EC_PUBKEY,
+PEM_read_NETSCAPE_CERT_SEQUENCE,
+PEM_read_bio_NETSCAPE_CERT_SEQUENCE,
+PEM_write_NETSCAPE_CERT_SEQUENCE,
+PEM_write_bio_NETSCAPE_CERT_SEQUENCE,
+PEM_read_PKCS8,
+PEM_read_bio_PKCS8,
+PEM_write_PKCS8,
+PEM_write_bio_PKCS8,
+PEM_write_PKCS8_PRIV_KEY_INFO,
+PEM_read_bio_PKCS8_PRIV_KEY_INFO,
+PEM_read_PKCS8_PRIV_KEY_INFO,
+PEM_write_bio_PKCS8_PRIV_KEY_INFO,
+PEM_read_SSL_SESSION,
+PEM_read_bio_SSL_SESSION,
+PEM_write_SSL_SESSION,
+PEM_write_bio_SSL_SESSION
+- PEM object encoding routines
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ #include <openssl/pem.h>
+
+ DECLARE_PEM_rw(name, TYPE)
+
+ TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u);
+ TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u);
+ int PEM_write_TYPE(FILE *fp, const TYPE *a);
+ int PEM_write_bio_TYPE(BIO *bp, const TYPE *a);
+
+=head1 DESCRIPTION
+
+In the description below, I<TYPE> is used
+as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
+The macro B<DECLARE_PEM_rw> expands to the set of declarations shown in
+the next four lines of the synopsis.
+
+These routines convert between local instances of ASN1 datatypes and
+the PEM encoding. For more information on the templates, see
+L<ASN1_ITEM(3)>. For more information on the lower-level routines used
+by the functions here, see L<PEM_read(3)>.
+
+PEM_read_TYPE() reads a PEM-encoded object of I<TYPE> from the file B<fp>
+and returns it. The B<cb> and B<u> parameters are as described in
+L<pem_password_cb(3)>.
+
+PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B<bp>.
+
+PEM_write_TYPE() writes the PEM encoding of the object B<a> to the file B<fp>.
+
+PEM_write_bio_TYPE() similarly writes to the BIO B<bp>.
+
+=head1 RETURN VALUES
+
+PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated
+object, which should be released by calling TYPE_free(), or NULL on error.
+
+PEM_write_TYPE() and PEM_write_bio_TYPE() return the number of bytes written
+or zero on error.
+
+=head1 SEE ALSO
+
+L<PEM_read(3)>
+
+=head1 COPYRIGHT
+
+Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+pem_password_cb,
+PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
+PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey,
+PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
+PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
+PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY,
+PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey,
+PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
+PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey,
+PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
+PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
+PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
+PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
+PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
+PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
+PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
+PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
+PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX,
+PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ,
+PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,
+PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,
+PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,
+PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/pem.h>
+
+ typedef int (*pem_password_cb)(char *buf, int size, int rwflag, void *u);
+
+ EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+ EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x,
+ const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+ int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+ int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+ int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+ EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
+ int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
+
+ RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
+ pem_password_cb *cb, void *u);
+ RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+ int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
+ pem_password_cb *cb, void *u);
+ RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
+ int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
+
+ RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
+ pem_password_cb *cb, void *u);
+ RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
+ int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
+
+ DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
+ pem_password_cb *cb, void *u);
+ DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+ int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
+ unsigned char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
+ pem_password_cb *cb, void *u);
+ DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
+ int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
+
+ DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
+ DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
+ int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
+ int PEM_write_DSAparams(FILE *fp, DSA *x);
+
+ DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
+ DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
+ int PEM_write_bio_DHparams(BIO *bp, DH *x);
+ int PEM_write_DHparams(FILE *fp, DH *x);
+
+ X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
+ X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
+ int PEM_write_bio_X509(BIO *bp, X509 *x);
+ int PEM_write_X509(FILE *fp, X509 *x);
+
+ X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
+ X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
+ int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
+ int PEM_write_X509_AUX(FILE *fp, X509 *x);
+
+ X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
+ pem_password_cb *cb, void *u);
+ X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
+ int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
+ int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
+ int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
+
+ X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
+ pem_password_cb *cb, void *u);
+ X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
+ pem_password_cb *cb, void *u);
+ int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
+ int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
+
+ PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
+ PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
+ int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
+ int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
+
+=head1 DESCRIPTION
+
+The PEM functions read or write structures in PEM format. In
+this sense PEM format is simply base64 encoded data surrounded
+by header lines.
+
+For more details about the meaning of arguments see the
+B<PEM FUNCTION ARGUMENTS> section.
+
+Each operation has four functions associated with it. For
+clarity the term "B<foobar> functions" will be used to collectively
+refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
+PEM_write_bio_foobar() and PEM_write_foobar() functions.
+
+The B<PrivateKey> functions read or write a private key in PEM format using an
+EVP_PKEY structure. The write routines use PKCS#8 private key format and are
+equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
+handle traditional and PKCS#8 format encrypted and unencrypted keys.
+
+PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy
+"traditional" format.
+
+PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
+key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
+PKCS#5 v2.0 password based encryption algorithms. The B<cipher> argument
+specifies the encryption algorithm to use: unlike some other PEM routines the
+encryption is applied at the PKCS#8 level and not in the PEM headers. If
+B<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
+structure is used instead.
+
+PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
+also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
+it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
+to use is specified in the B<nid> parameter and should be the NID of the
+corresponding OBJECT IDENTIFIER (see NOTES section).
+
+The B<PUBKEY> functions process a public key using an EVP_PKEY
+structure. The public key is encoded as a SubjectPublicKeyInfo
+structure.
+
+The B<RSAPrivateKey> functions process an RSA private key using an
+RSA structure. The write routines uses traditional format. The read
+routines handles the same formats as the B<PrivateKey>
+functions but an error occurs if the private key is not RSA.
+
+The B<RSAPublicKey> functions process an RSA public key using an
+RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
+structure.
+
+The B<RSA_PUBKEY> functions also process an RSA public key using
+an RSA structure. However the public key is encoded using a
+SubjectPublicKeyInfo structure and an error occurs if the public
+key is not RSA.
+
+The B<DSAPrivateKey> functions process a DSA private key using a
+DSA structure. The write routines uses traditional format. The read
+routines handles the same formats as the B<PrivateKey>
+functions but an error occurs if the private key is not DSA.
+
+The B<DSA_PUBKEY> functions process a DSA public key using
+a DSA structure. The public key is encoded using a
+SubjectPublicKeyInfo structure and an error occurs if the public
+key is not DSA.
+
+The B<DSAparams> functions process DSA parameters using a DSA
+structure. The parameters are encoded using a Dss-Parms structure
+as defined in RFC2459.
+
+The B<DHparams> functions process DH parameters using a DH
+structure. The parameters are encoded using a PKCS#3 DHparameter
+structure.
+
+The B<X509> functions process an X509 certificate using an X509
+structure. They will also process a trusted X509 certificate but
+any trust settings are discarded.
+
+The B<X509_AUX> functions process a trusted X509 certificate using
+an X509 structure.
+
+The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
+certificate request using an X509_REQ structure. The B<X509_REQ>
+write functions use B<CERTIFICATE REQUEST> in the header whereas
+the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
+(as required by some CAs). The B<X509_REQ> read functions will
+handle either form so there are no B<X509_REQ_NEW> read functions.
+
+The B<X509_CRL> functions process an X509 CRL using an X509_CRL
+structure.
+
+The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
+structure.
+
+=head1 PEM FUNCTION ARGUMENTS
+
+The PEM functions have many common arguments.
+
+The B<bp> BIO parameter (if present) specifies the BIO to read from
+or write to.
+
+The B<fp> FILE parameter (if present) specifies the FILE pointer to
+read from or write to.
+
+The PEM read functions all take an argument B<TYPE **x> and return
+a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
+uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
+NULL but B<*x> is NULL then the structure returned will be written
+to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
+to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
+Irrespective of the value of B<x> a pointer to the structure is always
+returned (or NULL if an error occurred).
+
+The PEM functions which write private keys take an B<enc> parameter
+which specifies the encryption algorithm to use, encryption is done
+at the PEM level. If this parameter is set to NULL then the private
+key is written in unencrypted form.
+
+The B<cb> argument is the callback to use when querying for the pass
+phrase used for encrypted PEM structures (normally only private keys).
+
+For the PEM write routines if the B<kstr> parameter is not NULL then
+B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
+ignored.
+
+If the B<cb> parameters is set to NULL and the B<u> parameter is not
+NULL then the B<u> parameter is interpreted as a null terminated string
+to use as the passphrase. If both B<cb> and B<u> are NULL then the
+default callback routine is used which will typically prompt for the
+passphrase on the current terminal with echoing turned off.
+
+The default passphrase callback is sometimes inappropriate (for example
+in a GUI application) so an alternative can be supplied. The callback
+routine has the following form:
+
+ int cb(char *buf, int size, int rwflag, void *u);
+
+B<buf> is the buffer to write the passphrase to. B<size> is the maximum
+length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
+which is set to 0 when reading and 1 when writing. A typical routine
+will ask the user to verify the passphrase (for example by prompting
+for it twice) if B<rwflag> is 1. The B<u> parameter has the same
+value as the B<u> parameter passed to the PEM routine. It allows
+arbitrary data to be passed to the callback by the application
+(for example a window handle in a GUI application). The callback
+B<must> return the number of characters in the passphrase or 0 if
+an error occurred.
+
+=head1 EXAMPLES
+
+Although the PEM routines take several arguments in almost all applications
+most of them are set to 0 or NULL.
+
+Read a certificate in PEM format from a BIO:
+
+ X509 *x;
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+ if (x == NULL) {
+ /* Error */
+ }
+
+Alternative method:
+
+ X509 *x = NULL;
+ if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
+ /* Error */
+ }
+
+Write a certificate to a BIO:
+
+ if (!PEM_write_bio_X509(bp, x)) {
+ /* Error */
+ }
+
+Write a private key (using traditional format) to a BIO using
+triple DES encryption, the pass phrase is prompted for:
+
+ if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) {
+ /* Error */
+ }
+
+Write a private key (using PKCS#8 format) to a BIO using triple
+DES encryption, using the pass phrase "hello":
+
+ if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) {
+ /* Error */
+ }
+
+Read a private key from a BIO using a pass phrase callback:
+
+ key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
+ if (key == NULL) {
+ /* Error */
+ }
+
+Skeleton pass phrase callback:
+
+ int pass_cb(char *buf, int size, int rwflag, void *u)
+ {
+ int len;
+ char *tmp;
+
+ /* We'd probably do something else if 'rwflag' is 1 */
+ printf("Enter pass phrase for \"%s\"\n", (char *)u);
+
+ /* get pass phrase, length 'len' into 'tmp' */
+ tmp = "hello";
+ len = strlen(tmp);
+ if (len <= 0)
+ return 0;
+
+ if (len > size)
+ len = size;
+ memcpy(buf, tmp, len);
+ return len;
+ }
+
+=head1 NOTES
+
+The old B<PrivateKey> write routines are retained for compatibility.
+New applications should write private keys using the
+PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
+because they are more secure (they use an iteration count of 2048 whereas
+the traditional routines use a count of 1) unless compatibility with older
+versions of OpenSSL is important.
+
+The B<PrivateKey> read routines can be used in all applications because
+they handle all formats transparently.
+
+A frequent cause of problems is attempting to use the PEM routines like
+this:
+
+ X509 *x;
+ PEM_read_bio_X509(bp, &x, 0, NULL);
+
+this is a bug because an attempt will be made to reuse the data at B<x>
+which is an uninitialised pointer.
+
+=head1 PEM ENCRYPTION FORMAT
+
+These old B<PrivateKey> routines use a non standard technique for encryption.
+
+The private key (or other data) takes the following form:
+
+ -----BEGIN RSA PRIVATE KEY-----
+ Proc-Type: 4,ENCRYPTED
+ DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
+
+ ...base64 encoded data...
+ -----END RSA PRIVATE KEY-----
+
+The line beginning with I<Proc-Type> contains the version and the
+protection on the encapsulated data. The line beginning I<DEK-Info>
+contains two comma separated values: the encryption algorithm name as
+used by EVP_get_cipherbyname() and an initialization vector used by the
+cipher encoded as a set of hexadecimal digits. After those two lines is
+the base64-encoded encrypted data.
+
+The encryption key is derived using EVP_BytesToKey(). The cipher's
+initialization vector is passed to EVP_BytesToKey() as the B<salt>
+parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used
+(regardless of the size of the initialization vector). The user's
+password is passed to EVP_BytesToKey() using the B<data> and B<datal>
+parameters. Finally, the library uses an iteration count of 1 for
+EVP_BytesToKey().
+
+The B<key> derived by EVP_BytesToKey() along with the original initialization
+vector is then used to decrypt the encrypted data. The B<iv> produced by
+EVP_BytesToKey() is not utilized or needed, and NULL should be passed to
+the function.
+
+The pseudo code to derive the key would look similar to:
+
+ EVP_CIPHER* cipher = EVP_des_ede3_cbc();
+ EVP_MD* md = EVP_md5();
+
+ unsigned int nkey = EVP_CIPHER_key_length(cipher);
+ unsigned int niv = EVP_CIPHER_iv_length(cipher);
+ unsigned char key[nkey];
+ unsigned char iv[niv];
+
+ memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv);
+ rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/);
+ if (rc != nkey) {
+ /* Error */
+ }
+
+ /* On success, use key and iv to initialize the cipher */
+
+=head1 BUGS
+
+The PEM read routines in some versions of OpenSSL will not correctly reuse
+an existing structure. Therefore the following:
+
+ PEM_read_bio_X509(bp, &x, 0, NULL);
+
+where B<x> already contains a valid certificate, may not work, whereas:
+
+ X509_free(x);
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+
+is guaranteed to work.
+
+=head1 RETURN CODES
+
+The read routines return either a pointer to the structure read or NULL
+if an error occurred.
+
+The write routines return 1 for success or 0 for failure.
+
+=head1 HISTORY
+
+The old Netscape certificate sequences were no longer documented
+in OpenSSL 1.1; applications should use the PKCS7 standard instead
+as they will be formally deprecated in a future releases.
+
+=head1 SEE ALSO
+
+L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format.
+
+It is otherwise identical to the function SMIME_write_CMS().
+
+=head1 NOTES
+
+This function is effectively a version of the PEM_write_bio_CMS() supporting
+streaming.
+
+=head1 RETURN VALUES
+
+PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>,
+L<CMS_verify(3)>, L<CMS_encrypt(3)>
+L<CMS_decrypt(3)>,
+L<PEM_write(3)>,
+L<SMIME_write_CMS(3)>,
+L<i2d_CMS_bio_stream(3)>
+
+=head1 HISTORY
+
+PEM_write_bio_CMS_stream() was added to OpenSSL 1.0.0
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format.
+
+It is otherwise identical to the function SMIME_write_PKCS7().
+
+=head1 NOTES
+
+This function is effectively a version of the PEM_write_bio_PKCS7() supporting
+streaming.
+
+=head1 RETURN VALUES
+
+PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
+L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
+L<PKCS7_decrypt(3)>,
+L<SMIME_write_PKCS7(3)>,
+L<i2d_PKCS7_bio_stream(3)>
+
+=head1 HISTORY
+
+PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0
+
+=head1 COPYRIGHT
+
+Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS12_create - create a PKCS#12 structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ PKCS12 *PKCS12_create(const char *pass, const char *name, EVP_PKEY *pkey,
+ X509 *cert, STACK_OF(X509) *ca,
+ int nid_key, int nid_cert, int iter, int mac_iter, int keytype);
+
+=head1 DESCRIPTION
+
+PKCS12_create() creates a PKCS#12 structure.
+
+B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for
+the supplied certificate and key. B<pkey> is the private key to include in
+the structure and B<cert> its corresponding certificates. B<ca>, if not B<NULL>
+is an optional set of certificates to also include in the structure.
+
+B<nid_key> and B<nid_cert> are the encryption algorithms that should be used
+for the key and certificate respectively. B<iter> is the encryption algorithm
+iteration count to use and B<mac_iter> is the MAC iteration count to use.
+B<keytype> is the type of key.
+
+=head1 NOTES
+
+The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype>
+can all be set to zero and sensible defaults will be used.
+
+These defaults are: 40 bit RC2 encryption for certificates, triple DES
+encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER
+(currently 2048) and a MAC iteration count of 1.
+
+The default MAC iteration count is 1 in order to retain compatibility with
+old software which did not interpret MAC iteration counts. If such compatibility
+is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER.
+
+B<keytype> adds a flag to the store private key. This is a non standard extension
+that is only currently interpreted by MSIE. If set to zero the flag is omitted,
+if set to B<KEY_SIG> the key can be used for signing only, if set to B<KEY_EX>
+it can be used for signing and encryption. This option was useful for old
+export grade software which could use signing only keys of arbitrary size but
+had restrictions on the permissible sizes of keys which could be used for
+encryption.
+
+If a certificate contains an B<alias> or B<keyid> then this will be
+used for the corresponding B<friendlyName> or B<localKeyID> in the
+PKCS12 structure.
+
+Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or
+certificate is required. In previous versions both had to be present or
+a fatal error is returned.
+
+B<nid_key> or B<nid_cert> can be set to -1 indicating that no encryption
+should be used.
+
+B<mac_iter> can be set to -1 and the MAC will then be omitted entirely.
+
+=head1 SEE ALSO
+
+L<d2i_PKCS12(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS12_newpass - change the password of a PKCS12 structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+ int PKCS12_newpass(PKCS12 *p12, const char *oldpass, const char *newpass);
+
+=head1 DESCRIPTION
+
+PKCS12_newpass() changes the password of a PKCS12 structure.
+
+B<p12> is a pointer to a PKCS12 structure. B<oldpass> is the existing password
+and B<newpass> is the new password.
+
+=head1 RETURN VALUES
+
+PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
+retrieve the most recent error from PKCS12_newpass() with ERR_get_error().
+
+=head1 EXAMPLE
+
+This example loads a PKCS#12 file, changes its password and writes out
+the result to a new file.
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <openssl/pem.h>
+ #include <openssl/err.h>
+ #include <openssl/pkcs12.h>
+
+ int main(int argc, char **argv)
+ {
+ FILE *fp;
+ PKCS12 *p12;
+ if (argc != 5) {
+ fprintf(stderr, "Usage: pkread p12file password newpass opfile\n");
+ return 1;
+ }
+ if ((fp = fopen(argv[1], "rb")) == NULL) {
+ fprintf(stderr, "Error opening file %s\n", argv[1]);
+ return 1;
+ }
+ p12 = d2i_PKCS12_fp(fp, NULL);
+ fclose(fp);
+ if (p12 == NULL) {
+ fprintf(stderr, "Error reading PKCS#12 file\n");
+ ERR_print_errors_fp(stderr);
+ return 1;
+ }
+ if (PKCS12_newpass(p12, argv[2], argv[3]) == 0) {
+ fprintf(stderr, "Error changing password\n");
+ ERR_print_errors_fp(stderr);
+ PKCS12_free(p12);
+ return 1;
+ }
+ if ((fp = fopen(argv[4], "wb")) == NULL) {
+ fprintf(stderr, "Error opening file %s\n", argv[4]);
+ PKCS12_free(p12);
+ return 1;
+ }
+ i2d_PKCS12_fp(fp, p12);
+ PKCS12_free(p12);
+ fclose(fp);
+ return 0;
+ }
+
+
+=head1 NOTES
+
+If the PKCS#12 structure does not have a password, then you must use the empty
+string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
+PKCS12_newpass() failure.
+
+If the wrong password is used for B<oldpass> then the function will fail,
+with a MAC verification error. In rare cases the PKCS12 structure does not
+contain a MAC: in this case it will usually fail with a decryption padding
+error.
+
+=head1 BUGS
+
+The password format is a NULL terminated ASCII string which is converted to
+Unicode form internally. As a result some passwords cannot be supplied to
+this function.
+
+=head1 SEE ALSO
+
+L<PKCS12_create(3)>, L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS12_parse - parse a PKCS#12 structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs12.h>
+
+int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca);
+
+=head1 DESCRIPTION
+
+PKCS12_parse() parses a PKCS12 structure.
+
+B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use.
+If successful the private key will be written to B<*pkey>, the corresponding
+certificate to B<*cert> and any additional certificates to B<*ca>.
+
+=head1 NOTES
+
+The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in
+which case additional certificates will be discarded. B<*ca> can also be a
+valid STACK in which case additional certificates are appended to B<*ca>. If
+B<*ca> is B<NULL> a new STACK will be allocated.
+
+The B<friendlyName> and B<localKeyID> attributes (if present) on each
+certificate will be stored in the B<alias> and B<keyid> attributes of the
+B<X509> structure.
+
+=head1 RETURN VALUES
+
+PKCS12_parse() returns 1 for success and zero if an error occurred.
+
+The error can be obtained from L<ERR_get_error(3)>
+
+=head1 BUGS
+
+Only a single private key and corresponding certificate is returned by this
+function. More complex PKCS#12 files with multiple private keys will only
+return the first match.
+
+Only B<friendlyName> and B<localKeyID> attributes are currently stored in
+certificates. Other attributes are discarded.
+
+Attributes currently cannot be stored in the private key B<EVP_PKEY> structure.
+
+=head1 SEE ALSO
+
+L<d2i_PKCS12(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int PKCS5_PBKDF2_HMAC(const char *pass, int passlen,
+ const unsigned char *salt, int saltlen, int iter,
+ const EVP_MD *digest,
+ int keylen, unsigned char *out);
+
+int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen,
+ const unsigned char *salt, int saltlen, int iter,
+ int keylen, unsigned char *out);
+
+=head1 DESCRIPTION
+
+PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count
+as specified in RFC 2898.
+
+B<pass> is the password used in the derivation of length B<passlen>. B<pass>
+is an optional parameter and can be NULL. If B<passlen> is -1, then the
+function will calculate the length of B<pass> using strlen().
+
+B<salt> is the salt used in the derivation of length B<saltlen>. If the
+B<salt> is NULL, then B<saltlen> must be 0. The function will not
+attempt to calculate the length of the B<salt> because it is not assumed to
+be NULL terminated.
+
+B<iter> is the iteration count and its value should be greater than or
+equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
+B<iter> less than 1 is treated as a single iteration.
+
+B<digest> is the message digest function used in the derivation. Values include
+any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls
+PKCS5_PBKDF2_HMAC() with EVP_sha1().
+
+The derived key will be written to B<out>. The size of the B<out> buffer
+is specified via B<keylen>.
+
+=head1 NOTES
+
+A typical application of this function is to derive keying material for an
+encryption algorithm from a password in the B<pass>, a salt in B<salt>,
+and an iteration count.
+
+Increasing the B<iter> parameter slows down the algorithm which makes it
+harder for an attacker to perform a brute force attack using a large number
+of candidate passwords.
+
+=head1 RETURN VALUES
+
+PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error.
+
+=head1 SEE ALSO
+
+L<evp(3)>, L<rand(3)>,
+L<EVP_BytesToKey(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData
+structure. B<pkey> is the private key of the recipient, B<cert> is the
+recipients certificate, B<data> is a BIO to write the content to and
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Although the recipients certificate is not needed to decrypt the data it is needed
+to locate the appropriate (of possible several) recipients in the PKCS#7 structure.
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+=head1 RETURN VALUES
+
+PKCS7_decrypt() returns either 1 for success or 0 for failure.
+The error can be obtained from ERR_get_error(3)
+
+=head1 BUGS
+
+PKCS7_decrypt() must be passed the correct recipient key and certificate. It would
+be better if it could look up the correct key and certificate from a database.
+
+The lack of single pass processing and need to hold all data in memory as
+mentioned in PKCS7_sign() also applies to PKCS7_verify().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_encrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS7_encrypt - create a PKCS#7 envelopedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs>
+is a list of recipient certificates. B<in> is the content to be encrypted.
+B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
+certificates supplied to this function must all contain RSA public keys, though
+they do not have to be signed using the RSA algorithm.
+
+EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use
+because most clients will support it.
+
+Some old "export grade" clients may only support weak encryption using 40 or 64
+bit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc()
+respectively.
+
+The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
+its parameters.
+
+Many browsers implement a "sign and encrypt" option which is simply an S/MIME
+envelopedData containing an S/MIME signed message. This can be readily produced
+by storing the S/MIME signed message in a memory BIO and passing it to
+PKCS7_encrypt().
+
+The following flags can be passed in the B<flags> parameter.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are
+prepended to the data.
+
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation
+occurs. This option should be used if the supplied data is in binary format
+otherwise the translation will corrupt it. If B<PKCS7_BINARY> is set then
+B<PKCS7_TEXT> is ignored.
+
+If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output
+suitable for streaming I/O: no data is read from the BIO B<in>.
+
+=head1 NOTES
+
+If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
+complete and outputting its contents via a function that does not
+properly finalize the B<PKCS7> structure will give unpredictable
+results.
+
+Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
+PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_PKCS7().
+
+=head1 RETURN VALUES
+
+PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred.
+The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_decrypt(3)>
+
+=head1 HISTORY
+
+The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS7_sign - create a PKCS#7 signedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is
+the certificate to sign with, B<pkey> is the corresponding private key.
+B<certs> is an optional additional set of certificates to include in the PKCS#7
+structure (for example any intermediate CAs in the chain).
+
+The data to be signed is read from BIO B<data>.
+
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter.
+
+Many S/MIME clients expect the signed content to include valid MIME headers. If
+the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
+to the data.
+
+If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
+PKCS7 structure, the signer's certificate must still be supplied in the
+B<signcert> parameter though. This can reduce the size of the signature if the
+signers certificate can be obtained by other means: for example a previously
+signed message.
+
+The data being signed is included in the PKCS7 structure, unless
+B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7
+detached signatures which are used in S/MIME plaintext signed messages for
+example.
+
+Normally the supplied content is translated into MIME canonical format (as
+required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation
+occurs. This option should be used if the supplied data is in binary format
+otherwise the translation will corrupt it.
+
+The signedData structure includes several PKCS#7 autenticatedAttributes
+including the signing time, the PKCS#7 content type and the supported list of
+ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
+authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
+the SMIMECapabilities are omitted.
+
+If present the SMIMECapabilities attribute indicates support for the following
+algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
+these algorithms is disabled then it will not be included.
+
+If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is
+just initialized ready to perform the signing operation. The signing is however
+B<not> performed and the data to be signed is not read from the B<data>
+parameter. Signing is deferred until after the data has been written. In this
+way data can be signed in a single pass.
+
+If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
+which additional signers and capabilities can be added before finalization.
+
+
+=head1 NOTES
+
+If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
+complete and outputting its contents via a function that does not properly
+finalize the B<PKCS7> structure will give unpredictable results.
+
+Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
+PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_PKCS7().
+
+If a signer is specified it will use the default digest for the signing
+algorithm. This is B<SHA1> for both RSA and DSA keys.
+
+The B<certs>, B<signcert> and B<pkey> parameters can all be
+B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added
+using the function PKCS7_sign_add_signer(). PKCS7_final() must also be
+called to finalize the structure if streaming is not enabled. Alternative
+signing digests can also be specified using this method.
+
+If B<signcert> and B<pkey> are NULL then a certificates only
+PKCS#7 structure is output.
+
+In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must
+B<NOT> be NULL.
+
+=head1 BUGS
+
+Some advanced attributes such as counter signatures are not supported.
+
+=head1 RETURN VALUES
+
+PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_verify(3)>
+
+=head1 HISTORY
+
+The B<PKCS7_PARTIAL> flag, and the ability for B<certs>, B<signcert>,
+and B<pkey> parameters to be B<NULL> to be was added in OpenSSL 1.0.0
+
+The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS7_sign_add_signer - add a signer PKCS7 signed data structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags);
+
+
+=head1 DESCRIPTION
+
+PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private
+key B<pkey> using message digest B<md> to a PKCS7 signed data structure
+B<p7>.
+
+The PKCS7 structure should be obtained from an initial call to PKCS7_sign()
+with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7
+signed data structure.
+
+If the B<md> parameter is B<NULL> then the default digest for the public
+key algorithm will be used.
+
+Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure
+is not complete and must be finalized either by streaming (if applicable) or
+a call to PKCS7_final().
+
+
+=head1 NOTES
+
+The main purpose of this function is to provide finer control over a PKCS#7
+signed data structure where the simpler PKCS7_sign() function defaults are
+not appropriate. For example if multiple signers or non default digest
+algorithms are needed.
+
+Any of the following flags (ored together) can be passed in the B<flags>
+parameter.
+
+If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content
+digest value from the PKCS7 structure: to add a signer to an existing structure.
+An error occurs if a matching digest value cannot be found to copy. The
+returned PKCS7 structure will be valid and finalized when this flag is set.
+
+If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the
+B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes
+can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is
+needed to finalize it.
+
+If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
+PKCS7 structure, the signer's certificate must still be supplied in the
+B<signcert> parameter though. This can reduce the size of the signature if the
+signers certificate can be obtained by other means: for example a previously
+signed message.
+
+The signedData structure includes several PKCS#7 autenticatedAttributes
+including the signing time, the PKCS#7 content type and the supported list of
+ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
+authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
+the SMIMECapabilities are omitted.
+
+If present the SMIMECapabilities attribute indicates support for the following
+algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
+these algorithms is disabled then it will not be included.
+
+
+PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
+structure just added, this can be used to set additional attributes
+before it is finalized.
+
+=head1 RETURN VALUES
+
+PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
+structure just added or NULL if an error occurs.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
+L<PKCS7_final(3)>,
+
+=head1 HISTORY
+
+PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0
+
+=head1 COPYRIGHT
+
+Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags);
+
+ STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
+
+=head1 DESCRIPTION
+
+PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7
+structure to verify. B<certs> is a set of certificates in which to search for
+the signer's certificate. B<store> is a trusted certificate store (used for
+chain verification). B<indata> is the signed data if the content is not
+present in B<p7> (that is it is detached). The content is written to B<out>
+if it is not NULL.
+
+B<flags> is an optional set of flags, which can be used to modify the verify
+operation.
+
+PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does
+B<not> check their validity or whether any signatures are valid. The B<certs>
+and B<flags> parameters have the same meanings as in PKCS7_verify().
+
+=head1 VERIFY PROCESS
+
+Normally the verify process proceeds as follows.
+
+Initially some sanity checks are performed on B<p7>. The type of B<p7> must
+be signedData. There must be at least one signature on the data and if
+the content is detached B<indata> cannot be B<NULL>. If the content is
+not detached and B<indata> is not B<NULL>, then the structure has both
+embedded and external content. To treat this as an error, use the flag
+B<PKCS7_NO_DUAL_CONTENT>.
+The default behavior allows this, for compatibility with older
+versions of OpenSSL.
+
+An attempt is made to locate all the signer's certificates, first looking in
+the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates
+contained in the B<p7> structure itself. If any signer's certificates cannot be
+located the operation fails.
+
+Each signer's certificate is chain verified using the B<smimesign> purpose and
+the supplied trusted certificate store. Any internal certificates in the message
+are used as untrusted CAs. If any chain verify fails an error code is returned.
+
+Finally the signed content is read (and written to B<out> is it is not NULL) and
+the signature's checked.
+
+If all signature's verify correctly then the function is successful.
+
+Any of the following flags (ored together) can be passed in the B<flags> parameter
+to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is
+meaningful to PKCS7_get0_signers().
+
+If B<PKCS7_NOINTERN> is set the certificates in the message itself are not
+searched when locating the signer's certificate. This means that all the signers
+certificates must be in the B<certs> parameter.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
+from the content. If the content is not of type B<text/plain> then an error is
+returned.
+
+If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified.
+
+If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are
+not used as untrusted CAs. This means that the whole verify chain (apart from
+the signer's certificate) must be contained in the trusted store.
+
+If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked.
+
+=head1 NOTES
+
+One application of B<PKCS7_NOINTERN> is to only accept messages signed by
+a small number of certificates. The acceptable certificates would be passed
+in the B<certs> parameter. In this case if the signer is not one of the
+certificates supplied in B<certs> then the verify will fail because the
+signer cannot be found.
+
+Care should be taken when modifying the default verify behaviour, for example
+setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification
+and any signed message will be considered valid. This combination is however
+useful if one merely wishes to write the content to B<out> and its validity
+is not considered important.
+
+Chain verification should arguably be performed using the signing time rather
+than the current time. However since the signing time is supplied by the
+signer it cannot be trusted without additional evidence (such as a trusted
+timestamp).
+
+=head1 RETURN VALUES
+
+PKCS7_verify() returns one for a successful verification and zero
+if an error occurs.
+
+PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred.
+
+The error can be obtained from L<ERR_get_error(3)>
+
+=head1 BUGS
+
+The trusted certificate store is not searched for the signers certificate,
+this is primarily due to the inadequacies of the current B<X509_STORE>
+functionality.
+
+The lack of single pass processing and need to hold all data in memory as
+mentioned in PKCS7_sign() also applies to PKCS7_verify().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_sign(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add
+entropy to the PRNG
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ void RAND_seed(const void *buf, int num);
+
+ void RAND_add(const void *buf, int num, double entropy);
+
+ int RAND_status(void);
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
+ void RAND_screen(void);
+ #endif
+
+=head1 DESCRIPTION
+
+RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus,
+if the data at B<buf> are unpredictable to an adversary, this
+increases the uncertainty about the state and makes the PRNG output
+less predictable. Suitable input comes from user interaction (random
+key presses, mouse movements) and certain hardware events. The
+B<entropy> argument is (the lower bound of) an estimate of how much
+randomness is contained in B<buf>, measured in bytes. Details about
+sources of randomness and how to estimate their entropy can be found
+in the literature, e.g. RFC 1750.
+
+RAND_add() may be called with sensitive data such as user entered
+passwords. The seed values cannot be recovered from the PRNG output.
+
+OpenSSL makes sure that the PRNG state is unique for each thread. On
+systems that provide C</dev/urandom>, the randomness device is used
+to seed the PRNG transparently. However, on all other systems, the
+application is responsible for seeding the PRNG by calling RAND_add(),
+L<RAND_egd(3)>
+or L<RAND_load_file(3)>.
+
+RAND_seed() is equivalent to RAND_add() when B<num == entropy>.
+
+RAND_event() and RAND_screen() are deprecated and should not be called.
+
+=head1 RETURN VALUES
+
+RAND_status() returns 1 if the PRNG has been seeded
+with enough data, 0 otherwise.
+
+RAND_event() calls RAND_poll() and returns RAND_status().
+
+RAND_screen calls RAND_poll().
+
+The other functions do not return values.
+
+=head1 HISTORY
+
+RAND_event() and RAND_screen() are deprecated since OpenSSL
+1.1.0. Use the functions described above instead.
+
+=head1 SEE ALSO
+
+L<rand(3)>, L<RAND_egd(3)>,
+L<RAND_load_file(3)>, L<RAND_cleanup(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RAND_bytes, RAND_pseudo_bytes - generate random data
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ int RAND_bytes(unsigned char *buf, int num);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ int RAND_pseudo_bytes(unsigned char *buf, int num);
+ #endif
+
+=head1 DESCRIPTION
+
+RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
+into B<buf>. An error occurs if the PRNG has not been seeded with
+enough randomness to ensure an unpredictable byte sequence.
+
+RAND_pseudo_bytes() has been deprecated. Users should use RAND_bytes() instead.
+RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>.
+Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be
+unique if they are of sufficient length, but are not necessarily
+unpredictable. They can be used for non-cryptographic purposes and for
+certain purposes in cryptographic protocols, but usually not for key
+generation etc.
+
+The contents of B<buf> is mixed into the entropy pool before retrieving
+the new pseudo-random bytes unless disabled at compile time (see FAQ).
+
+=head1 RETURN VALUES
+
+RAND_bytes() returns 1 on success, 0 otherwise. The error code can be
+obtained by L<ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the
+bytes generated are cryptographically strong, 0 otherwise. Both
+functions return -1 if they are not supported by the current RAND
+method.
+
+=head1 SEE ALSO
+
+L<rand(3)>, L<ERR_get_error(3)>,
+L<RAND_add(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RAND_cleanup - erase the PRNG state
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void RAND_cleanup(void)
+ #endif
+
+=head1 DESCRIPTION
+
+Prior to OpenSSL 1.1.0 RAND_cleanup() erases the memory used by the PRNG. This
+function is deprecated and as of version 1.1.0 does nothing. No explicit
+initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>.
+
+=head1 RETURN VALUE
+
+RAND_cleanup() returns no value.
+
+=head1 SEE ALSO
+
+L<rand(3)>
+
+=head1 HISTORY
+
+RAND_cleanup() was deprecated in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ int RAND_egd(const char *path);
+ int RAND_egd_bytes(const char *path, int bytes);
+
+ int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);
+
+=head1 DESCRIPTION
+
+RAND_egd() queries the entropy gathering daemon EGD on socket B<path>.
+It queries 255 bytes and uses L<RAND_add(3)> to seed the
+OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for
+RAND_egd_bytes(path, 255);
+
+RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>.
+It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the
+OpenSSL built-in PRNG.
+This function is more flexible than RAND_egd().
+When only one secret key must
+be generated, it is not necessary to request the full amount 255 bytes from
+the EGD socket. This can be advantageous, since the amount of entropy
+that can be retrieved from EGD over time is limited.
+
+RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket
+B<path>. If B<buf> is given, B<bytes> bytes are queried and written into
+B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the
+OpenSSL built-in PRNG using L<RAND_add(3)>.
+
+=head1 NOTES
+
+On systems without /dev/*random devices providing entropy from the kernel,
+the EGD entropy gathering daemon can be used to collect entropy. It provides
+a socket interface through which entropy can be gathered in chunks up to
+255 bytes. Several chunks can be queried during one connection.
+
+EGD is available from http://www.lothar.com/tech/crypto/ (C<perl
+Makefile.PL; make; make install> to install). It is run as B<egd>
+I<path>, where I<path> is an absolute path designating a socket. When
+RAND_egd() is called with that path as an argument, it tries to read
+random bytes that EGD has collected. RAND_egd() retrieves entropy from the
+daemon using the daemon's "non-blocking read" command which shall
+be answered immediately by the daemon without waiting for additional
+entropy to be collected. The write and read socket operations in the
+communication are blocking.
+
+Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is
+available from
+http://prngd.sourceforge.net/ .
+PRNGD does employ an internal PRNG itself and can therefore never run
+out of entropy.
+
+OpenSSL automatically queries EGD when entropy is requested via RAND_bytes()
+or the status is checked via RAND_status() for the first time, if the socket
+is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.
+
+=head1 RETURN VALUE
+
+RAND_egd() and RAND_egd_bytes() return the number of bytes read from the
+daemon on success, and -1 if the connection failed or the daemon did not
+return enough data to fully seed the PRNG.
+
+RAND_query_egd_bytes() returns the number of bytes read from the daemon on
+success, and -1 if the connection failed. The PRNG state is not considered.
+
+=head1 SEE ALSO
+
+L<rand(3)>, L<RAND_add(3)>,
+L<RAND_cleanup(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ const char *RAND_file_name(char *buf, size_t num);
+
+ int RAND_load_file(const char *filename, long max_bytes);
+
+ int RAND_write_file(const char *filename);
+
+=head1 DESCRIPTION
+
+RAND_file_name() generates a default path for the random seed
+file. B<buf> points to a buffer of size B<num> in which to store the
+filename.
+
+On all systems, if the environment variable B<RANDFILE> is set, its
+value will be used as the seed file name.
+
+Otherwise, the file is called ".rnd", found in platform dependent locations:
+
+=over 4
+
+=item On Windows (in order of preference)
+
+%HOME%, %USERPROFILE%, %SYSTEMROOT%, C:\
+
+=item On VMS
+
+SYS$LOGIN:
+
+=item On all other systems
+
+$HOME
+
+=back
+
+If C<$HOME> (on non-Windows and non-VMS system) is not set either, or
+B<num> is too small for the path name, an error occurs.
+
+RAND_load_file() reads a number of bytes from file B<filename> and
+adds them to the PRNG. If B<max_bytes> is non-negative,
+up to B<max_bytes> are read;
+if B<max_bytes> is -1, the complete file is read.
+
+RAND_write_file() writes a number of random bytes (currently 1024) to
+file B<filename> which can be used to initialize the PRNG by calling
+RAND_load_file() in a later session.
+
+=head1 RETURN VALUES
+
+RAND_load_file() returns the number of bytes read.
+
+RAND_write_file() returns the number of bytes written, and -1 if the
+bytes written were generated without appropriate seed.
+
+RAND_file_name() returns a pointer to B<buf> on success, and NULL on
+error.
+
+=head1 SEE ALSO
+
+L<rand(3)>, L<RAND_add(3)>, L<RAND_cleanup(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand.h>
+
+ void RAND_set_rand_method(const RAND_METHOD *meth);
+
+ const RAND_METHOD *RAND_get_rand_method(void);
+
+ RAND_METHOD *RAND_OpenSSL(void);
+
+=head1 DESCRIPTION
+
+A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number
+generation. By modifying the method, alternative implementations such as
+hardware RNGs may be used. IMPORTANT: See the NOTES section for important
+information about how these RAND API functions are affected by the use of
+B<ENGINE> API calls.
+
+Initially, the default RAND_METHOD is the OpenSSL internal implementation, as
+returned by RAND_OpenSSL().
+
+RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is
+true only whilst no ENGINE has been set as a default for RAND, so this function
+is no longer recommended.
+
+RAND_get_default_method() returns a pointer to the current RAND_METHOD.
+However, the meaningfulness of this result is dependent on whether the ENGINE
+API is being used, so this function is no longer recommended.
+
+=head1 THE RAND_METHOD STRUCTURE
+
+ typedef struct rand_meth_st
+ {
+ void (*seed)(const void *buf, int num);
+ int (*bytes)(unsigned char *buf, int num);
+ void (*cleanup)(void);
+ void (*add)(const void *buf, int num, int entropy);
+ int (*pseudorand)(unsigned char *buf, int num);
+ int (*status)(void);
+ } RAND_METHOD;
+
+The components point to method implementations used by (or called by), in order,
+RAND_seed(), RAND_bytes(), internal RAND cleanup, RAND_add(), RAND_pseudo_rand()
+and RAND_status().
+Each component may be NULL if the function is not implemented.
+
+=head1 RETURN VALUES
+
+RAND_set_rand_method() returns no value. RAND_get_rand_method() and
+RAND_OpenSSL() return pointers to the respective methods.
+
+=head1 NOTES
+
+RAND_METHOD implementations are grouped together with other
+algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
+default ENGINE is specified for RAND functionality using an ENGINE API function,
+that will override any RAND defaults set using the RAND API (ie.
+RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way
+to control default implementations for use in RAND and other cryptographic
+algorithms.
+
+=head1 SEE ALSO
+
+L<rand(3)>, L<engine(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RC4_set_key, RC4 - RC4 encryption
+
+=head1 SYNOPSIS
+
+ #include <openssl/rc4.h>
+
+ void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data);
+
+ void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata,
+ unsigned char *outdata);
+
+=head1 DESCRIPTION
+
+This library implements the Alleged RC4 cipher, which is described for
+example in I<Applied Cryptography>. It is believed to be compatible
+with RC4[TM], a proprietary cipher of RSA Security Inc.
+
+RC4 is a stream cipher with variable key length. Typically, 128 bit
+(16 byte) keys are used for strong encryption, but shorter insecure
+key sizes have been widely used due to export restrictions.
+
+RC4 consists of a key setup phase and the actual encryption or
+decryption phase.
+
+RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long
+key at B<data>.
+
+RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using
+B<key> and places the result at B<outdata>. Repeated RC4() calls with
+the same B<key> yield a continuous key stream.
+
+Since RC4 is a stream cipher (the input is XORed with a pseudo-random
+key stream to produce the output), decryption uses the same function
+calls as encryption.
+
+=head1 RETURN VALUES
+
+RC4_set_key() and RC4() do not return values.
+
+=head1 NOTE
+
+Applications should use the higher level functions
+L<EVP_EncryptInit(3)> etc. instead of calling these
+functions directly.
+
+It is difficult to securely use stream ciphers. For example, do not perform
+multiple encryptions using the same key stream.
+
+=head1 SEE ALSO
+
+L<EVP_EncryptInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final -
+RIPEMD-160 hash function
+
+=head1 SYNOPSIS
+
+ #include <openssl/ripemd.h>
+
+ unsigned char *RIPEMD160(const unsigned char *d, unsigned long n,
+ unsigned char *md);
+
+ int RIPEMD160_Init(RIPEMD160_CTX *c);
+ int RIPEMD160_Update(RIPEMD_CTX *c, const void *data,
+ unsigned long len);
+ int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c);
+
+=head1 DESCRIPTION
+
+RIPEMD-160 is a cryptographic hash function with a
+160 bit output.
+
+RIPEMD160() computes the RIPEMD-160 message digest of the B<n>
+bytes at B<d> and places it in B<md> (which must have space for
+RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
+is placed in a static array.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure.
+
+RIPEMD160_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+RIPEMD160_Final() places the message digest in B<md>, which must have
+space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases
+the B<RIPEMD160_CTX>.
+
+=head1 RETURN VALUES
+
+RIPEMD160() returns a pointer to the hash value.
+
+RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for
+success, 0 otherwise.
+
+=head1 NOTE
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)> etc. instead of calling these
+functions directly.
+
+=head1 CONFORMING TO
+
+ISO/IEC 10118-3 (draft) (??)
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
+
+ void RSA_blinding_off(RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA is vulnerable to timing attacks. In a setup where attackers can
+measure the time of RSA decryption or signature operations, blinding
+must be used to protect the RSA operation from that attack.
+
+RSA_blinding_on() turns blinding on for key B<rsa> and generates a
+random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
+initialized B<BN_CTX>. The random number generator must be seeded
+prior to calling RSA_blinding_on().
+
+RSA_blinding_off() turns blinding off and frees the memory used for
+the blinding factor.
+
+=head1 RETURN VALUES
+
+RSA_blinding_on() returns 1 on success, and 0 if an error occurred.
+
+RSA_blinding_off() returns no value.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_check_key_ex, RSA_check_key - validate private RSA keys
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_check_key_ex(RSA *rsa, BN_GENCB *cb);
+
+ int RSA_check_key(RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_check_key_ex() function validates RSA keys.
+It checks that B<p> and B<q> are
+in fact prime, and that B<n = p*q>.
+
+It does not work on RSA public keys that have only the modulus
+and public exponent elements populated.
+It also checks that B<d*e = 1 mod (p-1*q-1)>,
+and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>.
+It performs integrity checks on all
+the RSA key material, so the RSA key structure must contain all the private
+key data too.
+Therefore, it cannot be used with any arbitrary RSA key object,
+even if it is otherwise fit for regular RSA operation.
+
+The B<cb> parameter is a callback that will be invoked in the same
+manner as L<BN_is_prime_ex(3)>.
+
+RSA_check_key() is equivalent to RSA_check_key_ex() with a NULL B<cb>.
+
+=head1 RETURN VALUE
+
+RSA_check_key_ex() and RSA_check_key()
+return 1 if B<rsa> is a valid RSA key, and 0 otherwise.
+They return -1 if an error occurs while checking the key.
+
+If the key is invalid or an error occurred, the reason code can be
+obtained using L<ERR_get_error(3)>.
+
+=head1 NOTES
+
+Unlike most other RSA functions, this function does B<not> work
+transparently with any underlying ENGINE implementation because it uses the
+key data in the RSA structure directly. An ENGINE implementation can
+override the way key data is stored and handled, and can even provide
+support for HSM keys - in which case the RSA structure may contain B<no>
+key data at all! If the ENGINE in question is only being used for
+acceleration or analysis purposes, then in all likelihood the RSA key data
+is complete and untouched, but this can't be assumed in the general case.
+
+=head1 BUGS
+
+A method of verifying the RSA key using opaque RSA API functions might need
+to be considered. Right now RSA_check_key() simply uses the RSA structure
+elements directly, bypassing the RSA_METHOD table altogether (and
+completely violating encapsulation and object-orientation in the process).
+The best fix will probably be to introduce a "check_key()" handler to the
+RSA_METHOD function table so that alternative implementations can also
+provide their own verifiers.
+
+=head1 SEE ALSO
+
+L<BN_is_prime_ex(3)>,
+L<ERR_get_error(3)>
+
+=head1 HISTORY
+
+RSA_check_key_ex() appeared after OpenSSL 1.0.2.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_generate_key_ex, RSA_generate_key - generate RSA key pair
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x00908000L
+ RSA *RSA_generate_key(int num, unsigned long e,
+ void (*callback)(int, int, void *), void *cb_arg);
+ #endif
+
+=head1 DESCRIPTION
+
+RSA_generate_key_ex() generates a key pair and stores it in the B<RSA>
+structure provided in B<rsa>. The pseudo-random number generator must
+be seeded prior to calling RSA_generate_key_ex().
+
+The modulus size will be of length B<bits>, and the public exponent will be
+B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
+The exponent is an odd number, typically 3, 17 or 65537.
+
+A callback function may be used to provide feedback about the
+progress of the key generation. If B<cb> is not B<NULL>, it
+will be called as follows using the BN_GENCB_call() function
+described on the L<BN_generate_prime(3)> page.
+
+=over 4
+
+=item *
+
+While a random prime number is generated, it is called as
+described in L<BN_generate_prime(3)>.
+
+=item *
+
+When the n-th randomly generated prime is rejected as not
+suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
+
+=item *
+
+When a random p has been found with p-1 relatively prime to B<e>,
+it is called as B<BN_GENCB_call(cb, 3, 0)>.
+
+=back
+
+The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
+
+RSA_generate_key is deprecated (new applications should use
+RSA_generate_key_ex instead). RSA_generate_key works in the same was as
+RSA_generate_key_ex except it uses "old style" call backs. See
+L<BN_generate_prime(3)> for further details.
+
+=head1 RETURN VALUE
+
+If key generation fails, RSA_generate_key() returns B<NULL>.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 BUGS
+
+B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
+
+RSA_generate_key() goes into an infinite loop for illegal input values.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<rand(3)>,
+L<RSA_generate_key(3)>, L<BN_generate_prime(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key,
+RSA_get0_factors, RSA_get0_crt_params, RSA_clear_flags,
+RSA_test_flags, RSA_set_flags, RSA_get0_engine - Routines for getting
+and setting data in an RSA object
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_set0_key(RSA *r, BIGNUM *n, BIGNUM *e, BIGNUM *d);
+ int RSA_set0_factors(RSA *r, BIGNUM *p, BIGNUM *q);
+ int RSA_set0_crt_params(RSA *r, BIGNUM *dmp1, BIGNUM *dmq1, BIGNUM *iqmp);
+ void RSA_get0_key(const RSA *r,
+ const BIGNUM **n, const BIGNUM **e, const BIGNUM **d);
+ void RSA_get0_factors(const RSA *r, const BIGNUM **p, const BIGNUM **q);
+ void RSA_get0_crt_params(const RSA *r,
+ const BIGNUM **dmp1, const BIGNUM **dmq1,
+ const BIGNUM **iqmp);
+ void RSA_clear_flags(RSA *r, int flags);
+ int RSA_test_flags(const RSA *r, int flags);
+ void RSA_set_flags(RSA *r, int flags);
+ ENGINE *RSA_get0_engine(RSA *r);
+
+=head1 DESCRIPTION
+
+An RSA object contains the components for the public and private key,
+B<n>, B<e>, B<d>, B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp>. B<n> is
+the modulus common to both public and private key, B<e> is the public
+exponent and B<d> is the private exponent. B<p>, B<q>, B<dmp1>,
+B<dmq1> and B<iqmp> are the factors for the second representation of a
+private key (see PKCS#1 section 3 Key Types), where B<p> and B<q> are
+the first and second factor of B<n> and B<dmp1>, B<dmq1> and B<iqmp>
+are the exponents and coefficient for CRT calculations.
+
+The B<n>, B<e> and B<d> parameters can be obtained by calling
+RSA_get0_key(). If they have not been set yet, then B<*n>, B<*e> and
+B<*d> will be set to NULL. Otherwise, they are set to pointers to
+their respective values. These point directly to the internal
+representations of the values and therefore should not be freed
+by the caller.
+
+The B<n>, B<e> and B<d> parameter values can be set by calling
+RSA_set0_key() and passing the new values for B<n>, B<e> and B<d> as
+parameters to the function. The values B<n> and B<e> must be non-NULL
+the first time this function is called on a given RSA object. The
+value B<d> may be NULL. On subsequent calls any of these values may be
+NULL which means the corresponding RSA field is left untouched.
+Calling this function transfers the memory management of the values to
+the RSA object, and therefore the values that have been passed in
+should not be freed by the caller after this function has been called.
+
+In a similar fashion, the B<p> and B<q> parameters can be obtained and
+set with RSA_get0_factors() and RSA_set0_factors(), and the B<dmp1>,
+B<dmq1> and B<iqmp> parameters can be obtained and set with
+RSA_get0_crt_params() and RSA_set0_crt_params().
+
+RSA_set_flags() sets the flags in the B<flags> parameter on the RSA
+object. Multiple flags can be passed in one go (bitwise ORed together).
+Any flags that are already set are left set. RSA_test_flags() tests to
+see whether the flags passed in the B<flags> parameter are currently
+set in the RSA object. Multiple flags can be tested in one go. All
+flags that are currently set are returned, or zero if none of the
+flags are set. RSA_clear_flags() clears the specified flags within the
+RSA object.
+
+RSA_get0_engine() returns a handle to the ENGINE that has been set for
+this RSA object, or NULL if no such ENGINE has been set.
+
+=head1 NOTES
+
+Values retrieved with RSA_get0_key() are owned by the RSA object used
+in the call and may therefore I<not> be passed to RSA_set0_key(). If
+needed, duplicate the received value using BN_dup() and pass the
+duplicate. The same applies to RSA_get0_factors() and RSA_set0_factors()
+as well as RSA_get0_crt_params() and RSA_set0_crt_params().
+
+=head1 RETURN VALUES
+
+RSA_set0_key(), RSA_set0_factors and RSA_set0_crt_params() return 1 on
+success or 0 on failure.
+
+RSA_test_flags() returns the current state of the flags in the RSA object.
+
+RSA_get0_engine() returns the ENGINE set for the RSA object or NULL if no
+ENGINE has been set.
+
+=head1 SEE ALSO
+
+L<rsa(3)>, L<RSA_new(3)>, L<RSA_size(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_meth_get0_app_data, RSA_meth_set0_app_data,
+RSA_meth_new, RSA_meth_free, RSA_meth_dup, RSA_meth_get0_name,
+RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags,
+RSA_meth_get_pub_enc,
+RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec,
+RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec,
+RSA_meth_set_priv_dec, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp,
+RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_init,
+RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish,
+RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify,
+RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen
+- Routines to build up RSA methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ RSA_METHOD *RSA_meth_new(const char *name, int flags);
+ void RSA_meth_free(RSA_METHOD *meth);
+ RSA_METHOD *RSA_meth_dup(const RSA_METHOD *meth);
+ const char *RSA_meth_get0_name(const RSA_METHOD *meth);
+ int RSA_meth_set1_name(RSA_METHOD *meth, const char *name);
+ int RSA_meth_get_flags(RSA_METHOD *meth);
+ int RSA_meth_set_flags(RSA_METHOD *meth, int flags);
+ void *RSA_meth_get0_app_data(const RSA_METHOD *meth);
+ int RSA_meth_set0_app_data(RSA_METHOD *meth, void *app_data);
+ int (*RSA_meth_get_pub_enc(const RSA_METHOD *meth))
+ (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+ int RSA_meth_set_pub_enc(RSA_METHOD *rsa,
+ int (*pub_enc) (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa,
+ int padding));
+ int (*RSA_meth_get_pub_dec(const RSA_METHOD *meth))
+ (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+ int RSA_meth_set_pub_dec(RSA_METHOD *rsa,
+ int (*pub_dec) (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa,
+ int padding));
+ int (*RSA_meth_get_priv_enc(const RSA_METHOD *meth))
+ (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+ int RSA_meth_set_priv_enc(RSA_METHOD *rsa,
+ int (*priv_enc) (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa,
+ int padding));
+ int (*RSA_meth_get_priv_dec(const RSA_METHOD *meth))
+ (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+ int RSA_meth_set_priv_dec(RSA_METHOD *rsa,
+ int (*priv_dec) (int flen, const unsigned char *from,
+ unsigned char *to, RSA *rsa,
+ int padding));
+ /* Can be null */
+ int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))
+ (BIGNUM *r0, const BIGNUM *I, RSA *rsa, BN_CTX *ctx);
+ int RSA_meth_set_mod_exp(RSA_METHOD *rsa,
+ int (*mod_exp) (BIGNUM *r0, const BIGNUM *I, RSA *rsa,
+ BN_CTX *ctx));
+ /* Can be null */
+ int (*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))
+ (BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
+ int RSA_meth_set_bn_mod_exp(RSA_METHOD *rsa,
+ int (*bn_mod_exp) (BIGNUM *r,
+ const BIGNUM *a,
+ const BIGNUM *p,
+ const BIGNUM *m,
+ BN_CTX *ctx,
+ BN_MONT_CTX *m_ctx));
+ /* called at new */
+ int (*RSA_meth_get_init(const RSA_METHOD *meth)) (RSA *rsa);
+ int RSA_meth_set_init(RSA_METHOD *rsa, int (*init) (RSA *rsa));
+ /* called at free */
+ int (*RSA_meth_get_finish(const RSA_METHOD *meth)) (RSA *rsa);
+ int RSA_meth_set_finish(RSA_METHOD *rsa, int (*finish) (RSA *rsa));
+ int (*RSA_meth_get_sign(const RSA_METHOD *meth))
+ (int type,
+ const unsigned char *m, unsigned int m_length,
+ unsigned char *sigret, unsigned int *siglen,
+ const RSA *rsa);
+ int RSA_meth_set_sign(RSA_METHOD *rsa,
+ int (*sign) (int type, const unsigned char *m,
+ unsigned int m_length,
+ unsigned char *sigret, unsigned int *siglen,
+ const RSA *rsa));
+ int (*RSA_meth_get_verify(const RSA_METHOD *meth))
+ (int dtype, const unsigned char *m,
+ unsigned int m_length, const unsigned char *sigbuf,
+ unsigned int siglen, const RSA *rsa);
+ int RSA_meth_set_verify(RSA_METHOD *rsa,
+ int (*verify) (int dtype, const unsigned char *m,
+ unsigned int m_length,
+ const unsigned char *sigbuf,
+ unsigned int siglen, const RSA *rsa));
+ int (*RSA_meth_get_keygen(const RSA_METHOD *meth))
+ (RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
+ int RSA_meth_set_keygen(RSA_METHOD *rsa,
+ int (*keygen) (RSA *rsa, int bits, BIGNUM *e,
+ BN_GENCB *cb));
+
+=head1 DESCRIPTION
+
+The B<RSA_METHOD> type is a structure used for the provision of custom
+RSA implementations. It provides a set of of functions used by OpenSSL
+for the implementation of the various RSA capabilities. See the L<rsa>
+page for more information.
+
+RSA_meth_new() creates a new B<RSA_METHOD> structure. It should be
+given a unique B<name> and a set of B<flags>. The B<name> should be a
+NULL terminated string, which will be duplicated and stored in the
+B<RSA_METHOD> object. It is the callers responsibility to free the
+original string. The flags will be used during the construction of a
+new B<RSA> object based on this B<RSA_METHOD>. Any new B<RSA> object
+will have those flags set by default.
+
+RSA_meth_dup() creates a duplicate copy of the B<RSA_METHOD> object
+passed as a parameter. This might be useful for creating a new
+B<RSA_METHOD> based on an existing one, but with some differences.
+
+RSA_meth_free() destroys an B<RSA_METHOD> structure and frees up any
+memory associated with it.
+
+RSA_meth_get0_name() will return a pointer to the name of this
+RSA_METHOD. This is a pointer to the internal name string and so
+should not be freed by the caller. RSA_meth_set1_name() sets the name
+of the RSA_METHOD to B<name>. The string is duplicated and the copy is
+stored in the RSA_METHOD structure, so the caller remains responsible
+for freeing the memory associated with the name.
+
+RSA_meth_get_flags() returns the current value of the flags associated
+with this RSA_METHOD. RSA_meth_set_flags() provides the ability to set
+these flags.
+
+The functions RSA_meth_get0_app_data() and RSA_meth_set0_app_data()
+provide the ability to associate implementation specific data with the
+RSA_METHOD. It is the application's responsibility to free this data
+before the RSA_METHOD is freed via a call to RSA_meth_free().
+
+RSA_meth_get_sign() and RSA_meth_set_sign() get and set the function
+used for creating an RSA signature respectively. This function will be
+called in response to the application calling RSA_sign(). The
+parameters for the function have the same meaning as for RSA_sign().
+
+RSA_meth_get_verify() and RSA_meth_set_verify() get and set the
+function used for verifying an RSA signature respectively. This
+function will be called in response to the application calling
+RSA_verify(). The parameters for the function have the same meaning as
+for RSA_verify().
+
+RSA_meth_get_mod_exp() and RSA_meth_set_mod_exp() get and set the
+function used for CRT computations.
+
+RSA_meth_get_bn_mod_exp() and RSA_meth_set_bn_mod_exp() get and set
+the function used for CRT computations, specifically the following
+value:
+
+ r = a ^ p mod m
+
+Both the mod_exp() and bn_mod_exp() functions are called by the
+default OpenSSL method during encryption, decryption, signing and
+verification.
+
+RSA_meth_get_init() and RSA_meth_set_init() get and set the function
+used for creating a new RSA instance respectively. This function will
+be called in response to the application calling RSA_new() (if the
+current default RSA_METHOD is this one) or RSA_new_method(). The
+RSA_new() and RSA_new_method() functions will allocate the memory for
+the new RSA object, and a pointer to this newly allocated structure
+will be passed as a parameter to the function. This function may be
+NULL.
+
+RSA_meth_get_finish() and RSA_meth_set_finish() get and set the
+function used for destroying an instance of an RSA object respectively.
+This function will be called in response to the application calling
+RSA_free(). A pointer to the RSA to be destroyed is passed as a
+parameter. The destroy function should be used for RSA implementation
+specific clean up. The memory for the RSA itself should not be freed
+by this function. This function may be NULL.
+
+RSA_meth_get_keygen() and RSA_meth_set_keygen() get and set the
+function used for generating a new RSA key pair respectively. This
+function will be called in response to the application calling
+RSA_generate_key(). The parameter for the function has the same
+meaning as for RSA_generate_key().
+
+RSA_meth_get_pub_enc(), RSA_meth_set_pub_enc(),
+RSA_meth_get_pub_dec(), RSA_meth_set_pub_dec(),
+RSA_meth_get_priv_enc(), RSA_meth_set_priv_enc(),
+RSA_meth_get_priv_dec(), RSA_meth_set_priv_dec() get and set the
+functions used for public and private key encryption and decryption.
+These functions will be called in response to the application calling
+RSA_public_encrypt(), RSA_private_decrypt(), RSA_private_encrypt() and
+RSA_public_decrypt() and take the same parameters as those.
+
+
+=head1 RETURN VALUES
+
+RSA_meth_new() and RSA_meth_dup() return the newly allocated
+RSA_METHOD object or NULL on failure.
+
+RSA_meth_get0_name() and RSA_meth_get_flags() return the name and
+flags associated with the RSA_METHOD respectively.
+
+All other RSA_meth_get_*() functions return the appropriate function
+pointer that has been set in the RSA_METHOD, or NULL if no such
+pointer has yet been set.
+
+RSA_meth_set1_name and all RSA_meth_set_*() functions return 1 on
+success or 0 on failure.
+
+=head1 SEE ALSO
+
+L<RSA_new(3)>, L<RSA_generate_key(3)>, L<RSA_sign(3)>,
+L<RSA_set_method(3)>, L<RSA_size(3)>, L<RSA_get0_key(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_new, RSA_free - allocate and free RSA objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ RSA * RSA_new(void);
+
+ void RSA_free(RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to
+calling RSA_new_method(NULL).
+
+RSA_free() frees the B<RSA> structure and its components. The key is
+erased before the memory is returned to the system.
+If B<rsa> is NULL nothing is done.
+
+=head1 RETURN VALUES
+
+If the allocation fails, RSA_new() returns B<NULL> and sets an error
+code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns
+a pointer to the newly allocated structure.
+
+RSA_free() returns no value.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<RSA_generate_key(3)>,
+L<RSA_new_method(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
+RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
+RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
+RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
+RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
+padding
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+ int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+ int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
+ unsigned char *f, int fl, unsigned char *p, int pl);
+
+ int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl);
+
+ int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+ int RSA_padding_add_none(unsigned char *to, int tlen,
+ unsigned char *f, int fl);
+
+ int RSA_padding_check_none(unsigned char *to, int tlen,
+ unsigned char *f, int fl, int rsa_len);
+
+=head1 DESCRIPTION
+
+The RSA_padding_xxx_xxx() functions are called from the RSA encrypt,
+decrypt, sign and verify functions. Normally they should not be called
+from application programs.
+
+However, they can also be called directly to implement padding for other
+asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and
+RSA_padding_check_PKCS1_OAEP() may be used in an application combined
+with B<RSA_NO_PADDING> in order to implement OAEP with an encoding
+parameter.
+
+RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into
+B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl>
+does not meet the size requirements of the encoding method.
+
+The following encoding methods are implemented:
+
+=over 4
+
+=item PKCS1_type_1
+
+PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures
+
+=item PKCS1_type_2
+
+PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2)
+
+=item PKCS1_OAEP
+
+PKCS #1 v2.0 EME-OAEP
+
+=item SSLv23
+
+PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
+
+=item none
+
+simply copy the data
+
+=back
+
+The random number generator must be seeded prior to calling
+RSA_padding_add_xxx().
+
+RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
+a valid encoding for a B<rsa_len> byte RSA key in the respective
+encoding method and stores the recovered data of at most B<tlen> bytes
+(for B<RSA_NO_PADDING>: of size B<tlen>)
+at B<to>.
+
+For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
+of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
+
+=head1 RETURN VALUES
+
+The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
+The RSA_padding_check_xxx() functions return the length of the
+recovered data, -1 on error. Error codes can be obtained by calling
+L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<RSA_public_encrypt(3)>,
+L<RSA_private_decrypt(3)>,
+L<RSA_sign(3)>, L<RSA_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_print, RSA_print_fp,
+DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp,
+DHparams_print, DHparams_print_fp - print cryptographic parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_print(BIO *bp, RSA *x, int offset);
+ int RSA_print_fp(FILE *fp, RSA *x, int offset);
+
+ #include <openssl/dsa.h>
+
+ int DSAparams_print(BIO *bp, DSA *x);
+ int DSAparams_print_fp(FILE *fp, DSA *x);
+ int DSA_print(BIO *bp, DSA *x, int offset);
+ int DSA_print_fp(FILE *fp, DSA *x, int offset);
+
+ #include <openssl/dh.h>
+
+ int DHparams_print(BIO *bp, DH *x);
+ int DHparams_print_fp(FILE *fp, DH *x);
+
+=head1 DESCRIPTION
+
+A human-readable hexadecimal output of the components of the RSA
+key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>.
+
+The output lines are indented by B<offset> spaces.
+
+=head1 RETURN VALUES
+
+These functions return 1 on success, 0 on error.
+
+=head1 SEE ALSO
+
+L<BN_bn2bin(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_private_encrypt, RSA_public_decrypt - low level signature operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_private_encrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ int RSA_public_decrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+=head1 DESCRIPTION
+
+These functions handle RSA signatures at a low level.
+
+RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a
+message digest with an algorithm identifier) using the private key
+B<rsa> and stores the signature in B<to>. B<to> must point to
+B<RSA_size(rsa)> bytes of memory.
+
+B<padding> denotes one of the following modes:
+
+=over 4
+
+=item RSA_PKCS1_PADDING
+
+PKCS #1 v1.5 padding. This function does not handle the
+B<algorithmIdentifier> specified in PKCS #1. When generating or
+verifying PKCS #1 signatures, L<RSA_sign(3)> and L<RSA_verify(3)> should be
+used.
+
+=item RSA_NO_PADDING
+
+Raw RSA signature. This mode should I<only> be used to implement
+cryptographically sound padding modes in the application code.
+Signing user data directly with RSA is insecure.
+
+=back
+
+RSA_public_decrypt() recovers the message digest from the B<flen>
+bytes long signature at B<from> using the signer's public key
+B<rsa>. B<to> must point to a memory section large enough to hold the
+message digest (which is smaller than B<RSA_size(rsa) -
+11>). B<padding> is the padding mode that was used to sign the data.
+
+=head1 RETURN VALUES
+
+RSA_private_encrypt() returns the size of the signature (i.e.,
+RSA_size(rsa)). RSA_public_decrypt() returns the size of the
+recovered message digest.
+
+On error, -1 is returned; the error codes can be
+obtained by L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<RSA_sign(3)>, L<RSA_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_public_encrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ int RSA_private_decrypt(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+=head1 DESCRIPTION
+
+RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a
+session key) using the public key B<rsa> and stores the ciphertext in
+B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory.
+
+B<padding> denotes one of the following modes:
+
+=over 4
+
+=item RSA_PKCS1_PADDING
+
+PKCS #1 v1.5 padding. This currently is the most widely used mode.
+
+=item RSA_PKCS1_OAEP_PADDING
+
+EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty
+encoding parameter. This mode is recommended for all new applications.
+
+=item RSA_SSLV23_PADDING
+
+PKCS #1 v1.5 padding with an SSL-specific modification that denotes
+that the server is SSL3 capable.
+
+=item RSA_NO_PADDING
+
+Raw RSA encryption. This mode should I<only> be used to implement
+cryptographically sound padding modes in the application code.
+Encrypting user data directly with RSA is insecure.
+
+=back
+
+B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
+based padding modes, less than RSA_size(B<rsa>) - 41 for
+RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING.
+The random number generator must be seeded prior to calling
+RSA_public_encrypt().
+
+RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the
+private key B<rsa> and stores the plaintext in B<to>. B<to> must point
+to a memory section large enough to hold the decrypted data (which is
+smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that
+was used to encrypt the data.
+
+=head1 RETURN VALUES
+
+RSA_public_encrypt() returns the size of the encrypted data (i.e.,
+RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the
+recovered plaintext.
+
+On error, -1 is returned; the error codes can be
+obtained by L<ERR_get_error(3)>.
+
+=head1 CONFORMING TO
+
+SSL, PKCS #1 v2.0
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<rand(3)>,
+L<RSA_size(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_set_default_method, RSA_get_default_method, RSA_set_method,
+RSA_get_method, RSA_PKCS1_OpenSSL, RSA_null_method, RSA_flags,
+RSA_new_method - select RSA method
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ void RSA_set_default_method(const RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_default_method(void);
+
+ int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_method(const RSA *rsa);
+
+ RSA_METHOD *RSA_PKCS1_OpenSSL(void);
+
+ RSA_METHOD *RSA_null_method(void);
+
+ int RSA_flags(const RSA *rsa);
+
+ RSA *RSA_new_method(ENGINE *engine);
+
+=head1 DESCRIPTION
+
+An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
+operations. By modifying the method, alternative implementations such as
+hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these RSA API functions are affected by the
+use of B<ENGINE> API calls.
+
+Initially, the default RSA_METHOD is the OpenSSL internal implementation,
+as returned by RSA_PKCS1_OpenSSL().
+
+RSA_set_default_method() makes B<meth> the default method for all RSA
+structures created later. B<NB>: This is true only whilst no ENGINE has
+been set as a default for RSA, so this function is no longer recommended.
+
+RSA_get_default_method() returns a pointer to the current default
+RSA_METHOD. However, the meaningfulness of this result is dependent on
+whether the ENGINE API is being used, so this function is no longer
+recommended.
+
+RSA_set_method() selects B<meth> to perform all operations using the key
+B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the
+previous method was supplied by an ENGINE, the handle to that ENGINE will
+be released during the change. It is possible to have RSA keys that only
+work with certain RSA_METHOD implementations (eg. from an ENGINE module
+that supports embedded hardware-protected keys), and in such cases
+attempting to change the RSA_METHOD for the key can have unexpected
+results.
+
+RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>.
+This method may or may not be supplied by an ENGINE implementation, but if
+it is, the return value can only be guaranteed to be valid as long as the
+RSA key itself is valid and does not have its implementation changed by
+RSA_set_method().
+
+RSA_flags() returns the B<flags> that are set for B<rsa>'s current
+RSA_METHOD. See the BUGS section.
+
+RSA_new_method() allocates and initializes an RSA structure so that
+B<engine> will be used for the RSA operations. If B<engine> is NULL, the
+default ENGINE for RSA operations is used, and if no default ENGINE is set,
+the RSA_METHOD controlled by RSA_set_default_method() is used.
+
+RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
+
+RSA_new_method() allocates and initializes an B<RSA> structure so that
+B<method> will be used for the RSA operations. If B<method> is B<NULL>,
+the default method is used.
+
+=head1 THE RSA_METHOD STRUCTURE
+
+ typedef struct rsa_meth_st
+ {
+ /* name of the implementation */
+ const char *name;
+
+ /* encrypt */
+ int (*rsa_pub_enc)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* verify arbitrary data */
+ int (*rsa_pub_dec)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* sign arbitrary data */
+ int (*rsa_priv_enc)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* decrypt */
+ int (*rsa_priv_dec)(int flen, unsigned char *from,
+ unsigned char *to, RSA *rsa, int padding);
+
+ /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
+ implementations) */
+ int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
+
+ /* compute r = a ^ p mod m (May be NULL for some implementations) */
+ int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+ const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
+
+ /* called at RSA_new */
+ int (*init)(RSA *rsa);
+
+ /* called at RSA_free */
+ int (*finish)(RSA *rsa);
+
+ /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key
+ * operations, even if p,q,dmp1,dmq1,iqmp
+ * are NULL
+ * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
+ */
+ int flags;
+
+ char *app_data; /* ?? */
+
+ int (*rsa_sign)(int type,
+ const unsigned char *m, unsigned int m_length,
+ unsigned char *sigret, unsigned int *siglen, const RSA *rsa);
+ int (*rsa_verify)(int dtype,
+ const unsigned char *m, unsigned int m_length,
+ const unsigned char *sigbuf, unsigned int siglen,
+ const RSA *rsa);
+ /* keygen. If NULL builtin RSA key generation will be used */
+ int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
+
+ } RSA_METHOD;
+
+=head1 RETURN VALUES
+
+RSA_PKCS1_OpenSSL(), RSA_PKCS1_null_method(), RSA_get_default_method()
+and RSA_get_method() return pointers to the respective RSA_METHODs.
+
+RSA_set_default_method() returns no value.
+
+RSA_set_method() returns a pointer to the old RSA_METHOD implementation
+that was replaced. However, this return value should probably be ignored
+because if it was supplied by an ENGINE, the pointer could be invalidated
+at any time if the ENGINE is unloaded (in fact it could be unloaded as a
+result of the RSA_set_method() function releasing its handle to the
+ENGINE). For this reason, the return type may be replaced with a B<void>
+declaration in a future release.
+
+RSA_new_method() returns NULL and sets an error code that can be obtained
+by L<ERR_get_error(3)> if the allocation fails. Otherwise
+it returns a pointer to the newly allocated structure.
+
+=head1 BUGS
+
+The behaviour of RSA_flags() is a mis-feature that is left as-is for now
+to avoid creating compatibility problems. RSA functionality, such as the
+encryption functions, are controlled by the B<flags> value in the RSA key
+itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key
+(which is what this function returns). If the flags element of an RSA key
+is changed, the changes will be honoured by RSA functionality but will not
+be reflected in the return value of the RSA_flags() function - in effect
+RSA_flags() behaves more like an RSA_default_flags() function (which does
+not currently exist).
+
+=head1 SEE ALSO
+
+L<RSA_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_sign, RSA_verify - RSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_sign(int type, const unsigned char *m, unsigned int m_len,
+ unsigned char *sigret, unsigned int *siglen, RSA *rsa);
+
+ int RSA_verify(int type, const unsigned char *m, unsigned int m_len,
+ unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_sign() signs the message digest B<m> of size B<m_len> using the
+private key B<rsa> as specified in PKCS #1 v2.0. It stores the
+signature in B<sigret> and the signature size in B<siglen>. B<sigret>
+must point to RSA_size(B<rsa>) bytes of memory.
+Note that PKCS #1 adds meta-data, placing limits on the size of the
+key that can be used.
+See L<RSA_private_encrypt(3)> for lower-level
+operations.
+
+B<type> denotes the message digest algorithm that was used to generate
+B<m>.
+If B<type> is B<NID_md5_sha1>,
+an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding
+and no algorithm identifier) is created.
+
+RSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
+matches a given message digest B<m> of size B<m_len>. B<type> denotes
+the message digest algorithm that was used to generate the signature.
+B<rsa> is the signer's public key.
+
+=head1 RETURN VALUES
+
+RSA_sign() returns 1 on success.
+RSA_verify() returns 1 on successful verification.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 CONFORMING TO
+
+SSL, PKCS #1 v2.0
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<RSA_private_encrypt(3)>,
+L<RSA_public_decrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
+ unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
+ RSA *rsa);
+
+ int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m,
+ unsigned int m_len, unsigned char *sigbuf, unsigned int siglen,
+ RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size
+B<m_len> using the private key B<rsa> represented in DER using PKCS #1
+padding. It stores the signature in B<sigret> and the signature size
+in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of
+memory.
+
+B<dummy> is ignored.
+
+The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING().
+
+RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf>
+of size B<siglen> is the DER representation of a given octet string
+B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's
+public key.
+
+=head1 RETURN VALUES
+
+RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise.
+RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0
+otherwise.
+
+The error codes can be obtained by L<ERR_get_error(3)>.
+
+=head1 BUGS
+
+These functions serve no recognizable purpose.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>,
+L<rand(3)>, L<RSA_sign(3)>,
+L<RSA_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+RSA_size, RSA_bits - get RSA modulus size
+
+=head1 SYNOPSIS
+
+#include <openssl/rsa.h>
+
+int RSA_size(const RSA *rsa);
+
+int RSA_bits(const RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_size() returns the RSA modulus size in bytes. It can be used to
+determine how much memory must be allocated for an RSA encrypted
+value.
+
+RSA_bits() returns the number of significant bits.
+
+B<rsa> and B<rsa-E<gt>n> must not be B<NULL>.
+
+=head1 RETURN VALUE
+
+The size.
+
+=head1 SEE ALSO
+
+L<BN_num_bits(3)>
+
+=head1 HISTORY
+
+RSA_bits() was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free,
+SCT_get_version, SCT_set_version,
+SCT_get_log_entry_type, SCT_set_log_entry_type,
+SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id,
+SCT_get_timestamp, SCT_set_timestamp,
+SCT_get_signature_nid, SCT_set_signature_nid,
+SCT_get0_signature, SCT_set0_signature, SCT_set1_signature,
+SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions,
+SCT_get_source, SCT_set_source
+ - A Certificate Transparency Signed Certificate Timestamp
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ typedef enum {
+ CT_LOG_ENTRY_TYPE_NOT_SET = -1,
+ CT_LOG_ENTRY_TYPE_X509 = 0,
+ CT_LOG_ENTRY_TYPE_PRECERT = 1
+ } ct_log_entry_type_t;
+
+ typedef enum {
+ SCT_VERSION_NOT_SET = -1,
+ SCT_VERSION_V1 = 0
+ } sct_version_t;
+
+ typedef enum {
+ SCT_SOURCE_UNKNOWN,
+ SCT_SOURCE_TLS_EXTENSION,
+ SCT_SOURCE_X509V3_EXTENSION,
+ SCT_SOURCE_OCSP_STAPLED_RESPONSE
+ } sct_source_t;
+
+ SCT *SCT_new(void);
+ SCT *SCT_new_from_base64(unsigned char version,
+ const char *logid_base64,
+ ct_log_entry_type_t entry_type,
+ uint64_t timestamp,
+ const char *extensions_base64,
+ const char *signature_base64);
+
+ void SCT_free(SCT *sct);
+ void SCT_LIST_free(STACK_OF(SCT) *a);
+
+ sct_version_t SCT_get_version(const SCT *sct);
+ int SCT_set_version(SCT *sct, sct_version_t version);
+
+ ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
+ int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);
+
+ size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
+ int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
+ int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);
+
+ uint64_t SCT_get_timestamp(const SCT *sct);
+ void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
+
+ int SCT_get_signature_nid(const SCT *sct);
+ int SCT_set_signature_nid(SCT *sct, int nid);
+
+ size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
+ void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
+ int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);
+
+ size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
+ void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
+ int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);
+
+ sct_source_t SCT_get_source(const SCT *sct);
+ int SCT_set_source(SCT *sct, sct_source_t source);
+
+=head1 DESCRIPTION
+
+Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2.
+They constitute a promise by a Certificate Transparency (CT) log to publicly
+record a certificate. By cryptographically verifying that a log did indeed issue
+an SCT, some confidence can be gained that the certificate is publicly known.
+
+An internal representation of an SCT can be created in one of two ways.
+The first option is to create a blank SCT, using SCT_new(), and then populate
+it using:
+
+=over
+
+=item * SCT_set_version() to set the SCT version.
+
+Only SCT_VERSION_V1 is currently supported.
+
+=item * SCT_set_log_entry_type() to set the type of certificate the SCT was issued for:
+
+B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
+B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
+
+=item * SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from.
+
+The former takes ownership, whereas the latter makes a copy.
+See RFC 6962, Section 3.2 for the definition of LogID.
+
+=item * SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds).
+
+=item * SCT_set_signature_nid() to set the NID of the signature.
+
+=item * SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.
+
+The former takes ownership, whereas the latter makes a copy.
+
+=item * SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions.
+
+The former takes ownership, whereas the latter makes a copy.
+
+=back
+
+Alternatively, the SCT can be pre-populated from the following data using
+SCT_new_from_base64():
+
+=over
+
+=item * The SCT version (only SCT_VERSION_V1 is currently supported).
+
+=item * The LogID (see RFC 6962, Section 3.2), base64 encoded.
+
+=item * The type of certificate the SCT was issued for:
+
+B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
+B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
+
+=item * The time that the SCT was issued (epoch time in milliseconds).
+
+=item * The SCT extensions, base64 encoded.
+
+=item * The SCT signature, base64 encoded.
+
+=back
+
+SCT_set_source() can be used to record where the SCT was found
+(TLS extension, X.509 certificate extension or OCSP response). This is not
+required for verifying the SCT.
+
+=head1 NOTES
+
+Some of the setters return int, instead of void. These will all return 1 on
+success, 0 on failure. They will not make changes on failure.
+
+All of the setters will reset the validation status of the SCT to
+SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_validate(3)>).
+
+SCT_set_source() will call SCT_set_log_entry_type() if the type of
+certificate the SCT was issued for can be inferred from where the SCT was found.
+For example, an SCT found in an X.509 extension must have been issued for a pre-
+certificate.
+
+SCT_set_source() will not refuse unknown values.
+
+=head1 RETURN VALUES
+
+SCT_set_version() returns 1 if the specified version is supported, 0 otherwise.
+
+SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise.
+
+SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a
+valid SHA-256 hash, 0 otherwise. Aditionally, B<SCT_set1_log_id> returns 0 if
+malloc fails.
+
+B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise.
+
+B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer
+is copied successfully, 0 otherwise (i.e. if malloc fails).
+
+B<SCT_set_source> returns 1 on success, 0 otherwise.
+
+=head1 SEE ALSO
+
+L<ct(3)>,
+L<SCT_verify(3)>,
+L<OBJ_nid2obj(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SCT_print, SCT_LIST_print, SCT_validation_status_string -
+Prints Signed Certificate Timestamps in a human-readable way
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ void SCT_print(const SCT *sct, BIO *out, int indent, const CTLOG_STORE *logs);
+ void SCT_LIST_print(const STACK_OF(SCT) *sct_list, BIO *out, int indent,
+ const char *separator, const CTLOG_STORE *logs);
+ const char *SCT_validation_status_string(const SCT *sct);
+
+=head1 DESCRIPTION
+
+SCT_print() prints a single Signed Certificate Timestamp (SCT) to a L<bio> in
+a human-readable format. SCT_LIST_print() prints an entire list of SCTs in a
+similar way. A separator can be specified to delimit each SCT in the output.
+
+The output can be indented by a specified number of spaces. If a B<CTLOG_STORE>
+is provided, it will be used to print the description of the CT log that issued
+each SCT (if that log is in the CTLOG_STORE). Alternatively, NULL can be passed
+as the CTLOG_STORE parameter to disable this feature.
+
+SCT_validation_status_string() will return the validation status of an SCT as
+a human-readable string. Call SCT_validate() or SCT_LIST_validate()
+beforehand in order to set the validation status of an SCT first.
+
+=head1 SEE ALSO
+
+L<ct(3)>,
+L<bio(3)>,
+L<CTLOG_STORE_new(3)>,
+L<SCT_validate(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SCT_validate, SCT_LIST_validate, SCT_get_validation_status -
+checks Signed Certificate Timestamps (SCTs) are valid
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ typedef enum {
+ SCT_VALIDATION_STATUS_NOT_SET,
+ SCT_VALIDATION_STATUS_UNKNOWN_LOG,
+ SCT_VALIDATION_STATUS_VALID,
+ SCT_VALIDATION_STATUS_INVALID,
+ SCT_VALIDATION_STATUS_UNVERIFIED,
+ SCT_VALIDATION_STATUS_UNKNOWN_VERSION
+ } sct_validation_status_t;
+
+ int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx);
+ int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx);
+ sct_validation_status_t SCT_get_validation_status(const SCT *sct);
+
+=head1 DESCRIPTION
+
+SCT_validate() will check that an SCT is valid and verify its signature.
+SCT_LIST_validate() performs the same checks on an entire stack of SCTs.
+The result of the validation checks can be obtained by passing the SCT to
+SCT_get_validation_status().
+
+A CT_POLICY_EVAL_CTX must be provided that specifies:
+
+=over
+
+=item * The certificate the SCT was issued for.
+
+Failure to provide the certificate will result in the validation status being
+SCT_VALIDATION_STATUS_UNVERIFIED.
+
+=item * The issuer of that certificate.
+
+This is only required if the SCT was issued for a pre-certificate
+(see RFC 6962). If it is required but not provided, the validation status will
+be SCT_VALIDATION_STATUS_UNVERIFIED.
+
+=item * A CTLOG_STORE that contains the CT log that issued this SCT.
+
+If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
+status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.
+
+=back
+
+If the SCT is of an unsupported version (only v1 is currently supported), the
+validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION.
+
+If the SCT's signature is incorrect, the validation status will be
+SCT_VALIDATION_STATUS_INVALID. Otherwise, if all checks have passed, the
+validation status will be SCT_VALIDATION_STATUS_VALID.
+
+=head1 NOTES
+
+A return value of 0 from SCT_LIST_validate() should not be interpreted as a
+failure. At a minimum, only one valid SCT may provide sufficient confidence
+that a certificate has been publicly logged.
+
+=head1 RETURN VALUES
+
+SCT_validate() returns a negative integer if an internal error occurs, 0 if the
+SCT fails validation, or 1 if the SCT passes validation.
+
+SCT_LIST_validate() returns a negative integer if an internal error occurs, 0
+if any of SCTs fails validation, or 1 if they all pass validation.
+
+SCT_get_validation_status() returns the validation status of the SCT.
+If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the
+returned value will be SCT_VALIDATION_STATUS_NOT_SET.
+
+=head1 SEE ALSO
+
+L<ct(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update,
+SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384,
+SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update,
+SHA512_Final - Secure Hash Algorithm
+
+=head1 SYNOPSIS
+
+ #include <openssl/sha.h>
+
+ int SHA1_Init(SHA_CTX *c);
+ int SHA1_Update(SHA_CTX *c, const void *data, size_t len);
+ int SHA1_Final(unsigned char *md, SHA_CTX *c);
+ unsigned char *SHA1(const unsigned char *d, size_t n,
+ unsigned char *md);
+
+ int SHA224_Init(SHA256_CTX *c);
+ int SHA224_Update(SHA256_CTX *c, const void *data, size_t len);
+ int SHA224_Final(unsigned char *md, SHA256_CTX *c);
+ unsigned char *SHA224(const unsigned char *d, size_t n,
+ unsigned char *md);
+
+ int SHA256_Init(SHA256_CTX *c);
+ int SHA256_Update(SHA256_CTX *c, const void *data, size_t len);
+ int SHA256_Final(unsigned char *md, SHA256_CTX *c);
+ unsigned char *SHA256(const unsigned char *d, size_t n,
+ unsigned char *md);
+
+ int SHA384_Init(SHA512_CTX *c);
+ int SHA384_Update(SHA512_CTX *c, const void *data, size_t len);
+ int SHA384_Final(unsigned char *md, SHA512_CTX *c);
+ unsigned char *SHA384(const unsigned char *d, size_t n,
+ unsigned char *md);
+
+ int SHA512_Init(SHA512_CTX *c);
+ int SHA512_Update(SHA512_CTX *c, const void *data, size_t len);
+ int SHA512_Final(unsigned char *md, SHA512_CTX *c);
+ unsigned char *SHA512(const unsigned char *d, size_t n,
+ unsigned char *md);
+
+=head1 DESCRIPTION
+
+Applications should use the higher level functions
+L<EVP_DigestInit(3)> etc. instead of calling the hash
+functions directly.
+
+SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a
+160 bit output.
+
+SHA1() computes the SHA-1 message digest of the B<n>
+bytes at B<d> and places it in B<md> (which must have space for
+SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest
+is placed in a static array. Note: setting B<md> to NULL is B<not thread safe>.
+
+The following functions may be used if the message is not completely
+stored in memory:
+
+SHA1_Init() initializes a B<SHA_CTX> structure.
+
+SHA1_Update() can be called repeatedly with chunks of the message to
+be hashed (B<len> bytes at B<data>).
+
+SHA1_Final() places the message digest in B<md>, which must have space
+for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>.
+
+The SHA224, SHA256, SHA384 and SHA512 families of functions operate in the
+same way as for the SHA1 functions. Note that SHA224 and SHA256 use a
+B<SHA256_CTX> object instead of B<SHA_CTX>. SHA384 and SHA512 use B<SHA512_CTX>.
+The buffer B<md> must have space for the output from the SHA variant being used
+(defined by SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH and
+SHA512_DIGEST_LENGTH). Also note that, as for the SHA1() function above, the
+SHA224(), SHA256(), SHA384() and SHA512() functions are not thread safe if
+B<md> is NULL.
+
+The predecessor of SHA-1, SHA, is also implemented, but it should be
+used only when backward compatibility is required.
+
+=head1 RETURN VALUES
+
+SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash
+value.
+
+SHA1_Init(), SHA1_Update() and SHA1_Final() and equivalent SHA224, SHA256,
+SHA384 and SHA512 functions return 1 for success, 0 otherwise.
+
+=head1 CONFORMING TO
+
+US Federal Information Processing Standard FIPS PUB 180-4 (Secure Hash
+Standard),
+ANSI X9.30
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SMIME_read_CMS - parse S/MIME message
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont);
+
+=head1 DESCRIPTION
+
+SMIME_read_CMS() parses a message in S/MIME format.
+
+B<in> is a BIO to read the message from.
+
+If cleartext signing is used then the content is saved in a memory bio which is
+written to B<*bcont>, otherwise B<*bcont> is set to NULL.
+
+The parsed CMS_ContentInfo structure is returned or NULL if an
+error occurred.
+
+=head1 NOTES
+
+If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can
+then be passed to CMS_verify() with the B<CMS_DETACHED> flag set.
+
+Otherwise the type of the returned structure can be determined
+using CMS_get0_type().
+
+To support future functionality if B<bcont> is not NULL B<*bcont> should be
+initialized to NULL. For example:
+
+ BIO *cont = NULL;
+ CMS_ContentInfo *cms;
+
+ cms = SMIME_read_CMS(in, &cont);
+
+=head1 BUGS
+
+The MIME parser used by SMIME_read_CMS() is somewhat primitive. While it will
+handle most S/MIME messages more complex compound formats may not work.
+
+The parser assumes that the CMS_ContentInfo structure is always base64 encoded
+and will not handle the case where it is in binary format or uses quoted
+printable format.
+
+The use of a memory BIO to hold the signed content limits the size of message
+which can be processed due to memory restraints: a streaming single pass option
+should be available.
+
+=head1 RETURN VALUES
+
+SMIME_read_CMS() returns a valid B<CMS_ContentInfo> structure or B<NULL>
+if an error occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_type(3)>
+L<SMIME_read_CMS(3)>, L<CMS_sign(3)>,
+L<CMS_verify(3)>, L<CMS_encrypt(3)>
+L<CMS_decrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SMIME_read_PKCS7 - parse S/MIME message
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont);
+
+=head1 DESCRIPTION
+
+SMIME_read_PKCS7() parses a message in S/MIME format.
+
+B<in> is a BIO to read the message from.
+
+If cleartext signing is used then the content is saved in
+a memory bio which is written to B<*bcont>, otherwise
+B<*bcont> is set to B<NULL>.
+
+The parsed PKCS#7 structure is returned or B<NULL> if an
+error occurred.
+
+=head1 NOTES
+
+If B<*bcont> is not B<NULL> then the message is clear text
+signed. B<*bcont> can then be passed to PKCS7_verify() with
+the B<PKCS7_DETACHED> flag set.
+
+Otherwise the type of the returned structure can be determined
+using PKCS7_type().
+
+To support future functionality if B<bcont> is not B<NULL>
+B<*bcont> should be initialized to B<NULL>. For example:
+
+ BIO *cont = NULL;
+ PKCS7 *p7;
+
+ p7 = SMIME_read_PKCS7(in, &cont);
+
+=head1 BUGS
+
+The MIME parser used by SMIME_read_PKCS7() is somewhat primitive.
+While it will handle most S/MIME messages more complex compound
+formats may not work.
+
+The parser assumes that the PKCS7 structure is always base64
+encoded and will not handle the case where it is in binary format
+or uses quoted printable format.
+
+The use of a memory BIO to hold the signed content limits the size
+of message which can be processed due to memory restraints: a
+streaming single pass option should be available.
+
+=head1 RETURN VALUES
+
+SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL>
+is an error occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_type(3)>
+L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>,
+L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
+L<PKCS7_decrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SMIME_write_CMS - convert CMS structure to S/MIME format
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+SMIME_write_CMS() adds the appropriate MIME headers to a CMS
+structure to produce an S/MIME message.
+
+B<out> is the BIO to write the data to. B<cms> is the appropriate
+B<CMS_ContentInfo> structure. If streaming is enabled then the content must be
+supplied in the B<data> argument. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+The following flags can be passed in the B<flags> parameter.
+
+If B<CMS_DETACHED> is set then cleartext signing will be used, this option only
+makes sense for SignedData where B<CMS_DETACHED> is also set when CMS_sign() is
+called.
+
+If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to
+the content, this only makes sense if B<CMS_DETACHED> is also set.
+
+If the B<CMS_STREAM> flag is set streaming is performed. This flag should only
+be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo
+creation function.
+
+If cleartext signing is being used and B<CMS_STREAM> not set then the data must
+be read twice: once to compute the signature in CMS_sign() and once to output
+the S/MIME message.
+
+If streaming is performed the content is output in BER format using indefinite
+length constructed encoding except in the case of signed data with detached
+content where the content is absent and DER format is used.
+
+=head1 BUGS
+
+SMIME_write_CMS() always base64 encodes CMS structures, there should be an
+option to disable this.
+
+=head1 RETURN VALUES
+
+SMIME_write_CMS() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>,
+L<CMS_verify(3)>, L<CMS_encrypt(3)>
+L<CMS_decrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7
+structure to produce an S/MIME message.
+
+B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7>
+structure. If streaming is enabled then the content must be supplied in the
+B<data> argument. B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+The following flags can be passed in the B<flags> parameter.
+
+If B<PKCS7_DETACHED> is set then cleartext signing will be used,
+this option only makes sense for signedData where B<PKCS7_DETACHED>
+is also set when PKCS7_sign() is also called.
+
+If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain>
+are added to the content, this only makes sense if B<PKCS7_DETACHED>
+is also set.
+
+If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should
+only be set if B<PKCS7_STREAM> was also set in the previous call to
+PKCS7_sign() or PKCS7_encrypt().
+
+If cleartext signing is being used and B<PKCS7_STREAM> not set then
+the data must be read twice: once to compute the signature in PKCS7_sign()
+and once to output the S/MIME message.
+
+If streaming is performed the content is output in BER format using indefinite
+length constructed encoding except in the case of signed data with detached
+content where the content is absent and DER format is used.
+
+=head1 BUGS
+
+SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there
+should be an option to disable this.
+
+=head1 RETURN VALUES
+
+SMIME_write_PKCS7() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
+L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
+L<PKCS7_decrypt(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_kx_nid,
+SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead,
+SSL_CIPHER_get_name, SSL_CIPHER_get_bits,
+SSL_CIPHER_get_version, SSL_CIPHER_description
+- get SSL_CIPHER properties
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
+ int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
+ char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
+ char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
+ int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
+ int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
+ int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
+ int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
+ int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
+
+=head1 DESCRIPTION
+
+SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the
+B<cipher> is NULL, it returns "(NONE)".
+
+SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>.
+If B<cipher> is NULL, 0 is returned.
+
+SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
+version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL.
+
+SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>.
+If there is no cipher (e.g. for ciphersuites with no encryption) then
+B<NID_undef> is returned.
+
+SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC
+used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then
+B<NID_undef> is returned.
+
+SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
+used by B<c>. If there is no key exchange, then B<NID_undef> is returned. Examples (not comprehensive):
+
+ NID_kx_rsa
+ NID_kx_ecdhe
+ NID_kx_dhe
+ NID_kx_psk
+
+SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method
+used by B<c>. If there is no authentication, then B<NID_undef> is returned.
+Examples (not comprehensive):
+
+ NID_auth_rsa
+ NID_auth_ecdsa
+ NID_auth_psk
+
+SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or
+ChaCha20/Poly1305), and 0 if it is not AEAD.
+
+SSL_CIPHER_description() returns a textual description of the cipher used
+into the buffer B<buf> of length B<len> provided. If B<buf> is provided, it
+must be at least 128 bytes, otherwise a buffer will be allocated using
+OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails,
+B<NULL> is returned.
+
+The string returned by SSL_CIPHER_description() consists of several fields
+separated by whitespace:
+
+=over 4
+
+=item <ciphername>
+
+Textual representation of the cipher name.
+
+=item <protocol version>
+
+Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
+
+=item Kx=<key exchange>
+
+Key exchange method such as B<RSA>, B<ECDHE>, etc.
+
+=item Au=<authentication>
+
+Authentication method such as B<RSA>, B<None>, etc.. None is the
+representation of anonymous ciphers.
+
+=item Enc=<symmetric encryption method>
+
+Encryption method, with number of secret bits, such as B<AESGCM(128)>.
+
+=item Mac=<message authentication code>
+
+Message digest, such as B<SHA256>.
+
+=back
+
+Some examples for the output of SSL_CIPHER_description():
+
+ ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
+ RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384
+
+=head1 HISTORY
+
+SSL_CIPHER_get_version() was updated to always return the correct protocol
+string in OpenSSL 1.1.
+
+SSL_CIPHER_description() was changed to return B<NULL> on error,
+rather than a fixed string, in OpenSSL 1.1
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_current_cipher(3)>,
+L<SSL_get_ciphers(3)>, L<ciphers(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_COMP_add_compression_method, SSL_COMP_free_compression_methods - handle SSL/TLS integrated compression methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void SSL_COMP_free_compression_methods(void)
+ #endif
+
+=head1 DESCRIPTION
+
+SSL_COMP_add_compression_method() adds the compression method B<cm> with
+the identifier B<id> to the list of available compression methods. This
+list is globally maintained for all SSL operations within this application.
+It cannot be set for specific SSL_CTX or SSL objects.
+
+In versions of OpenSSL prior to 1.1.0 SSL_COMP_free_compression_methods() freed
+the internal table of compression methods that were built internally, and
+possibly augmented by adding SSL_COMP_add_compression_method(). However this is
+now unnecessary from version 1.1.0. No explicit initialisation or
+de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> and
+L<OPENSSL_init_ssl(3)>. From OpenSSL 1.1.0 calling this function does nothing.
+
+=head1 NOTES
+
+The TLS standard (or SSLv3) allows the integration of compression methods
+into the communication. The TLS RFC does however not specify compression
+methods or their corresponding identifiers, so there is currently no compatible
+way to integrate compression with unknown peers. It is therefore currently not
+recommended to integrate compression into applications. Applications for
+non-public use may agree on certain compression methods. Using different
+compression methods with the same identifier will lead to connection failure.
+
+An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1)
+will unconditionally send the list of all compression methods enabled with
+SSL_COMP_add_compression_method() to the server during the handshake.
+Unlike the mechanisms to set a cipher list, there is no method available to
+restrict the list of compression method on a per connection basis.
+
+An OpenSSL server will match the identifiers listed by a client against
+its own compression methods and will unconditionally activate compression
+when a matching identifier is found. There is no way to restrict the list
+of compression methods supported on a per connection basis.
+
+If enabled during compilation, the OpenSSL library will have the
+COMP_zlib() compression method available.
+
+=head1 WARNINGS
+
+Once the identities of the compression methods for the TLS protocol have
+been standardized, the compression API will most likely be changed. Using
+it in the current state is not recommended.
+
+=head1 RETURN VALUES
+
+SSL_COMP_add_compression_method() may return the following values:
+
+=over 4
+
+=item Z<>0
+
+The operation succeeded.
+
+=item Z<>1
+
+The operation failed. Check the error queue to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 HISTORY
+
+SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CONF_CTX_new, SSL_CONF_CTX_free - SSL configuration allocation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_CONF_CTX *SSL_CONF_CTX_new(void);
+ void SSL_CONF_CTX_free(SSL_CONF_CTX *cctx);
+
+=head1 DESCRIPTION
+
+The function SSL_CONF_CTX_new() allocates and initialises an B<SSL_CONF_CTX>
+structure for use with the SSL_CONF functions.
+
+The function SSL_CONF_CTX_free() frees up the context B<cctx>.
+If B<cctx> is NULL nothing is done.
+
+=head1 RETURN VALUES
+
+SSL_CONF_CTX_new() returns either the newly allocated B<SSL_CONF_CTX> structure
+or B<NULL> if an error occurs.
+
+SSL_CONF_CTX_free() does not return a value.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_CTX_set_flags(3)>,
+L<SSL_CONF_CTX_set_ssl_ctx(3)>,
+L<SSL_CONF_CTX_set1_prefix(3)>,
+L<SSL_CONF_cmd(3)>,
+L<SSL_CONF_cmd_argv(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2
+
+=head1 COPYRIGHT
+
+Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CONF_CTX_set1_prefix - Set configuration context command prefix
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ unsigned int SSL_CONF_CTX_set1_prefix(SSL_CONF_CTX *cctx, const char *prefix);
+
+=head1 DESCRIPTION
+
+The function SSL_CONF_CTX_set1_prefix() sets the command prefix of B<cctx>
+to B<prefix>. If B<prefix> is B<NULL> it is restored to the default value.
+
+=head1 NOTES
+
+Command prefixes alter the commands recognised by subsequent SSL_CTX_cmd()
+calls. For example for files, if the prefix "SSL" is set then command names
+such as "SSLProtocol", "SSLOptions" etc. are recognised instead of "Protocol"
+and "Options". Similarly for command lines if the prefix is "--ssl-" then
+"--ssl-no_tls1_2" is recognised instead of "-no_tls1_2".
+
+If the B<SSL_CONF_FLAG_CMDLINE> flag is set then prefix checks are case
+sensitive and "-" is the default. In the unlikely even an application
+explicitly wants to set no prefix it must be explicitly set to "".
+
+If the B<SSL_CONF_FLAG_FILE> flag is set then prefix checks are case
+insensitive and no prefix is the default.
+
+=head1 RETURN VALUES
+
+SSL_CONF_CTX_set1_prefix() returns 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_CTX_new(3)>,
+L<SSL_CONF_CTX_set_flags(3)>,
+L<SSL_CONF_CTX_set_ssl_ctx(3)>,
+L<SSL_CONF_cmd(3)>,
+L<SSL_CONF_cmd_argv(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2
+
+=head1 COPYRIGHT
+
+Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CONF_CTX_set_flags, SSL_CONF_CTX_clear_flags - Set of clear SSL configuration context flags
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ unsigned int SSL_CONF_CTX_set_flags(SSL_CONF_CTX *cctx, unsigned int flags);
+ unsigned int SSL_CONF_CTX_clear_flags(SSL_CONF_CTX *cctx, unsigned int flags);
+
+=head1 DESCRIPTION
+
+The function SSL_CONF_CTX_set_flags() sets B<flags> in the context B<cctx>.
+
+The function SSL_CONF_CTX_clear_flags() clears B<flags> in the context B<cctx>.
+
+=head1 NOTES
+
+The flags set affect how subsequent calls to SSL_CONF_cmd() or
+SSL_CONF_argv() behave.
+
+Currently the following B<flags> values are recognised:
+
+=over 4
+
+=item SSL_CONF_FLAG_CMDLINE, SSL_CONF_FLAG_FILE
+
+recognise options intended for command line or configuration file use. At
+least one of these flags must be set.
+
+=item SSL_CONF_FLAG_CLIENT, SSL_CONF_FLAG_SERVER
+
+recognise options intended for use in SSL/TLS clients or servers. One or
+both of these flags must be set.
+
+=item SSL_CONF_FLAG_CERTIFICATE
+
+recognise certificate and private key options.
+
+=item SSL_CONF_FLAG_REQUIRE_PRIVATE
+
+If this option is set then if a private key is not specified for a certificate
+it will attempt to load a private key from the certificate file when
+SSL_CONF_CTX_finish() is called. If a key cannot be loaded from the certificate
+file an error occurs.
+
+=item SSL_CONF_FLAG_SHOW_ERRORS
+
+indicate errors relating to unrecognised options or missing arguments in
+the error queue. If this option isn't set such errors are only reflected
+in the return values of SSL_CONF_set_cmd() or SSL_CONF_set_argv()
+
+=back
+
+=head1 RETURN VALUES
+
+SSL_CONF_CTX_set_flags() and SSL_CONF_CTX_clear_flags() returns the new flags
+value after setting or clearing flags.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_CTX_new(3)>,
+L<SSL_CONF_CTX_set_ssl_ctx(3)>,
+L<SSL_CONF_CTX_set1_prefix(3)>,
+L<SSL_CONF_cmd(3)>,
+L<SSL_CONF_cmd_argv(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2
+
+=head1 COPYRIGHT
+
+Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CONF_CTX_set_ssl_ctx, SSL_CONF_CTX_set_ssl - set context to configure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CONF_CTX_set_ssl_ctx(SSL_CONF_CTX *cctx, SSL_CTX *ctx);
+ void SSL_CONF_CTX_set_ssl(SSL_CONF_CTX *cctx, SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CONF_CTX_set_ssl_ctx() sets the context associated with B<cctx> to the
+B<SSL_CTX> structure B<ctx>. Any previous B<SSL> or B<SSL_CTX> associated with
+B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to
+B<ctx>.
+
+SSL_CONF_CTX_set_ssl() sets the context associated with B<cctx> to the
+B<SSL> structure B<ssl>. Any previous B<SSL> or B<SSL_CTX> associated with
+B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to
+B<ssl>.
+
+=head1 NOTES
+
+The context need not be set or it can be set to B<NULL> in which case only
+syntax checking of commands is performed, where possible.
+
+=head1 RETURN VALUES
+
+SSL_CONF_CTX_set_ssl_ctx() and SSL_CTX_set_ssl() do not return a value.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_CTX_new(3)>,
+L<SSL_CONF_CTX_set_flags(3)>,
+L<SSL_CONF_CTX_set1_prefix(3)>,
+L<SSL_CONF_cmd(3)>,
+L<SSL_CONF_cmd_argv(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2
+
+=head1 COPYRIGHT
+
+Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CONF_cmd_value_type, SSL_CONF_finish,
+SSL_CONF_cmd - send configuration command
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
+ int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd);
+ int SSL_CONF_finish(SSL_CONF_CTX *cctx);
+
+=head1 DESCRIPTION
+
+The function SSL_CONF_cmd() performs configuration operation B<cmd> with
+optional parameter B<value> on B<ctx>. Its purpose is to simplify application
+configuration of B<SSL_CTX> or B<SSL> structures by providing a common
+framework for command line options or configuration files.
+
+SSL_CONF_cmd_value_type() returns the type of value that B<cmd> refers to.
+
+The function SSL_CONF_finish() must be called after all configuration
+operations have been completed. It is used to finalise any operations
+or to process defaults.
+
+=head1 SUPPORTED COMMAND LINE COMMANDS
+
+Currently supported B<cmd> names for command lines (i.e. when the
+flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names
+are case sensitive. Unless otherwise stated commands can be used by
+both clients and servers and the B<value> parameter is not used. The default
+prefix for command line commands is B<-> and that is reflected below.
+
+=over 4
+
+=item B<-sigalgs>
+
+This sets the supported signature algorithms for TLS v1.2. For clients this
+value is used directly for the supported signature algorithms extension. For
+servers it is used to determine which signature algorithms to support.
+
+The B<value> argument should be a colon separated list of signature algorithms
+in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
+is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
+OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
+Note: algorithm and hash names are case sensitive.
+
+If this option is not set then all signature algorithms supported by the
+OpenSSL library are permissible.
+
+=item B<-client_sigalgs>
+
+This sets the supported signature algorithms associated with client
+authentication for TLS v1.2. For servers the value is used in the supported
+signature algorithms field of a certificate request. For clients it is
+used to determine which signature algorithm to with the client certificate.
+If a server does not request a certificate this option has no effect.
+
+The syntax of B<value> is identical to B<-sigalgs>. If not set then
+the value set for B<-sigalgs> will be used instead.
+
+=item B<-curves>
+
+This sets the supported elliptic curves. For clients the curves are
+sent using the supported curves extension. For servers it is used
+to determine which curve to use. This setting affects curves used for both
+signatures and key exchange, if applicable.
+
+The B<value> argument is a colon separated list of curves. The curve can be
+either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
+B<prime256v1>). Curve names are case sensitive.
+
+=item B<-named_curve>
+
+This sets the temporary curve used for ephemeral ECDH modes. Only used by
+servers
+
+The B<value> argument is a curve name or the special value B<auto> which
+picks an appropriate curve based on client and server preferences. The curve
+can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
+(e.g B<prime256v1>). Curve names are case sensitive.
+
+=item B<-cipher>
+
+Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
+currently not performed unless a B<SSL> or B<SSL_CTX> structure is
+associated with B<cctx>.
+
+=item B<-cert>
+
+Attempts to use the file B<value> as the certificate for the appropriate
+context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
+structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
+structure is set. This option is only supported if certificate operations
+are permitted.
+
+=item B<-key>
+
+Attempts to use the file B<value> as the private key for the appropriate
+context. This option is only supported if certificate operations
+are permitted. Note: if no B<-key> option is set then a private key is
+not loaded unless the flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
+
+=item B<-dhparam>
+
+Attempts to use the file B<value> as the set of temporary DH parameters for
+the appropriate context. This option is only supported if certificate
+operations are permitted.
+
+=item B<-min_protocol>, B<-max_protocol>
+
+Sets the minimum and maximum supported protocol.
+Currently supported protocol values are B<SSLv3>, B<TLSv1>,
+B<TLSv1.1>, B<TLSv1.2> for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS,
+and B<None> for no limit.
+If the either bound is not specified then only the other bound applies,
+if specified.
+To restrict the supported protocol versions use these commands rather
+than the deprecated alternative commands below.
+
+=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
+
+Disables protocol support for SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 by setting the
+corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>
+and B<SSL_OP_NO_TLSv1_2> respectively.
+These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>.
+
+=item B<-bugs>
+
+Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
+
+=item B<-comp>
+
+Enables support for SSL/TLS compression, same as clearing
+B<SSL_OP_NO_COMPRESSION>.
+This command was introduced in OpenSSL 1.1.0.
+As of OpenSSL 1.1.0, compression is off by default.
+
+=item B<-no_comp>
+
+Disables support for SSL/TLS compression, same as setting
+B<SSL_OP_NO_COMPRESSION>.
+As of OpenSSL 1.1.0, compression is off by default.
+
+=item B<-no_ticket>
+
+Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
+
+=item B<-serverpref>
+
+Use server and not client preference order when determining which cipher suite,
+signature algorithm or elliptic curve to use for an incoming connection.
+Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
+
+=item B<-no_resumption_on_reneg>
+
+set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers.
+
+=item B<-legacyrenegotiation>
+
+permits the use of unsafe legacy renegotiation. Equivalent to setting
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
+
+=item B<-legacy_server_connect>, B<-no_legacy_server_connect>
+
+permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
+clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
+Set by default.
+
+=item B<-strict>
+
+enables strict mode protocol handling. Equivalent to setting
+B<SSL_CERT_FLAG_TLS_STRICT>.
+
+=back
+
+=head1 SUPPORTED CONFIGURATION FILE COMMANDS
+
+Currently supported B<cmd> names for configuration files (i.e. when the
+flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
+B<cmd> names are case insensitive so B<signaturealgorithms> is recognised
+as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
+are also case insensitive.
+
+Note: the command prefix (if set) alters the recognised B<cmd> values.
+
+=over 4
+
+=item B<CipherString>
+
+Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
+currently not performed unless an B<SSL> or B<SSL_CTX> structure is
+associated with B<cctx>.
+
+=item B<Certificate>
+
+Attempts to use the file B<value> as the certificate for the appropriate
+context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
+structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
+structure is set. This option is only supported if certificate operations
+are permitted.
+
+=item B<PrivateKey>
+
+Attempts to use the file B<value> as the private key for the appropriate
+context. This option is only supported if certificate operations
+are permitted. Note: if no B<PrivateKey> option is set then a private key is
+not loaded unless the B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
+
+=item B<ChainCAFile>, B<ChainCAPath>, B<VerifyCAFile>, B<VerifyCAPath>
+
+These options indicate a file or directory used for building certificate
+chains or verifying certificate chains. These options are only supported
+if certificate operations are permitted.
+
+=item B<ServerInfoFile>
+
+Attempts to use the file B<value> in the "serverinfo" extension using the
+function SSL_CTX_use_serverinfo_file.
+
+=item B<DHParameters>
+
+Attempts to use the file B<value> as the set of temporary DH parameters for
+the appropriate context. This option is only supported if certificate
+operations are permitted.
+
+=item B<SignatureAlgorithms>
+
+This sets the supported signature algorithms for TLS v1.2. For clients this
+value is used directly for the supported signature algorithms extension. For
+servers it is used to determine which signature algorithms to support.
+
+The B<value> argument should be a colon separated list of signature algorithms
+in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
+is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
+OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
+Note: algorithm and hash names are case sensitive.
+
+If this option is not set then all signature algorithms supported by the
+OpenSSL library are permissible.
+
+=item B<ClientSignatureAlgorithms>
+
+This sets the supported signature algorithms associated with client
+authentication for TLS v1.2. For servers the value is used in the supported
+signature algorithms field of a certificate request. For clients it is
+used to determine which signature algorithm to with the client certificate.
+
+The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
+the value set for B<SignatureAlgorithms> will be used instead.
+
+=item B<Curves>
+
+This sets the supported elliptic curves. For clients the curves are
+sent using the supported curves extension. For servers it is used
+to determine which curve to use. This setting affects curves used for both
+signatures and key exchange, if applicable.
+
+The B<value> argument is a colon separated list of curves. The curve can be
+either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
+B<prime256v1>). Curve names are case sensitive.
+
+=item B<MinProtocol>
+
+This sets the minimum supported SSL, TLS or DTLS version.
+
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
+B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+The value B<None> will disable the limit.
+
+=item B<MaxProtocol>
+
+This sets the maximum supported SSL, TLS or DTLS version.
+
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
+B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+The value B<None> will disable the limit.
+
+=item B<Protocol>
+
+This can be used to enable or disable certain versions of the SSL,
+TLS or DTLS protocol.
+
+The B<value> argument is a comma separated list of supported protocols
+to enable or disable.
+If a protocol is preceded by B<-> that version is disabled.
+
+All protocol versions are enabled by default.
+You need to disable at least one protocol version for this setting have any
+effect.
+Only enabling some protocol versions does not disable the other protocol
+versions.
+
+Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
+B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
+The special value B<ALL> refers to all supported versions.
+
+This can't enable protocols that are disabled using B<MinProtocol>
+or B<MaxProtocol>, but can disable protocols that are still allowed
+by them.
+
+The B<Protocol> command is fragile and deprecated; do not use it.
+Use B<MinProtocol> and B<MaxProtocol> instead.
+If you do use B<Protocol>, make sure that the resulting range of enabled
+protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make
+sure to also leave TLS 1.1 enabled.
+
+=item B<Options>
+
+The B<value> argument is a comma separated list of various flags to set.
+If a flag string is preceded B<-> it is disabled.
+See the L<SSL_CTX_set_options(3)> function for more details of
+individual options.
+
+Each option is listed below. Where an operation is enabled by default
+the B<-flag> syntax is needed to disable it.
+
+B<SessionTicket>: session ticket support, enabled by default. Inverse of
+B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting
+B<SSL_OP_NO_TICKET>.
+
+B<Compression>: SSL/TLS compression support, enabled by default. Inverse
+of B<SSL_OP_NO_COMPRESSION>.
+
+B<EmptyFragments>: use empty fragments as a countermeasure against a
+SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It
+is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>.
+
+B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
+
+B<DHSingle>: enable single use DH keys, set by default. Inverse of
+B<SSL_OP_DH_SINGLE>. Only used by servers.
+
+B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of
+B<SSL_OP_ECDH_SINGLE>. Only used by servers.
+
+B<ServerPreference> use server and not client preference order when
+determining which cipher suite, signature algorithm or elliptic curve
+to use for an incoming connection. Equivalent to
+B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
+
+B<NoResumptionOnRenegotiation> set
+B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers.
+
+B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation.
+Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
+
+B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
+for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
+Set by default.
+
+=item B<VerifyMode>
+
+The B<value> argument is a comma separated list of flags to set.
+
+B<Peer> enables peer verification: for clients only.
+
+B<Request> requests but does not require a certificate from the client.
+Servers only.
+
+B<Require> requests and requires a certificate from the client: an error
+occurs if the client does not present a certificate. Servers only.
+
+B<Once> requests a certificate from a client only on the initial connection:
+not when renegotiating. Servers only.
+
+=item B<ClientCAFile>, B<ClientCAPath>
+
+A file or directory of certificates in PEM format whose names are used as the
+set of acceptable names for client CAs. Servers only. This option is only
+supported if certificate operations are permitted.
+
+=back
+
+=head1 SUPPORTED COMMAND TYPES
+
+The function SSL_CONF_cmd_value_type() currently returns one of the following
+types:
+
+=over 4
+
+=item B<SSL_CONF_TYPE_UNKNOWN>
+
+The B<cmd> string is unrecognised, this return value can be use to flag
+syntax errors.
+
+=item B<SSL_CONF_TYPE_STRING>
+
+The value is a string without any specific structure.
+
+=item B<SSL_CONF_TYPE_FILE>
+
+The value is a file name.
+
+=item B<SSL_CONF_TYPE_DIR>
+
+The value is a directory name.
+
+=item B<SSL_CONF_TYPE_NONE>
+
+The value string is not used e.g. a command line option which doesn't take an
+argument.
+
+=back
+
+=head1 NOTES
+
+The order of operations is significant. This can be used to set either defaults
+or values which cannot be overridden. For example if an application calls:
+
+ SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
+ SSL_CONF_cmd(ctx, userparam, uservalue);
+
+it will disable SSLv3 support by default but the user can override it. If
+however the call sequence is:
+
+ SSL_CONF_cmd(ctx, userparam, uservalue);
+ SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
+
+SSLv3 is B<always> disabled and attempt to override this by the user are
+ignored.
+
+By checking the return code of SSL_CTX_cmd() it is possible to query if a
+given B<cmd> is recognised, this is useful is SSL_CTX_cmd() values are
+mixed with additional application specific operations.
+
+For example an application might call SSL_CTX_cmd() and if it returns
+-2 (unrecognised command) continue with processing of application specific
+commands.
+
+Applications can also use SSL_CTX_cmd() to process command lines though the
+utility function SSL_CTX_cmd_argv() is normally used instead. One way
+to do this is to set the prefix to an appropriate value using
+SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the
+following argument to B<value> (which may be NULL).
+
+In this case if the return value is positive then it is used to skip that
+number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is
+returned then B<cmd> is not recognised and application specific arguments
+can be checked instead. If -3 is returned a required argument is missing
+and an error is indicated. If 0 is returned some other error occurred and
+this can be reported back to the user.
+
+The function SSL_CONF_cmd_value_type() can be used by applications to
+check for the existence of a command or to perform additional syntax
+checking or translation of the command value. For example if the return
+value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
+pathname to an absolute pathname.
+
+=head1 EXAMPLES
+
+Set supported signature algorithms:
+
+ SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
+
+There are various ways to select the supported protocols.
+
+This set the minimum protocol version to TLSv1, and so disables SSLv3.
+This is the recommended way to disable protocols.
+
+ SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1");
+
+The following also disables SSLv3:
+
+ SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
+
+The following will first enable all protocols, and then disable
+SSLv3.
+If no protocol versions were disabled before this has the same effect as
+"-SSLv3", but if some versions were disables this will re-enable them before
+disabling SSLv3.
+
+ SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3");
+
+Only enable TLSv1.2:
+
+ SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2");
+ SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2");
+
+This also only enables TLSv1.2:
+
+ SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
+
+Disable TLS session tickets:
+
+ SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
+
+Enable compression:
+
+ SSL_CONF_cmd(ctx, "Options", "Compression");
+
+Set supported curves to P-256, P-384:
+
+ SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
+
+Set automatic support for any elliptic curve for key exchange:
+
+ SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
+
+=head1 RETURN VALUES
+
+SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
+B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
+returns the number of arguments processed. This is useful when processing
+command lines.
+
+A return value of -2 means B<cmd> is not recognised.
+
+A return value of -3 means B<cmd> is recognised and the command requires a
+value but B<value> is NULL.
+
+A return code of 0 indicates that both B<cmd> and B<value> are valid but an
+error occurred attempting to perform the operation: for example due to an
+error in the syntax of B<value> in this case the error queue may provide
+additional information.
+
+SSL_CONF_finish() returns 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_CTX_new(3)>,
+L<SSL_CONF_CTX_set_flags(3)>,
+L<SSL_CONF_CTX_set1_prefix(3)>,
+L<SSL_CONF_CTX_set_ssl_ctx(3)>,
+L<SSL_CONF_cmd_argv(3)>,
+L<SSL_CTX_set_options(3)>
+
+=head1 HISTORY
+
+SSL_CONF_cmd() was first added to OpenSSL 1.0.2
+
+B<SSL_OP_NO_SSL2> doesn't have effect since 1.1.0, but the macro is retained
+for backwards compatibility.
+
+B<SSL_CONF_TYPE_NONE> was first added to OpenSSL 1.1.0. In earlier versions of
+OpenSSL passing a command which didn't take an argument would return
+B<SSL_CONF_TYPE_UNKNOWN>.
+
+B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CONF_cmd_argv - SSL configuration command line processing
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CONF_cmd_argv(SSL_CONF_CTX *cctx, int *pargc, char ***pargv);
+
+=head1 DESCRIPTION
+
+The function SSL_CONF_cmd_argv() processes at most two command line
+arguments from B<pargv> and B<pargc>. The values of B<pargv> and B<pargc>
+are updated to reflect the number of command options processed. The B<pargc>
+argument can be set to B<NULL> is it is not used.
+
+=head1 RETURN VALUES
+
+SSL_CONF_cmd_argv() returns the number of command arguments processed: 0, 1, 2
+or a negative error code.
+
+If -2 is returned then an argument for a command is missing.
+
+If -1 is returned the command is recognised but couldn't be processed due
+to an error: for example a syntax error in the argument.
+
+=head1 SEE ALSO
+
+L<SSL_CONF_CTX_new(3)>,
+L<SSL_CONF_CTX_set_flags(3)>,
+L<SSL_CONF_CTX_set1_prefix(3)>,
+L<SSL_CONF_CTX_set_ssl_ctx(3)>,
+L<SSL_CONF_cmd(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2
+
+=head1 COPYRIGHT
+
+Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
+SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs,
+SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert,
+SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain,
+SSL_build_cert_chain, SSL_CTX_select_current_cert,
+SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra
+chain certificate processing
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
+ int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
+ int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
+ int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
+ int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
+ int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
+
+ int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
+ int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
+ int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
+ int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
+ int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
+ int SSL_clear_chain_certs(SSL *ssl);
+
+ int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
+ int SSL_build_cert_chain(SSL *ssl, flags);
+
+ int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
+ int SSL_select_current_cert(SSL *ssl, X509 *x509);
+ int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
+ int SSL_set_current_cert(SSL *ssl, long op);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain
+associated with the current certificate of B<ctx> to B<sk>.
+
+SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single
+certificate B<x509> to the chain associated with the current certificate of
+B<ctx>.
+
+SSL_CTX_get0_chain_certs() retrieves the chain associated with the current
+certificate of B<ctx>.
+
+SSL_CTX_clear_chain_certs() clears any existing chain associated with the
+current certificate of B<ctx>. (This is implemented by calling
+SSL_CTX_set0_chain() with B<sk> set to B<NULL>).
+
+SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally
+this uses the chain store or the verify store if the chain store is not set.
+If the function is successful the built chain will replace any existing chain.
+The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use
+existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT>
+to omit the root CA from the built chain, B<SSL_BUILD_CHAIN_FLAG_CHECK> to
+use all existing chain certificates only to build the chain (effectively
+sanity checking and rearranging them if necessary), the flag
+B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification:
+if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors
+are cleared from the error queue.
+
+Each of these functions operates on the I<current> end entity
+(i.e. server or client) certificate. This is the last certificate loaded or
+selected on the corresponding B<ctx> structure.
+
+SSL_CTX_select_current_cert() selects B<x509> as the current end entity
+certificate, but only if B<x509> has already been loaded into B<ctx> using a
+function such as SSL_CTX_use_certificate().
+
+SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(),
+SSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(),
+SSL_build_cert_chain(), SSL_select_current_cert() and SSL_set_current_cert()
+are similar except they apply to SSL structure B<ssl>.
+
+SSL_CTX_set_current_cert() changes the current certificate to a value based
+on the B<op> argument. Currently B<op> can be B<SSL_CERT_SET_FIRST> to use
+the first valid certificate or B<SSL_CERT_SET_NEXT> to set the next valid
+certificate after the current certificate. These two operations can be
+used to iterate over all certificates in an B<SSL_CTX> structure.
+
+SSL_set_current_cert() also supports the option B<SSL_CERT_SET_SERVER>.
+If B<ssl> is a server and has sent a certificate to a connected client
+this option sets that certificate to the current certificate and returns 1.
+If the negotiated ciphersuite is anonymous (and thus no certificate will
+be sent) 2 is returned and the current certificate is unchanged. If B<ssl>
+is not a server or a certificate has not been sent 0 is returned and
+the current certificate is unchanged.
+
+All these functions are implemented as macros. Those containing a B<1>
+increment the reference count of the supplied certificate or chain so it must
+be freed at some point after the operation. Those containing a B<0> do
+not increment reference counts and the supplied certificate or chain
+B<MUST NOT> be freed after the operation.
+
+=head1 NOTES
+
+The chains associate with an SSL_CTX structure are copied to any SSL
+structures when SSL_new() is called. SSL structures will not be affected
+by any chains subsequently changed in the parent SSL_CTX.
+
+One chain can be set for each key type supported by a server. So, for example,
+an RSA and a DSA certificate can (and often will) have different chains.
+
+The functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can
+be used to check application configuration and to ensure any necessary
+subordinate CAs are sent in the correct order. Misconfigured applications
+sending incorrect certificate chains often cause problems with peers.
+
+For example an application can add any set of certificates using
+SSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain()
+with the option B<SSL_BUILD_CHAIN_FLAG_CHECK> to check and reorder them.
+
+Applications can issue non fatal warnings when checking chains by setting
+the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS> and checking the return
+value.
+
+Calling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more
+efficient than the automatic chain building as it is only performed once.
+Automatic chain building is performed on each new session.
+
+If any certificates are added using these functions no certificates added
+using SSL_CTX_add_extra_chain_cert() will be used.
+
+=head1 RETURN VALUES
+
+SSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if
+no server certificate is used because the ciphersuites is anonymous and 0
+for failure.
+
+SSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success
+and 0 for failure. If the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> and
+a verification error occurs then 2 is returned.
+
+All other functions return 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_add_extra_chain_cert(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_add_extra_chain_cert, SSL_CTX_clear_extra_chain_certs - add or clear
+extra chain certificates
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);
+ long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the extra chain
+certificates associated with B<ctx>. Several certificates can be added one
+after another.
+
+SSL_CTX_clear_extra_chain_certs() clears all extra chain certificates
+associated with B<ctx>.
+
+These functions are implemented as macros.
+
+=head1 NOTES
+
+When sending a certificate chain, extra chain certificates are sent in order
+following the end entity certificate.
+
+If no chain is specified, the library will try to complete the chain from the
+available CA certificates in the trusted CA storage, see
+L<SSL_CTX_load_verify_locations(3)>.
+
+The B<x509> certificate provided to SSL_CTX_add_extra_chain_cert() will be
+freed by the library when the B<SSL_CTX> is destroyed. An application
+B<should not> free the B<x509> object.
+
+=head1 RESTRICTIONS
+
+Only one set of extra chain certificates can be specified per SSL_CTX
+structure. Different chains for different certificates (for example if both
+RSA and DSA certificates are specified by the same server) or different SSL
+structures with the same parent SSL_CTX cannot be specified using this
+function. For more flexibility functions such as SSL_add1_chain_cert() should
+be used instead.
+
+=head1 RETURN VALUES
+
+SSL_CTX_add_extra_chain_cert() and SSL_CTX_clear_extra_chain_certs() return
+1 on success and 0 for failure. Check out the error stack to find out the
+reason for failure.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_set_client_cert_cb(3)>,
+L<SSL_CTX_load_verify_locations(3)>
+L<SSL_CTX_set0_chain(3)>
+L<SSL_CTX_set1_chain(3)>
+L<SSL_CTX_add0_chain_cert(3)>
+L<SSL_CTX_add1_chain_cert(3)>
+L<SSL_set0_chain(3)>
+L<SSL_set1_chain(3)>
+L<SSL_add0_chain_cert(3)>
+L<SSL_add1_chain_cert(3)>
+L<SSL_CTX_build_cert_chain(3)>
+L<SSL_build_cert_chain(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);
+ int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c);
+
+ int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
+ int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
+
+=head1 DESCRIPTION
+
+SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The
+reference count for session B<c> is incremented by 1. If a session with
+the same session id already exists, the old session is removed by calling
+L<SSL_SESSION_free(3)>.
+
+SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>.
+L<SSL_SESSION_free(3)> is called once for B<c>.
+
+SSL_add_session() and SSL_remove_session() are synonyms for their
+SSL_CTX_*() counterparts.
+
+=head1 NOTES
+
+When adding a new session to the internal session cache, it is examined
+whether a session with the same session id already exists. In this case
+it is assumed that both sessions are identical. If the same session is
+stored in a different SSL_SESSION object, The old session is
+removed and replaced by the new session. If the session is actually
+identical (the SSL_SESSION object is identical), SSL_CTX_add_session()
+is a no-op, and the return value is 0.
+
+If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE
+flag then the internal cache will not be populated automatically by new
+sessions negotiated by the SSL/TLS implementation, even though the internal
+cache will be searched automatically for session-resume requests (the
+latter can be suppressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the
+application can use SSL_CTX_add_session() directly to have full control
+over the sessions that can be resumed if desired.
+
+
+=head1 RETURN VALUES
+
+The following values are returned by all functions:
+
+=over 4
+
+=item Z<>0
+
+ The operation failed. In case of the add operation, it was tried to add
+ the same (identical) session twice. In case of the remove operation, the
+ session was not found in the cache.
+
+=item Z<>1
+
+ The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_SESSION_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_config(SSL_CTX *ctx, const char *name);
+ int SSL_config(SSL *s, const char *name);
+
+=head1 DESCRIPTION
+
+The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or
+B<SSL> structure using the configuration B<name>.
+
+=head1 NOTES
+
+By calling SSL_CTX_config() or SSL_config() an application can perform many
+complex tasks based on the contents of the configuration file: greatly
+simplifying application configuration code. A degree of future proofing
+can also be achieved: an application can support configuration features
+in newer versions of OpenSSL automatically.
+
+A configuration file must have been previously loaded, for example using
+CONF_modules_load_file(). See L<config(3)> for details of the configuration
+file syntax.
+
+=head1 RETURN VALUES
+
+SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
+occurred.
+
+=head1 EXAMPLE
+
+If the file "config.cnf" contains the following:
+
+ testapp = test_sect
+
+ [test_sect]
+ # list of confuration modules
+
+ ssl_conf = ssl_sect
+
+ [ssl_sect]
+
+ server = server_section
+
+ [server_section]
+
+ RSA.Certificate = server-rsa.pem
+ ECDSA.Certificate = server-ecdsa.pem
+ Ciphers = ALL:!RC4
+
+An application could call:
+
+ if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) {
+ fprintf(stderr, "Error processing config file\n");
+ goto err;
+ }
+
+ ctx = SSL_CTX_new(TLS_server_method());
+
+ if (SSL_CTX_config(ctx, "server") == 0) {
+ fprintf(stderr, "Error configuring server.\n");
+ goto err;
+ }
+
+In this example two certificates and the cipher list are configured without
+the need for any additional application code.
+
+=head1 SEE ALSO
+
+L<config(3)>,
+L<SSL_CONF_cmd(3)>,
+L<CONF_modules_load_file(3)>
+
+=head1 HISTORY
+
+SSL_CTX_config() and SSL_config() were first added to OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal handling functions for SSL_CTX and SSL objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg);
+ long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)());
+
+ long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg);
+ long SSL_callback_ctrl(SSL *, int cmd, void (*fp)());
+
+=head1 DESCRIPTION
+
+The SSL_*_ctrl() family of functions is used to manipulate settings of
+the SSL_CTX and SSL objects. Depending on the command B<cmd> the arguments
+B<larg>, B<parg>, or B<fp> are evaluated. These functions should never
+be called directly. All functionalities needed are made available via
+other functions or macros.
+
+=head1 RETURN VALUES
+
+The return values of the SSL*_ctrl() functions depend on the command
+supplied via the B<cmd> parameter.
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable,
+SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa
+SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags,
+SSL_dane_set_flags, SSL_dane_clear_flags -
+enable DANE TLS authentication of the remote TLS server in the local
+TLS client
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_dane_enable(SSL_CTX *ctx);
+ int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md,
+ uint8_t mtype, uint8_t ord);
+ int SSL_dane_enable(SSL *s, const char *basedomain);
+ int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector,
+ uint8_t mtype, unsigned char *data, size_t dlen);
+ int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki);
+ int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector,
+ uint8_t *mtype, unsigned const char **data,
+ size_t *dlen);
+ unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags);
+ unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags);
+ unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags);
+ unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags);
+
+=head1 DESCRIPTION
+
+These functions implement support for DANE TLSA (RFC6698 and RFC7671)
+peer authentication.
+
+SSL_CTX_dane_enable() must be called first to initialize the shared state
+required for DANE support.
+Individual connections associated with the context can then enable
+per-connection DANE support as appropriate.
+DANE authentication is implemented in the L<X509_verify_cert(3)> function, and
+applications that override L<X509_verify_cert(3)> via
+L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer
+chain in whatever manner they see fit.
+
+SSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the
+supported digest algorithms.
+This must be done before any SSL handles are created for the context.
+
+The B<mtype> argument specifies a DANE TLSA matching type and the B<md>
+argument specifies the associated digest algorithm handle.
+The B<ord> argument specifies a strength ordinal.
+Algorithms with a larger strength ordinal are considered more secure.
+Strength ordinals are used to implement RFC7671 digest algorithm agility.
+Specifying a B<NULL> digest algorithm for a matching type disables
+support for that matching type.
+Matching type Full(0) cannot be modified or disabled.
+
+By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions
+of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()>
+with a strength ordinal of C<1> and matching type C<SHA2-512(2)>
+is mapped to C<EVP_sha512()> with a strength ordinal of C<2>.
+
+SSL_dane_enable() must be called before the SSL handshake is initiated with
+L<SSL_connect(3)> if (and only if) you want to enable DANE for that connection.
+(The connection must be associated with a DANE-enabled SSL context).
+The B<basedomain> argument specifies the RFC7671 TLSA base domain,
+which will be the primary peer reference identifier for certificate
+name checks.
+Additional server names can be specified via L<SSL_add1_host(3)>.
+The B<basedomain> is used as the default SNI hint if none has yet been
+specified via L<SSL_set_tlsext_host_name(3)>.
+
+SSL_dane_tlsa_add() may then be called one or more times, to load each of the
+TLSA records that apply to the remote TLS peer.
+(This too must be done prior to the beginning of the SSL handshake).
+The arguments specify the fields of the TLSA record.
+The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal
+ASCII presentation form, with an explicit length passed via B<dlen>.
+A return value of 0 indicates that "unusable" TLSA records (with invalid or
+unsupported parameters) were provided.
+A negative return value indicates an internal error in processing the record.
+
+The caller is expected to check the return value of each SSL_dane_tlsa_add()
+call and take appropriate action if none are usable or an internal error
+is encountered in processing some records.
+
+If no TLSA records are added successfully, DANE authentication is not enabled,
+and authentication will be based on any configured traditional trust-anchors;
+authentication success in this case does not mean that the peer was
+DANE-authenticated.
+
+SSL_get0_dane_authority() can be used to get more detailed information about
+the matched DANE trust-anchor after successful connection completion.
+The return value is negative if DANE verification failed (or was not enabled),
+0 if an EE TLSA record directly matched the leaf certificate, or a positive
+number indicating the depth at which a TA record matched an issuer certificate.
+The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>.
+The return value is an index into this verified chain, rather than the list of
+certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>.
+
+If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain
+certificate, a pointer to the matching certificate is returned via B<mcert>.
+The returned address is a short-term internal reference to the certificate and
+must not be freed by the application.
+Applications that want to retain access to the certificate can call
+L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via
+L<X509_free(3)> once no longer needed.
+
+If no TLSA records directly matched any elements of the certificate chain, but
+a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an
+element of the chain, then that key is returned via B<mspki> argument (if not
+NULL).
+In this case the return value is the depth of the top-most element of the
+validated certificate chain.
+As with B<mcert> this is a short-term internal reference, and
+L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and
+release long-term references respectively.
+
+SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that
+matched the peer certificate chain.
+The return value indicates the match depth or failure to match just as with
+SSL_get0_dane_authority().
+When the return value is non-negative, the storage pointed to by the B<usage>,
+B<selector>, B<mtype> and B<data> parameters is updated to the corresponding
+TLSA record fields.
+The B<data> field is in binary wire form, and is therefore not NUL-terminated,
+its length is returned via the B<dlen> parameter.
+If any of these parameters is NULL, the corresponding field is not returned.
+The B<data> parameter is set to a short-term internal-copy of the associated
+data field and must not be freed by the application.
+Applications that need long-term access to this field need to copy the content.
+
+SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable
+optional DANE verification features.
+SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable
+the same features.
+The B<flags> argument is a bitmask of the features to enable or disable.
+The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle
+associated with that context at the time the handle is created.
+Subsequent changes in the context's B<flags> have no effect on the B<flags> set
+for the handle.
+
+At present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS>
+which can be used to disable server name checks when authenticating via
+DANE-EE(3) TLSA records.
+For some applications, primarily web browsers, it is not safe to disable name
+checks due to "unknown key share" attacks, in which a malicious server can
+convince a client that a connection to a victim server is instead a secure
+connection to the malicious server.
+The malicious server may then be able to violate cross-origin scripting
+restrictions.
+Thus, despite the text of RFC7671, name checks are by default enabled for
+DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
+to do so.
+In particular, SMTP and XMPP clients should set this option as SRV and MX
+records already make it possible for a remote domain to redirect client
+connections to any server of its choice, and in any case SMTP and XMPP clients
+do not execute scripts downloaded from remote servers.
+
+=head1 RETURN VALUES
+
+The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(),
+SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success.
+Negative return values indicate resource problems (out of memory, etc.) in the
+SSL library, while a return value of B<0> indicates incorrect usage or invalid
+input, such as an unsupported TLSA record certificate usage, selector or
+matching type.
+Invalid input also includes malformed data, either a digest length that does
+not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form)
+certificate or a public key that fails to parse.
+
+The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a
+negative value when DANE authentication failed or was not enabled, a
+non-negative value indicates the chain depth at which the TLSA record matched a
+chain certificate, or the depth of the top-most certificate, when the TLSA
+record is a full public key that is its signer.
+
+The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(),
+SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect
+before they were called.
+
+=head1 EXAMPLE
+
+Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
+DNSSEC-validated TLSA records.
+The calls below will perform DANE authentication and arrange to match either
+the MX hostname or the destination domain name in the SMTP server certificate.
+Wildcards are supported, but must match the entire label.
+The actual name matched in the certificate (which might be a wildcard) is
+retrieved, and must be copied by the application if it is to be retained beyond
+the lifetime of the SSL connection.
+
+ SSL_CTX *ctx;
+ SSL *ssl;
+ int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL;
+ int num_usable = 0;
+ const char *nexthop_domain = "example.com";
+ const char *dane_tlsa_domain = "smtp.example.com";
+ uint8_t usage, selector, mtype;
+
+ if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL)
+ /* handle error */
+ if (SSL_CTX_dane_enable(ctx) <= 0)
+ /* handle error */
+
+ if ((ssl = SSL_new(ctx)) == NULL)
+ /* handle error */
+
+ if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0)
+ /* handle error */
+
+ /*
+ * For many applications it is safe to skip DANE-EE(3) namechecks. Do not
+ * disable the checks unless "unknown key share" attacks pose no risk for
+ * your application.
+ */
+ SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS);
+
+ if (!SSL_add1_host(ssl, nexthop_domain))
+ /* handle error */
+ SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
+
+ for (... each TLSA record ...) {
+ unsigned char *data;
+ size_t len;
+ int ret;
+
+ /* set usage, selector, mtype, data, len */
+
+ /*
+ * Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3).
+ * They treat all other certificate usages, and in particular PKIX-TA(0)
+ * and PKIX-EE(1), as unusable.
+ */
+ switch (usage) {
+ default:
+ case 0: /* PKIX-TA(0) */
+ case 1: /* PKIX-EE(1) */
+ continue;
+ case 2: /* DANE-TA(2) */
+ case 3: /* DANE-EE(3) */
+ break;
+ }
+
+ ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len);
+ /* free data as appropriate */
+
+ if (ret < 0)
+ /* handle SSL library internal error */
+ else if (ret == 0)
+ /* handle unusable TLSA record */
+ else
+ ++num_usable;
+ }
+
+ /*
+ * At this point, the verification mode is still the default SSL_VERIFY_NONE.
+ * Opportunistic DANE clients use unauthenticated TLS when all TLSA records
+ * are unusable, so continue the handshake even if authentication fails.
+ */
+ if (num_usable == 0) {
+ /* Log all records unusable? */
+
+ /* Optionally set verify_cb to a suitable non-NULL callback. */
+ SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb);
+ } else {
+ /* At least one usable record. We expect to verify the peer */
+
+ /* Optionally set verify_cb to a suitable non-NULL callback. */
+
+ /*
+ * Below we elect to fail the handshake when peer verification fails.
+ * Alternatively, use the permissive SSL_VERIFY_NONE verification mode,
+ * complete the handshake, check the verification status, and if not
+ * verified disconnect gracefully at the application layer, especially if
+ * application protocol supports informing the server that authentication
+ * failed.
+ */
+ SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb);
+ }
+
+ /*
+ * Load any saved session for resumption, making sure that the previous
+ * session applied the same security and authentication requirements that
+ * would be expected of a fresh connection.
+ */
+
+ /* Perform SSL_connect() handshake and handle errors here */
+
+ if (SSL_session_reused(ssl)) {
+ if (SSL_get_verify_result(ssl) == X509_V_OK) {
+ /*
+ * Resumed session was originally verified, this connection is
+ * authenticated.
+ */
+ } else {
+ /*
+ * Resumed session was not originally verified, this connection is not
+ * authenticated.
+ */
+ }
+ } else if (SSL_get_verify_result(ssl) == X509_V_OK) {
+ const char *peername = SSL_get0_peername(ssl);
+ EVP_PKEY *mspki = NULL;
+
+ int depth = SSL_get0_dane_authority(ssl, NULL, &mspki);
+ if (depth >= 0) {
+ (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL);
+ printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype,
+ (mspki != NULL) ? "TA public key verified certificate" :
+ depth ? "matched TA certificate" : "matched EE certificate",
+ depth);
+ }
+ if (peername != NULL) {
+ /* Name checks were in scope and matched the peername */
+ printf("Verified peername: %s\n", peername);
+ }
+ } else {
+ /*
+ * Not authenticated, presumably all TLSA rrs unusable, but possibly a
+ * callback suppressed connection termination despite the presence of
+ * usable TLSA RRs none of which matched. Do whatever is appropriate for
+ * fresh unauthenticated connections.
+ */
+ }
+
+=head1 NOTES
+
+It is expected that the majority of clients employing DANE TLS will be doing
+"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435.
+That is, they will use DANE authentication when DNSSEC-validated TLSA records
+are published for a given peer, and otherwise will use unauthenticated TLS or
+even cleartext.
+
+Such applications should generally treat any TLSA records published by the peer
+with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include
+them among the TLSA records used to authenticate peer connections.
+In addition, some TLSA records with supported usages may be "unusable" as a
+result of invalid or unsupported parameters.
+
+When a peer has TLSA records, but none are "usable", an opportunistic
+application must avoid cleartext, but cannot authenticate the peer,
+and so should generally proceed with an unauthenticated connection.
+Opportunistic applications need to note the return value of each
+call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid
+or unsupported parameters) disable peer authentication by calling
+L<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>.
+
+=head1 SEE ALSO
+
+L<SSL_new(3)>,
+L<SSL_add1_host(3)>,
+L<SSL_set_hostflags(3)>,
+L<SSL_set_tlsext_host_name(3)>,
+L<SSL_set_verify(3)>,
+L<SSL_CTX_set_cert_verify_callback(3)>,
+L<SSL_get0_verified_chain(3)>,
+L<SSL_get_peer_cert_chain(3)>,
+L<SSL_get_verify_result(3)>,
+L<SSL_connect(3)>,
+L<SSL_get0_peername(3)>,
+L<X509_verify_cert(3)>,
+L<X509_up_ref(3)>,
+L<X509_free(3)>,
+L<EVP_get_digestbyname(3)>,
+L<EVP_PKEY_up_ref(3)>,
+L<EVP_PKEY_free(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm);
+ void SSL_flush_sessions(SSL_CTX *ctx, long tm);
+
+=head1 DESCRIPTION
+
+SSL_CTX_flush_sessions() causes a run through the session cache of
+B<ctx> to remove sessions expired at time B<tm>.
+
+SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions().
+
+=head1 NOTES
+
+If enabled, the internal session cache will collect all sessions established
+up to the specified maximum number (see SSL_CTX_sess_set_cache_size()).
+As sessions will not be reused ones they are expired, they should be
+removed from the cache to save resources. This can either be done
+ automatically whenever 255 new sessions were established (see
+L<SSL_CTX_set_session_cache_mode(3)>)
+or manually by calling SSL_CTX_flush_sessions().
+
+The parameter B<tm> specifies the time which should be used for the
+expiration test, in most cases the actual time given by time(0)
+will be used.
+
+SSL_CTX_flush_sessions() will only check sessions stored in the internal
+cache. When a session is found and removed, the remove_session_cb is however
+called to synchronize with the external cache (see
+L<SSL_CTX_sess_set_get_cb(3)>).
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_sess_set_get_cb(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_free - free an allocated SSL_CTX object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_free(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_free() decrements the reference count of B<ctx>, and removes the
+SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the reference count has reached 0.
+
+It also calls the free()ing procedures for indirectly affected items, if
+applicable: the session cache, the list of ciphers, the list of Client CAs,
+the certificates and keys.
+
+If B<ctx> is NULL nothing is done.
+
+=head1 WARNINGS
+
+If a session-remove callback is set (SSL_CTX_sess_set_remove_cb()), this
+callback will be called for each session being freed from B<ctx>'s
+session cache. This implies, that all corresponding sessions from an
+external session cache are removed as well. If this is not desired, the user
+should explicitly unset the callback by calling
+SSL_CTX_sess_set_remove_cb(B<ctx>, NULL) prior to calling SSL_CTX_free().
+
+=head1 RETURN VALUES
+
+SSL_CTX_free() does not provide diagnostic information.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_new(3)>, L<ssl(3)>,
+L<SSL_CTX_sess_set_get_cb(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param -
+get and set verification parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx)
+ X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl)
+ int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm)
+ int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm)
+
+=head1 DESCRIPTION
+
+SSL_CTX_get0_param() and SSL_get0_param() retrieve an internal pointer to
+the verification parameters for B<ctx> or B<ssl> respectively. The returned
+pointer must not be freed by the calling application.
+
+SSL_CTX_set1_param() and SSL_set1_param() set the verification parameters
+to B<vpm> for B<ctx> or B<ssl>.
+
+=head1 NOTES
+
+Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure
+using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
+them to suit its needs: for example to add a hostname check.
+
+=head1 EXAMPLE
+
+Check hostname matches "www.foo.com" in peer certificate:
+
+ X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
+ X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
+
+=head1 RETURN VALUES
+
+SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
+B<X509_VERIFY_PARAM> structure.
+
+SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
+for failure.
+
+=head1 SEE ALSO
+
+L<X509_VERIFY_PARAM_set_flags(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_get_verify_mode(const SSL_CTX *ctx);
+ int SSL_get_verify_mode(const SSL *ssl);
+ int SSL_CTX_get_verify_depth(const SSL_CTX *ctx);
+ int SSL_get_verify_depth(const SSL *ssl);
+ int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *);
+ int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *);
+
+=head1 DESCRIPTION
+
+SSL_CTX_get_verify_mode() returns the verification mode currently set in
+B<ctx>.
+
+SSL_get_verify_mode() returns the verification mode currently set in
+B<ssl>.
+
+SSL_CTX_get_verify_depth() returns the verification depth limit currently set
+in B<ctx>. If no limit has been explicitly set, -1 is returned and the
+default value will be used.
+
+SSL_get_verify_depth() returns the verification depth limit currently set
+in B<ssl>. If no limit has been explicitly set, -1 is returned and the
+default value will be used.
+
+SSL_CTX_get_verify_callback() returns a function pointer to the verification
+callback currently set in B<ctx>. If no callback was explicitly set, the
+NULL pointer is returned and the default callback will be used.
+
+SSL_get_verify_callback() returns a function pointer to the verification
+callback currently set in B<ssl>. If no callback was explicitly set, the
+NULL pointer is returned and the default callback will be used.
+
+=head1 RETURN VALUES
+
+See DESCRIPTION
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular
+client extension type
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type);
+
+=head1 DESCRIPTION
+
+SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a
+client extension of type B<ext_type> using SSL_CTX_add_client_custom_ext().
+
+=head1 RETURN VALUES
+
+Returns 1 if a handler has been set, 0 otherwise.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_add_client_custom_ext(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_load_verify_locations, SSL_CTX_set_default_verify_paths,
+SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file - set
+default locations for trusted CA certificates
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
+ const char *CApath);
+
+ int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
+
+ int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx);
+
+ int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at
+which CA certificates for verification purposes are located. The certificates
+available via B<CAfile> and B<CApath> are trusted.
+
+SSL_CTX_set_default_verify_paths() specifies that the default locations from
+which CA certificates are loaded should be used. There is one default directory
+and one default file. The default CA certificates directory is called "certs" in
+the default OpenSSL directory. Alternatively the SSL_CERT_DIR environment
+variable can be defined to override this location. The default CA certificates
+file is called "cert.pem" in the default OpenSSL directory. Alternatively the
+SSL_CERT_FILE environment variable can be defined to override this location.
+
+SSL_CTX_set_default_verify_dir() is similar to
+SSL_CTX_set_default_verify_paths() except that just the default directory is
+used.
+
+SSL_CTX_set_default_verify_file() is similar to
+SSL_CTX_set_default_verify_paths() except that just the default file is
+used.
+
+=head1 NOTES
+
+If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
+format. The file can contain several CA certificates identified by
+
+ -----BEGIN CERTIFICATE-----
+ ... (CA certificate in base64 encoding) ...
+ -----END CERTIFICATE-----
+
+sequences. Before, between, and after the certificates text is allowed
+which can be used e.g. for descriptions of the certificates.
+
+The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
+function.
+
+If B<CApath> is not NULL, it points to a directory containing CA certificates
+in PEM format. The files each contain one CA certificate. The files are
+looked up by the CA subject name hash value, which must hence be available.
+If more than one CA certificate with the same name hash value exist, the
+extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
+is performed in the ordering of the extension number, regardless of other
+properties of the certificates.
+Use the B<c_rehash> utility to create the necessary links.
+
+The certificates in B<CApath> are only looked up when required, e.g. when
+building the certificate chain or when actually performing the verification
+of a peer certificate.
+
+When looking up CA certificates, the OpenSSL library will first search the
+certificates in B<CAfile>, then those in B<CApath>. Certificate matching
+is done based on the subject name, the key identifier (if present), and the
+serial number as taken from the certificate to be verified. If these data
+do not match, the next certificate will be tried. If a first certificate
+matching the parameters is found, the verification process will be performed;
+no other certificates for the same parameters will be searched in case of
+failure.
+
+In server mode, when requesting a client certificate, the server must send
+the list of CAs of which it will accept client certificates. This list
+is not influenced by the contents of B<CAfile> or B<CApath> and must
+explicitly be set using the
+L<SSL_CTX_set_client_CA_list(3)>
+family of functions.
+
+When building its own certificate chain, an OpenSSL client/server will
+try to fill in missing certificates from B<CAfile>/B<CApath>, if the
+certificate chain was not explicitly specified (see
+L<SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_use_certificate(3)>.
+
+=head1 WARNINGS
+
+If several CA certificates matching the name, key identifier, and serial
+number condition are available, only the first one will be examined. This
+may lead to unexpected results if the same CA certificate is available
+with different expiration dates. If a "certificate expired" verification
+error occurs, no other certificate will be searched. Make sure to not
+have expired certificates mixed with valid ones.
+
+=head1 EXAMPLES
+
+Generate a CA certificate file with descriptive text from the CA certificates
+ca1.pem ca2.pem ca3.pem:
+
+ #!/bin/sh
+ rm CAfile.pem
+ for i in ca1.pem ca2.pem ca3.pem ; do
+ openssl x509 -in $i -text >> CAfile.pem
+ done
+
+Prepare the directory /some/where/certs containing several CA certificates
+for use as B<CApath>:
+
+ cd /some/where/certs
+ c_rehash .
+
+=head1 RETURN VALUES
+
+For SSL_CTX_load_verify_locations the following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The operation failed because B<CAfile> and B<CApath> are NULL or the
+processing at one of the locations specified failed. Check the error
+stack to find out the reason.
+
+=item Z<>1
+
+The operation succeeded.
+
+=back
+
+SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
+SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
+missing default location is still treated as a success.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_client_CA_list(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_set_cert_store(3)>,
+L<SSL_CTX_set_client_CA_list(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
+SSL_CTX_new, SSL_CTX_up_ref, SSLv3_method, SSLv3_server_method,
+SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method,
+TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method,
+TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method,
+SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method,
+DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method,
+DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method
+- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
+functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
+ int SSL_CTX_up_ref(SSL_CTX *ctx);
+
+ const SSL_METHOD *TLS_method(void);
+ const SSL_METHOD *TLS_server_method(void);
+ const SSL_METHOD *TLS_client_method(void);
+
+ const SSL_METHOD *SSLv23_method(void);
+ const SSL_METHOD *SSLv23_server_method(void);
+ const SSL_METHOD *SSLv23_client_method(void);
+
+ #ifndef OPENSSL_NO_SSL3_METHOD
+ const SSL_METHOD *SSLv3_method(void);
+ const SSL_METHOD *SSLv3_server_method(void);
+ const SSL_METHOD *SSLv3_client_method(void);
+ #endif
+
+ #ifndef OPENSSL_NO_TLS1_METHOD
+ const SSL_METHOD *TLSv1_method(void);
+ const SSL_METHOD *TLSv1_server_method(void);
+ const SSL_METHOD *TLSv1_client_method(void);
+ #endif
+
+ #ifndef OPENSSL_NO_TLS1_1_METHOD
+ const SSL_METHOD *TLSv1_1_method(void);
+ const SSL_METHOD *TLSv1_1_server_method(void);
+ const SSL_METHOD *TLSv1_1_client_method(void);
+ #endif
+
+ #ifndef OPENSSL_NO_TLS1_2_METHOD
+ const SSL_METHOD *TLSv1_2_method(void);
+ const SSL_METHOD *TLSv1_2_server_method(void);
+ const SSL_METHOD *TLSv1_2_client_method(void);
+ #endif
+
+ const SSL_METHOD *DTLS_method(void);
+ const SSL_METHOD *DTLS_server_method(void);
+ const SSL_METHOD *DTLS_client_method(void);
+
+ #ifndef OPENSSL_NO_DTLS1_METHOD
+ const SSL_METHOD *DTLSv1_method(void);
+ const SSL_METHOD *DTLSv1_server_method(void);
+ const SSL_METHOD *DTLSv1_client_method(void);
+ #endif
+
+ #ifndef OPENSSL_NO_DTLS1_2_METHOD
+ const SSL_METHOD *DTLSv1_2_method(void);
+ const SSL_METHOD *DTLSv1_2_server_method(void);
+ const SSL_METHOD *DTLSv1_2_client_method(void);
+ #endif
+
+=head1 DESCRIPTION
+
+SSL_CTX_new() creates a new B<SSL_CTX> object as framework to
+establish TLS/SSL or DTLS enabled connections. An B<SSL_CTX> object is
+reference counted. Creating an B<SSL_CTX> object for the first time increments
+the reference count. Freeing it (using SSL_CTX_free) decrements it. When the
+reference count drops to zero, any memory or resources allocated to the
+B<SSL_CTX> object are freed. SSL_CTX_up_ref() increments the reference count for
+an existing B<SSL_CTX> structure.
+
+=head1 NOTES
+
+The SSL_CTX object uses B<method> as connection method.
+The methods exist in a generic type (for client and server use), a server only
+type, and a client only type.
+B<method> can be of the following types:
+
+=over 4
+
+=item TLS_method(), TLS_server_method(), TLS_client_method()
+
+These are the general-purpose I<version-flexible> SSL/TLS methods.
+The actual protocol version used will be negotiated to the highest version
+mutually supported by the client and the server.
+The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2.
+Applications should use these methods, and avoid the version-specific
+methods described below.
+
+=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
+
+Use of these functions is deprecated. They have been replaced with the above
+TLS_method(), TLS_server_method() and TLS_client_method() respectively. New
+code should use those functions instead.
+
+=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
+
+A TLS/SSL connection established with these methods will only understand the
+TLSv1.2 protocol.
+
+=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
+
+A TLS/SSL connection established with these methods will only understand the
+TLSv1.1 protocol.
+
+=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
+
+A TLS/SSL connection established with these methods will only understand the
+TLSv1 protocol.
+
+=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
+
+A TLS/SSL connection established with these methods will only understand the
+SSLv3 protocol.
+The SSLv3 protocol is deprecated and should not be used.
+
+=item DTLS_method(), DTLS_server_method(), DTLS_client_method()
+
+These are the version-flexible DTLS methods.
+Currently supported protocols are DTLS 1.0 and DTLS 1.2.
+
+=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
+
+These are the version-specific methods for DTLSv1.2.
+
+=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
+
+These are the version-specific methods for DTLSv1.
+
+=back
+
+SSL_CTX_new() initializes the list of ciphers, the session cache setting, the
+callbacks, the keys and certificates and the options to their default values.
+
+TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
+DTLS_server_method() and DTLS_client_method() are the I<version-flexible>
+methods.
+All other methods only support one specific protocol version.
+Use the I<version-flexible> methods instead of the version specific methods.
+
+If you want to limit the supported protocols for the version flexible
+methods you can use L<SSL_CTX_set_min_proto_version(3)>,
+L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and
+LSSL_set_max_proto_version(3)> functions.
+Using these functions it is possible to choose e.g. TLS_server_method()
+and be able to negotiate with all possible clients, but to only
+allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2.
+
+The list of protocols available can also be limited using the
+B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and
+B<SSL_OP_NO_TLSv1_2> options of the L<SSL_CTX_set_options(3)> or
+L<SSL_set_options(3)> functions, but this approach is not recommended.
+Clients should avoid creating "holes" in the set of protocols they support.
+When disabling a protocol, make sure that you also disable either all previous
+or all subsequent protocol versions.
+In clients, when a protocol version is disabled without disabling I<all>
+previous protocol versions, the effect is to also disable all subsequent
+protocol versions.
+
+The SSLv3 protocol is deprecated and should generally not be used.
+Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set
+the minimum protocol to at least B<TLS1_VERSION>.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+The creation of a new SSL_CTX object failed. Check the error stack to find out
+the reason.
+
+=item Pointer to an SSL_CTX object
+
+The return value points to an allocated SSL_CTX object.
+
+SSL_CTX_up_ref() returns 1 for success and 0 for failure.
+
+=back
+
+=head1 HISTORY
+
+Support for SSLv2 and the corresponding SSLv2_method(),
+SSLv2_server_method() and SSLv2_client_method() functions where
+removed in OpenSSL 1.1.0.
+
+SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
+were deprecated and the preferred TLS_method(), TLS_server_method()
+and TLS_client_method() functions were introduced in OpenSSL 1.1.0.
+
+All version-specific methods were deprecated in OpenSSL 1.1.0.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
+L<SSL_CTX_set_min_proto_version(3)>, L<ssl(3)>, L<SSL_set_connect_state(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_sess_number(SSL_CTX *ctx);
+ long SSL_CTX_sess_connect(SSL_CTX *ctx);
+ long SSL_CTX_sess_connect_good(SSL_CTX *ctx);
+ long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);
+ long SSL_CTX_sess_accept(SSL_CTX *ctx);
+ long SSL_CTX_sess_accept_good(SSL_CTX *ctx);
+ long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);
+ long SSL_CTX_sess_hits(SSL_CTX *ctx);
+ long SSL_CTX_sess_cb_hits(SSL_CTX *ctx);
+ long SSL_CTX_sess_misses(SSL_CTX *ctx);
+ long SSL_CTX_sess_timeouts(SSL_CTX *ctx);
+ long SSL_CTX_sess_cache_full(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sess_number() returns the current number of sessions in the internal
+session cache.
+
+SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in
+client mode.
+
+SSL_CTX_sess_connect_good() returns the number of successfully established
+SSL/TLS sessions in client mode.
+
+SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations
+in client mode.
+
+SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in
+server mode.
+
+SSL_CTX_sess_accept_good() returns the number of successfully established
+SSL/TLS sessions in server mode.
+
+SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations
+in server mode.
+
+SSL_CTX_sess_hits() returns the number of successfully reused sessions.
+In client mode a session set with L<SSL_set_session(3)>
+successfully reused is counted as a hit. In server mode a session successfully
+retrieved from internal or external cache is counted as a hit.
+
+SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions
+from the external session cache in server mode.
+
+SSL_CTX_sess_misses() returns the number of sessions proposed by clients
+that were not found in the internal session cache in server mode.
+
+SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients
+and either found in the internal or external session cache in server mode,
+ but that were invalid due to timeout. These sessions are not included in
+the SSL_CTX_sess_hits() count.
+
+SSL_CTX_sess_cache_full() returns the number of sessions that were removed
+because the maximum session cache size was exceeded.
+
+=head1 RETURN VALUES
+
+The functions return the values indicated in the DESCRIPTION section.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_set_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>
+L<SSL_CTX_sess_set_cache_size(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t);
+ long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sess_set_cache_size() sets the size of the internal session cache
+of context B<ctx> to B<t>.
+This value is a hint and not an absolute; see the notes below.
+
+SSL_CTX_sess_get_cache_size() returns the currently valid session cache size.
+
+=head1 NOTES
+
+The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT,
+currently 1024*20, so that up to 20000 sessions can be held. This size
+can be modified using the SSL_CTX_sess_set_cache_size() call. A special
+case is the size 0, which is used for unlimited size.
+
+If adding the session makes the cache exceed its size, then unused
+sessions are dropped from the end of the cache.
+Cache space may also be reclaimed by calling
+L<SSL_CTX_flush_sessions(3)> to remove
+expired sessions.
+
+If the size of the session cache is reduced and more sessions are already
+in the session cache, old session will be removed at the next time a
+session shall be added. This removal is not synchronized with the
+expiration of sessions.
+
+=head1 RETURN VALUES
+
+SSL_CTX_sess_set_cache_size() returns the previously valid size.
+
+SSL_CTX_sess_get_cache_size() returns the currently valid size.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_sess_number(3)>,
+L<SSL_CTX_flush_sessions(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
+ int (*new_session_cb)(SSL *, SSL_SESSION *));
+ void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
+ void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
+ void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
+ SSL_SESSION (*get_session_cb)(SSL *, const unsigned char *, int, int *));
+
+ int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
+ void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
+ SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, const unsigned char *data, int len, int *copy);
+
+ int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
+ void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
+ SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
+ int len, int *copy);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
+called whenever a new session was negotiated.
+
+SSL_CTX_sess_set_remove_cb() sets the callback function, which is
+automatically called whenever a session is removed by the SSL engine,
+because it is considered faulty or the session has become obsolete because
+of exceeding the timeout value.
+
+SSL_CTX_sess_set_get_cb() sets the callback function which is called,
+whenever a SSL/TLS client proposed to resume a session but the session
+could not be found in the internal session cache (see
+L<SSL_CTX_set_session_cache_mode(3)>).
+(SSL/TLS server only.)
+
+SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
+SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the
+provided callback functions. If a callback function has not been set,
+the NULL pointer is returned.
+
+=head1 NOTES
+
+In order to allow external session caching, synchronization with the internal
+session cache is realized via callback functions. Inside these callback
+functions, session can be saved to disk or put into a database using the
+L<d2i_SSL_SESSION(3)> interface.
+
+The new_session_cb() is called, whenever a new session has been negotiated
+and session caching is enabled (see
+L<SSL_CTX_set_session_cache_mode(3)>).
+The new_session_cb() is passed the B<ssl> connection and the ssl session
+B<sess>. If the callback returns B<0>, the session will be immediately
+removed again.
+
+The remove_session_cb() is called, whenever the SSL engine removes a session
+from the internal cache. This happens when the session is removed because
+it is expired or when a connection was not shutdown cleanly. It also happens
+for all sessions in the internal session cache when
+L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed
+the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
+
+The get_session_cb() is only called on SSL/TLS servers with the session id
+proposed by the client. The get_session_cb() is always called, also when
+session caching was disabled. The get_session_cb() is passed the
+B<ssl> connection, the session id of length B<length> at the memory location
+B<data>. With the parameter B<copy> the callback can require the
+SSL engine to increment the reference count of the SSL_SESSION object,
+Normally the reference count is not incremented and therefore the
+session must not be explicitly freed with
+L<SSL_SESSION_free(3)>.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<d2i_SSL_SESSION(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_flush_sessions(3)>,
+L<SSL_SESSION_free(3)>,
+L<SSL_CTX_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_sessions - access internal session cache
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_sessions() returns a pointer to the lhash databases containing the
+internal session cache for B<ctx>.
+
+=head1 NOTES
+
+The sessions in the internal session cache are kept in an
+L<lhash(3)> type database. It is possible to directly
+access this database e.g. for searching. In parallel, the sessions
+form a linked list which is maintained separately from the
+L<lhash(3)> operations, so that the database must not be
+modified directly but by using the
+L<SSL_CTX_add_session(3)> family of functions.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<lhash(3)>,
+L<SSL_CTX_add_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves,
+SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve - EC supported curve functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen);
+ int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list);
+
+ int SSL_set1_curves(SSL *ssl, int *clist, int clistlen);
+ int SSL_set1_curves_list(SSL *ssl, char *list);
+
+ int SSL_get1_curves(SSL *ssl, int *curves);
+ int SSL_get_shared_curve(SSL *s, int n);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set1_curves() sets the supported curves for B<ctx> to B<clistlen>
+curves in the array B<clist>. The array consist of all NIDs of curves in
+preference order. For a TLS client the curves are used directly in the
+supported curves extension. For a TLS server the curves are used to
+determine the set of shared curves.
+
+SSL_CTX_set1_curves_list() sets the supported curves for B<ctx> to
+string B<list>. The string is a colon separated list of curve NIDs or
+names, for example "P-521:P-384:P-256".
+
+SSL_set1_curves() and SSL_set1_curves_list() are similar except they set
+supported curves for the SSL structure B<ssl>.
+
+SSL_get1_curves() returns the set of supported curves sent by a client
+in the supported curves extension. It returns the total number of
+supported curves. The B<curves> parameter can be B<NULL> to simply
+return the number of curves for memory allocation purposes. The
+B<curves> array is in the form of a set of curve NIDs in preference
+order. It can return zero if the client did not send a supported curves
+extension.
+
+SSL_get_shared_curve() returns shared curve B<n> for a server-side
+SSL B<ssl>. If B<n> is -1 then the total number of shared curves is
+returned, which may be zero. Other than for diagnostic purposes,
+most applications will only be interested in the first shared curve
+so B<n> is normally set to zero. If the value B<n> is out of range,
+NID_undef is returned.
+
+All these functions are implemented as macros.
+
+=head1 NOTES
+
+If an application wishes to make use of several of these functions for
+configuration purposes either on a command line or in a file it should
+consider using the SSL_CONF interface instead of manually parsing options.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves() and
+SSL_set1_curves_list(), return 1 for success and 0 for failure.
+
+SSL_get1_curves() returns the number of curves, which may be zero.
+
+SSL_get_shared_curve() returns the NID of shared curve B<n> or NID_undef if there
+is no shared curve B<n>; or the total number of shared curves if B<n>
+is -1.
+
+When called on a client B<ssl>, SSL_get_shared_curve() has no meaning and
+returns -1.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_add_extra_chain_cert(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list,
+SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs,
+SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list,
+SSL_set1_client_sigalgs_list - set supported signature algorithms
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen);
+ long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen);
+ long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str);
+ long SSL_set1_sigalgs_list(SSL *ssl, const char *str);
+
+ long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen);
+ long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen);
+ long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str);
+ long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set1_sigalgs() and SSL_set1_sigalgs() set the supported signature
+algorithms for B<ctx> or B<ssl>. The array B<slist> of length B<slistlen>
+must consist of pairs of NIDs corresponding to digest and public key
+algorithms.
+
+SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported
+signature algorithms for B<ctx> or B<ssl>. The B<str> parameter
+must be a null terminated string consisting or a colon separated list of
+public key algorithms and digests separated by B<+>.
+
+SSL_CTX_set1_client_sigalgs(), SSL_set1_client_sigalgs(),
+SSL_CTX_set1_client_sigalgs_list() and SSL_set1_client_sigalgs_list() set
+signature algorithms related to client authentication, otherwise they are
+identical to SSL_CTX_set1_sigalgs(), SSL_set1_sigalgs(),
+SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list().
+
+All these functions are implemented as macros. The signature algorithm
+parameter (integer array or string) is not freed: the application should
+free it, if necessary.
+
+=head1 NOTES
+
+If an application wishes to allow the setting of signature algorithms
+as one of many user configurable options it should consider using the more
+flexible SSL_CONF API instead.
+
+The signature algorithms set by a client are used directly in the supported
+signature algorithm in the client hello message.
+
+The supported signature algorithms set by a server are not sent to the
+client but are used to determine the set of shared signature algorithms
+and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE)
+their order.
+
+The client authentication signature algorithms set by a server are sent
+in a certificate request message if client authentication is enabled,
+otherwise they are unused.
+
+Similarly client authentication signature algorithms set by a client are
+used to determined the set of client authentication shared signature
+algorithms.
+
+Signature algorithms will neither be advertised nor used if the security level
+prohibits them (for example SHA1 if the security level is 4 or more).
+
+Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and
+NID_sha512 digest NIDs are supported and the public key algorithm NIDs
+EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC.
+
+The short or long name values for digests can be used in a string (for
+example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and
+the public key algorithm strings "RSA", "DSA" or "ECDSA".
+
+The use of MD5 as a digest is strongly discouraged due to security weaknesses.
+
+=head1 EXAMPLES
+
+Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
+using an array:
+
+ const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA};
+
+ SSL_CTX_set1_sigalgs(ctx, slist, 4);
+
+Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
+using a string:
+
+ SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256");
+
+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_shared_sigalgs(3)>,
+L<SSL_CONF_CTX_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store,
+SSL_CTX_set0_chain_cert_store, SSL_CTX_set1_chain_cert_store,
+SSL_set0_verify_cert_store, SSL_set1_verify_cert_store,
+SSL_set0_chain_cert_store, SSL_set1_chain_cert_store - set certificate
+verification or chain store
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st);
+ int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st);
+ int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st);
+ int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st);
+
+ int SSL_set0_verify_cert_store(SSL *ctx, X509_STORE *st);
+ int SSL_set1_verify_cert_store(SSL *ctx, X509_STORE *st);
+ int SSL_set0_chain_cert_store(SSL *ctx, X509_STORE *st);
+ int SSL_set1_chain_cert_store(SSL *ctx, X509_STORE *st);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store()
+set the certificate store used for certificate verification to B<st>.
+
+SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store()
+set the certificate store used for certificate chain building to B<st>.
+
+SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(),
+SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar
+except they apply to SSL structure B<ssl>.
+
+All these functions are implemented as macros. Those containing a B<1>
+increment the reference count of the supplied store so it must
+be freed at some point after the operation. Those containing a B<0> do
+not increment reference counts and the supplied store B<MUST NOT> be freed
+after the operation.
+
+=head1 NOTES
+
+The stores pointers associated with an SSL_CTX structure are copied to any SSL
+structures when SSL_new() is called. As a result SSL structures will not be
+affected if the parent SSL_CTX store pointer is set to a new value.
+
+The verification store is used to verify the certificate chain sent by the
+peer: that is an SSL/TLS client will use the verification store to verify
+the server's certificate chain and a SSL/TLS server will use it to verify
+any client certificate chain.
+
+The chain store is used to build the certificate chain.
+
+If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set or a certificate chain is
+configured already (for example using the functions such as
+L<SSL_CTX_add1_chain_cert(3)> or
+L<SSL_CTX_add_extra_chain_cert(3)>) then
+automatic chain building is disabled.
+
+If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set then automatic chain building
+is disabled.
+
+If the chain or the verification store is not set then the store associated
+with the parent SSL_CTX is used instead to retain compatibility with previous
+versions of OpenSSL.
+
+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_add_extra_chain_cert(3)>
+L<SSL_CTX_set0_chain(3)>
+L<SSL_CTX_set1_chain(3)>
+L<SSL_CTX_add0_chain_cert(3)>
+L<SSL_CTX_add1_chain_cert(3)>
+L<SSL_set0_chain(3)>
+L<SSL_set1_chain(3)>
+L<SSL_add0_chain_cert(3)>
+L<SSL_add1_chain_cert(3)>
+L<SSL_CTX_build_cert_chain(3)>
+L<SSL_build_cert_chain(3)>
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.0.2.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
+SSL_select_next_proto, SSL_get0_alpn_selected - handle application layer
+protocol negotiation (ALPN)
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
+ unsigned int protos_len);
+ int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
+ unsigned int protos_len);
+ void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
+ int (*cb) (SSL *ssl,
+ const unsigned char **out,
+ unsigned char *outlen,
+ const unsigned char *in,
+ unsigned int inlen,
+ void *arg), void *arg);
+ int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
+ const unsigned char *server,
+ unsigned int server_len,
+ const unsigned char *client,
+ unsigned int client_len)
+ void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
+ unsigned int *len);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
+set the list of protocols available to be negotiated. The B<protos> must be in
+protocol-list format, described below. The length of B<protos> is specified in
+B<protos_len>.
+
+SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
+server to select which protocol to use for the incoming connection. When B<cb>
+is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
+the application callback.
+
+B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
+vector in protocol-list format. The value of the B<out>, B<outlen> vector
+should be set to the value of a single protocol selected from the B<in>,
+B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
+buffer that outlives the handshake. The B<arg> parameter is the pointer set via
+SSL_CTX_set_alpn_select_cb().
+
+SSL_select_next_proto() is a helper function used to select protocols. It
+implements the standard protocol selection. It is expected that this function
+is called from the application callback B<cb>. The protocol data in B<server>,
+B<server_len> and B<client>, B<client_len> must be in the protocol-list format
+described below. The first item in the B<server>, B<server_len> list that
+matches an item in the B<client>, B<client_len> list is selected, and returned
+in B<out>, B<outlen>. The B<out> value will point into either B<server> or
+B<client>, so it should be copied immediately. If no match is found, the first
+item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
+function can also be used in the NPN callback.
+
+SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
+with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
+is set to 0 if no protocol has been selected. B<data> must not be freed.
+
+=head1 NOTES
+
+The protocol-lists must be in wire-format, which is defined as a vector of
+non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
+included in the length. Each string is limited to 255 bytes. A byte-string
+length of 0 is invalid. A truncated byte-string is invalid. The length of the
+vector is not in the vector itself, but in a separate variable.
+
+Example:
+
+ unsigned char vector[] = {
+ 6, 's', 'p', 'd', 'y', '/', '1',
+ 8, 'h', 't', 't', 'p', '/', '1', '.', '1'
+ };
+ unsigned int length = sizeof(vector);
+
+The ALPN callback is executed after the servername callback; as that servername
+callback may update the SSL_CTX, and subsequently, the ALPN callback.
+
+If there is no ALPN proposed in the ClientHello, the ALPN callback is not
+invoked.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
+non-0 on failure. WARNING: these functions reverse the return value convention.
+
+SSL_select_next_proto() returns one of the following:
+
+=over 4
+
+=item OPENSSL_NPN_NEGOTIATED
+
+A match was found and is returned in B<out>, B<outlen>.
+
+=item OPENSSL_NPN_NO_OVERLAP
+
+No match was found. The first item in B<client>, B<client_len> is returned in
+B<out>, B<outlen>.
+
+=back
+
+The ALPN select callback B<cb>, must return one of the following:
+
+=over 4
+
+=item SSL_TLSEXT_ERR_OK
+
+ALPN protocol selected.
+
+=item SSL_TLSEXT_ERR_NOACK
+
+ALPN protocol not selected.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
+L<SSL_CTX_set_tlsext_servername_arg(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg);
+ void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg);
+
+ int (*cert_cb)(SSL *ssl, void *arg);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb() callback,
+B<arg> value is pointer which is passed to the application callback.
+
+When cert_cb() is NULL, no callback function is used.
+
+cert_cb() is the application defined callback. It is called before a
+certificate will be used by a client or server. The callback can then inspect
+the passed B<ssl> structure and set or clear any appropriate certificates. If
+the callback is successful it B<MUST> return 1 even if no certificates have
+been set. A zero is returned on error which will abort the handshake with a
+fatal internal error alert. A negative return value will suspend the handshake
+and the handshake function will return immediately.
+L<SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to
+indicate, that the handshake was suspended. The next call to the handshake
+function will again lead to the call of cert_cb(). It is the job of the
+cert_cb() to store information about the state of the last call,
+if required to continue.
+
+=head1 NOTES
+
+An application will typically call SSL_use_certificate() and
+SSL_use_PrivateKey() to set the end entity certificate and private key.
+It can add intermediate and optionally the root CA certificates using
+SSL_add1_chain_cert().
+
+It might also call SSL_certs_clear() to delete any certificates associated
+with the B<SSL> object.
+
+The certificate callback functionality supersedes the (largely broken)
+functionality provided by the old client certificate callback interface.
+It is B<always> called even is a certificate is already set so the callback
+can modify or delete the existing certificate.
+
+A more advanced callback might examine the handshake parameters and set
+whatever chain is appropriate. For example a legacy client supporting only
+TLS v1.0 might receive a certificate chain signed using SHA1 whereas a
+TLS v1.2 client which advertises support for SHA256 could receive a chain
+using SHA256.
+
+Normal server sanity checks are performed on any certificates set
+by the callback. So if an EC chain is set for a curve the client does not
+support it will B<not> be used.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_use_certificate(3)>,
+L<SSL_add1_chain_cert(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_clear(3)>, L<SSL_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate verification storage
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store);
+ X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cert_store() sets/replaces the certificate verification storage
+of B<ctx> to/with B<store>. If another X509_STORE object is currently
+set in B<ctx>, it will be X509_STORE_free()ed.
+
+SSL_CTX_get_cert_store() returns a pointer to the current certificate
+verification storage.
+
+=head1 NOTES
+
+In order to verify the certificates presented by the peer, trusted CA
+certificates must be accessed. These CA certificates are made available
+via lookup methods, handled inside the X509_STORE. From the X509_STORE
+the X509_STORE_CTX used when verifying certificates is created.
+
+Typically the trusted certificate store is handled indirectly via using
+L<SSL_CTX_load_verify_locations(3)>.
+Using the SSL_CTX_set_cert_store() and SSL_CTX_get_cert_store() functions
+it is possible to manipulate the X509_STORE object beyond the
+L<SSL_CTX_load_verify_locations(3)>
+call.
+
+Currently no detailed documentation on how to use the X509_STORE
+object is available. Not all members of the X509_STORE are used when
+the verification takes place. So will e.g. the verify_callback() be
+overridden with the verify_callback() set via the
+L<SSL_CTX_set_verify(3)> family of functions.
+This document must therefore be updated when documentation about the
+X509_STORE object and its handling becomes available.
+
+=head1 RESTRICTIONS
+
+The X509_STORE structure used by an SSL_CTX is used for verifying peer
+certificates and building certificate chains, it is also shared by
+every child SSL structure. Applications wanting finer control can use
+functions such as SSL_CTX_set1_verify_cert_store() instead.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_cert_store() does not return diagnostic output.
+
+SSL_CTX_get_cert_store() returns the current setting.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_load_verify_locations(3)>,
+L<SSL_CTX_set_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *, void *), void *arg);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cert_verify_callback() sets the verification callback function for
+I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at
+the time when L<SSL_new(3)> is called.
+
+=head1 NOTES
+
+Whenever a certificate is verified during a SSL/TLS handshake, a verification
+function is called. If the application does not explicitly specify a
+verification callback function, the built-in verification function is used.
+If a verification callback I<callback> is specified via
+SSL_CTX_set_cert_verify_callback(), the supplied callback function is called
+instead. By setting I<callback> to NULL, the default behaviour is restored.
+
+When the verification must be performed, I<callback> will be called with
+the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The
+argument I<arg> is specified by the application when setting I<callback>.
+
+I<callback> should return 1 to indicate verification success and 0 to
+indicate verification failure. If SSL_VERIFY_PEER is set and I<callback>
+returns 0, the handshake will fail. As the verification procedure may
+allow to continue the connection in case of failure (by always returning 1)
+the verification result must be set in any case using the B<error>
+member of I<x509_store_ctx> so that the calling application will be informed
+about the detailed result of the verification procedure!
+
+Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
+function set using L<SSL_CTX_set_verify(3)>.
+
+=head1 WARNINGS
+
+Do not mix the verification callback described in this function with the
+B<verify_callback> function called during the verification process. The
+latter is set using the L<SSL_CTX_set_verify(3)>
+family of functions.
+
+Providing a complete verification procedure including certificate purpose
+settings etc is a complex task. The built-in procedure is quite powerful
+and in most cases it should be sufficient to modify its behaviour using
+the B<verify_callback> function.
+
+=head1 BUGS
+
+SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_verify(3)>,
+L<SSL_get_verify_result(3)>,
+L<SSL_CTX_load_verify_locations(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
+ int SSL_set_cipher_list(SSL *ssl, const char *str);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx>
+using the control string B<str>. The format of the string is described
+in L<ciphers(1)>. The list of ciphers is inherited by all
+B<ssl> objects created from B<ctx>.
+
+SSL_set_cipher_list() sets the list of ciphers only for B<ssl>.
+
+=head1 NOTES
+
+The control string B<str> should be universally usable and not depend
+on details of the library configuration (ciphers compiled in). Thus no
+syntax checking takes place. Items that are not recognized, because the
+corresponding ciphers are not compiled in or because they are mistyped,
+are simply ignored. Failure is only flagged if no ciphers could be collected
+at all.
+
+It should be noted, that inclusion of a cipher to be used into the list is
+a necessary condition. On the client side, the inclusion into the list is
+also sufficient unless the security level excludes it. On the server side,
+additional restrictions apply. All ciphers have additional requirements.
+ADH ciphers don't need a certificate, but DH-parameters must have been set.
+All other ciphers need a corresponding certificate and key.
+
+A RSA cipher can only be chosen, when a RSA certificate is available.
+RSA ciphers using DHE need a certificate and key and additional DH-parameters
+(see L<SSL_CTX_set_tmp_dh_callback(3)>).
+
+A DSA cipher can only be chosen, when a DSA certificate is available.
+DSA ciphers always use DH key exchange and therefore need DH-parameters
+(see L<SSL_CTX_set_tmp_dh_callback(3)>).
+
+When these conditions are not met for any cipher in the list (e.g. a
+client only supports export RSA ciphers with an asymmetric key length
+of 512 bits and the server is not configured to use temporary RSA
+keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
+and the handshake will fail.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
+could be selected and 0 on complete failure.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_ciphers(3)>,
+L<SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)>,
+L<ciphers(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
+SSL_add_client_CA - set list of CAs sent to the client when requesting a
+client certificate
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
+ void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
+ int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
+ int SSL_add_client_CA(SSL *ssl, X509 *cacert);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for B<ctx>.
+
+SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for the chosen B<ssl>, overriding the
+setting valid for B<ssl>'s SSL_CTX object.
+
+SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+B<ctx>.
+
+SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
+
+=head1 NOTES
+
+When a TLS/SSL server requests a client certificate (see
+B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
+it will accept certificates, to the client.
+
+This list must explicitly be set using SSL_CTX_set_client_CA_list() for
+B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
+specified overrides the previous setting. The CAs listed do not become
+trusted (B<list> only contains the names, not the complete certificates); use
+L<SSL_CTX_load_verify_locations(3)>
+to additionally load them for verification.
+
+If the list of acceptable CAs is compiled in a file, the
+L<SSL_load_client_CA_file(3)>
+function can be used to help importing the necessary data.
+
+SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
+items the list of client CAs. If no list was specified before using
+SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
+CA list for B<ctx> or B<ssl> (as appropriate) is opened.
+
+These functions are only useful for TLS/SSL servers.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
+diagnostic information.
+
+SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
+values:
+
+=over 4
+
+=item Z<>0
+
+A failure while manipulating the STACK_OF(X509_NAME) object occurred or
+the X509_NAME could not be extracted from B<cacert>. Check the error stack
+to find out the reason.
+
+=item Z<>1
+
+The operation succeeded.
+
+=back
+
+=head1 EXAMPLES
+
+Scan all certificates in B<CAfile> and list them as acceptable CAs:
+
+ SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_load_client_CA_file(3)>,
+L<SSL_CTX_load_verify_locations(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
+ int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+ int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_client_cert_cb() sets the client_cert_cb() callback, that is
+called when a client certificate is requested by a server and no certificate
+was yet set for the SSL object.
+
+When client_cert_cb() is NULL, no callback function is used.
+
+SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback
+function.
+
+client_cert_cb() is the application defined callback. If it wants to
+set a certificate, a certificate/private key combination must be set
+using the B<x509> and B<pkey> arguments and "1" must be returned. The
+certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
+If no certificate should be set, "0" has to be returned and no certificate
+will be sent. A negative return value will suspend the handshake and the
+handshake function will return immediately. L<SSL_get_error(3)>
+will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
+suspended. The next call to the handshake function will again lead to the call
+of client_cert_cb(). It is the job of the client_cert_cb() to store information
+about the state of the last call, if required to continue.
+
+=head1 NOTES
+
+During a handshake (or renegotiation) a server may request a certificate
+from the client. A client certificate must only be sent, when the server
+did send the request.
+
+When a certificate was set using the
+L<SSL_CTX_use_certificate(3)> family of functions,
+it will be sent to the server. The TLS standard requires that only a
+certificate is sent, if it matches the list of acceptable CAs sent by the
+server. This constraint is violated by the default behavior of the OpenSSL
+library. Using the callback function it is possible to implement a proper
+selection routine or to allow a user interaction to choose the certificate to
+be sent.
+
+If a callback function is defined and no certificate was yet defined for the
+SSL object, the callback function will be called.
+If the callback function returns a certificate, the OpenSSL library
+will try to load the private key and certificate data into the SSL
+object using the SSL_use_certificate() and SSL_use_private_key() functions.
+Thus it will permanently install the certificate and key for this SSL
+object. It will not be reset by calling L<SSL_clear(3)>.
+If the callback returns no certificate, the OpenSSL library will not send
+a certificate.
+
+=head1 BUGS
+
+The client_cert_cb() cannot return a complete certificate chain, it can
+only return one client certificate. If the chain only has a length of 2,
+the root CA certificate may be omitted according to the TLS standard and
+thus a standard conforming answer can be sent to the server. For a
+longer chain, the client must send the complete chain (with the option
+to leave out the root CA certificate). This can only be accomplished by
+either adding the intermediate CA certificates into the trusted
+certificate store for the SSL_CTX object (resulting in having to add
+CA certificates that otherwise maybe would not be trusted), or by adding
+the chain certificates using the
+L<SSL_CTX_add_extra_chain_cert(3)>
+function, which is only available for the SSL_CTX object as a whole and that
+therefore probably can only apply for one client certificate, making
+the concept of the callback function (to allow the choice from several
+certificates) questionable.
+
+Once the SSL object has been used in conjunction with the callback function,
+the certificate will be set for the SSL object and will not be cleared
+even when L<SSL_clear(3)> is being called. It is therefore
+mandatory to destroy the SSL object using L<SSL_free(3)>
+and create a new one to return to the previous state.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_clear(3)>, L<SSL_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct,
+SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback,
+SSL_ct_is_enabled, SSL_CTX_ct_is_enabled -
+control Certificate Transparency policy
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_enable_ct(SSL *s, int validation_mode);
+ int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode);
+ int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback,
+ void *arg);
+ int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx,
+ ssl_ct_validation_cb callback,
+ void *arg);
+ void SSL_disable_ct(SSL *s);
+ void SSL_CTX_disable_ct(SSL_CTX *ctx);
+ int SSL_ct_is_enabled(const SSL *s);
+ int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed
+certificate timestamps (SCTs) either for a given SSL connection or for all
+connections that share the given SSL context, respectively.
+This is accomplished by setting a built-in CT validation callback.
+The behaviour of the callback is determined by the B<validation_mode> argument,
+which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or
+B<SSL_CT_VALIDATION_STRICT> as described below.
+
+If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full
+TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer
+presents no valid SCTs the handshake will be aborted.
+If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue
+despite lack of valid SCTs.
+However, in that case if the verification status before the built-in callback
+was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the
+callback.
+Applications can call L<SSL_get_verify_result(3)> to check the status at
+handshake completion, even after session resumption since the verification
+status is part of the saved session state.
+See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>.
+
+If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the
+handshake continues, and the verification status is not modified, regardless of
+the validation status of any SCTs.
+The application can still inspect the validation status of the SCTs at
+handshake completion.
+Note that with session resumption there will not be any SCTs presented during
+the handshake.
+Therefore, in applications that delay SCT policy enforcement until after
+handshake completion, such delayed SCT checks should only be performed when the
+session is not resumed.
+
+SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback()
+register a custom callback that may implement a different policy than either of
+the above.
+This callback can examine the peer's SCTs and determine whether they are
+sufficient to allow the connection to continue.
+The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE>
+and the callback returns a non-positive result.
+
+An arbitrary callback context argument, B<arg>, can be passed in when setting
+the callback.
+This will be passed to the callback whenever it is invoked.
+Ownership of this context remains with the caller.
+
+If no callback is set, SCTs will not be requested and Certificate Transparency
+validation will not occur.
+
+No callback will be invoked when the peer presents no certificate, e.g. by
+employing an anonymous (aNULL) ciphersuite.
+In that case the handshake continues as it would had no callback been
+requested.
+Callbacks are also not invoked when the peer certificate chain is invalid or
+validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509
+PKI, or no X.509 PKI at all, respectively.
+Clients that require SCTs are expected to not have enabled any aNULL ciphers
+nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA
+records.
+
+SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether
+enabled via the built-in or the custom callbacks, by setting a NULL callback.
+These may be implemented as macros.
+
+SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is
+enabled via either SSL_enable_ct() or a non-null custom callback, and 0
+otherwise.
+
+=head1 NOTES
+
+When SCT processing is enabled, OCSP stapling will be enabled. This is because
+one possible source of SCTs is the OCSP response from a server.
+
+=head1 RESTRICTIONS
+
+Certificate Transparency validation cannot be enabled and so a callback cannot
+be set if a custom client extension handler has been registered to handle SCT
+extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>).
+
+=head1 RETURN VALUES
+
+SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and
+SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully
+set.
+They return 0 if an error occurs, e.g. a custom client extension handler has
+been setup to handle SCTs.
+
+SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result.
+
+SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT
+validation callback is set, or 0 if no callback (or equivalently a NULL
+callback) is set.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+<SSL_get_verify_result(3)>,
+L<SSL_session_reused(3)>,
+L<SSL_set_verify(3)>,
+L<SSL_CTX_set_verify(3)>,
+L<ssl_ct_validation_cb(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file -
+load a Certificate Transparency log list from a file
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx);
+ int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency
+(CT) logs from the default file location, "ct_log_list.cnf", found in the
+directory where OpenSSL is installed.
+
+SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a specific path.
+See L<CTLOG_STORE_new(3)> for the file format.
+
+=head1 NOTES
+
+These functions will not clear the existing CT log list - it will be appended
+to. To replace the existing list, use L<SSL_CTX_set0_ctlog_store> first.
+
+If an error occurs whilst parsing a particular log entry in the file, that log
+entry will be skipped.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file()
+return 1 if the log list is successfully loaded, and 0 if an error occurs. In
+the case of an error, the log list may have been partially loaded.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_ct_validation_callback(3)>,
+L<CTLOG_STORE_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata,
+SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata,
+SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata,
+SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata - set or
+get passwd callback for encrypted PEM file handling
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);
+ void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);
+ pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx);
+ void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx);
+
+ void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb);
+ void SSL_set_default_passwd_cb_userdata(SSL *s, void *u);
+ pem_password_cb *SSL_get_default_passwd_cb(SSL *s);
+ void *SSL_get_default_passwd_cb_userdata(SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_default_passwd_cb() sets the default password callback called
+when loading/storing a PEM certificate with encryption.
+
+SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to userdata, B<u>,
+which will be provided to the password callback on invocation.
+
+SSL_CTX_get_default_passwd_cb() returns a function pointer to the password
+callback currently set in B<ctx>. If no callback was explicitly set, the
+NULL pointer is returned.
+
+SSL_CTX_get_default_passwd_cb_userdata() returns a pointer to the userdata
+currently set in B<ctx>. If no userdata was explicitly set, the NULL pointer
+is returned.
+
+SSL_set_default_passwd_cb(), SSL_set_default_passwd_cb_userdata(),
+SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform
+the same function as their SSL_CTX counterparts, but using an SSL object.
+
+The password callback, which must be provided by the application, hands back the
+password to be used during decryption.
+On invocation a pointer to userdata
+is provided. The function must store the password into the provided buffer
+B<buf> which is of size B<size>. The actual length of the password must
+be returned to the calling function. B<rwflag> indicates whether the
+callback is used for reading/decryption (rwflag=0) or writing/encryption
+(rwflag=1).
+For more details, see L<pem_password_cb(3)>.
+
+=head1 NOTES
+
+When loading or storing private keys, a password might be supplied to
+protect the private key. The way this password can be supplied may depend
+on the application. If only one private key is handled, it can be practical
+to have the callback handle the password dialog interactively. If several
+keys have to be handled, it can be practical to ask for the password once,
+then keep it in memory and use it several times. In the last case, the
+password could be stored into the userdata storage and the
+callback only returns the password already stored.
+
+When asking for the password interactively, the callback can use
+B<rwflag> to check, whether an item shall be encrypted (rwflag=1).
+In this case the password dialog may ask for the same password twice
+for comparison in order to catch typos, that would make decryption
+impossible.
+
+Other items in PEM formatting (certificates) can also be encrypted, it is
+however not usual, as certificate information is considered public.
+
+=head1 RETURN VALUES
+
+These functions do not provide diagnostic information.
+
+=head1 EXAMPLES
+
+The following example returns the password provided as userdata to the
+calling function. The password is considered to be a '\0' terminated
+string. If the password does not fit into the buffer, the password is
+truncated.
+
+ int my_cb(char *buf, int size, int rwflag, void *u)
+ {
+ strncpy(buf, (char *)u, size);
+ buf[size - 1] = '\0';
+ return strlen(buf);
+ }
+
+=head1 HISTORY
+
+SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(),
+SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were
+first added to OpenSSL 1.1.0
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_use_certificate(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=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 between 1 and 32 bytes. The session id is not
+security critical but must be unique for the server. Additionally, the session id is
+transmitted in the clear when reusing the session so it must not contain
+sensitive information.
+
+Without a callback being set, an OpenSSL server will generate a unique
+session id from pseudo random numbers of the maximum possible length.
+Using the callback function, the session id can be changed to contain
+additional information like e.g. a host id in order to improve load balancing
+or external caching techniques.
+
+The callback function receives a pointer to the memory location to put
+B<id> into and a pointer to the maximum allowed length B<id_len>. The
+buffer at location B<id> is only guaranteed to have the size B<id_len>.
+The callback is only allowed to generate a shorter id and reduce B<id_len>;
+the callback B<must never> increase B<id_len> or write to the location
+B<id> exceeding the given limit.
+
+The location B<id> is filled with 0x00 before the callback is called, so the
+callback may only fill part of the possible length and leave B<id_len>
+untouched while maintaining reproducibility.
+
+Since the sessions must be distinguished, session ids must be unique.
+Without the callback a random number is used, so that the probability
+of generating the same session id is extremely small (2^256 for SSLv3/TLSv1).
+In order to assure the uniqueness of the generated session id, the callback must call
+SSL_has_matching_session_id() and generate another id if a conflict occurs.
+If an id conflict is not resolved, the handshake will fail.
+If the application codes e.g. a unique host id, a unique process number, and
+a unique sequence number into the session id, uniqueness could easily be
+achieved without randomness added (it should however be taken care that
+no confidential information is leaked this way). If the application can not
+guarantee uniqueness, it is recommended to use the maximum B<id_len> and
+fill in the bytes not used to code special information with random data
+to avoid collisions.
+
+SSL_has_matching_session_id() will only query the internal session cache,
+not the external one. Since the session id is generated before the
+handshake is completed, it is not immediately added to the cache. If
+another thread is using the same internal session cache, a race condition
+can occur in that another thread generates the same session id.
+Collisions can also occur when using an external session cache, since
+the external cache is not tested with SSL_has_matching_session_id()
+and the same race condition applies.
+
+The callback must return 0 if it cannot generate a session id for whatever
+reason and return 1 on success.
+
+=head1 EXAMPLES
+
+The callback function listed will generate a session id with the
+server id given, and will fill the rest with pseudo random bytes:
+
+ const char session_id_prefix = "www-18";
+
+ #define MAX_SESSION_ID_ATTEMPTS 10
+ static int generate_session_id(const SSL *ssl, unsigned char *id,
+ unsigned int *id_len)
+ {
+ unsigned int count = 0;
+ do {
+ RAND_pseudo_bytes(id, *id_len);
+ /*
+ * Prefix the session_id with the required prefix. NB: If our
+ * prefix is too long, clip it - but there will be worse effects
+ * anyway, eg. the server could only possibly create 1 session
+ * ID (ie. the prefix!) so all future session negotiations will
+ * fail due to conflicts.
+ */
+ memcpy(id, session_id_prefix,
+ (strlen(session_id_prefix) < *id_len) ?
+ strlen(session_id_prefix) : *id_len);
+ }
+ while (SSL_has_matching_session_id(ssl, id, *id_len) &&
+ (++count < MAX_SESSION_ID_ATTEMPTS));
+ if (count >= MAX_SESSION_ID_ATTEMPTS)
+ return 0;
+ return 1;
+ }
+
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
+always return 1.
+
+SSL_has_matching_session_id() returns 1 if another session with the
+same id is already in the cache.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_version(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
+ void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
+
+ void SSL_set_info_callback(SSL *ssl, void (*callback)());
+ void (*SSL_get_info_callback(const SSL *ssl))();
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
+obtain state information for SSL objects created from B<ctx> during connection
+setup and use. The setting for B<ctx> is overridden from the setting for
+a specific SSL object, if specified.
+When B<callback> is NULL, no callback function is used.
+
+SSL_set_info_callback() sets the B<callback> function, that can be used to
+obtain state information for B<ssl> during connection setup and use.
+When B<callback> is NULL, the callback setting currently valid for
+B<ctx> is used.
+
+SSL_CTX_get_info_callback() returns a pointer to the currently set information
+callback function for B<ctx>.
+
+SSL_get_info_callback() returns a pointer to the currently set information
+callback function for B<ssl>.
+
+=head1 NOTES
+
+When setting up a connection and during use, it is possible to obtain state
+information from the SSL/TLS engine. When set, an information callback function
+is called whenever the state changes, an alert appears, or an error occurs.
+
+The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
+The B<where> argument specifies information about where (in which context)
+the callback function was called. If B<ret> is 0, an error condition occurred.
+If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
+information.
+
+B<where> is a bitmask made up of the following bits:
+
+=over 4
+
+=item SSL_CB_LOOP
+
+Callback has been called to indicate state change inside a loop.
+
+=item SSL_CB_EXIT
+
+Callback has been called to indicate error exit of a handshake function.
+(May be soft error with retry option for non-blocking setups.)
+
+=item SSL_CB_READ
+
+Callback has been called during read operation.
+
+=item SSL_CB_WRITE
+
+Callback has been called during write operation.
+
+=item SSL_CB_ALERT
+
+Callback has been called due to an alert being sent or received.
+
+=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ)
+
+=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE)
+
+=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP)
+
+=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT)
+
+=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP)
+
+=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT)
+
+=item SSL_CB_HANDSHAKE_START
+
+Callback has been called because a new handshake is started.
+
+=item SSL_CB_HANDSHAKE_DONE 0x20
+
+Callback has been called because a handshake is finished.
+
+=back
+
+The current state information can be obtained using the
+L<SSL_state_string(3)> family of functions.
+
+The B<ret> information can be evaluated using the
+L<SSL_alert_type_string(3)> family of functions.
+
+=head1 RETURN VALUES
+
+SSL_set_info_callback() does not provide diagnostic information.
+
+SSL_get_info_callback() returns the current setting.
+
+=head1 EXAMPLES
+
+The following example callback function prints state strings, information
+about alerts being handled and error messages to the B<bio_err> BIO.
+
+ void apps_ssl_info_callback(SSL *s, int where, int ret)
+ {
+ const char *str;
+ int w;
+
+ w = where & ~SSL_ST_MASK;
+
+ if (w & SSL_ST_CONNECT) str = "SSL_connect";
+ else if (w & SSL_ST_ACCEPT) str = "SSL_accept";
+ else str = "undefined";
+
+ if (where & SSL_CB_LOOP)
+ {
+ BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s));
+ }
+ else if (where & SSL_CB_ALERT)
+ {
+ str = (where & SSL_CB_READ) ? "read" : "write";
+ BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n",
+ str,
+ SSL_alert_type_string_long(ret),
+ SSL_alert_desc_string_long(ret));
+ }
+ else if (where & SSL_CB_EXIT)
+ {
+ if (ret == 0)
+ BIO_printf(bio_err, "%s:failed in %s\n",
+ str, SSL_state_string_long(s));
+ else if (ret < 0)
+ {
+ BIO_printf(bio_err, "%s:error in %s\n",
+ str, SSL_state_string_long(s));
+ }
+ }
+ }
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_state_string(3)>,
+L<SSL_alert_type_string(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list - manipulate allowed size for the peer's certificate chain
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size);
+ long SSL_CTX_get_max_cert_list(SSL_CTX *ctx);
+
+ long SSL_set_max_cert_list(SSL *ssl, long size);
+ long SSL_get_max_cert_list(SSL *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's
+certificate chain for all SSL objects created from B<ctx> to be <size> bytes.
+The SSL objects inherit the setting valid for B<ctx> at the time
+L<SSL_new(3)> is being called.
+
+SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>.
+
+SSL_set_max_cert_list() sets the maximum size allowed for the peer's
+certificate chain for B<ssl> to be <size> bytes. This setting stays valid
+until a new value is set.
+
+SSL_get_max_cert_list() returns the currently set maximum size for B<ssl>.
+
+=head1 NOTES
+
+During the handshake process, the peer may send a certificate chain.
+The TLS/SSL standard does not give any maximum size of the certificate chain.
+The OpenSSL library handles incoming data by a dynamically allocated buffer.
+In order to prevent this buffer from growing without bounds due to data
+received from a faulty or malicious peer, a maximum size for the certificate
+chain is set.
+
+The default value for the maximum certificate chain size is 100kB (30kB
+on the 16bit DOS platform). This should be sufficient for usual certificate
+chains (OpenSSL's default maximum chain length is 10, see
+L<SSL_CTX_set_verify(3)>, and certificates
+without special extensions have a typical size of 1-2kB).
+
+For special applications it can be necessary to extend the maximum certificate
+chain size allowed to be sent by the peer, see e.g. the work on
+"Internet X.509 Public Key Infrastructure Proxy Certificate Profile"
+and "TLS Delegation Protocol" at http://www.ietf.org/ and
+http://www.globus.org/ .
+
+Under normal conditions it should never be necessary to set a value smaller
+than the default, as the buffer is handled dynamically and only uses the
+memory actually required by the data sent by the peer.
+
+If the maximum certificate chain size allowed is exceeded, the handshake will
+fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously
+set value.
+
+SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently
+set value.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_new(3)>,
+L<SSL_CTX_set_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version,
+SSL_set_min_proto_version, SSL_set_max_proto_version - Set minimum
+and maximum supported protocol version
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version);
+ int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version);
+ int SSL_set_min_proto_version(SSL *ssl, int version);
+ int SSL_set_max_proto_version(SSL *ssl, int version);
+
+=head1 DESCRIPTION
+
+The functions set the minimum and maximum supported protocol versions
+for the B<ctx> or B<ssl>.
+This works in combination with the options set via
+L<SSL_CTX_set_options(3)> that also make it possible to disable
+specific protocol versions.
+Use these functions instead of disabling specific protocol versions.
+
+Setting the minimum or maximum version to 0, will enable protocol
+versions down to the lowest version, or up to the highest version
+supported by the library, respectively.
+
+Currently supported versions are B<SSL3_VERSION>, B<TLS1_VERSION>,
+B<TLS1_1_VERSION>, B<TLS1_2_VERSION> for TLS and B<DTLS1_VERSION>,
+B<DTLS1_2_VERSION> for DTLS.
+
+=head1 RETURN VALUES
+
+These functions return 1 on success and 0 on failure.
+
+=head1 NOTES
+
+All these functions are implemented using macros.
+
+=head1 HISTORY
+
+The functions were added in OpenSSL 1.1.0
+
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
+ long SSL_set_mode(SSL *ssl, long mode);
+
+ long SSL_CTX_get_mode(SSL_CTX *ctx);
+ long SSL_get_mode(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
+Options already set before are not cleared.
+
+SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
+Options already set before are not cleared.
+
+SSL_CTX_get_mode() returns the mode set for B<ctx>.
+
+SSL_get_mode() returns the mode set for B<ssl>.
+
+=head1 NOTES
+
+The following mode changes are available:
+
+=over 4
+
+=item SSL_MODE_ENABLE_PARTIAL_WRITE
+
+Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
+when just a single record has been written). When not set (the default),
+SSL_write() will only report success once the complete chunk was written.
+Once SSL_write() returns with r, r bytes have been successfully written
+and the next call to SSL_write() must only send the n-r bytes left,
+imitating the behaviour of write().
+
+=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
+
+Make it possible to retry SSL_write() with changed buffer location
+(the buffer contents must stay the same). This is not the default to avoid
+the misconception that non-blocking SSL_write() behaves like
+non-blocking write().
+
+=item SSL_MODE_AUTO_RETRY
+
+Never bother the application with retries if the transport is blocking.
+If a renegotiation take place during normal operation, a
+L<SSL_read(3)> or L<SSL_write(3)> would return
+with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.
+In a non-blocking environment applications must be prepared to handle
+incomplete read/write operations.
+In a blocking environment, applications are not always prepared to
+deal with read/write operations returning without success report. The
+flag SSL_MODE_AUTO_RETRY will cause read/write operations to only
+return after the handshake and successful completion.
+
+=item SSL_MODE_RELEASE_BUFFERS
+
+When we no longer need a read buffer or a write buffer for a given SSL,
+then release the memory we were using to hold it.
+Using this flag can
+save around 34k per idle SSL connection.
+This flag has no effect on SSL v2 connections, or on DTLS connections.
+
+=item SSL_MODE_SEND_FALLBACK_SCSV
+
+Send TLS_FALLBACK_SCSV in the ClientHello.
+To be set only by applications that reconnect with a downgraded protocol
+version; see draft-ietf-tls-downgrade-scsv-00 for details.
+
+DO NOT ENABLE THIS if your application attempts a normal handshake.
+Only use this in explicit fallback retries, following the guidance
+in draft-ietf-tls-downgrade-scsv-00.
+
+=item SSL_MODE_ASYNC
+
+Enable asynchronous processing. TLS I/O operations may indicate a retry with
+SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is
+used to perform cryptographic operations. See L<SSL_get_error(3)>.
+
+=back
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
+after adding B<mode>.
+
+SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)>
+
+=head1 HISTORY
+
+SSL_MODE_ASYNC was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_set_msg_callback_arg - install callback for observing protocol messages
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+ void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
+
+ void SSL_set_msg_callback(SSL *ssl, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+ void SSL_set_msg_callback_arg(SSL *ssl, void *arg);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to
+define a message callback function I<cb> for observing all SSL/TLS
+protocol messages (such as handshake messages) that are received or
+sent. SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
+can be used to set argument I<arg> to the callback function, which is
+available for arbitrary application use.
+
+SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
+default settings that will be copied to new B<SSL> objects by
+L<SSL_new(3)>. SSL_set_msg_callback() and
+SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
+object. Using a B<0> pointer for I<cb> disables the message callback.
+
+When I<cb> is called by the SSL/TLS library for a protocol message,
+the function arguments have the following meaning:
+
+=over 4
+
+=item I<write_p>
+
+This flag is B<0> when a protocol message has been received and B<1>
+when a protocol message has been sent.
+
+=item I<version>
+
+The protocol version according to which the protocol message is
+interpreted by the library. Currently, this is one of
+B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL
+3.0 and TLS 1.0, respectively).
+
+=item I<content_type>
+
+In the case of SSL 2.0, this is always B<0>. In the case of SSL 3.0
+or TLS 1.0, this is one of the B<ContentType> values defined in the
+protocol specification (B<change_cipher_spec(20)>, B<alert(21)>,
+B<handshake(22)>; but never B<application_data(23)> because the
+callback will only be called for protocol messages).
+
+=item I<buf>, I<len>
+
+I<buf> points to a buffer containing the protocol message, which
+consists of I<len> bytes. The buffer is no longer valid after the
+callback function has returned.
+
+=item I<ssl>
+
+The B<SSL> object that received or sent the message.
+
+=item I<arg>
+
+The user-defined argument optionally defined by
+SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg().
+
+=back
+
+=head1 NOTES
+
+Protocol messages are passed to the callback function after decryption
+and fragment collection where applicable. (Thus record boundaries are
+not visible.)
+
+If processing a received protocol message results in an error,
+the callback function may not be called. For example, the callback
+function will never see messages that are considered too large to be
+processed.
+
+Due to automatic protocol version negotiation, I<version> is not
+necessarily the protocol version used by the sender of the message: If
+a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
+I<version> will be B<SSL3_VERSION>.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options,
+SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
+SSL_get_secure_renegotiation_support - manipulate SSL options
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_options(SSL_CTX *ctx, long options);
+ long SSL_set_options(SSL *ssl, long options);
+
+ long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
+ long SSL_clear_options(SSL *ssl, long options);
+
+ long SSL_CTX_get_options(SSL_CTX *ctx);
+ long SSL_get_options(SSL *ssl);
+
+ long SSL_get_secure_renegotiation_support(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
+Options already set before are not cleared!
+
+SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
+Options already set before are not cleared!
+
+SSL_CTX_clear_options() clears the options set via bitmask in B<options>
+to B<ctx>.
+
+SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.
+
+SSL_CTX_get_options() returns the options set for B<ctx>.
+
+SSL_get_options() returns the options set for B<ssl>.
+
+SSL_get_secure_renegotiation_support() indicates whether the peer supports
+secure renegotiation.
+Note, this is implemented via a macro.
+
+=head1 NOTES
+
+The behaviour of the SSL library can be changed by setting several options.
+The options are coded as bitmasks and can be combined by a bitwise B<or>
+operation (|).
+
+SSL_CTX_set_options() and SSL_set_options() affect the (external)
+protocol behaviour of the SSL library. The (internal) behaviour of
+the API can be changed by using the similar
+L<SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
+
+During a handshake, the option settings of the SSL object are used. When
+a new SSL object is created from a context using SSL_new(), the current
+option setting is copied. Changes to B<ctx> do not affect already created
+SSL objects. SSL_clear() does not affect the settings.
+
+The following B<bug workaround> options are available:
+
+=over 4
+
+=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
+
+...
+
+=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
+
+...
+
+=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG
+
+Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
+OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
+
+=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG
+
+...
+
+=item SSL_OP_TLS_D5_BUG
+
+...
+
+=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
+
+Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
+vulnerability affecting CBC ciphers, which cannot be handled by some
+broken SSL implementations. This option has no effect for connections
+using other ciphers.
+
+=item SSL_OP_TLSEXT_PADDING
+
+Adds a padding extension to ensure the ClientHello size is never between
+256 and 511 bytes in length. This is needed as a workaround for some
+implementations.
+
+=item SSL_OP_ALL
+
+All of the above bug workarounds.
+
+=back
+
+It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround
+options if compatibility with somewhat broken implementations is
+desired.
+
+The following B<modifying> options are available:
+
+=over 4
+
+=item SSL_OP_TLS_ROLLBACK_BUG
+
+Disable version rollback attack detection.
+
+During the client key exchange, the client must send the same information
+about acceptable SSL/TLS protocol levels as during the first hello. Some
+clients violate this rule by adapting to the server's answer. (Example:
+the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
+only understands up to SSLv3. In this case the client must still use the
+same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
+to the server's answer and violate the version rollback protection.)
+
+=item SSL_OP_SINGLE_DH_USE
+
+Always create a new key when using temporary/ephemeral DH parameters
+(see L<SSL_CTX_set_tmp_dh_callback(3)>).
+This option must be used to prevent small subgroup attacks, when
+the DH parameters were not generated using "strong" primes
+(e.g. when using DSA-parameters, see L<dhparam(1)>).
+If "strong" primes were used, it is not strictly necessary to generate
+a new DH key during each handshake but it is also recommended.
+B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever
+temporary/ephemeral DH parameters are used.
+
+=item SSL_OP_EPHEMERAL_RSA
+
+This option is no longer implemented and is treated as no op.
+
+=item SSL_OP_CIPHER_SERVER_PREFERENCE
+
+When choosing a cipher, use the server's preferences instead of the client
+preferences. When not set, the SSL server will always follow the clients
+preferences. When set, the SSL/TLS server will choose following its
+own preferences.
+
+=item SSL_OP_PKCS1_CHECK_1
+
+...
+
+=item SSL_OP_PKCS1_CHECK_2
+
+...
+
+
+=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1,
+SSL_OP_NO_TLSv1_2, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
+
+These options turn off the SSLv3, TLSv1, TLSv1.1 or TLSv1.2 protocol
+versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
+respectively.
+As of OpenSSL 1.1.0, these options are deprecated, use
+L<SSL_CTX_set_min_proto_version(3)> and
+L<SSL_CTX_set_max_proto_version(3)> instead.
+
+=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
+
+When performing renegotiation as a server, always start a new session
+(i.e., session resumption requests are only accepted in the initial
+handshake). This option is not needed for clients.
+
+=item SSL_OP_NO_TICKET
+
+Normally clients and servers will, where possible, transparently make use
+of RFC4507bis tickets for stateless session resumption.
+
+If this option is set this functionality is disabled and tickets will
+not be used by clients or servers.
+
+=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
+
+Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
+servers. See the B<SECURE RENEGOTIATION> section for more details.
+
+=item SSL_OP_LEGACY_SERVER_CONNECT
+
+Allow legacy insecure renegotiation between OpenSSL and unpatched servers
+B<only>: this option is currently set by default. See the
+B<SECURE RENEGOTIATION> section for more details.
+
+=item SSL_OP_NO_ENCRYPT_THEN_MAC
+
+Normally clients and servers will transparently attempt to negotiate the
+RFC7366 Encrypt-then-MAC option on TLS and DTLS connection.
+
+If this option is set, Encrypt-then-MAC is disabled. Clients will not
+propose, and servers will not accept the extension.
+
+=back
+
+=head1 SECURE RENEGOTIATION
+
+OpenSSL always attempts to use secure renegotiation as
+described in RFC5746. This counters the prefix attack described in
+CVE-2009-3555 and elsewhere.
+
+This attack has far reaching consequences which application writers should be
+aware of. In the description below an implementation supporting secure
+renegotiation is referred to as I<patched>. A server not supporting secure
+renegotiation is referred to as I<unpatched>.
+
+The following sections describe the operations permitted by OpenSSL's secure
+renegotiation implementation.
+
+=head2 Patched client and server
+
+Connections and renegotiation are always permitted by OpenSSL implementations.
+
+=head2 Unpatched client and patched OpenSSL server
+
+The initial connection succeeds but client renegotiation is denied by the
+server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal
+B<handshake_failure> alert in SSL v3.0.
+
+If the patched OpenSSL server attempts to renegotiate a fatal
+B<handshake_failure> alert is sent. This is because the server code may be
+unaware of the unpatched nature of the client.
+
+If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
+renegotiation B<always> succeeds.
+
+=head2 Patched OpenSSL client and unpatched server.
+
+If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
+and renegotiation between patched OpenSSL clients and unpatched servers
+succeeds. If neither option is set then initial connections to unpatched
+servers will fail.
+
+The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even
+though it has security implications: otherwise it would be impossible to
+connect to unpatched servers (i.e. all of them initially) and this is clearly
+not acceptable. Renegotiation is permitted because this does not add any
+additional security issues: during an attack clients do not see any
+renegotiations anyway.
+
+As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
+B<not> be set by default in a future version of OpenSSL.
+
+OpenSSL client applications wishing to ensure they can connect to unpatched
+servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
+
+OpenSSL client applications that want to ensure they can B<not> connect to
+unpatched servers (and thus avoid any security issues) should always B<clear>
+B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or
+SSL_clear_options().
+
+The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that
+B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure
+renegotiation between OpenSSL clients and unpatched servers B<only>, while
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections
+and renegotiation between OpenSSL and unpatched clients or servers.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
+after adding B<options>.
+
+SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
+after clearing B<options>.
+
+SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
+
+SSL_get_secure_renegotiation_support() returns 1 is the peer supports
+secure renegotiation and 0 if it does not.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)>,
+L<SSL_CTX_set_min_proto_version(3)>,
+L<dhparam(1)>
+
+=head1 HISTORY
+
+The attempt to always try to use secure renegotiation was added in
+Openssl 0.9.8m.
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx,
+ unsigned int (*callback)(SSL *ssl, const char *hint,
+ char *identity, unsigned int max_identity_len,
+ unsigned char *psk, unsigned int max_psk_len));
+ void SSL_set_psk_client_callback(SSL *ssl,
+ unsigned int (*callback)(SSL *ssl, const char *hint,
+ char *identity, unsigned int max_identity_len,
+ unsigned char *psk, unsigned int max_psk_len));
+
+
+=head1 DESCRIPTION
+
+A client application must provide a callback function which is called
+when the client is sending the ClientKeyExchange message to the server.
+
+The purpose of the callback function is to select the PSK identity and
+the pre-shared key to use during the connection setup phase.
+
+The callback is set using functions SSL_CTX_set_psk_client_callback()
+or SSL_set_psk_client_callback(). The callback function is given the
+connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint
+sent by the server in parameter B<hint>, a buffer B<identity> of
+length B<max_identity_len> bytes where the resulting
+B<NULL>-terminated identity is to be stored, and a buffer B<psk> of
+length B<max_psk_len> bytes where the resulting pre-shared key is to
+be stored.
+
+=head1 NOTES
+
+Note that parameter B<hint> given to the callback may be B<NULL>.
+
+=head1 RETURN VALUES
+
+Return values from the client callback are interpreted as follows:
+
+On success (callback found a PSK identity and a pre-shared key to use)
+the length (> 0) of B<psk> in bytes is returned.
+
+Otherwise or on errors callback should return 0. In this case
+the connection setup fails.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+Copyright 2005 Nokia.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, SSL_get_quiet_shutdown - manipulate shutdown behaviour
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode);
+ int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);
+
+ void SSL_set_quiet_shutdown(SSL *ssl, int mode);
+ int SSL_get_quiet_shutdown(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ctx> to be
+B<mode>. SSL objects created from B<ctx> inherit the B<mode> valid at the time
+L<SSL_new(3)> is called. B<mode> may be 0 or 1.
+
+SSL_CTX_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ctx>.
+
+SSL_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ssl> to be
+B<mode>. The setting stays valid until B<ssl> is removed with
+L<SSL_free(3)> or SSL_set_quiet_shutdown() is called again.
+It is not changed when L<SSL_clear(3)> is called.
+B<mode> may be 0 or 1.
+
+SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>.
+
+=head1 NOTES
+
+Normally when a SSL connection is finished, the parties must send out
+"close notify" alert messages using L<SSL_shutdown(3)>
+for a clean shutdown.
+
+When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)>
+will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.
+(L<SSL_shutdown(3)> then behaves like
+L<SSL_set_shutdown(3)> called with
+SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.)
+The session is thus considered to be shutdown, but no "close notify" alert
+is sent to the peer. This behaviour violates the TLS standard.
+
+The default is normal shutdown behaviour as described by the TLS standard.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_quiet_shutdown() and SSL_set_quiet_shutdown() do not return
+diagnostic information.
+
+SSL_CTX_get_quiet_shutdown() and SSL_get_quiet_shutdown return the current
+setting.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_shutdown(3)>,
+L<SSL_set_shutdown(3)>, L<SSL_new(3)>,
+L<SSL_clear(3)>, L<SSL_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead,
+SSL_set_read_ahead, SSL_get_read_ahead,
+SSL_CTX_get_default_read_ahead
+- manage whether to read as many input bytes as possible
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_read_ahead(SSL *s, int yes);
+ int SSL_get_read_ahead(const SSL *s);
+
+ SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes);
+ long SSL_CTX_get_read_ahead(SSL_CTX *ctx);
+ long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as
+many input bytes as possible (for non-blocking reads) or not. For example if
+B<x> bytes are currently required by OpenSSL, but B<y> bytes are available from
+the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes
+into its buffer (providing that the buffer is large enough) if reading ahead is
+on, or B<x> bytes otherwise. The parameter B<yes> or B<m> should be 0 to ensure
+reading ahead is off, or non zero otherwise.
+SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead().
+
+SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading
+ahead has been set or not.
+
+=head1 NOTES
+
+These functions have no impact when used with DTLS. The return values for
+SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting
+B<read_ahead> can impact the behaviour of the SSL_pending() function
+(see L<SSL_pending(3)>).
+
+=head1 RETURN VALUES
+
+SSL_get_read_ahead() and SSL_CTX_get_read_ahead() return 0 if reading ahead is off,
+and non zero otherwise.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_pending(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_security_level(SSL_CTX *ctx, int level);
+ void SSL_set_security_level(SSL *s, int level);
+
+ int SSL_CTX_get_security_level(const SSL_CTX *ctx);
+ int SSL_get_security_level(const SSL *s);
+
+ void SSL_CTX_set_security_callback(SSL_CTX *ctx,
+ int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid,
+ void *other, void *ex));
+
+ void SSL_set_security_callback(SSL *s,
+ int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid,
+ void *other, void *ex));
+
+ int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex);
+ int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex);
+
+ void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex);
+ void SSL_set0_security_ex_data(SSL *s, void *ex);
+
+ void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx);
+ void *SSL_get0_security_ex_data(const SSL *s);
+
+=head1 DESCRIPTION
+
+The functions SSL_CTX_set_security_level() and SSL_set_security_level() set
+the security level to B<level>. If not set the library default security level
+is used.
+
+The functions SSL_CTX_get_security_level() and SSL_get_security_level()
+retrieve the current security level.
+
+SSL_CTX_set_security_callback(), SSL_set_security_callback(),
+SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set
+the security callback associated with B<ctx> or B<s>. If not set a default
+security callback is used. The meaning of the parameters and the behaviour
+of the default callbacks is described below.
+
+SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(),
+SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the
+extra data pointer passed to the B<ex> parameter of the callback. This
+value is passed to the callback verbatim and can be set to any convenient
+application specific value.
+
+=head1 DEFAULT CALLBACK BEHAVIOUR
+
+If an application doesn't set its own security callback the default
+callback is used. It is intended to provide sane defaults. The meaning
+of each level is described below.
+
+=over 4
+
+=item B<Level 0>
+
+Everything is permitted. This retains compatibility with previous versions of
+OpenSSL.
+
+=item B<Level 1>
+
+The security level corresponds to a minimum of 80 bits of security. Any
+parameters offering below 80 bits of security are excluded. As a result RSA,
+DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits
+are prohibited. All export ciphersuites are prohibited since they all offer
+less than 80 bits of security. SSL version 2 is prohibited. Any ciphersuite
+using MD5 for the MAC is also prohibited.
+
+=item B<Level 2>
+
+Security level set to 112 bits of security. As a result RSA, DSA and DH keys
+shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited.
+In addition to the level 1 exclusions any ciphersuite using RC4 is also
+prohibited. SSL version 3 is also not allowed. Compression is disabled.
+
+=item B<Level 3>
+
+Security level set to 128 bits of security. As a result RSA, DSA and DH keys
+shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited.
+In addition to the level 2 exclusions ciphersuites not offering forward
+secrecy are prohibited. TLS versions below 1.1 are not permitted. Session
+tickets are disabled.
+
+=item B<Level 4>
+
+Security level set to 192 bits of security. As a result RSA, DSA and DH keys
+shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited.
+Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are
+not permitted.
+
+=item B<Level 5>
+
+Security level set to 256 bits of security. As a result RSA, DSA and DH keys
+shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited.
+
+=back
+
+=head1 APPLICATION DEFINED SECURITY CALLBACKS
+
+I<Documentation to be provided.>
+
+=head1 NOTES
+
+B<WARNING> at this time setting the security level higher than 1 for
+general internet use is likely to cause B<considerable> interoperability
+issues and is not recommended. This is because the B<SHA1> algorithm
+is very widely used in certificates and will be rejected at levels
+higher than 1 because it only offers 80 bits of security.
+
+The default security level can be configured when OpenSSL is compiled by
+setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used.
+
+The security framework disables or reject parameters inconsistent with the
+set security level. In the past this was difficult as applications had to set
+a number of distinct parameters (supported ciphers, supported curves supported
+signature algorithms) to achieve this end and some cases (DH parameter size
+for example) could not be checked at all.
+
+By setting an appropriate security level much of this complexity can be
+avoided.
+
+The bits of security limits affect all relevant parameters including
+ciphersuite encryption algorithms, supported ECC curves, supported
+signature algorithms, DH parameter sizes, certificate key sizes and
+signature algorithms. This limit applies no matter what other custom
+settings an application has set: so if the ciphersuite is set to B<ALL>
+then only ciphersuites consistent with the security level are permissible.
+
+See SP800-57 for how the security limits are related to individual
+algorithms.
+
+Some security levels require large key sizes for non-ECC public key
+algorithms which can severely degrade performance. For example 256 bits
+of security requires the use of RSA keys of at least 15360 bits in size.
+
+Some restrictions can be gracefully handled: for example ciphersuites
+offering insufficient security are not sent by the client and will not
+be selected by the server. Other restrictions such as the peer certificate
+key size or the DH parameter size will abort the handshake with a fatal
+alert.
+
+Attempts to set certificates or parameters with insufficient security are
+also blocked. For example trying to set a certificate using a 512 bit RSA
+key using SSL_CTX_use_certificate() at level 1. Applications which do not
+check the return values for errors will misbehave: for example it might
+appear that a certificate is not set at all because it had been rejected.
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
+ long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_session_cache_mode() enables/disables session caching
+by setting the operational mode for B<ctx> to <mode>.
+
+SSL_CTX_get_session_cache_mode() returns the currently used cache mode.
+
+=head1 NOTES
+
+The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
+The sessions can be held in memory for each B<ctx>, if more than one
+SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
+object.
+
+In order to reuse a session, a client must send the session's id to the
+server. It can only send exactly one id. The server then either
+agrees to reuse the session or it starts a full handshake (to create a new
+session).
+
+A server will 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
+L<SSL_CTX_set_session_id_context(3)>).
+
+The following session cache modes and modifiers are available:
+
+=over 4
+
+=item SSL_SESS_CACHE_OFF
+
+No session caching for client or server takes place.
+
+=item SSL_SESS_CACHE_CLIENT
+
+Client sessions are added to the session cache. As there is no reliable way
+for the OpenSSL library to know whether a session should be reused or which
+session to choose (due to the abstract BIO layer the SSL engine does not
+have details about the connection), the application must select the session
+to be reused by using the L<SSL_set_session(3)>
+function. This option is not activated by default.
+
+=item SSL_SESS_CACHE_SERVER
+
+Server sessions are added to the session cache. When a client proposes a
+session to be reused, the server looks for the corresponding session in (first)
+the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set),
+then (second) in the external cache if available. If the session is found, the
+server will try to reuse the session. This is the default.
+
+=item SSL_SESS_CACHE_BOTH
+
+Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
+
+=item SSL_SESS_CACHE_NO_AUTO_CLEAR
+
+Normally the session cache is checked for expired sessions every
+255 connections using the
+L<SSL_CTX_flush_sessions(3)> function. Since
+this may lead to a delay which cannot be controlled, the automatic
+flushing may be disabled and
+L<SSL_CTX_flush_sessions(3)> can be called
+explicitly by the application.
+
+=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
+
+By setting this flag, session-resume operations in an SSL/TLS server will not
+automatically look up sessions in the internal cache, even if sessions are
+automatically stored there. If external session caching callbacks are in use,
+this flag guarantees that all lookups are directed to the external cache.
+As automatic lookup only applies for SSL/TLS servers, the flag has no effect on
+clients.
+
+=item SSL_SESS_CACHE_NO_INTERNAL_STORE
+
+Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER,
+sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
+Normally a new session is added to the internal cache as well as any external
+session caching (callback) that is configured for the SSL_CTX. This flag will
+prevent sessions being stored in the internal cache (though the application can
+add them manually using L<SSL_CTX_add_session(3)>). Note:
+in any SSL/TLS servers where external caching is configured, any successful
+session lookups in the external cache (ie. for session-resume requests) would
+normally be copied into the local cache before processing continues - this flag
+prevents these additions to the internal cache as well.
+
+=item SSL_SESS_CACHE_NO_INTERNAL
+
+Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and
+SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time.
+
+
+=back
+
+The default mode is SSL_SESS_CACHE_SERVER.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_session_cache_mode() returns the previously set cache mode.
+
+SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
+
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_set_session(3)>,
+L<SSL_session_reused(3)>,
+L<SSL_CTX_add_session(3)>,
+L<SSL_CTX_sess_number(3)>,
+L<SSL_CTX_sess_set_cache_size(3)>,
+L<SSL_CTX_sess_set_get_cb(3)>,
+L<SSL_CTX_set_session_id_context(3)>,
+L<SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_flush_sessions(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only)
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx,
+ unsigned int sid_ctx_len);
+ int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
+ unsigned int sid_ctx_len);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length
+B<sid_ctx_len> within which a session can be reused for the B<ctx> object.
+
+SSL_set_session_id_context() sets the context B<sid_ctx> of length
+B<sid_ctx_len> within which a session can be reused for the B<ssl> object.
+
+=head1 NOTES
+
+Sessions are generated within a certain context. When exporting/importing
+sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible,
+to re-import a session generated from another context (e.g. another
+application), which might lead to malfunctions. Therefore each application
+must set its own session id context B<sid_ctx> which is used to distinguish
+the contexts and is stored in exported sessions. The B<sid_ctx> can be
+any kind of binary data with a given length, it is therefore possible
+to use e.g. the name of the application and/or the hostname and/or service
+name ...
+
+The session id context becomes part of the session. The session id context
+is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and
+SSL_set_session_id_context() functions are therefore only useful on the
+server side.
+
+OpenSSL clients will check the session id context returned by the server
+when reusing a session.
+
+The maximum length of the B<sid_ctx> is limited to
+B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
+
+=head1 WARNINGS
+
+If the session id context is not set on an SSL/TLS server and client
+certificates are used, stored sessions
+will not be reused but a fatal error will be flagged and the handshake
+will fail.
+
+If a server returns a different session id context to an OpenSSL client
+when reusing a session, an error will be flagged and the handshake will
+fail. OpenSSL servers will always return the correct session id context,
+as an OpenSSL server checks the session id context itself before reusing
+a session as described above.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_session_id_context() and SSL_set_session_id_context()
+return the following values:
+
+=over 4
+
+=item Z<>0
+
+The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded
+the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error
+is logged to the error stack.
+
+=item Z<>1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
+SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
+SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
+SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control
+fragment sizes and pipelining operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
+ long SSL_set_max_send_fragment(SSL *ssl, long m);
+
+ long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
+ long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
+
+ long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
+ long SSL_set_split_send_fragment(SSL *ssl, long m);
+
+ void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
+ void SSL_set_default_read_buffer_len(SSL *s, size_t len);
+
+=head1 DESCRIPTION
+
+Some engines are able to process multiple simultaneous crypto operations. This
+capability could be utilised to parallelise the processing of a single
+connection. For example a single write can be split into multiple records and
+each one encrypted independently and in parallel. Note: this will only work in
+TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
+capability is known as "pipelining" within OpenSSL.
+
+In order to benefit from the pipelining capability. You need to have an engine
+that provides ciphers that support this. The OpenSSL "dasync" engine provides
+AES128-SHA based ciphers that have this capability. However these are for
+development and test purposes only.
+
+SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
+B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
+value restricts the amount of plaintext bytes that will be sent in any one
+SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
+functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.
+
+SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
+of pipelines that will be used at any one time. This value applies to both
+"read" pipelining and "write" pipelining. By default only one pipeline will be
+used (i.e. normal non-parallel operation). The number of pipelines set must be
+in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
+automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
+explained further below. OpenSSL will only every use more than one pipeline if
+a ciphersuite is negotiated that uses a pipeline capable cipher provided by an
+engine.
+
+Pipelining operates slightly differently for reading encrypted data compared to
+writing encrypted data. SSL_CTX_set_split_send_fragment() and
+SSL_set_split_send_fragment() define how data is split up into pipelines when
+writing encrypted data. The number of pipelines used will be determined by the
+amount of data provided to the SSL_write() call divided by
+B<split_send_fragment>.
+
+For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
+then:
+
+SSL_write called with 0-2000 bytes == 1 pipeline used
+
+SSL_write called with 2001-4000 bytes == 2 pipelines used
+
+SSL_write called with 4001-6000 bytes == 3 pipelines used
+
+SSL_write called with 6001+ bytes == 4 pipelines used
+
+B<split_send_fragment> must always be less than or equal to
+B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
+This will mean that the same number of records will always be created as would
+have been created in the non-parallel case, although the data will be
+apportioned differently. In the parallel case data will be spread equally
+between the pipelines.
+
+Read pipelining is controlled in a slightly different way than with write
+pipelining. While reading we are constrained by the number of records that the
+peer (and the network) can provide to us in one go. The more records we can get
+in one go the more opportunity we have to parallelise the processing. As noted
+above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
+is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
+read as much data into the read buffer as the network can provide and will fit
+into the buffer. Without this set data is read into the read buffer one record
+at a time. The more data that can be read, the more opportunity there is for
+parallelising the processing at the cost of increased memory overhead per
+connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
+function (see L<SSL_pending(3)>).
+
+The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
+functions control the size of the read buffer that will be used. The B<len>
+parameter sets the size of the buffer. The value will only be used if it is
+greater than the default that would have been used anyway. The normal default
+value depends on a number of factors but it will be at least
+SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
+
+=head1 RETURN VALUES
+
+All non-void functions return 1 on success and 0 on failure.
+
+=head1 NOTES
+
+With the exception of SSL_CTX_set_default_read_buffer_len() and
+SSL_set_default_read_buffer_len() all these functions are implemented using
+macros.
+
+=head1 HISTORY
+
+The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
+SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
+SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
+functions were added in OpenSSL 1.1.0.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method
+- choose a new TLS/SSL method
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *method);
+ int SSL_set_ssl_method(SSL *s, const SSL_METHOD *method);
+ const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects
+newly created from this B<ctx>. SSL objects already created with
+L<SSL_new(3)> are not affected, except when
+L<SSL_clear(3)> is being called.
+
+SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl>
+object. It may be reset, when SSL_clear() is called.
+
+SSL_get_ssl_method() returns a function pointer to the TLS/SSL method
+set in B<ssl>.
+
+=head1 NOTES
+
+The available B<method> choices are described in
+L<SSL_CTX_new(3)>.
+
+When L<SSL_clear(3)> is called and no session is connected to
+an SSL object, the method of the SSL object is reset to the method currently
+set in the corresponding SSL_CTX object.
+
+=head1 RETURN VALUES
+
+The following return values can occur for SSL_CTX_set_ssl_version()
+and SSL_set_ssl_method():
+
+=over 4
+
+=item Z<>0
+
+The new choice failed, check the error stack to find out the reason.
+
+=item Z<>1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_CTX_new(3)>, L<SSL_new(3)>,
+L<SSL_clear(3)>, L<ssl(3)>,
+L<SSL_set_connect_state(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_timeout(SSL_CTX *ctx, long t);
+ long SSL_CTX_get_timeout(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_timeout() sets the timeout for newly created sessions for
+B<ctx> to B<t>. The timeout value B<t> must be given in seconds.
+
+SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>.
+
+=head1 NOTES
+
+Whenever a new session is created, it is assigned a maximum lifetime. This
+lifetime is specified by storing the creation time of the session and the
+timeout value valid at this time. If the actual time is later than creation
+time plus timeout, the session is not reused.
+
+Due to this realization, all sessions behave according to the timeout value
+valid at the time of the session negotiation. Changes of the timeout value
+do not affect already established sessions.
+
+The expiration time of a single session can be modified using the
+L<SSL_SESSION_get_time(3)> family of functions.
+
+Expired sessions are removed from the internal session cache, whenever
+L<SSL_CTX_flush_sessions(3)> is called, either
+directly by the application or automatically (see
+L<SSL_CTX_set_session_cache_mode(3)>)
+
+The default value for session timeout is decided on a per protocol
+basis, see L<SSL_get_default_timeout(3)>.
+All currently supported protocols have the same default timeout value
+of 300 seconds.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_timeout() returns the previously set timeout value.
+
+SSL_CTX_get_timeout() returns the currently set timeout value.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_SESSION_get_time(3)>,
+L<SSL_CTX_flush_sessions(3)>,
+L<SSL_get_default_timeout(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tlsext_status_cb,
+SSL_CTX_get_tlsext_status_cb,
+SSL_CTX_set_tlsext_status_arg,
+SSL_CTX_get_tlsext_status_arg,
+SSL_CTX_set_tlsext_status_type,
+SSL_CTX_get_tlsext_status_type,
+SSL_set_tlsext_status_type,
+SSL_get_tlsext_status_type,
+SSL_get_tlsext_status_ocsp_resp,
+SSL_set_tlsext_status_ocsp_resp
+- OCSP Certificate Status Request functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/tls1.h>
+
+ long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx,
+ int (*callback)(SSL *, void *));
+ long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx,
+ int (**callback)(SSL *, void *));
+
+ long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
+ long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg);
+
+ long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type);
+ long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx);
+
+ long SSL_set_tlsext_status_type(SSL *s, int type);
+ long SSL_get_tlsext_status_type(SSL *s);
+
+ long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
+ long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
+
+=head1 DESCRIPTION
+
+A client application may request that a server send back an OCSP status response
+(also known as OCSP stapling). To do so the client should call the
+SSL_CTX_set_tlsext_status_type() function prior to the creation of any SSL
+objects. Alternatively an application can call the SSL_set_tlsext_status_type()
+function on an individual SSL object prior to the start of the handshake.
+Currently the only supported type is B<TLSEXT_STATUSTYPE_ocsp>. This value
+should be passed in the B<type> argument. Calling
+SSL_CTX_get_tlsext_status_type() will return the type B<TLSEXT_STATUSTYPE_ocsp>
+previously set via SSL_CTX_set_tlsext_status_type() or -1 if not set.
+
+The client should additionally provide a callback function to decide what to do
+with the returned OCSP response by calling SSL_CTX_set_tlsext_status_cb(). The
+callback function should determine whether the returned OCSP response is
+acceptable or not. The callback will be passed as an argument the value
+previously set via a call to SSL_CTX_set_tlsext_status_arg(). Note that the
+callback will not be called in the event of a handshake where session resumption
+occurs (because there are no Certificates exchanged in such a handshake).
+The callback previously set via SSL_CTX_set_tlsext_status_cb() can be retrieved
+by calling SSL_CTX_get_tlsext_status_cb(), and the argument by calling
+SSL_CTX_get_tlsext_status_arg().
+
+On the client side SSL_get_tlsext_status_type() can be used to determine whether
+the client has previously called SSL_set_tlsext_status_type(). It will return
+B<TLSEXT_STATUSTYPE_ocsp> if it has been called or -1 otherwise. On the server
+side SSL_get_tlsext_status_type() can be used to determine whether the client
+requested OCSP stapling. If the client requested it then this function will
+return B<TLSEXT_STATUSTYPE_ocsp>, or -1 otherwise.
+
+The response returned by the server can be obtained via a call to
+SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to point
+to the OCSP response data and the return value will be the length of that data.
+Typically a callback would obtain an OCSP_RESPONSE object from this data via a
+call to the d2i_OCSP_RESPONSE() function. If the server has not provided any
+response data then B<*resp> will be NULL and the return value from
+SSL_get_tlsext_status_ocsp_resp() will be -1.
+
+A server application must also call the SSL_CTX_set_tlsext_status_cb() function
+if it wants to be able to provide clients with OCSP Certificate Status
+responses. Typically the server callback would obtain the server certificate
+that is being sent back to the client via a call to SSL_get_certificate();
+obtain the OCSP response to be sent back; and then set that response data by
+calling SSL_set_tlsext_status_ocsp_resp(). A pointer to the response data should
+be provided in the B<resp> argument, and the length of that data should be in
+the B<len> argument.
+
+=head1 RETURN VALUES
+
+The callback when used on the client side should return a negative value on
+error; 0 if the response is not acceptable (in which case the handshake will
+fail) or a positive value if it is acceptable.
+
+The callback when used on the server side should return with either
+SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be
+returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be
+returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has
+occurred).
+
+SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(),
+SSL_CTX_set_tlsext_status_type(), SSL_set_tlsext_status_type() and
+SSL_set_tlsext_status_ocsp_resp() return 0 on error or 1 on success.
+
+SSL_CTX_get_tlsext_status_type() returns the value previously set by
+SSL_CTX_set_tlsext_status_type(), or -1 if not set.
+
+SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data
+or -1 if there is no OCSP response data.
+
+SSL_get_tlsext_status_type() returns B<TLSEXT_STATUSTYPE_ocsp> on the client
+side if SSL_set_tlsext_status_type() was previously called, or on the server
+side if the client requested OCSP stapling. Otherwise -1 is returned.
+
+=head1 HISTORY
+
+SSL_get_tlsext_status_type(), SSL_CTX_get_tlsext_status_type() and
+SSL_CTX_set_tlsext_status_type() were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing
+
+=head1 SYNOPSIS
+
+ #include <openssl/tls1.h>
+
+ long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
+ int (*cb)(SSL *s, unsigned char key_name[16],
+ unsigned char iv[EVP_MAX_IV_LENGTH],
+ EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_tlsext_ticket_key_cb() sets a callback function I<cb> for handling
+session tickets for the ssl context I<sslctx>. Session tickets, defined in
+RFC5077 provide an enhanced session resumption capability where the server
+implementation is not required to maintain per session state. It only applies
+to TLS and there is no SSLv3 implementation.
+
+The callback function I<cb> will be called for every client instigated TLS
+session when session ticket extension is presented in the TLS hello
+message. It is the responsibility of this function to create or retrieve the
+cryptographic parameters and to maintain their state.
+
+The OpenSSL library uses your callback function to help implement a common TLS
+ticket construction state according to RFC5077 Section 4 such that per session
+state is unnecessary and a small set of cryptographic variables needs to be
+maintained by the callback function implementation.
+
+In order to reuse a session, a TLS client must send the a session ticket
+extension to the server. The client can only send exactly one session ticket.
+The server, through the callback function, either agrees to reuse the session
+ticket information or it starts a full TLS handshake to create a new session
+ticket.
+
+Before the callback function is started I<ctx> and I<hctx> have been
+initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively.
+
+For new sessions tickets, when the client doesn't present a session ticket, or
+an attempted retrieval of the ticket failed, or a renew option was indicated,
+the callback function will be called with I<enc> equal to 1. The OpenSSL
+library expects that the function will set an arbitrary I<name>, initialize
+I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>.
+
+The I<name> is 16 characters long and is used as a key identifier.
+
+The I<iv> length is the length of the IV of the corresponding cipher. The
+maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
+
+The initialization vector I<iv> should be a random value. The cipher context
+I<ctx> should use the initialisation vector I<iv>. The cipher context can be
+set using L<EVP_EncryptInit_ex(3)>. The hmac context can be set using
+L<HMAC_Init_ex(3)>.
+
+When the client presents a session ticket, the callback function with be called
+with I<enc> set to 0 indicating that the I<cb> function should retrieve a set
+of parameters. In this case I<name> and I<iv> have already been parsed out of
+the session ticket. The OpenSSL library expects that the I<name> will be used
+to retrieve a cryptographic parameters and that the cryptographic context
+I<ctx> will be set with the retrieved parameters and the initialization vector
+I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The I<hctx> needs to be
+set using L<HMAC_Init_ex(3)>.
+
+If the I<name> is still valid but a renewal of the ticket is required the
+callback function should return 2. The library will call the callback again
+with an argument of enc equal to 1 to set the new ticket.
+
+The return value of the I<cb> function is used by OpenSSL to determine what
+further processing will occur. The following return values have meaning:
+
+=over 4
+
+=item Z<>2
+
+This indicates that the I<ctx> and I<hctx> have been set and the session can
+continue on those parameters. Additionally it indicates that the session
+ticket is in a renewal period and should be replaced. The OpenSSL library will
+call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077
+3.3 paragraph 2).
+
+=item Z<>1
+
+This indicates that the I<ctx> and I<hctx> have been set and the session can
+continue on those parameters.
+
+=item Z<>0
+
+This indicates that it was not possible to set/retrieve a session ticket and
+the SSL/TLS session will continue by negotiating a set of cryptographic
+parameters or using the alternate SSL/TLS resumption mechanism, session ids.
+
+If called with enc equal to 0 the library will call the I<cb> again to get
+a new set of parameters.
+
+=item less than 0
+
+This indicates an error.
+
+=back
+
+=head1 NOTES
+
+Session resumption shortcuts the TLS so that the client certificate
+negotiation don't occur. It makes up for this by storing client certificate
+an all other negotiated state information encrypted within the ticket. In a
+resumed session the applications will have all this state information available
+exactly as if a full negotiation had occurred.
+
+If an attacker can obtain the key used to encrypt a session ticket, they can
+obtain the master secret for any ticket using that key and decrypt any traffic
+using that session: even if the ciphersuite supports forward secrecy. As
+a result applications may wish to use multiple keys and avoid using long term
+keys stored in files.
+
+Applications can use longer keys to maintain a consistent level of security.
+For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key
+the overall security is only 128 bits because breaking the ticket key will
+enable an attacker to obtain the session keys.
+
+=head1 EXAMPLES
+
+Reference Implementation:
+ SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
+ ....
+
+ static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
+ {
+ if (enc) { /* create new session */
+ if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) {
+ return -1; /* insufficient random */
+ }
+
+ key = currentkey(); /* something that you need to implement */
+ if ( !key ) {
+ /* current key doesn't exist or isn't valid */
+ key = createkey(); /* something that you need to implement.
+ * createkey needs to initialise, a name,
+ * an aes_key, a hmac_key and optionally
+ * an expire time. */
+ if ( !key ) { /* key couldn't be created */
+ return 0;
+ }
+ }
+ memcpy(key_name, key->name, 16);
+
+ EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
+ HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
+
+ return 1;
+
+ } else { /* retrieve session */
+ key = findkey(name);
+
+ if (!key || key->expire < now() ) {
+ return 0;
+ }
+
+ HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
+ EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv );
+
+ if (key->expire < ( now() - RENEW_TIME ) ) {
+ /* return 2 - this session will get a new ticket even though the current is still valid */
+ return 2;
+ }
+ return 1;
+
+ }
+ }
+
+
+
+=head1 RETURN VALUES
+
+returns 0 to indicate the callback function was set.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_set_session(3)>,
+L<SSL_session_reused(3)>,
+L<SSL_CTX_add_session(3)>,
+L<SSL_CTX_sess_number(3)>,
+L<SSL_CTX_sess_set_get_cb(3)>,
+L<SSL_CTX_set_session_id_context(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
+ DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
+
+ void SSL_set_tmp_dh_callback(SSL *ctx,
+ DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_set_tmp_dh(SSL *ssl, DH *dh)
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be
+used when a DH parameters are required to B<tmp_dh_callback>.
+The callback is inherited by all B<ssl> objects created from B<ctx>.
+
+SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>.
+The key is inherited by all B<ssl> objects created from B<ctx>.
+
+SSL_set_tmp_dh_callback() sets the callback only for B<ssl>.
+
+SSL_set_tmp_dh() sets the parameters only for B<ssl>.
+
+These functions apply to SSL/TLS servers only.
+
+=head1 NOTES
+
+When using a cipher with RSA authentication, an ephemeral DH key exchange
+can take place. Ciphers with DSA keys always use ephemeral DH keys as well.
+In these cases, the session data are negotiated using the
+ephemeral/temporary DH key and the key supplied and certified
+by the certificate chain is only used for signing.
+Anonymous ciphers (without a permanent server key) also use ephemeral DH keys.
+
+Using ephemeral DH key exchange yields forward secrecy, as the connection
+can only be decrypted, when the DH key is known. By generating a temporary
+DH key inside the server application that is lost when the application
+is left, it becomes impossible for an attacker to decrypt past sessions,
+even if he gets hold of the normal (certified) key, as this key was
+only used for signing.
+
+In order to perform a DH key exchange the server must use a DH group
+(DH parameters) and generate a DH key. The server will always generate
+a new DH key during the negotiation.
+
+As generating DH parameters is extremely time consuming, an application
+should not generate the parameters on the fly but supply the parameters.
+DH parameters can be reused, as the actual key is newly generated during
+the negotiation. The risk in reusing DH parameters is that an attacker
+may specialize on a very often used DH group. Applications should therefore
+generate their own DH parameters during the installation process using the
+openssl L<dhparam(1)> application. This application
+guarantees that "strong" primes are used.
+
+Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current
+version of the OpenSSL distribution contain the 'SKIP' DH parameters,
+which use safe primes and were generated verifiably pseudo-randomly.
+These files can be converted into C code using the B<-C> option of the
+L<dhparam(1)> application. Generation of custom DH
+parameters during installation should still be preferred to stop an
+attacker from specializing on a commonly used group. File dh1024.pem
+contains old parameters that must not be used by applications.
+
+An application may either directly specify the DH parameters or
+can supply the DH parameters via a callback function.
+
+Previous versions of the callback used B<is_export> and B<keylength>
+parameters to control parameter generation for export and non-export
+cipher suites. Modern servers that do not support export ciphersuites
+are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use
+the callback but ignore B<keylength> and B<is_export> and simply
+supply at least 2048-bit parameters in the callback.
+
+=head1 EXAMPLES
+
+Setup DH parameters with a key length of 2048 bits. (Error handling
+partly left out.)
+
+ Command-line parameter generation:
+ $ openssl dhparam -out dh_param_2048.pem 2048
+
+ Code for setting up parameters during server initialization:
+
+ ...
+ SSL_CTX ctx = SSL_CTX_new();
+ ...
+
+ /* Set up ephemeral DH parameters. */
+ DH *dh_2048 = NULL;
+ FILE *paramfile;
+ paramfile = fopen("dh_param_2048.pem", "r");
+ if (paramfile) {
+ dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
+ fclose(paramfile);
+ } else {
+ /* Error. */
+ }
+ if (dh_2048 == NULL) {
+ /* Error. */
+ }
+ if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
+ /* Error. */
+ }
+ ...
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
+diagnostic output.
+
+SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
+on failure. Check the error queue to find out the reason of failure.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_options(3)>,
+L<ciphers(1)>, L<dhparam(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
+ int (*verify_callback)(int, X509_STORE_CTX *));
+ void SSL_set_verify(SSL *s, int mode,
+ int (*verify_callback)(int, X509_STORE_CTX *));
+ void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth);
+ void SSL_set_verify_depth(SSL *s, int depth);
+
+ int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
+specifies the B<verify_callback> function to be used. If no callback function
+shall be specified, the NULL pointer can be used for B<verify_callback>.
+
+SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
+specifies the B<verify_callback> function to be used. If no callback function
+shall be specified, the NULL pointer can be used for B<verify_callback>. In
+this case last B<verify_callback> set specifically for this B<ssl> remains. If
+no special B<callback> was set before, the default callback for the underlying
+B<ctx> is used, that was valid at the time B<ssl> was created with
+L<SSL_new(3)>.
+
+SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
+verification that shall be allowed for B<ctx>. (See the BUGS section.)
+
+SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
+verification that shall be allowed for B<ssl>. (See the BUGS section.)
+
+=head1 NOTES
+
+The verification of certificates can be controlled by a set of logically
+or'ed B<mode> flags:
+
+=over 4
+
+=item SSL_VERIFY_NONE
+
+B<Server mode:> the server will not send a client certificate request to the
+client, so the client will not send a certificate.
+
+B<Client mode:> if not using an anonymous cipher (by default disabled), the
+server will send a certificate which will be checked. The result of the
+certificate verification process can be checked after the TLS/SSL handshake
+using the L<SSL_get_verify_result(3)> function.
+The handshake will be continued regardless of the verification result.
+
+=item SSL_VERIFY_PEER
+
+B<Server mode:> the server sends a client certificate request to the client.
+The certificate returned (if any) is checked. If the verification process
+fails, the TLS/SSL handshake is
+immediately terminated with an alert message containing the reason for
+the verification failure.
+The behaviour can be controlled by the additional
+SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags.
+
+B<Client mode:> the server certificate is verified. If the verification process
+fails, the TLS/SSL handshake is
+immediately terminated with an alert message containing the reason for
+the verification failure. If no server certificate is sent, because an
+anonymous cipher is used, SSL_VERIFY_PEER is ignored.
+
+=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT
+
+B<Server mode:> if the client did not return a certificate, the TLS/SSL
+handshake is immediately terminated with a "handshake failure" alert.
+This flag must be used together with SSL_VERIFY_PEER.
+
+B<Client mode:> ignored
+
+=item SSL_VERIFY_CLIENT_ONCE
+
+B<Server mode:> only request a client certificate on the initial TLS/SSL
+handshake. Do not ask for a client certificate again in case of a
+renegotiation. This flag must be used together with SSL_VERIFY_PEER.
+
+B<Client mode:> ignored
+
+=back
+
+If the B<mode> is SSL_VERIFY_NONE none of the other flags may be set.
+
+The actual verification procedure is performed either using the built-in
+verification procedure or using another application provided verification
+function set with
+L<SSL_CTX_set_cert_verify_callback(3)>.
+The following descriptions apply in the case of the built-in procedure. An
+application provided procedure also has access to the verify depth information
+and the verify_callback() function, but the way this information is used
+may be different.
+
+SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up
+to which depth certificates in a chain are used during the verification
+procedure. If the certificate chain is longer than allowed, the certificates
+above the limit are ignored. Error messages are generated as if these
+certificates would not be present, most likely a
+X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
+The depth count is "level 0:peer certificate", "level 1: CA certificate",
+"level 2: higher level CA certificate", and so on. Setting the maximum
+depth to 2 allows the levels 0, 1, and 2. The default depth limit is 100,
+allowing for the peer certificate and additional 100 CA certificates.
+
+The B<verify_callback> function is used to control the behaviour when the
+SSL_VERIFY_PEER flag is set. It must be supplied by the application and
+receives two arguments: B<preverify_ok> indicates, whether the verification of
+the certificate in question was passed (preverify_ok=1) or not
+(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used
+for the certificate chain verification.
+
+The certificate chain is checked starting with the deepest nesting level
+(the root CA certificate) and worked upward to the peer's certificate.
+At each level signatures and issuer attributes are checked. Whenever
+a verification error is found, the error number is stored in B<x509_ctx>
+and B<verify_callback> is called with B<preverify_ok>=0. By applying
+X509_CTX_store_* functions B<verify_callback> can locate the certificate
+in question and perform additional steps (see EXAMPLES). If no error is
+found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
+before advancing to the next level.
+
+The return value of B<verify_callback> controls the strategy of the further
+verification process. If B<verify_callback> returns 0, the verification
+process is immediately stopped with "verification failed" state. If
+SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
+the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
+the verification process is continued. If B<verify_callback> always returns
+1, the TLS/SSL handshake will not be terminated with respect to verification
+failures and the connection will be established. The calling process can
+however retrieve the error code of the last verification error using
+L<SSL_get_verify_result(3)> or by maintaining its
+own error storage managed by B<verify_callback>.
+
+If no B<verify_callback> is specified, the default callback will be used.
+Its return value is identical to B<preverify_ok>, so that any verification
+failure will lead to a termination of the TLS/SSL handshake with an
+alert message, if SSL_VERIFY_PEER is set.
+
+=head1 RETURN VALUES
+
+The SSL*_set_verify*() functions do not provide diagnostic information.
+
+=head1 EXAMPLES
+
+The following code sequence realizes an example B<verify_callback> function
+that will always continue the TLS/SSL handshake regardless of verification
+failure, if wished. The callback realizes a verification depth limit with
+more informational output.
+
+All verification errors are printed; information about the certificate chain
+is printed on request.
+The example is realized for a server that does allow but not require client
+certificates.
+
+The example makes use of the ex_data technique to store application data
+into/retrieve application data from the SSL structure
+(see L<SSL_get_ex_new_index(3)>,
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
+
+ ...
+ typedef struct {
+ int verbose_mode;
+ int verify_depth;
+ int always_continue;
+ } mydata_t;
+ int mydata_index;
+ ...
+ static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
+ {
+ char buf[256];
+ X509 *err_cert;
+ int err, depth;
+ SSL *ssl;
+ mydata_t *mydata;
+
+ err_cert = X509_STORE_CTX_get_current_cert(ctx);
+ err = X509_STORE_CTX_get_error(ctx);
+ depth = X509_STORE_CTX_get_error_depth(ctx);
+
+ /*
+ * Retrieve the pointer to the SSL of the connection currently treated
+ * and the application specific data stored into the SSL object.
+ */
+ ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
+ mydata = SSL_get_ex_data(ssl, mydata_index);
+
+ X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
+
+ /*
+ * Catch a too long certificate chain. The depth limit set using
+ * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
+ * that whenever the "depth>verify_depth" condition is met, we
+ * have violated the limit and want to log this error condition.
+ * We must do it here, because the CHAIN_TOO_LONG error would not
+ * be found explicitly; only errors introduced by cutting off the
+ * additional certificates would be logged.
+ */
+ if (depth > mydata->verify_depth) {
+ preverify_ok = 0;
+ err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
+ X509_STORE_CTX_set_error(ctx, err);
+ }
+ if (!preverify_ok) {
+ printf("verify error:num=%d:%s:depth=%d:%s\n", err,
+ X509_verify_cert_error_string(err), depth, buf);
+ }
+ else if (mydata->verbose_mode)
+ {
+ printf("depth=%d:%s\n", depth, buf);
+ }
+
+ /*
+ * At this point, err contains the last verification error. We can use
+ * it for something special
+ */
+ if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT))
+ {
+ X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256);
+ printf("issuer= %s\n", buf);
+ }
+
+ if (mydata->always_continue)
+ return 1;
+ else
+ return preverify_ok;
+ }
+ ...
+
+ mydata_t mydata;
+
+ ...
+ mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
+
+ ...
+ SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
+ verify_callback);
+
+ /*
+ * Let the verify_callback catch the verify_depth error so that we get
+ * an appropriate error in the logfile.
+ */
+ SSL_CTX_set_verify_depth(verify_depth + 1);
+
+ /*
+ * Set up the SSL specific data into "mydata" and store it into th SSL
+ * structure.
+ */
+ mydata.verify_depth = verify_depth; ...
+ SSL_set_ex_data(ssl, mydata_index, &mydata);
+
+ ...
+ SSL_accept(ssl); /* check of success left out for clarity */
+ if (peer = SSL_get_peer_certificate(ssl))
+ {
+ if (SSL_get_verify_result(ssl) == X509_V_OK)
+ {
+ /* The client sent a certificate which verified OK */
+ }
+ }
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_new(3)>,
+L<SSL_CTX_get_verify_mode(3)>,
+L<SSL_get_verify_result(3)>,
+L<SSL_CTX_load_verify_locations(3)>,
+L<SSL_get_peer_certificate(3)>,
+L<SSL_CTX_set_cert_verify_callback(3)>,
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
+L<SSL_get_ex_new_index(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1,
+SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1,
+SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file,
+SSL_use_certificate_chain_file,
+SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1,
+SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey,
+SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file,
+SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey,
+SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1,
+SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key
+- load certificate and key data
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
+ int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
+ int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
+ int SSL_use_certificate(SSL *ssl, X509 *x);
+ int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
+ int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
+
+ int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
+ int SSL_use_certificate_chain_file(SSL *ssl, const char *file);
+
+ int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
+ int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
+ long len);
+ int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
+ int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
+ int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
+ int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
+ int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
+ int SSL_use_PrivateKey_ASN1(int pk, SSL *ssl, unsigned char *d, long len);
+ int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
+ int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
+ int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
+ int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
+
+ int SSL_CTX_check_private_key(const SSL_CTX *ctx);
+ int SSL_check_private_key(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+These functions load the certificates and private keys into the SSL_CTX
+or SSL object, respectively.
+
+The SSL_CTX_* class of functions loads the certificates and keys into the
+SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl>
+created from B<ctx> with L<SSL_new(3)> by copying, so that
+changes applied to B<ctx> do not propagate to already existing SSL objects.
+
+The SSL_* class of functions only loads certificates and keys into a
+specific SSL object. The specific information is kept, when
+L<SSL_clear(3)> is called for this SSL object.
+
+SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>,
+SSL_use_certificate() loads B<x> into B<ssl>. The rest of the
+certificates needed to form the complete certificate chain can be
+specified using the
+L<SSL_CTX_add_extra_chain_cert(3)>
+function.
+
+SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from
+the memory location B<d> (with length B<len>) into B<ctx>,
+SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>.
+
+SSL_CTX_use_certificate_file() loads the first certificate stored in B<file>
+into B<ctx>. The formatting B<type> of the certificate must be specified
+from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
+SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>.
+See the NOTES section on why SSL_CTX_use_certificate_chain_file()
+should be preferred.
+
+SSL_CTX_use_certificate_chain_file() loads a certificate chain from
+B<file> into B<ctx>. The certificates must be in PEM format and must
+be sorted starting with the subject's certificate (actual client or server
+certificate), followed by intermediate CA certificates if applicable, and
+ending at the highest level (root) CA. SSL_use_certificate_chain_file() is
+similar except it loads the certificate chain into B<ssl>.
+
+SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.
+SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA
+to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;
+SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.
+If a certificate has already been set and the private does not belong
+to the certificate an error is returned. To change a certificate, private
+key pair the new certificate needs to be set with SSL_use_certificate()
+or SSL_CTX_use_certificate() before setting the private key with
+SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey().
+
+
+SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>
+stored at memory location B<d> (length B<len>) to B<ctx>.
+SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA
+stored at memory location B<d> (length B<len>) to B<ctx>.
+SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private
+key to B<ssl>.
+
+SSL_CTX_use_PrivateKey_file() adds the first private key found in
+B<file> to B<ctx>. The formatting B<type> of the certificate must be specified
+from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
+SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in
+B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found
+in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private
+RSA key found to B<ssl>.
+
+SSL_CTX_check_private_key() checks the consistency of a private key with
+the corresponding certificate loaded into B<ctx>. If more than one
+key/certificate pair (RSA/DSA) is installed, the last item installed will
+be checked. If e.g. the last item was a RSA certificate or key, the RSA
+key/certificate pair will be checked. SSL_check_private_key() performs
+the same check for B<ssl>. If no key/certificate was explicitly added for
+this B<ssl>, the last item added into B<ctx> will be checked.
+
+=head1 NOTES
+
+The internal certificate store of OpenSSL can hold several private
+key/certificate pairs at a time. The certificate used depends on the
+cipher selected, see also L<SSL_CTX_set_cipher_list(3)>.
+
+When reading certificates and private keys from file, files of type
+SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain
+one certificate or private key, consequently
+SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting.
+Files of type SSL_FILETYPE_PEM can contain more than one item.
+
+SSL_CTX_use_certificate_chain_file() adds the first certificate found
+in the file to the certificate store. The other certificates are added
+to the store of chain certificates using L<SSL_CTX_add1_chain_cert(3)>. Note: versions of OpenSSL before 1.0.2 only had a single
+certificate chain store for all certificate types, OpenSSL 1.0.2 and later
+have a separate chain store for each type. SSL_CTX_use_certificate_chain_file()
+should be used instead of the SSL_CTX_use_certificate_file() function in order
+to allow the use of complete certificate chains even when no trusted CA
+storage is used or when the CA issuing the certificate shall not be added to
+the trusted CA storage.
+
+If additional certificates are needed to complete the chain during the
+TLS negotiation, CA certificates are additionally looked up in the
+locations of trusted CA certificates, see
+L<SSL_CTX_load_verify_locations(3)>.
+
+The private keys loaded from file can be encrypted. In order to successfully
+load encrypted keys, a function returning the passphrase must have been
+supplied, see
+L<SSL_CTX_set_default_passwd_cb(3)>.
+(Certificate files might be encrypted as well from the technical point
+of view, it however does not make sense as the data in the certificate
+is considered public anyway.)
+
+=head1 RETURN VALUES
+
+On success, the functions return 1.
+Otherwise check out the error stack to find out the reason.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>,
+L<SSL_CTX_load_verify_locations(3)>,
+L<SSL_CTX_set_default_passwd_cb(3)>,
+L<SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_client_cert_cb(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint,
+SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK
+identity hint to use
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
+ int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
+
+ void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx,
+ unsigned int (*callback)(SSL *ssl, const char *identity,
+ unsigned char *psk, int max_psk_len));
+ void SSL_set_psk_server_callback(SSL *ssl,
+ unsigned int (*callback)(SSL *ssl, const char *identity,
+ unsigned char *psk, int max_psk_len));
+
+
+=head1 DESCRIPTION
+
+SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK
+identity hint B<hint> to SSL context object
+B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated
+PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint>
+is B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
+
+In the case where PSK identity hint is B<NULL>, the server
+does not send the ServerKeyExchange message to the client.
+
+A server application must provide a callback function which is called
+when the server receives the ClientKeyExchange message from the
+client. The purpose of the callback function is to validate the
+received PSK identity and to fetch the pre-shared key used during the
+connection setup phase. The callback is set using functions
+SSL_CTX_set_psk_server_callback() or
+SSL_set_psk_server_callback(). The callback function is given the
+connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent
+by the client in parameter B<identity>, and a buffer B<psk> of length
+B<max_psk_len> bytes where the pre-shared key is to be stored.
+
+
+=head1 RETURN VALUES
+
+SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return
+1 on success, 0 otherwise.
+
+Return values from the server callback are interpreted as follows:
+
+=over 4
+
+=item Z<>0
+
+PSK identity was not found. An "unknown_psk_identity" alert message
+will be sent and the connection setup fails.
+
+=item E<gt>0
+
+PSK identity was found and the server callback has provided the PSK
+successfully in parameter B<psk>. Return value is the length of
+B<psk> in bytes. It is an error to return a value greater than
+B<max_psk_len>.
+
+If the PSK identity was not found but the callback instructs the
+protocol to continue anyway, the callback must provide some random
+data to B<psk> and return the length of the random data, so the
+connection will fail with decryption_error before it will be finished
+completely.
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+Copyright 2005 Nokia.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo,
+ size_t serverinfo_length);
+
+ int SSL_CTX_use_serverinfo_file(SSL_CTX *ctx, const char *file);
+
+=head1 DESCRIPTION
+
+These functions load "serverinfo" TLS ServerHello Extensions into the SSL_CTX.
+A "serverinfo" extension is returned in response to an empty ClientHello
+Extension.
+
+SSL_CTX_use_serverinfo() loads one or more serverinfo extensions from
+a byte array into B<ctx>. The extensions must be concatenated into a
+sequence of bytes. Each extension must consist of a 2-byte Extension Type,
+a 2-byte length, and then length bytes of extension_data.
+
+SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from
+B<file> into B<ctx>. The extensions must be in PEM format. Each extension
+must consist of a 2-byte Extension Type, a 2-byte length, and then length
+bytes of extension_data. Each PEM extension name must begin with the phrase
+"BEGIN SERVERINFO FOR ".
+
+If more than one certificate (RSA/DSA) is installed using
+SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the
+last certificate installed. If e.g. the last item was a RSA certificate, the
+loaded serverinfo extension data will be loaded for that certificate. To
+use the serverinfo extension for multiple certificates,
+SSL_CTX_use_serverinfo() needs to be called multiple times, once B<after>
+each time a certificate is loaded.
+
+=head1 RETURN VALUES
+
+On success, the functions return 1.
+On failure, the functions return 0. Check out the error stack to find out
+the reason.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_free - free an allocated SSL_SESSION structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_SESSION_free(SSL_SESSION *session);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_free() decrements the reference count of B<session> and removes
+the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated
+memory, if the reference count has reached 0.
+If B<session> is NULL nothing is done.
+
+=head1 NOTES
+
+SSL_SESSION objects are allocated, when a TLS/SSL handshake operation
+is successfully completed. Depending on the settings, see
+L<SSL_CTX_set_session_cache_mode(3)>,
+the SSL_SESSION objects are internally referenced by the SSL_CTX and
+linked into its session cache. SSL objects may be using the SSL_SESSION object;
+as a session may be reused, several SSL objects may be using one SSL_SESSION
+object at the same time. It is therefore crucial to keep the reference
+count (usage information) correct and not delete a SSL_SESSION object
+that is still used, as this may lead to program failures due to
+dangling pointers. These failures may also appear delayed, e.g.
+when an SSL_SESSION object was completely freed as the reference count
+incorrectly became 0, but it is still referenced in the internal
+session cache and the cache list is processed during a
+L<SSL_CTX_flush_sessions(3)> operation.
+
+SSL_SESSION_free() must only be called for SSL_SESSION objects, for
+which the reference count was explicitly incremented (e.g.
+by calling SSL_get1_session(), see L<SSL_get_session(3)>)
+or when the SSL_SESSION object was generated outside a TLS handshake
+operation, e.g. by using L<d2i_SSL_SESSION(3)>.
+It must not be called on other SSL_SESSION objects, as this would cause
+incorrect reference counts and therefore program failures.
+
+=head1 RETURN VALUES
+
+SSL_SESSION_free() does not provide diagnostic information.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_flush_sessions(3)>,
+L<d2i_SSL_SESSION(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get0_cipher - retrieve the SSL cipher associated with a session
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSSION *s);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_get0_cipher() retrieves the cipher that was used by the
+connection when the session was created, or NULL if it cannot be determined.
+
+The value returned is a pointer to an object maintained within B<s> and
+should not be released.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<d2i_SSL_SESSION(3)>,
+L<SSL_SESSION_get_time(3)>,
+L<SSL_SESSION_get0_hostname(3)>,
+L<SSL_SESSION_free(3)>
+
+=head1 HISTORY
+
+SSL_SESSION_get0_cipher() was first added to OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get0_hostname - retrieve the SNI hostname associated with a session
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_SESSION_get0_hostname(const SSL_SESSSION *s);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the
+client when the session was created, or NULL if no value was sent.
+
+The value returned is a pointer to memory maintained within B<s> and
+should not be free'd.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<d2i_SSL_SESSION(3)>,
+L<SSL_SESSION_get_time(3)>,
+L<SSL_SESSION_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get0_id_context - get the SSL ID context associated with a session
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s,
+ unsigned int *len)
+
+=head1 DESCRIPTION
+
+SSL_SESSION_get0_id_context() returns the ID context associated with
+the SSL/TLS session B<s>. The length of the ID context is written to
+B<*len> if B<len> is not NULL.
+
+The value returned is a pointer to an object maintained within B<s> and
+should not be released.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_set_session_id_context(3)>
+
+=head1 HISTORY
+
+SSL_SESSION_get0_id_context() was first added to OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get_protocol_version - retrieve session protocol version
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_SESSION_get_protocol_version(const SSL_SESSION *s);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_get_protocol_version() returns the protocol version number used
+by session B<s>.
+
+=head1 RETURN VALUES
+
+SSL_SESSION_get_protocol_version() returns a number indicating the protocol
+version used for the session; this number matches the constants I<e.g.>
+B<TLS1_VERSION> or B<TLS1_2_VERSION>.
+
+Note that the SSL_SESSION_get_protocol_version() function
+does B<not> perform a null check on the provided session B<s> pointer.
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 HISTORY
+
+SSL_SESSION_get_protocol_version() was first added to OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout,
+SSL_SESSION_set_timeout
+SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout,
+- retrieve and manipulate session time and timeout settings
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_SESSION_get_time(const SSL_SESSION *s);
+ long SSL_SESSION_set_time(SSL_SESSION *s, long tm);
+ long SSL_SESSION_get_timeout(const SSL_SESSION *s);
+ long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm);
+
+ long SSL_get_time(const SSL_SESSION *s);
+ long SSL_set_time(SSL_SESSION *s, long tm);
+ long SSL_get_timeout(const SSL_SESSION *s);
+ long SSL_set_timeout(SSL_SESSION *s, long tm);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_get_time() returns the time at which the session B<s> was
+established. The time is given in seconds since the Epoch and therefore
+compatible to the time delivered by the time() call.
+
+SSL_SESSION_set_time() replaces the creation time of the session B<s> with
+the chosen value B<tm>.
+
+SSL_SESSION_get_timeout() returns the timeout value set for session B<s>
+in seconds.
+
+SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds
+to B<tm>.
+
+The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout()
+functions are synonyms for the SSL_SESSION_*() counterparts.
+
+=head1 NOTES
+
+Sessions are expired by examining the creation time and the timeout value.
+Both are set at creation time of the session to the actual time and the
+default timeout value at creation, respectively, as set by
+L<SSL_CTX_set_timeout(3)>.
+Using these functions it is possible to extend or shorten the lifetime
+of the session.
+
+=head1 RETURN VALUES
+
+SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently
+valid values.
+
+SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success.
+
+If any of the function is passed the NULL pointer for the session B<s>,
+0 is returned.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_timeout(3)>,
+L<SSL_get_default_timeout(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_get0_ticket,
+SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint,
+- get details about the ticket associated with a session
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_SESSION_has_ticket(const SSL_SESSION *s);
+ unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s);
+ void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick,
+ size_t *len);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_has_ticket() returns 1 if there is a Session Ticket associated with
+this session, and 0 otherwise.
+
+SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds
+associated with the session ticket.
+
+SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a
+session. The length of the ticket is written to B<*len>. If B<tick> is non
+NULL then a pointer to the ticket is written to B<*tick>. The pointer is only
+valid while the connection is in use. The session (and hence the ticket pointer)
+may also become invalid as a result of a call to SSL_CTX_flush_sessions().
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<d2i_SSL_SESSION(3)>,
+L<SSL_SESSION_get_time(3)>,
+L<SSL_SESSION_free(3)>
+
+=head1 HISTORY
+
+SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint and
+SSL_SESSION_get0_ticket were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_SESSION_set1_id - set the SSL session ID
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid,
+ unsigned int sid_len);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_set1_id() sets the the session ID for the B<ssl> SSL/TLS session
+to B<sid> of length B<sid_len>.
+
+=head1 RETURN VALUES
+
+SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example
+if the supplied session ID length exceeds B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 HISTORY
+
+SSL_SESSION_set1_id() was first added to OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_accept(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL handshake.
+The communication channel must already have been set and assigned to the
+B<ssl> by setting an underlying B<BIO>.
+
+=head1 NOTES
+
+The behaviour of SSL_accept() depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_accept() will only return once the
+handshake has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_accept() will also return
+when the underlying BIO could not satisfy the needs of SSL_accept()
+to continue the handshake, indicating the problem by the return value -1.
+In this case a call to SSL_get_error() with the
+return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_accept().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The TLS/SSL handshake was not successful but was shut down controlled and
+by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=item Z<>1
+
+The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
+established.
+
+=item E<lt>0
+
+The TLS/SSL handshake was not successful because a fatal error occurred either
+at the protocol level or a connection failure occurred. The shutdown was
+not clean. It can also occur of action is need to continue the operation
+for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_connect(3)>,
+L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>,
+L<SSL_set_connect_state(3)>,
+L<SSL_do_handshake(3)>,
+L<SSL_CTX_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_alert_type_string(int value);
+ const char *SSL_alert_type_string_long(int value);
+
+ const char *SSL_alert_desc_string(int value);
+ const char *SSL_alert_desc_string_long(int value);
+
+=head1 DESCRIPTION
+
+SSL_alert_type_string() returns a one letter string indicating the
+type of the alert specified by B<value>.
+
+SSL_alert_type_string_long() returns a string indicating the type of the alert
+specified by B<value>.
+
+SSL_alert_desc_string() returns a two letter string as a short form
+describing the reason of the alert specified by B<value>.
+
+SSL_alert_desc_string_long() returns a string describing the reason
+of the alert specified by B<value>.
+
+=head1 NOTES
+
+When one side of an SSL/TLS communication wants to inform the peer about
+a special situation, it sends an alert. The alert is sent as a special message
+and does not influence the normal data stream (unless its contents results
+in the communication being canceled).
+
+A warning alert is sent, when a non-fatal error condition occurs. The
+"close notify" alert is sent as a warning alert. Other examples for
+non-fatal errors are certificate errors ("certificate expired",
+"unsupported certificate"), for which a warning alert may be sent.
+(The sending party may however decide to send a fatal error.) The
+receiving side may cancel the connection on reception of a warning
+alert on it discretion.
+
+Several alert messages must be sent as fatal alert messages as specified
+by the TLS RFC. A fatal alert always leads to a connection abort.
+
+=head1 RETURN VALUES
+
+The following strings can occur for SSL_alert_type_string() or
+SSL_alert_type_string_long():
+
+=over 4
+
+=item "W"/"warning"
+
+=item "F"/"fatal"
+
+=item "U"/"unknown"
+
+This indicates that no support is available for this alert type.
+Probably B<value> does not contain a correct alert message.
+
+=back
+
+The following strings can occur for SSL_alert_desc_string() or
+SSL_alert_desc_string_long():
+
+=over 4
+
+=item "CN"/"close notify"
+
+The connection shall be closed. This is a warning alert.
+
+=item "UM"/"unexpected message"
+
+An inappropriate message was received. This alert is always fatal
+and should never be observed in communication between proper
+implementations.
+
+=item "BM"/"bad record mac"
+
+This alert is returned if a record is received with an incorrect
+MAC. This message is always fatal.
+
+=item "DF"/"decompression failure"
+
+The decompression function received improper input (e.g. data
+that would expand to excessive length). This message is always
+fatal.
+
+=item "HF"/"handshake failure"
+
+Reception of a handshake_failure alert message indicates that the
+sender was unable to negotiate an acceptable set of security
+parameters given the options available. This is a fatal error.
+
+=item "NC"/"no certificate"
+
+A client, that was asked to send a certificate, does not send a certificate
+(SSLv3 only).
+
+=item "BC"/"bad certificate"
+
+A certificate was corrupt, contained signatures that did not
+verify correctly, etc
+
+=item "UC"/"unsupported certificate"
+
+A certificate was of an unsupported type.
+
+=item "CR"/"certificate revoked"
+
+A certificate was revoked by its signer.
+
+=item "CE"/"certificate expired"
+
+A certificate has expired or is not currently valid.
+
+=item "CU"/"certificate unknown"
+
+Some other (unspecified) issue arose in processing the
+certificate, rendering it unacceptable.
+
+=item "IP"/"illegal parameter"
+
+A field in the handshake was out of range or inconsistent with
+other fields. This is always fatal.
+
+=item "DC"/"decryption failed"
+
+A TLSCiphertext decrypted in an invalid way: either it wasn't an
+even multiple of the block length or its padding values, when
+checked, weren't correct. This message is always fatal.
+
+=item "RO"/"record overflow"
+
+A TLSCiphertext record was received which had a length more than
+2^14+2048 bytes, or a record decrypted to a TLSCompressed record
+with more than 2^14+1024 bytes. This message is always fatal.
+
+=item "CA"/"unknown CA"
+
+A valid certificate chain or partial chain was received, but the
+certificate was not accepted because the CA certificate could not
+be located or couldn't be matched with a known, trusted CA. This
+message is always fatal.
+
+=item "AD"/"access denied"
+
+A valid certificate was received, but when access control was
+applied, the sender decided not to proceed with negotiation.
+This message is always fatal.
+
+=item "DE"/"decode error"
+
+A message could not be decoded because some field was out of the
+specified range or the length of the message was incorrect. This
+message is always fatal.
+
+=item "CY"/"decrypt error"
+
+A handshake cryptographic operation failed, including being
+unable to correctly verify a signature, decrypt a key exchange,
+or validate a finished message.
+
+=item "ER"/"export restriction"
+
+A negotiation not in compliance with export restrictions was
+detected; for example, attempting to transfer a 1024 bit
+ephemeral RSA key for the RSA_EXPORT handshake method. This
+message is always fatal.
+
+=item "PV"/"protocol version"
+
+The protocol version the client has attempted to negotiate is
+recognized, but not supported. (For example, old protocol
+versions might be avoided for security reasons). This message is
+always fatal.
+
+=item "IS"/"insufficient security"
+
+Returned instead of handshake_failure when a negotiation has
+failed specifically because the server requires ciphers more
+secure than those supported by the client. This message is always
+fatal.
+
+=item "IE"/"internal error"
+
+An internal error unrelated to the peer or the correctness of the
+protocol makes it impossible to continue (such as a memory
+allocation failure). This message is always fatal.
+
+=item "US"/"user canceled"
+
+This handshake is being canceled for some reason unrelated to a
+protocol failure. If the user cancels an operation after the
+handshake is complete, just closing the connection by sending a
+close_notify is more appropriate. This alert should be followed
+by a close_notify. This message is generally a warning.
+
+=item "NR"/"no renegotiation"
+
+Sent by the client in response to a hello request or by the
+server in response to a client hello after initial handshaking.
+Either of these would normally lead to renegotiation; when that
+is not appropriate, the recipient should respond with this alert;
+at that point, the original requester can decide whether to
+proceed with the connection. One case where this would be
+appropriate would be where a server has spawned a process to
+satisfy a request; the process might receive security parameters
+(key length, authentication, etc.) at startup and it might be
+difficult to communicate changes to these parameters after that
+point. This message is always a warning.
+
+=item "UP"/"unknown PSK identity"
+
+Sent by the server to indicate that it does not recognize a PSK
+identity or an SRP identity.
+
+=item "UK"/"unknown"
+
+This indicates that no description is available for this alert type.
+Probably B<value> does not contain a correct alert message.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_info_callback(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_check_chain - check certificate chain suitability
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain);
+
+=head1 DESCRIPTION
+
+SSL_check_chain() checks whether certificate B<x>, private key B<pk> and
+certificate chain B<chain> is suitable for use with the current session
+B<s>.
+
+=head1 RETURN VALUES
+
+SSL_check_chain() returns a bitmap of flags indicating the validity of the
+chain.
+
+B<CERT_PKEY_VALID>: the chain can be used with the current session.
+If this flag is B<not> set then the certificate will never be used even
+if the application tries to set it because it is inconsistent with the
+peer preferences.
+
+B<CERT_PKEY_SIGN>: the EE key can be used for signing.
+
+B<CERT_PKEY_EE_SIGNATURE>: the signature algorithm of the EE certificate is
+acceptable.
+
+B<CERT_PKEY_CA_SIGNATURE>: the signature algorithms of all CA certificates
+are acceptable.
+
+B<CERT_PKEY_EE_PARAM>: the parameters of the end entity certificate are
+acceptable (e.g. it is a supported curve).
+
+B<CERT_PKEY_CA_PARAM>: the parameters of all CA certificates are acceptable.
+
+B<CERT_PKEY_EXPLICIT_SIGN>: the end entity certificate algorithm
+can be used explicitly for signing (i.e. it is mentioned in the signature
+algorithms extension).
+
+B<CERT_PKEY_ISSUER_NAME>: the issuer name is acceptable. This is only
+meaningful for client authentication.
+
+B<CERT_PKEY_CERT_TYPE>: the certificate type is acceptable. Only meaningful
+for client authentication.
+
+B<CERT_PKEY_SUITEB>: chain is suitable for Suite B use.
+
+=head1 NOTES
+
+SSL_check_chain() must be called in servers after a client hello message or in
+clients after a certificate request message. It will typically be called
+in the certificate callback.
+
+An application wishing to support multiple certificate chains may call this
+function on each chain in turn: starting with the one it considers the
+most secure. It could then use the chain of the first set which returns
+suitable flags.
+
+As a minimum the flag B<CERT_PKEY_VALID> must be set for a chain to be
+usable. An application supporting multiple chains with different CA signature
+algorithms may also wish to check B<CERT_PKEY_CA_SIGNATURE> too. If no
+chain is suitable a server should fall back to the most secure chain which
+sets B<CERT_PKEY_VALID>.
+
+The validity of a chain is determined by checking if it matches a supported
+signature algorithm, supported curves and in the case of client authentication
+certificate types and issuer names.
+
+Since the supported signature algorithms extension is only used in TLS 1.2
+and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be
+very useful. Applications may wish to specify a different "legacy" chain
+for earlier versions of TLS or DTLS.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_set_cert_cb(3)>,
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_clear - reset SSL object to allow another connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_clear(SSL *ssl);
+
+=head1 DESCRIPTION
+
+Reset B<ssl> to allow another connection. All settings (method, ciphers,
+BIOs) are kept.
+
+=head1 NOTES
+
+SSL_clear is used to prepare an SSL object for a new connection. While all
+settings are kept, a side effect is the handling of the current SSL session.
+If a session is still B<open>, it is considered bad and will be removed
+from the session cache, as required by RFC2246. A session is considered open,
+if L<SSL_shutdown(3)> was not called for the connection
+or at least L<SSL_set_shutdown(3)> was used to
+set the SSL_SENT_SHUTDOWN state.
+
+If a session was closed cleanly, the session object will be kept and all
+settings corresponding. This explicitly means, that e.g. the special method
+used during the session will be kept for the next handshake. So if the
+session was a TLSv1 session, a SSL client object will use a TLSv1 client
+method for the next handshake and a SSL server object will use a TLSv1
+server method, even if TLS_*_methods were chosen on startup. This
+will might lead to connection failures (see L<SSL_new(3)>)
+for a description of the method's properties.
+
+=head1 WARNINGS
+
+SSL_clear() resets the SSL object to allow for another connection. The
+reset operation however keeps several settings of the last sessions
+(some of these settings were made automatically during the last
+handshake). It only makes sense for a new connection with the exact
+same peer that shares these settings, and may fail if that peer
+changes its settings between connections. Use the sequence
+L<SSL_get_session(3)>;
+L<SSL_new(3)>;
+L<SSL_set_session(3)>;
+L<SSL_free(3)>
+instead to avoid such failures
+(or simply L<SSL_free(3)>; L<SSL_new(3)>
+if session reuse is not desired).
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The SSL_clear() operation could not be performed. Check the error stack to
+find out the reason.
+
+=item Z<>1
+
+The SSL_clear() operation was successful.
+
+=back
+
+L<SSL_new(3)>, L<SSL_free(3)>,
+L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
+L<SSL_CTX_set_options(3)>, L<ssl(3)>,
+L<SSL_CTX_set_client_cert_cb(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_connect(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_connect() initiates the TLS/SSL handshake with a server. The communication
+channel must already have been set and assigned to the B<ssl> by setting an
+underlying B<BIO>.
+
+=head1 NOTES
+
+The behaviour of SSL_connect() depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_connect() will only return once the
+handshake has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_connect() will also return
+when the underlying BIO could not satisfy the needs of SSL_connect()
+to continue the handshake, indicating the problem by the return value -1.
+In this case a call to SSL_get_error() with the
+return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_connect().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The TLS/SSL handshake was not successful but was shut down controlled and
+by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=item Z<>1
+
+The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
+established.
+
+=item E<lt>0
+
+The TLS/SSL handshake was not successful, because a fatal error occurred either
+at the protocol level or a connection failure occurred. The shutdown was
+not clean. It can also occur of action is need to continue the operation
+for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_accept(3)>,
+L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>,
+L<SSL_set_connect_state(3)>,
+L<SSL_do_handshake(3)>,
+L<SSL_CTX_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_do_handshake - perform a TLS/SSL handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_do_handshake(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the
+connection is in client mode, the handshake will be started. The handshake
+routines may have to be explicitly set in advance using either
+L<SSL_set_connect_state(3)> or
+L<SSL_set_accept_state(3)>.
+
+=head1 NOTES
+
+The behaviour of SSL_do_handshake() depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_do_handshake() will only return
+once the handshake has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return
+when the underlying BIO could not satisfy the needs of SSL_do_handshake()
+to continue the handshake. In this case a call to SSL_get_error() with the
+return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_do_handshake().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The TLS/SSL handshake was not successful but was shut down controlled and
+by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=item Z<>1
+
+The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
+established.
+
+=item E<lt>0
+
+The TLS/SSL handshake was not successful because a fatal error occurred either
+at the protocol level or a connection failure occurred. The shutdown was
+not clean. It can also occur of action is need to continue the operation
+for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_connect(3)>,
+L<SSL_accept(3)>, L<ssl(3)>, L<bio(3)>,
+L<SSL_set_connect_state(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_extension_supported,
+SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext
+- custom TLS extension handling
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
+ custom_ext_add_cb add_cb,
+ custom_ext_free_cb free_cb, void *add_arg,
+ custom_ext_parse_cb parse_cb,
+ void *parse_arg);
+
+ int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
+ custom_ext_add_cb add_cb,
+ custom_ext_free_cb free_cb, void *add_arg,
+ custom_ext_parse_cb parse_cb,
+ void *parse_arg);
+
+ int SSL_extension_supported(unsigned int ext_type);
+
+ typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type,
+ const unsigned char **out,
+ size_t *outlen, int *al,
+ void *add_arg);
+
+ typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type,
+ const unsigned char *out,
+ void *add_arg);
+
+ typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type,
+ const unsigned char *in,
+ size_t inlen, int *al,
+ void *parse_arg);
+
+
+=head1 DESCRIPTION
+
+SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client
+with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
+B<parse_cb>.
+
+SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server
+with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
+B<parse_cb>.
+
+In both cases the extension type must not be handled by OpenSSL internally
+or an error occurs.
+
+SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
+internally by OpenSSL and 0 otherwise.
+
+=head1 EXTENSION CALLBACKS
+
+The callback B<add_cb> is called to send custom extension data to be
+included in ClientHello for TLS clients or ServerHello for servers. The
+B<ext_type> parameter is set to the extension type which will be added and
+B<add_arg> to the value set when the extension handler was added.
+
+If the application wishes to include the extension B<ext_type> it should
+set B<*out> to the extension data, set B<*outlen> to the length of the
+extension data and return 1.
+
+If the B<add_cb> does not wish to include the extension it must return 0.
+
+If B<add_cb> returns -1 a fatal handshake error occurs using the TLS
+alert value specified in B<*al>.
+
+For clients (but not servers) if B<add_cb> is set to NULL a zero length
+extension is added for B<ext_type>.
+
+For clients every registered B<add_cb> is always called to see if the
+application wishes to add an extension to ClientHello.
+
+For servers every registered B<add_cb> is called once if and only if the
+corresponding extension was received in ClientHello to see if the application
+wishes to add the extension to ServerHello. That is, if no corresponding extension
+was received in ClientHello then B<add_cb> will not be called.
+
+If an extension is added (that is B<add_cb> returns 1) B<free_cb> is called
+(if it is set) with the value of B<out> set by the add callback. It can be
+used to free up any dynamic extension data set by B<add_cb>. Since B<out> is
+constant (to permit use of constant data in B<add_cb>) applications may need to
+cast away const to free the data.
+
+The callback B<parse_cb> receives data for TLS extensions. For TLS clients
+the extension data will come from ServerHello and for TLS servers it will
+come from ClientHello.
+
+The extension data consists of B<inlen> bytes in the buffer B<in> for the
+extension B<extension_type>.
+
+If the B<parse_cb> considers the extension data acceptable it must return
+1. If it returns 0 or a negative value a fatal handshake error occurs
+using the TLS alert value specified in B<*al>.
+
+The buffer B<in> is a temporary internal buffer which will not be valid after
+the callback returns.
+
+=head1 NOTES
+
+The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values
+which will be passed to the corresponding callbacks. They can, for example,
+be used to store the extension data received in a convenient structure or
+pass the extension data to be added or freed when adding extensions.
+
+The B<ext_type> parameter corresponds to the B<extension_type> field of
+RFC5246 et al. It is B<not> a NID.
+
+If the same custom extension type is received multiple times a fatal
+B<decode_error> alert is sent and the handshake aborts. If a custom extension
+is received in ServerHello which was not sent in ClientHello a fatal
+B<unsupported_extension> alert is sent and the handshake is aborted. The
+ServerHello B<add_cb> callback is only called if the corresponding extension
+was received in ClientHello. This is compliant with the TLS specifications.
+This behaviour ensures that each callback is called at most once and that
+an application can never send unsolicited extensions.
+
+=head1 RETURN VALUES
+
+SSL_CTX_add_client_custom_ext() and SSL_CTX_add_server_custom_ext() return 1 for
+success and 0 for failure. A failure can occur if an attempt is made to
+add the same B<ext_type> more than once, if an attempt is made to use an
+extension type handled internally by OpenSSL or if an internal error occurs
+(for example a memory allocation failure).
+
+SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
+internally by OpenSSL and 0 otherwise.
+
+=head1 COPYRIGHT
+
+Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_free - free an allocated SSL structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_free(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_free() decrements the reference count of B<ssl>, and removes the SSL
+structure pointed to by B<ssl> and frees up the allocated memory if the
+reference count has reached 0.
+If B<ssl> is NULL nothing is done.
+
+=head1 NOTES
+
+SSL_free() also calls the free()ing procedures for indirectly affected items, if
+applicable: the buffering BIO, the read and write BIOs,
+cipher lists specially created for this B<ssl>, the B<SSL_SESSION>.
+Do not explicitly free these indirectly freed up items before or after
+calling SSL_free(), as trying to free things twice may lead to program
+failure.
+
+The ssl session has reference counts from two users: the SSL object, for
+which the reference count is removed by SSL_free() and the internal
+session cache. If the session is considered bad, because
+L<SSL_shutdown(3)> was not called for the connection
+and L<SSL_set_shutdown(3)> was not used to set the
+SSL_SENT_SHUTDOWN state, the session will also be removed
+from the session cache as required by RFC2246.
+
+=head1 RETURN VALUES
+
+SSL_free() does not provide diagnostic information.
+
+L<SSL_new(3)>, L<SSL_clear(3)>,
+L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get0_peer_scts - get SCTs received
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_get0_peer_scts() returns the signed certificate timestamps (SCTs) that have
+been received. If this is the first time that this function has been called for
+a given B<SSL> instance, it will examine the TLS extensions, OCSP response and
+the peer's certificate for SCTs. Future calls will return the same SCTs.
+
+=head1 RESTRICTIONS
+
+If no Certificate Transparency validation callback has been set (using
+B<SSL_CTX_set_ct_validation_callback> or B<SSL_set_ct_validation_callback>),
+this function is not guaranteed to return all of the SCTs that the peer is
+capable of sending.
+
+=head1 RETURN VALUES
+
+SSL_get0_peer_scts() returns a list of SCTs found, or NULL if an error occurs.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_ct_validation_callback(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_SSL_CTX() returns a pointer to the SSL_CTX object, from which
+B<ssl> was created with L<SSL_new(3)>.
+
+=head1 RETURN VALUES
+
+The pointer to the SSL_CTX object is returned.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_new(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_waiting_for_async,
+SSL_get_all_async_fds,
+SSL_get_changed_async_fds
+- manage asynchronous operations
+
+=for comment multiple includes
+
+=head1 SYNOPSIS
+
+ #include <openssl/async.h>
+ #include <openssl/ssl.h>
+
+ int SSL_waiting_for_async(SSL *s);
+ int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds);
+ int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds,
+ OSSL_ASYNC_FD *delfd, size_t *numdelfds);
+
+=head1 DESCRIPTION
+
+SSL_waiting_for_async() determines whether an SSL connection is currently
+waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in
+L<SSL_CTX_set_mode(3)>).
+
+SSL_get_all_async_fds() returns a list of file descriptor which can be used in a
+call to select() or poll() to determine whether the current asynchronous
+operation has completed or not. A completed operation will result in data
+appearing as "read ready" on the file descriptor (no actual data should be read
+from the file descriptor). This function should only be called if the SSL object
+is currently waiting for asynchronous work to complete (i.e.
+SSL_ERROR_WANT_ASYNC has been received - see L<SSL_get_error(3)>). Typically the
+list will only contain one file descriptor. However if multiple asynchronous
+capable engines are in use then more than one is possible. The number of file
+descriptors returned is stored in B<*numfds> and the file descriptors themselves
+are in B<*fds>. The B<fds> parameter may be NULL in which case no file
+descriptors are returned but B<*numfds> is still populated. It is the callers
+responsibility to ensure sufficient memory is allocated at B<*fds> so typically
+this function is called twice (once with a NULL B<fds> parameter and once
+without).
+
+SSL_get_changed_async_fds() returns a list of the asynchronous file descriptors
+that have been added and a list that have been deleted since the last
+SSL_ERROR_WANT_ASYNC was received (or since the SSL object was created if no
+SSL_ERROR_WANT_ASYNC has been received). Similar to SSL_get_all_async_fds() it
+is the callers responsibility to ensure that B<*addfd> and B<*delfd> have
+sufficient memory allocated, although they may be NULL. The number of added fds
+and the number of deleted fds are stored in B<*numaddfds> and B<*numdelfds>
+respectively.
+
+=head1 RETURN VALUES
+
+SSL_waiting_for_async() will return 1 if the current SSL operation is waiting
+for an async operation to complete and 0 otherwise.
+
+SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or
+0 on error.
+
+=head1 NOTES
+
+On Windows platforms the openssl/async.h header is dependent on some
+of the types customarily made available by including windows.h. The
+application developer is likely to require control over when the latter
+is included, commonly as one of the first included headers. Therefore
+it is defined as an application developer's responsibility to include
+windows.h prior to async.h.
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)>
+
+=head1 HISTORY
+
+SSL_waiting_for_async(), SSL_get_all_async_fds() and SSL_get_changed_async_fds()
+were first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get1_supported_ciphers, SSL_get_client_ciphers,
+SSL_get_ciphers, SSL_CTX_get_ciphers, SSL_get_cipher_list
+- get list of available SSL_CIPHERs
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl);
+ STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx);
+ STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s);
+ STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl);
+ const char *SSL_get_cipher_list(const SSL *ssl, int priority);
+
+=head1 DESCRIPTION
+
+SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>,
+sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL
+is returned.
+
+SSL_CTX_get_ciphers() returns the stack of available SSL_CIPHERs for B<ctx>.
+
+SSL_get1_supported_ciphers() returns the stack of enabled SSL_CIPHERs for
+B<ssl>, sorted by preference.
+The list depends on settings like the cipher list, the supported protocol
+versions, the security level, and the enabled signature algorithms.
+SRP and PSK ciphers are only enabled if the appropriate callbacks or settings
+have been applied.
+This is the list that will be sent by the client to the server.
+The list supported by the server might include more ciphers in case there is a
+hole in the list of supported protocols.
+The server will also not use ciphers from this list depending on the
+configured certificates and DH parameters.
+If B<ssl> is NULL or no ciphers are available, NULL is returned.
+
+SSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the
+list received from the client on B<ssl>. If B<ssl> is NULL, no ciphers are
+available, or B<ssl> is not operating in server mode, NULL is returned.
+
+SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER
+listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are
+available, or there are less ciphers than B<priority> available, NULL
+is returned.
+
+=head1 NOTES
+
+The details of the ciphers obtained by SSL_get_ciphers(), SSL_CTX_get_ciphers()
+SSL_get1_supported_ciphers() and SSL_get_client_ciphers() can be obtained using
+the L<SSL_CIPHER_get_name(3)> family of functions.
+
+Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the
+sorted list of available ciphers, until NULL is returned.
+
+Note: SSL_get_ciphers(), SSL_CTX_get_ciphers() and SSL_get_client_ciphers()
+return a pointer to an internal cipher stack, which will be freed later on when
+the SSL or SSL_SESSION object is freed. Therefore, the calling code B<MUST NOT>
+free the return value itself.
+
+The stack returned by SSL_get1_supported_ciphers() should be freed using
+sk_SSL_CIPHER_free().
+
+=head1 RETURN VALUES
+
+See DESCRIPTION
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>,
+L<SSL_CIPHER_get_name(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
+ STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
+B<ctx> using L<SSL_CTX_set_client_CA_list(3)>.
+
+SSL_get_client_CA_list() returns the list of client CAs explicitly
+set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
+L<SSL_CTX_set_client_CA_list(3)>, when in
+server mode. In client mode, SSL_get_client_CA_list returns the list of
+client CAs sent from the server, if any.
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
+diagnostic information.
+
+SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
+values:
+
+=over 4
+
+=item STACK_OF(X509_NAMES)
+
+List of CA names explicitly set (for B<ctx> or in server mode) or send
+by the server (client mode).
+
+=item NULL
+
+No client CA list was explicitly set (for B<ctx> or in server mode) or
+the server did not send a list of CAs (client mode).
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_client_cert_cb(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen);
+ size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen);
+ size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, size_t outlen);
+
+=head1 DESCRIPTION
+
+SSL_get_client_random() extracts the random value sent from the client
+to the server during the initial SSL/TLS handshake. It copies as many
+bytes as it can of this value into the buffer provided in B<out>,
+which must have at least B<outlen> bytes available. It returns the
+total number of bytes that were actually copied. If B<outlen> is
+zero, SSL_get_client_random() copies nothing, and returns the
+total size of the client_random value.
+
+SSL_get_server_random() behaves the same, but extracts the random value
+sent from the server to the client during the initial SSL/TLS handshake.
+
+SSL_SESSION_get_master_key() behaves the same, but extracts the master
+secret used to guarantee the security of the SSL/TLS session. This one
+can be dangerous if misused; see NOTES below.
+
+
+=head1 NOTES
+
+You probably shouldn't use these functions.
+
+These functions expose internal values from the TLS handshake, for
+use in low-level protocols. You probably should not use them, unless
+you are implementing something that needs access to the internal protocol
+details.
+
+Despite the names of SSL_get_client_random() and SSL_get_server_random(), they
+ARE NOT random number generators. Instead, they return the mostly-random values that
+were already generated and used in the TLS protocol. Using them
+in place of RAND_bytes() would be grossly foolish.
+
+The security of your TLS session depends on keeping the master key secret:
+do not expose it, or any information about it, to anybody.
+If you need to calculate another secret value that depends on the master
+secret, you should probably use SSL_export_keying_material() instead, and
+forget that you ever saw these functions.
+
+In current versions of the TLS protocols, the length of client_random
+(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for
+other outlen arguments to the SSL_get_*_random() functions is provided
+in case of the unlikely event that a future version or variant of TLS
+uses some other length there.
+
+Finally, though the "client_random" and "server_random" values are called
+"random", many TLS implementations will generate four bytes of those
+values based on their view of the current time.
+
+
+=head1 RETURN VALUES
+
+If B<outlen> is greater than 0, these functions return the number of bytes
+actually copied, which will be less than or equal to B<outlen>.
+
+If B<outlen> is 0, these functions return the maximum number
+of bytes they would copy--that is, the length of the underlying field.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<RAND_bytes(3)>,
+L<SSL_export_keying_material(3)>
+
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_current_cipher, SSL_get_cipher_name, SSL_get_cipher,
+SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl);
+
+ const char *SSL_get_cipher_name(const SSL *s);
+ const char *SSL_get_cipher(const SSL *s);
+ int SSL_get_cipher_bits(const SSL *s, int *np) \
+ const char *SSL_get_cipher_version(const SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing
+the description of the actually used cipher of a connection established with
+the B<ssl> object.
+See L<SSL_CIPHER_get_name(3)> for more details.
+
+SSL_get_cipher_name() obtains the
+name of the currently used cipher.
+SSL_get_cipher() is identical to SSL_get_cipher_name().
+SSL_get_cipher_bits() is a
+macro to obtain the number of secret/algorithm bits used and
+SSL_get_cipher_version() returns the protocol name.
+
+=head1 RETURN VALUES
+
+SSL_get_current_cipher() returns the cipher actually used, or NULL if
+no session has been established.
+
+=head1 NOTES
+
+These are implemented as macros.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CIPHER_get_name(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_default_timeout - get default session timeout value
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_get_default_timeout(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_default_timeout() returns the default timeout value assigned to
+SSL_SESSION objects negotiated for the protocol valid for B<ssl>.
+
+=head1 NOTES
+
+Whenever a new session is negotiated, it is assigned a timeout value,
+after which it will not be accepted for session reuse. If the timeout
+value was not explicitly set using
+L<SSL_CTX_set_timeout(3)>, the hardcoded default
+timeout for the protocol will be used.
+
+SSL_get_default_timeout() return this hardcoded value, which is 300 seconds
+for all currently supported protocols.
+
+=head1 RETURN VALUES
+
+See description.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_SESSION_get_time(3)>,
+L<SSL_CTX_flush_sessions(3)>,
+L<SSL_get_default_timeout(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_error - obtain result code for TLS/SSL I/O operation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_error(const SSL *ssl, int ret);
+
+=head1 DESCRIPTION
+
+SSL_get_error() returns a result code (suitable for the C "switch"
+statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(),
+SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by
+that TLS/SSL I/O function must be passed to SSL_get_error() in parameter
+B<ret>.
+
+In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
+current thread's OpenSSL error queue. Thus, SSL_get_error() must be
+used in the same thread that performed the TLS/SSL I/O operation, and no
+other OpenSSL function calls should appear in between. The current
+thread's error queue must be empty before the TLS/SSL I/O operation is
+attempted, or SSL_get_error() will not work reliably.
+
+=head1 RETURN VALUES
+
+The following return values can currently occur:
+
+=over 4
+
+=item SSL_ERROR_NONE
+
+The TLS/SSL I/O operation completed. This result code is returned
+if and only if B<ret E<gt> 0>.
+
+=item SSL_ERROR_ZERO_RETURN
+
+The TLS/SSL connection has been closed. If the protocol version is SSL 3.0
+or TLS 1.0, this result code is returned only if a closure
+alert has occurred in the protocol, i.e. if the connection has been
+closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN>
+does not necessarily indicate that the underlying transport
+has been closed.
+
+=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
+
+The operation did not complete; the same TLS/SSL I/O function should be
+called again later. If, by then, the underlying B<BIO> has data
+available for reading (if the result code is B<SSL_ERROR_WANT_READ>)
+or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL
+protocol progress will take place, i.e. at least part of an TLS/SSL
+record will be read or written. Note that the retry may again lead to
+a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition.
+There is no fixed upper limit for the number of iterations that
+may be necessary until progress becomes visible at application
+protocol level.
+
+For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or
+poll() on the underlying socket can be used to find out when the
+TLS/SSL I/O function should be retried.
+
+Caveat: Any TLS/SSL I/O function can lead to either of
+B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular,
+SSL_read() or SSL_peek() may want to write data and SSL_write() may want
+to read data. This is mainly because TLS/SSL handshakes may occur at any
+time during the protocol (initiated by either the client or the server);
+SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes.
+
+=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT
+
+The operation did not complete; the same TLS/SSL I/O function should be
+called again later. The underlying BIO was not connected yet to the peer
+and the call would block in connect()/accept(). The SSL function should be
+called again when the connection is established. These messages can only
+appear with a BIO_s_connect() or BIO_s_accept() BIO, respectively.
+In order to find out, when the connection has been successfully established,
+on many platforms select() or poll() for writing on the socket file descriptor
+can be used.
+
+=item SSL_ERROR_WANT_X509_LOOKUP
+
+The operation did not complete because an application callback set by
+SSL_CTX_set_client_cert_cb() has asked to be called again.
+The TLS/SSL I/O function should be called again later.
+Details depend on the application.
+
+=item SSL_ERROR_WANT_ASYNC
+
+The operation did not complete because an asynchronous engine is still
+processing data. This will only occur if the mode has been set to SSL_MODE_ASYNC
+using L<SSL_CTX_set_mode(3)> or L<SSL_set_mode(3)> and an asynchronous capable
+engine is being used. An application can determine whether the engine has
+completed its processing using select() or poll() on the asynchronous wait file
+descriptor. This file descriptor is available by calling
+L<SSL_get_all_async_fds(3)> or L<SSL_get_changed_async_fds(3)>. The TLS/SSL I/O
+function should be called again later. The function B<must> be called from the
+same thread that the original call was made from.
+
+=item SSL_ERROR_WANT_ASYNC_JOB
+
+The asynchronous job could not be started because there were no async jobs
+available in the pool (see ASYNC_init_thread(3)). This will only occur if the
+mode has been set to SSL_MODE_ASYNC using L<SSL_CTX_set_mode(3)> or
+L<SSL_set_mode(3)> and a maximum limit has been set on the async job pool
+through a call to L<ASYNC_init_thread(3)>. The application should retry the
+operation after a currently executing asynchronous operation for the current
+thread has completed.
+
+=item SSL_ERROR_SYSCALL
+
+Some I/O error occurred. The OpenSSL error queue may contain more
+information on the error. If the error queue is empty
+(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
+about the error: If B<ret == 0>, an EOF was observed that violates
+the protocol. If B<ret == -1>, the underlying B<BIO> reported an
+I/O error (for socket I/O on Unix systems, consult B<errno> for details).
+
+=item SSL_ERROR_SSL
+
+A failure in the SSL library occurred, usually a protocol error. The
+OpenSSL error queue contains more information on the error.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<err(3)>
+
+=head1 HISTORY
+
+SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_extms_support - extended master secret support
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_extms_support(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_extms_support() indicates whether the current session used extended
+master secret.
+
+This function is implemented as a macro.
+
+=head1 RETURN VALUES
+
+SSL_get_extms_support() returns 1 if the current session used extended
+master secret, 0 if it did not and -1 if a handshake is currently in
+progress i.e. it is not possible to determine if extended master secret
+was used.
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_fd, SSL_get_rfd, SSL_get_wfd - get file descriptor linked to an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_fd(const SSL *ssl);
+ int SSL_get_rfd(const SSL *ssl);
+ int SSL_get_wfd(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_fd() returns the file descriptor which is linked to B<ssl>.
+SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the
+read or the write channel, which can be different. If the read and the
+write channel are different, SSL_get_fd() will return the file descriptor
+of the read channel.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item -1
+
+The operation failed, because the underlying BIO is not of the correct type
+(suitable for file descriptors).
+
+=item E<gt>=0
+
+The file descriptor linked to B<ssl>.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_set_fd(3)>, L<ssl(3)> , L<bio(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_peer_cert_chain, SSL_get0_verified_chain - get the X509 certificate
+chain of the peer
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl);
+ STACK_OF(X509) *SSL_get0_verified_chain(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) certificates
+forming the certificate chain sent by the peer. If called on the client side,
+the stack also contains the peer's certificate; if called on the server
+side, the peer's certificate must be obtained separately using
+L<SSL_get_peer_certificate(3)>.
+If the peer did not present a certificate, NULL is returned.
+
+NB: SSL_get_peer_chain() returns the peer chain as sent by the peer: it
+only consists of certificates the peer has sent (in the order the peer
+has sent them) it is B<not> a verified chain.
+
+SSL_get0_verified_chain() returns the B<verified> certificate chain
+of the peer including the peer's end entity certificate. It must be called
+after a session has been successfully established. If peer verification was
+not successful (as indicated by SSL_get_verify_result() not returning
+X509_V_OK) the chain may be incomplete or invalid.
+
+=head1 NOTES
+
+If the session is resumed peers do not send certificates so a NULL pointer
+is returned by these functions. Applications can call SSL_session_reused()
+to determine whether a session is resumed.
+
+The reference count of each certificate in the returned STACK_OF(X509) object
+is not incremented and the returned stack may be invalidated by renegotiation.
+If applications wish to use any certificates in the returned chain
+indefinitely they must increase the reference counts using X509_up_ref() or
+obtain a copy of the whole chain with X509_chain_up_ref().
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+No certificate was presented by the peer or no connection was established
+or the certificate chain is no longer available when a session is reused.
+
+=item Pointer to a STACK_OF(X509)
+
+The return value points to the certificate chain presented by the peer.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_peer_certificate(3)>, L<X509_up_ref(3)>,
+L<X509_chain_up_ref(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_peer_certificate - get the X509 certificate of the peer
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ X509 *SSL_get_peer_certificate(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_peer_certificate() returns a pointer to the X509 certificate the
+peer presented. If the peer did not present a certificate, NULL is returned.
+
+=head1 NOTES
+
+Due to the protocol definition, a TLS/SSL server will always send a
+certificate, if present. A client will only send a certificate when
+explicitly requested to do so by the server (see
+L<SSL_CTX_set_verify(3)>). If an anonymous cipher
+is used, no certificates are sent.
+
+That a certificate is returned does not indicate information about the
+verification state, use L<SSL_get_verify_result(3)>
+to check the verification state.
+
+The reference count of the X509 object is incremented by one, so that it
+will not be destroyed when the session containing the peer certificate is
+freed. The X509 object must be explicitly freed using X509_free().
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+No certificate was presented by the peer or no connection was established.
+
+=item Pointer to an X509 certificate
+
+The return value points to the certificate presented by the peer.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_verify_result(3)>,
+L<SSL_CTX_set_verify(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and hint
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_get_psk_identity_hint(const SSL *ssl);
+ const char *SSL_get_psk_identity(const SSL *ssl);
+
+
+=head1 DESCRIPTION
+
+SSL_get_psk_identity_hint() is used to retrieve the PSK identity hint
+used during the connection setup related to SSL object
+B<ssl>. Similarly, SSL_get_psk_identity() is used to retrieve the PSK
+identity used during the connection setup.
+
+
+=head1 RETURN VALUES
+
+If non-B<NULL>, SSL_get_psk_identity_hint() returns the PSK identity
+hint and SSL_get_psk_identity() returns the PSK identity. Both are
+B<NULL>-terminated. SSL_get_psk_identity_hint() may return B<NULL> if
+no PSK identity hint was used during the connection setup.
+
+Note that the return value is valid only during the lifetime of the
+SSL object B<ssl>.
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+Copyright 2005 Nokia.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_rbio, SSL_get_wbio - get BIO linked to an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ BIO *SSL_get_rbio(SSL *ssl);
+ BIO *SSL_get_wbio(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the
+read or the write channel, which can be different. The reference count
+of the BIO is not incremented.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+No BIO was connected to the SSL object
+
+=item Any other pointer
+
+The BIO linked to B<ssl>.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_set_bio(3)>, L<ssl(3)> , L<bio(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_session, SSL_get0_session, SSL_get1_session - retrieve TLS/SSL session data
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_SESSION *SSL_get_session(const SSL *ssl);
+ SSL_SESSION *SSL_get0_session(const SSL *ssl);
+ SSL_SESSION *SSL_get1_session(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in
+B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so
+that the pointer can become invalid by other operations.
+
+SSL_get0_session() is the same as SSL_get_session().
+
+SSL_get1_session() is the same as SSL_get_session(), but the reference
+count of the B<SSL_SESSION> is incremented by one.
+
+=head1 NOTES
+
+The ssl session contains all information required to re-establish the
+connection without a new handshake.
+
+SSL_get0_session() returns a pointer to the actual session. As the
+reference counter is not incremented, the pointer is only valid while
+the connection is in use. If L<SSL_clear(3)> or
+L<SSL_free(3)> is called, the session may be removed completely
+(if considered bad), and the pointer obtained will become invalid. Even
+if the session is valid, it can be removed at any time due to timeout
+during L<SSL_CTX_flush_sessions(3)>.
+
+If the data is to be kept, SSL_get1_session() will increment the reference
+count, so that the session will not be implicitly removed by other operations
+but stays in memory. In order to remove the session
+L<SSL_SESSION_free(3)> must be explicitly called once
+to decrement the reference count again.
+
+SSL_SESSION objects keep internal link information about the session cache
+list, when being inserted into one SSL_CTX object's session cache.
+One SSL_SESSION object, regardless of its reference count, must therefore
+only be used with one SSL_CTX object (and the SSL objects created
+from this SSL_CTX object).
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+There is no session available in B<ssl>.
+
+=item Pointer to an SSL_SESSION
+
+The return value points to the data of an SSL session.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_free(3)>,
+L<SSL_clear(3)>,
+L<SSL_SESSION_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_shared_sigalgs, SSL_get_sigalgs - get supported signature algorithms
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_shared_sigalgs(SSL *s, int idx,
+ int *psign, int *phash, int *psignhash,
+ unsigned char *rsig, unsigned char *rhash);
+
+ int SSL_get_sigalgs(SSL *s, int idx,
+ int *psign, int *phash, int *psignhash,
+ unsigned char *rsig, unsigned char *rhash);
+
+=head1 DESCRIPTION
+
+SSL_get_shared_sigalgs() returns information about the shared signature
+algorithms supported by peer B<s>. The parameter B<idx> indicates the index
+of the shared signature algorithm to return starting from zero. The signature
+algorithm NID is written to B<*psign>, the hash NID to B<*phash> and the
+sign and hash NID to B<*psignhash>. The raw signature and hash values
+are written to B<*rsig> and B<*rhash>.
+
+SSL_get_sigalgs() is similar to SSL_get_shared_sigalgs() except it returns
+information about all signature algorithms supported by B<s> in the order
+they were sent by the peer.
+
+=head1 RETURN VALUES
+
+SSL_get_shared_sigalgs() and SSL_get_sigalgs() return the number of
+signature algorithms or B<0> if the B<idx> parameter is out of range.
+
+=head1 NOTES
+
+These functions are typically called for debugging purposes (to report
+the peer's preferences) or where an application wants finer control over
+certificate selection. Most applications will rely on internal handling
+and will not need to call them.
+
+If an application is only interested in the highest preference shared
+signature algorithm it can just set B<idx> to zero.
+
+Any or all of the parameters B<psign>, B<phash>, B<psignhash>, B<rsig> or
+B<rhash> can be set to B<NULL> if the value is not required. By setting
+them all to B<NULL> and setting B<idx> to zero the total number of
+signature algorithms can be determined: which can be zero.
+
+These functions must be called after the peer has sent a list of supported
+signature algorithms: after a client hello (for servers) or a certificate
+request (for clients). They can (for example) be called in the certificate
+callback.
+
+Only TLS 1.2 and DTLS 1.2 currently support signature algorithms. If these
+functions are called on an earlier version of TLS or DTLS zero is returned.
+
+The shared signature algorithms returned by SSL_get_shared_sigalgs() are
+ordered according to configuration and peer preferences.
+
+The raw values correspond to the on the wire form as defined by RFC5246 et al.
+The NIDs are OpenSSL equivalents. For example if the peer sent sha256(4) and
+rsa(1) then B<*rhash> would be 4, B<*rsign> 1, B<*phash> NID_sha256, B<*psig>
+NID_rsaEncryption and B<*psighash> NID_sha256WithRSAEncryption.
+
+If a signature algorithm is not recognised the corresponding NIDs
+will be set to B<NID_undef>. This may be because the value is not supported
+or is not an appropriate combination (for example MD5 and DSA).
+
+=head1 SEE ALSO
+
+L<SSL_CTX_set_cert_cb(3)>,
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_verify_result - get result of peer certificate verification
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_get_verify_result(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_verify_result() returns the result of the verification of the
+X509 certificate presented by the peer, if any.
+
+=head1 NOTES
+
+SSL_get_verify_result() can only return one error code while the verification
+of a certificate can fail because of many reasons at the same time. Only
+the last verification error that occurred during the processing is available
+from SSL_get_verify_result().
+
+The verification result is part of the established session and is restored
+when a session is reused.
+
+=head1 BUGS
+
+If no peer certificate was presented, the returned result code is
+X509_V_OK. This is because no verification error occurred, it does however
+not indicate success. SSL_get_verify_result() is only useful in connection
+with L<SSL_get_peer_certificate(3)>.
+
+=head1 RETURN VALUES
+
+The following return values can currently occur:
+
+=over 4
+
+=item X509_V_OK
+
+The verification succeeded or no peer certificate was presented.
+
+=item Any other value
+
+Documented in L<verify(1)>.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_set_verify_result(3)>,
+L<SSL_get_peer_certificate(3)>,
+L<verify(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_get_version, SSL_is_dtls - get the protocol information of a connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_get_version(const SSL *ssl);
+
+ int SSL_is_dtls(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_version() returns the name of the protocol used for the
+connection B<ssl>.
+
+SSL_is_dtls() returns one if the connection is using DTLS, zero if not.
+
+=head1 RETURN VALUES
+
+SSL_get_version() returns one of the following strings:
+
+=over 4
+
+=item SSLv3
+
+The connection uses the SSLv3 protocol.
+
+=item TLSv1
+
+The connection uses the TLSv1.0 protocol.
+
+=item TLSv1.1
+
+The connection uses the TLSv1.1 protocol.
+
+=item TLSv1.2
+
+The connection uses the TLSv1.2 protocol.
+
+=item unknown
+
+This indicates that no version has been set (no connection established).
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 HISTORY
+
+SSL_is_dtls() was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_library_init, OpenSSL_add_ssl_algorithms,
+- initialize SSL library by registering algorithms
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_library_init(void);
+
+ int OpenSSL_add_ssl_algorithms(void);
+
+=head1 DESCRIPTION
+
+SSL_library_init() registers the available SSL/TLS ciphers and digests.
+
+OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init() and is
+implemented as a macro.
+
+=head1 NOTES
+
+SSL_library_init() must be called before any other action takes place.
+SSL_library_init() is not reentrant.
+
+=head1 WARNING
+
+SSL_library_init() adds ciphers and digests used directly and indirectly by
+SSL/TLS.
+
+=head1 RETURN VALUES
+
+SSL_library_init() always returns "1", so it is safe to discard the return
+value.
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<RAND_add(3)>
+
+=head1 HISTORY
+
+The SSL_library_init() and OpenSSL_add_ssl_algorithms() functions were
+deprecated in OpenSSL 1.1.0 by OPENSSL_init_ssl().
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_load_client_CA_file - load certificate names from file
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
+
+=head1 DESCRIPTION
+
+SSL_load_client_CA_file() reads certificates from B<file> and returns
+a STACK_OF(X509_NAME) with the subject names found.
+
+=head1 NOTES
+
+SSL_load_client_CA_file() reads a file of PEM formatted certificates and
+extracts the X509_NAMES of the certificates found. While the name suggests
+the specific usage as support function for
+L<SSL_CTX_set_client_CA_list(3)>,
+it is not limited to CA certificates.
+
+=head1 EXAMPLES
+
+Load names of CAs from file and use it as a client CA list:
+
+ SSL_CTX *ctx;
+ STACK_OF(X509_NAME) *cert_names;
+
+ ...
+ cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
+ if (cert_names != NULL)
+ SSL_CTX_set_client_CA_list(ctx, cert_names);
+ else
+ error_handling();
+ ...
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+The operation failed, check out the error stack for the reason.
+
+=item Pointer to STACK_OF(X509_NAME)
+
+Pointer to the subject names of the successfully read certificates.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>,
+L<SSL_CTX_set_client_CA_list(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_new, SSL_up_ref - create a new SSL structure for a connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL *SSL_new(SSL_CTX *ctx);
+ int SSL_up_ref(SSL *s);
+
+=head1 DESCRIPTION
+
+SSL_new() creates a new B<SSL> structure which is needed to hold the
+data for a TLS/SSL connection. The new structure inherits the settings
+of the underlying context B<ctx>: connection method,
+options, verification settings, timeout settings. An B<SSL> structure is
+reference counted. Creating an B<SSL> structure for the first time increments
+the reference count. Freeing it (using SSL_free) decrements it. When the
+reference count drops to zero, any memory or resources allocated to the B<SSL>
+structure are freed. SSL_up_ref() increments the reference count for an
+existing B<SSL> structure.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+The creation of a new SSL structure failed. Check the error stack to
+find out the reason.
+
+=item Pointer to an SSL structure
+
+The return value points to an allocated SSL structure.
+
+SSL_up_ref() returns 1 for success and 0 for failure.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_free(3)>, L<SSL_clear(3)>,
+L<SSL_CTX_set_options(3)>,
+L<SSL_get_SSL_CTX(3)>,
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_pending, SSL_has_pending - check for readable bytes buffered in an
+SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_pending(const SSL *ssl);
+ int SSL_has_pending(const SSL *s);
+
+=head1 DESCRIPTION
+
+Data is received in whole blocks known as records from the peer. A whole record
+is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
+read by the application via a call to L<SSL_read(3)>.
+
+SSL_pending() returns the number of bytes which have been processed, buffered
+and are available inside B<ssl> for immediate read.
+
+If the B<SSL> object's I<read_ahead> flag is set (see
+L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
+record) may have been read containing more TLS/SSL records. This also applies to
+DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
+additional bytes will be buffered by OpenSSL but will remain unprocessed until
+they are needed. As these bytes are still in an unprocessed state SSL_pending()
+will ignore them. Therefore it is possible for no more bytes to be readable from
+the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
+to return 0, even though readable application data bytes are available (because
+the data is in unprocessed buffered records).
+
+SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
+unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
+return 1, and then a subsequent call to SSL_read() to return no data because the
+unprocessed buffered data when processed yielded no application data (for
+example this can happen during renegotiation). It is also possible in this
+scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()
+call because the buffered and unprocessed data is not yet processable (e.g.
+because OpenSSL has only received a partial record so far).
+
+=head1 RETURN VALUES
+
+SSL_pending() returns the number of buffered and processed application data
+bytes that are pending and are available for immediate read. SSL_has_pending()
+returns 1 if there is buffered record data in the SSL object and 0 otherwise.
+
+=head1 SEE ALSO
+
+L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
+L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>
+
+=head1 HISTORY
+
+The SSL_has_pending() function was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_read - read bytes from a TLS/SSL connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_read(SSL *ssl, void *buf, int num);
+
+=head1 DESCRIPTION
+
+SSL_read() tries to read B<num> bytes from the specified B<ssl> into the
+buffer B<buf>.
+
+=head1 NOTES
+
+If necessary, SSL_read() will negotiate a TLS/SSL session, if
+not already explicitly performed by L<SSL_connect(3)> or
+L<SSL_accept(3)>. If the
+peer requests a re-negotiation, it will be performed transparently during
+the SSL_read() operation. The behaviour of SSL_read() depends on the
+underlying BIO.
+
+For the transparent negotiation to succeed, the B<ssl> must have been
+initialized to client or server mode. This is being done by calling
+L<SSL_set_connect_state(3)> or SSL_set_accept_state()
+before the first call to an SSL_read() or L<SSL_write(3)>
+function.
+
+SSL_read() works based on the SSL/TLS records. The data are received in
+records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
+record has been completely received, it can be processed (decryption and
+check of integrity). Therefore data that was not retrieved at the last
+call of SSL_read() can still be buffered inside the SSL layer and will be
+retrieved on the next call to SSL_read(). If B<num> is higher than the
+number of bytes buffered, SSL_read() will return with the bytes buffered.
+If no more bytes are in the buffer, SSL_read() will trigger the processing
+of the next record. Only when the record has been received and processed
+completely, SSL_read() will return reporting success. At most the contents
+of the record will be returned. As the size of an SSL/TLS record may exceed
+the maximum packet size of the underlying transport (e.g. TCP), it may
+be necessary to read several packets from the transport layer before the
+record is complete and SSL_read() can succeed.
+
+If the underlying BIO is B<blocking>, SSL_read() will only return, once the
+read operation has been finished or an error occurred, except when a
+renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
+This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
+L<SSL_CTX_set_mode(3)> call.
+
+If the underlying BIO is B<non-blocking>, SSL_read() will also return
+when the underlying BIO could not satisfy the needs of SSL_read()
+to continue the operation. In this case a call to
+L<SSL_get_error(3)> with the
+return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
+call to SSL_read() can also cause write operations! The calling process
+then must repeat the call after taking appropriate action to satisfy the
+needs of SSL_read(). The action depends on the underlying BIO. When using a
+non-blocking socket, nothing is to be done, but select() can be used to check
+for the required condition. When using a buffering BIO, like a BIO pair, data
+must be written into or retrieved out of the BIO before being able to continue.
+
+L<SSL_pending(3)> can be used to find out whether there
+are buffered bytes available for immediate retrieval. In this case
+SSL_read() can be called without blocking or actually receiving new
+data from the underlying socket.
+
+=head1 WARNING
+
+When an SSL_read() operation has to be repeated because of
+B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
+with the same arguments.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item E<gt>0
+
+The read operation was successful; the return value is the number of
+bytes actually read from the TLS/SSL connection.
+
+=item Z<>0
+
+The read operation was not successful. The reason may either be a clean
+shutdown due to a "close notify" alert sent by the peer (in which case
+the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set
+(see L<SSL_shutdown(3)>,
+L<SSL_set_shutdown(3)>). It is also possible, that
+the peer simply shut down the underlying transport and the shutdown is
+incomplete. Call SSL_get_error() with the return value B<ret> to find out,
+whether an error occurred or the connection was shut down cleanly
+(SSL_ERROR_ZERO_RETURN).
+
+=item E<lt>0
+
+The read operation was not successful, because either an error occurred
+or action must be taken by the calling process. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_write(3)>,
+L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
+L<SSL_connect(3)>, L<SSL_accept(3)>
+L<SSL_set_connect_state(3)>,
+L<SSL_pending(3)>,
+L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
+L<ssl(3)>, L<bio(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_rstate_string(SSL *ssl);
+ const char *SSL_rstate_string_long(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_rstate_string() returns a 2 letter string indicating the current read state
+of the SSL object B<ssl>.
+
+SSL_rstate_string_long() returns a string indicating the current read state of
+the SSL object B<ssl>.
+
+=head1 NOTES
+
+When performing a read operation, the SSL/TLS engine must parse the record,
+consisting of header and body. When working in a blocking environment,
+SSL_rstate_string[_long]() should always return "RD"/"read done".
+
+This function should only seldom be needed in applications.
+
+=head1 RETURN VALUES
+
+SSL_rstate_string() and SSL_rstate_string_long() can return the following
+values:
+
+=over 4
+
+=item "RH"/"read header"
+
+The header of the record is being evaluated.
+
+=item "RB"/"read body"
+
+The body of the record is being evaluated.
+
+=item "RD"/"read done"
+
+The record has been completely processed.
+
+=item "unknown"/"unknown"
+
+The read state is unknown. This should never happen.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_session_reused - query whether a reused session was negotiated during handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_session_reused(SSL *ssl);
+
+=head1 DESCRIPTION
+
+Query, whether a reused session was negotiated during the handshake.
+
+=head1 NOTES
+
+During the negotiation, a client can propose to reuse a session. The server
+then looks up the session in its cache. If both client and server agree
+on the session, it will be reused and a flag is being set that can be
+queried by the application.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+A new session was negotiated.
+
+=item Z<>1
+
+A session was reused.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_set_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername -
+SSL server verification parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_set1_host(SSL *s, const char *hostname);
+ int SSL_add1_host(SSL *s, const char *hostname);
+ void SSL_set_hostflags(SSL *s, unsigned int flags);
+ const char *SSL_get0_peername(SSL *s);
+
+=head1 DESCRIPTION
+
+These functions configure server hostname checks in the SSL client.
+
+SSL_set1_host() sets the expected DNS hostname to B<name> clearing
+any previously specified host name or names. If B<name> is NULL,
+or the empty string the list of hostnames is cleared, and name
+checks are not performed on the peer certificate. When a non-empty
+B<name> is specified, certificate verification automatically checks
+the peer hostname via L<X509_check_host(3)> with B<flags> as specified
+via SSL_set_hostflags(). Clients that enable DANE TLSA authentication
+via L<SSL_dane_enable(3)> should leave it to that function to set
+the primary reference identifier of the peer, and should not call
+SSL_set1_host().
+
+SSL_add1_host() adds B<name> as an additional reference identifier
+that can match the peer's certificate. Any previous names set via
+SSL_set1_host() or SSL_add1_host() are retained, no change is made
+if B<name> is NULL or empty. When multiple names are configured,
+the peer is considered verified when any name matches. This function
+is required for DANE TLSA in the presence of service name indirection
+via CNAME, MX or SRV records as specified in RFC7671, RFC7672 or
+RFC7673.
+
+SSL_set_hostflags() sets the B<flags> that will be passed to
+L<X509_check_host(3)> when name checks are applicable, by default
+the B<flags> value is 0. See L<X509_check_host(3)> for the list
+of available flags and their meaning.
+
+SSL_get0_peername() returns the DNS hostname or subject CommonName
+from the peer certificate that matched one of the reference
+identifiers. When wildcard matching is not disabled, the name
+matched in the peer certificate may be a wildcard name. When one
+of the reference identifiers configured via SSL_set1_host() or
+SSL_add1_host() starts with ".", which indicates a parent domain prefix
+rather than a fixed name, the matched peer name may be a sub-domain
+of the reference identifier. The returned string is allocated by
+the library and is no longer valid once the associated B<ssl> handle
+is cleared or freed, or a renegotiation takes place. Applications
+must not free the return value.
+
+SSL clients are advised to use these functions in preference to
+explicitly calling L<X509_check_host(3)>. Hostname checks are out
+of scope with the RFC7671 DANE-EE(3) certificate usage, and the
+internal check will be suppressed as appropriate when DANE is
+enabled.
+
+=head1 RETURN VALUES
+
+SSL_set1_host() and SSL_add1_host() return 1 for success and 0 for
+failure.
+
+SSL_get0_peername() returns NULL if peername verification is not
+applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
+matched. Otherwise, it returns the matched peername. To determine
+whether verification succeeded call L<SSL_get_verify_result(3)>.
+
+=head1 EXAMPLE
+
+Suppose "smtp.example.com" is the MX host of the domain "example.com".
+The calls below will arrange to match either the MX hostname or the
+destination domain name in the SMTP server certificate. Wildcards
+are supported, but must match the entire label. The actual name
+matched in the certificate (which might be a wildcard) is retrieved,
+and must be copied by the application if it is to be retained beyond
+the lifetime of the SSL connection.
+
+ SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
+ if (!SSL_set1_host(ssl, "smtp.example.com")) {
+ /* handle error */
+ }
+ if (!SSL_add1_host(ssl, "example.com")) {
+ /* handle error */
+ }
+
+ /* XXX: Perform SSL_connect() handshake and handle errors here */
+
+ if (SSL_get_verify_result(ssl) == X509_V_OK) {
+ const char *peername = SSL_get0_peername(ssl);
+
+ if (peername != NULL) {
+ /* Name checks were in scope and matched the peername */
+ }
+ }
+
+=head1 SEE ALSO
+
+L<X509_check_host(3)>,
+L<SSL_get_verify_result(3)>.
+L<SSL_dane_enable(3)>.
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);
+ void SSL_set0_rbio(SSL *s, BIO *rbio);
+ void SSL_set0_wbio(SSL *s, BIO *wbio);
+
+=head1 DESCRIPTION
+
+SSL_set0_rbio() connects the BIO B<rbio> for the read operations of the B<ssl>
+object. The SSL engine inherits the behaviour of B<rbio>. If the BIO is
+non-blocking then the B<ssl> object will also have non-blocking behaviour. This
+function transfers ownership of B<rbio> to B<ssl>. It will be automatically
+freed using L<BIO_free_all(3)> when the B<ssl> is freed. On calling this
+function, any existing B<rbio> that was previously set will also be freed via a
+call to L<BIO_free_all(3)> (this includes the case where the B<rbio> is set to
+the same value as previously).
+
+SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects
+the BIO B<wbio> for the write operations of the B<ssl> object. Note that if the
+rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take
+ownership of one reference. Therefore it may be necessary to increment the
+number of references available using L<BIO_up_ref(3)> before calling the set0
+functions.
+
+SSL_set_bio() does a similar job as SSL_set0_rbio() and SSL_set0_wbio() except
+that it connects both the B<rbio> and the B<wbio> at the same time. This
+function transfers the ownership of B<rbio> and B<wbio> to B<ssl> except that
+the rules for this are much more complex. For this reason this function is
+considered a legacy function and SSL_set0_rbio() and SSL_set0_wbio() should be
+used in preference. The ownership rules are as follows:
+
+=over 4
+
+=item
+
+If neither the rbio or wbio have changed from their previous values then nothing
+is done.
+
+=item
+
+If the rbio and wbio parameters are different and both are different to their
+previously set values then one reference is consumed for the rbio and one
+reference is consumed for the wbio.
+
+=item
+
+If the rbio and wbio parameters are the same and the rbio is not the same as the
+previously set value then one reference is consumed.
+
+=item
+
+If the rbio and wbio parameters are the same and the rbio is the same as the
+previously set value, then no additional references are consumed.
+
+=item
+
+If the rbio and wbio parameters are different and the rbio is the same as the
+previously set value then one reference is consumbed for the wbio and no
+references are consumed for the rbio.
+
+=item
+
+If the rbio and wbio parameters are different and the wbio is the same as the
+previously set value and the old rbio and wbio values were the same as each
+other then one reference is consumed for the rbio and no references are consumed
+for the wbio.
+
+=item
+
+If the rbio and wbio parameters are different and the wbio is the same as the
+previously set value and the old rbio and wbio values were different to each
+other then one reference is consumed for the rbio and one reference is consumed
+for the wbio.
+
+=back
+
+=head1 RETURN VALUES
+
+SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail.
+
+=head1 SEE ALSO
+
+L<SSL_get_rbio(3)>,
+L<SSL_connect(3)>, L<SSL_accept(3)>,
+L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>
+
+=head1 HISTORY
+
+SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_connect_state, SSL_set_accept_state - prepare SSL object to work in client or server mode
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_connect_state(SSL *ssl);
+
+ void SSL_set_accept_state(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_set_connect_state() sets B<ssl> to work in client mode.
+
+SSL_set_accept_state() sets B<ssl> to work in server mode.
+
+=head1 NOTES
+
+When the SSL_CTX object was created with L<SSL_CTX_new(3)>,
+it was either assigned a dedicated client method, a dedicated server
+method, or a generic method, that can be used for both client and
+server connections. (The method might have been changed with
+L<SSL_CTX_set_ssl_version(3)> or
+SSL_set_ssl_method().)
+
+When beginning a new handshake, the SSL engine must know whether it must
+call the connect (client) or accept (server) routines. Even though it may
+be clear from the method chosen, whether client or server mode was
+requested, the handshake routines must be explicitly set.
+
+When using the L<SSL_connect(3)> or
+L<SSL_accept(3)> routines, the correct handshake
+routines are automatically set. When performing a transparent negotiation
+using L<SSL_write(3)> or L<SSL_read(3)>, the
+handshake routines must be explicitly set in advance using either
+SSL_set_connect_state() or SSL_set_accept_state().
+
+=head1 RETURN VALUES
+
+SSL_set_connect_state() and SSL_set_accept_state() do not return diagnostic
+information.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_new(3)>, L<SSL_CTX_new(3)>,
+LL<SSL_connect(3)>, L<SSL_accept(3)>,
+L<SSL_write(3)>, L<SSL_read(3)>,
+L<SSL_do_handshake(3)>,
+L<SSL_CTX_set_ssl_version(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_set_fd(SSL *ssl, int fd);
+ int SSL_set_rfd(SSL *ssl, int fd);
+ int SSL_set_wfd(SSL *ssl, int fd);
+
+=head1 DESCRIPTION
+
+SSL_set_fd() sets the file descriptor B<fd> as the input/output facility
+for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the
+socket file descriptor of a network connection.
+
+When performing the operation, a B<socket BIO> is automatically created to
+interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine
+inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will
+also have non-blocking behaviour.
+
+If there was already a BIO connected to B<ssl>, BIO_free() will be called
+(for both the reading and writing side, if different).
+
+SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only
+for the read channel or the write channel, which can be set independently.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The operation failed. Check the error stack to find out why.
+
+=item Z<>1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_fd(3)>, L<SSL_set_bio(3)>,
+L<SSL_connect(3)>, L<SSL_accept(3)>,
+L<SSL_shutdown(3)>, L<ssl(3)> , L<bio(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_set_session(SSL *ssl, SSL_SESSION *session);
+
+=head1 DESCRIPTION
+
+SSL_set_session() sets B<session> to be used when the TLS/SSL connection
+is to be established. SSL_set_session() is only useful for TLS/SSL clients.
+When the session is set, the reference count of B<session> is incremented
+by 1. If the session is not reused, the reference count is decremented
+again during SSL_connect(). Whether the session was reused can be queried
+with the L<SSL_session_reused(3)> call.
+
+If there is already a session set inside B<ssl> (because it was set with
+SSL_set_session() before or because the same B<ssl> was already used for
+a connection), SSL_SESSION_free() will be called for that session. If that old
+session is still B<open>, it is considered bad and will be removed from the
+session cache (if used). A session is considered open, if L<SSL_shutdown(3)> was
+not called for the connection (or at least L<SSL_set_shutdown(3)> was used to
+set the SSL_SENT_SHUTDOWN state).
+
+=head1 NOTES
+
+SSL_SESSION objects keep internal link information about the session cache
+list, when being inserted into one SSL_CTX object's session cache.
+One SSL_SESSION object, regardless of its reference count, must therefore
+only be used with one SSL_CTX object (and the SSL objects created
+from this SSL_CTX object).
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The operation failed; check the error stack to find out the reason.
+
+=item Z<>1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_SESSION_free(3)>,
+L<SSL_get_session(3)>,
+L<SSL_session_reused(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_shutdown(SSL *ssl, int mode);
+
+ int SSL_get_shutdown(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_set_shutdown() sets the shutdown state of B<ssl> to B<mode>.
+
+SSL_get_shutdown() returns the shutdown mode of B<ssl>.
+
+=head1 NOTES
+
+The shutdown state of an ssl connection is a bitmask of:
+
+=over 4
+
+=item Z<>0
+
+No shutdown setting, yet.
+
+=item SSL_SENT_SHUTDOWN
+
+A "close notify" shutdown alert was sent to the peer, the connection is being
+considered closed and the session is closed and correct.
+
+=item SSL_RECEIVED_SHUTDOWN
+
+A shutdown alert was received form the peer, either a normal "close notify"
+or a fatal error.
+
+=back
+
+SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time.
+
+The shutdown state of the connection is used to determine the state of
+the ssl session. If the session is still open, when
+L<SSL_clear(3)> or L<SSL_free(3)> is called,
+it is considered bad and removed according to RFC2246.
+The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN
+(according to the TLS RFC, it is acceptable to only send the "close notify"
+alert but to not wait for the peer's answer, when the underlying connection
+is closed).
+SSL_set_shutdown() can be used to set this state without sending a
+close alert to the peer (see L<SSL_shutdown(3)>).
+
+If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set,
+for setting SSL_SENT_SHUTDOWN the application must however still call
+L<SSL_shutdown(3)> or SSL_set_shutdown() itself.
+
+=head1 RETURN VALUES
+
+SSL_set_shutdown() does not return diagnostic information.
+
+SSL_get_shutdown() returns the current setting.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_shutdown(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_clear(3)>, L<SSL_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_set_verify_result - override result of peer certificate verification
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_verify_result(SSL *ssl, long verify_result);
+
+=head1 DESCRIPTION
+
+SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the
+result of the verification of the X509 certificate presented by the peer,
+if any.
+
+=head1 NOTES
+
+SSL_set_verify_result() overrides the verification result. It only changes
+the verification result of the B<ssl> object. It does not become part of the
+established session, so if the session is to be reused later, the original
+value will reappear.
+
+The valid codes for B<verify_result> are documented in L<verify(1)>.
+
+=head1 RETURN VALUES
+
+SSL_set_verify_result() does not provide a return value.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_get_verify_result(3)>,
+L<SSL_get_peer_certificate(3)>,
+L<verify(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_shutdown - shut down a TLS/SSL connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_shutdown(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
+"close notify" shutdown alert to the peer.
+
+=head1 NOTES
+
+SSL_shutdown() tries to send the "close notify" shutdown alert to the peer.
+Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
+a currently open session is considered closed and good and will be kept in the
+session cache for further reuse.
+
+The shutdown procedure consists of 2 steps: the sending of the "close notify"
+shutdown alert and the reception of the peer's "close notify" shutdown
+alert. According to the TLS standard, it is acceptable for an application
+to only send its shutdown alert and then close the underlying connection
+without waiting for the peer's response (this way resources can be saved,
+as the process can already terminate or serve another connection).
+When the underlying connection shall be used for more communications, the
+complete shutdown procedure (bidirectional "close notify" alerts) must be
+performed, so that the peers stay synchronized.
+
+SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step
+behaviour.
+
+=over 4
+
+=item When the application is the first party to send the "close notify"
+alert, SSL_shutdown() will only send the alert and then set the
+SSL_SENT_SHUTDOWN flag (so that the session is considered good and will
+be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional
+shutdown is enough (the underlying connection shall be closed anyway), this
+first call to SSL_shutdown() is sufficient. In order to complete the
+bidirectional shutdown handshake, SSL_shutdown() must be called again.
+The second call will make SSL_shutdown() wait for the peer's "close notify"
+shutdown alert. On success, the second call to SSL_shutdown() will return
+with 1.
+
+=item If the peer already sent the "close notify" alert B<and> it was
+already processed implicitly inside another function
+(L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
+SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN
+flag and will immediately return with 1.
+Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
+SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
+
+=back
+
+It is therefore recommended, to check the return value of SSL_shutdown()
+and call SSL_shutdown() again, if the bidirectional shutdown is not yet
+complete (return value of the first call is 0).
+
+The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
+
+If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
+handshake step has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
+when the underlying BIO could not satisfy the needs of SSL_shutdown()
+to continue the handshake. In this case a call to SSL_get_error() with the
+return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_shutdown().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+SSL_shutdown() can be modified to only set the connection to "shutdown"
+state but not actually send the "close notify" alert messages,
+see L<SSL_CTX_set_quiet_shutdown(3)>.
+When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
+and return 1.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item Z<>0
+
+The shutdown is not yet finished. Call SSL_shutdown() for a second time,
+if a bidirectional shutdown shall be performed.
+The output of L<SSL_get_error(3)> may be misleading, as an
+erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
+
+=item Z<>1
+
+The shutdown was successfully completed. The "close notify" alert was sent
+and the peer's "close notify" alert was received.
+
+=item E<lt>0
+
+The shutdown was not successful because a fatal error occurred either
+at the protocol level or a connection failure occurred. It can also occur if
+action is need to continue the operation for non-blocking BIOs.
+Call L<SSL_get_error(3)> with the return value B<ret>
+to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_connect(3)>,
+L<SSL_accept(3)>, L<SSL_set_shutdown(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_clear(3)>, L<SSL_free(3)>,
+L<ssl(3)>, L<bio(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_state_string(const SSL *ssl);
+ const char *SSL_state_string_long(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_state_string() returns a 6 letter string indicating the current state
+of the SSL object B<ssl>.
+
+SSL_state_string_long() returns a string indicating the current state of
+the SSL object B<ssl>.
+
+=head1 NOTES
+
+During its use, an SSL objects passes several states. The state is internally
+maintained. Querying the state information is not very informative before
+or when a connection has been established. It however can be of significant
+interest during the handshake.
+
+When using non-blocking sockets, the function call performing the handshake
+may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition,
+so that SSL_state_string[_long]() may be called.
+
+For both blocking or non-blocking sockets, the details state information
+can be used within the info_callback function set with the
+SSL_set_info_callback() call.
+
+=head1 RETURN VALUES
+
+Detailed description of possible states to be included later.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_CTX_set_info_callback(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup,
+SSL_want_async, SSL_want_async_job - obtain state information TLS/SSL I/O
+operation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_want(const SSL *ssl);
+ int SSL_want_nothing(const SSL *ssl);
+ int SSL_want_read(const SSL *ssl);
+ int SSL_want_write(const SSL *ssl);
+ int SSL_want_x509_lookup(const SSL *ssl);
+ int SSL_want_async(const SSL *ssl);
+ int SSL_want_async_job(const SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_want() returns state information for the SSL object B<ssl>.
+
+The other SSL_want_*() calls are shortcuts for the possible states returned
+by SSL_want().
+
+=head1 NOTES
+
+SSL_want() examines the internal state information of the SSL object. Its
+return values are similar to that of L<SSL_get_error(3)>.
+Unlike L<SSL_get_error(3)>, which also evaluates the
+error queue, the results are obtained by examining an internal state flag
+only. The information must therefore only be used for normal operation under
+non-blocking I/O. Error conditions are not handled and must be treated
+using L<SSL_get_error(3)>.
+
+The result returned by SSL_want() should always be consistent with
+the result of L<SSL_get_error(3)>.
+
+=head1 RETURN VALUES
+
+The following return values can currently occur for SSL_want():
+
+=over 4
+
+=item SSL_NOTHING
+
+There is no data to be written or to be read.
+
+=item SSL_WRITING
+
+There are data in the SSL buffer that must be written to the underlying
+B<BIO> layer in order to complete the actual SSL_*() operation.
+A call to L<SSL_get_error(3)> should return
+SSL_ERROR_WANT_WRITE.
+
+=item SSL_READING
+
+More data must be read from the underlying B<BIO> layer in order to
+complete the actual SSL_*() operation.
+A call to L<SSL_get_error(3)> should return
+SSL_ERROR_WANT_READ.
+
+=item SSL_X509_LOOKUP
+
+The operation did not complete because an application callback set by
+SSL_CTX_set_client_cert_cb() has asked to be called again.
+A call to L<SSL_get_error(3)> should return
+SSL_ERROR_WANT_X509_LOOKUP.
+
+=item SSL_ASYNC_PAUSED
+
+An asynchronous operation partially completed and was then paused. See
+L<SSL_get_all_async_fds(3)>. A call to L<SSL_get_error(3)> should return
+SSL_ERROR_WANT_ASYNC.
+
+=item SSL_ASYNC_NO_JOBS
+
+The asynchronous job could not be started because there were no async jobs
+available in the pool (see ASYNC_init_thread(3)). A call to L<SSL_get_error(3)>
+should return SSL_ERROR_WANT_ASYNC_JOB.
+
+=back
+
+SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup(),
+SSL_want_async() and SSL_want_async_job() return 1, when the corresponding
+condition is true or 0 otherwise.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<err(3)>, L<SSL_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL_write - write bytes to a TLS/SSL connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_write(SSL *ssl, const void *buf, int num);
+
+=head1 DESCRIPTION
+
+SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
+B<ssl> connection.
+
+=head1 NOTES
+
+If necessary, SSL_write() will negotiate a TLS/SSL session, if
+not already explicitly performed by L<SSL_connect(3)> or
+L<SSL_accept(3)>. If the
+peer requests a re-negotiation, it will be performed transparently during
+the SSL_write() operation. The behaviour of SSL_write() depends on the
+underlying BIO.
+
+For the transparent negotiation to succeed, the B<ssl> must have been
+initialized to client or server mode. This is being done by calling
+L<SSL_set_connect_state(3)> or SSL_set_accept_state()
+before the first call to an L<SSL_read(3)> or SSL_write() function.
+
+If the underlying BIO is B<blocking>, SSL_write() will only return, once the
+write operation has been finished or an error occurred, except when a
+renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
+This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
+L<SSL_CTX_set_mode(3)> call.
+
+If the underlying BIO is B<non-blocking>, SSL_write() will also return,
+when the underlying BIO could not satisfy the needs of SSL_write()
+to continue the operation. In this case a call to
+L<SSL_get_error(3)> with the
+return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
+call to SSL_write() can also cause read operations! The calling process
+then must repeat the call after taking appropriate action to satisfy the
+needs of SSL_write(). The action depends on the underlying BIO. When using a
+non-blocking socket, nothing is to be done, but select() can be used to check
+for the required condition. When using a buffering BIO, like a BIO pair, data
+must be written into or retrieved out of the BIO before being able to continue.
+
+SSL_write() will only return with success, when the complete contents
+of B<buf> of length B<num> has been written. This default behaviour
+can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
+L<SSL_CTX_set_mode(3)>. When this flag is set,
+SSL_write() will also return with success, when a partial write has been
+successfully completed. In this case the SSL_write() operation is considered
+completed. The bytes are sent and a new SSL_write() operation with a new
+buffer (with the already sent bytes removed) must be started.
+A partial write is performed with the size of a message block, which is
+16kB for SSLv3/TLSv1.
+
+=head1 WARNING
+
+When an SSL_write() operation has to be repeated because of
+B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
+with the same arguments.
+
+When calling SSL_write() with num=0 bytes to be sent the behaviour is
+undefined.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item E<gt>0
+
+The write operation was successful, the return value is the number of
+bytes actually written to the TLS/SSL connection.
+
+=item Z<>0
+
+The write operation was not successful. Probably the underlying connection
+was closed. Call SSL_get_error() with the return value B<ret> to find out,
+whether an error occurred or the connection was shut down cleanly
+(SSL_ERROR_ZERO_RETURN).
+
+=item E<lt>0
+
+The write operation was not successful, because either an error occurred
+or action must be taken by the calling process. Call SSL_get_error() with the
+return value B<ret> to find out the reason.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_error(3)>, L<SSL_read(3)>,
+L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
+L<SSL_connect(3)>, L<SSL_accept(3)>
+L<SSL_set_connect_state(3)>,
+L<ssl(3)>, L<bio(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+UI, UI_METHOD,
+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, - 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);
+
+ char *UI_construct_prompt(UI *ui_method,
+ const char *object_desc, const char *object_name);
+
+ void *UI_add_user_data(UI *ui, void *user_data);
+ void *UI_get0_user_data(UI *ui);
+
+ const char *UI_get0_result(UI *ui, int i);
+
+ int UI_process(UI *ui);
+
+ int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
+
+ void UI_set_default_method(const UI_METHOD *meth);
+ const UI_METHOD *UI_get_default_method(void);
+ const UI_METHOD *UI_get_method(UI *ui);
+ const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
+
+ UI_METHOD *UI_OpenSSL(void);
+
+=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)>), 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.
+If B<ui> is NULL nothing is done.
+
+UI_add_input_string() and UI_add_verify_string() add a prompt to the UI,
+as well as flags and a result buffer and the desired minimum and maximum
+sizes of the result, not counting the final NUL character. The given
+information is used to prompt for information, for example a password,
+and to verify a password (i.e. having the user enter it twice and check
+that the same string was entered twice). UI_add_verify_string() takes
+and extra argument that should be a pointer to the result buffer of the
+input string that it's supposed to verify, or verification will fail.
+
+UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered
+in a boolean way, with a single character for yes and a different character
+for no. A set of characters that can be used to cancel the prompt is given
+as well. The prompt itself is divided in two, one part being the
+descriptive text (given through the I<prompt> argument) and one describing
+the possible answers (given through the I<action_desc> argument).
+
+UI_add_info_string() and UI_add_error_string() add strings that are shown at
+the same time as the prompt for extra information or to show an error string.
+The difference between the two is only conceptual. With the builtin method,
+there's no technical difference between them. Other methods may make a
+difference between them, however.
+
+The flags currently supported are B<UI_INPUT_FLAG_ECHO>, which is relevant for
+UI_add_input_string() and will have the users response be echoed (when
+prompting for a password, this flag should obviously not be used, and
+B<UI_INPUT_FLAG_DEFAULT_PWD>, which means that a default password of some
+sort will be used (completely depending on the application and the UI
+method).
+
+UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(),
+UI_dup_info_string() and UI_dup_error_string() are basically the same
+as their UI_add counterparts, except that they make their own copies
+of all strings.
+
+UI_construct_prompt() is a helper function that can be used to create
+a prompt from two pieces of information: an description and a name.
+The default constructor (if there is none provided by the method used)
+creates a string "Enter I<description> for I<name>:". With the
+description "pass phrase" and the file name "foo.key", that becomes
+"Enter pass phrase for foo.key:". Other methods may create whatever
+string and may include encodings that will be processed by the other
+method functions.
+
+UI_add_user_data() adds a piece of memory for the method to use at any
+time. The builtin UI method doesn't care about this info. Note that several
+calls to this function doesn't add data, it replaces the previous blob
+with the one given as argument.
+
+UI_get0_user_data() retrieves the data that has last been given to the
+UI with UI_add_user_data().
+
+UI_get0_result() returns a pointer to the result buffer associated with
+the information indexed by I<i>.
+
+UI_process() goes through the information given so far, does all the printing
+and prompting and returns.
+
+UI_ctrl() adds extra control for the application author. For now, it
+understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process()
+print the OpenSSL error stack as part of processing the UI, and
+B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can
+be used again or not.
+
+UI_set_default_method() changes the default UI method to the one given.
+
+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 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get0_extensions, X509_CRL_get0_extensions, X509_REVOKED_get0_extensions,
+X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d,
+X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i,
+X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i,
+X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509v3.h>
+
+ void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit,
+ int *idx);
+ int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value,
+ int crit, unsigned long flags);
+
+ void *X509V3_EXT_d2i(X509_EXTENSION *ext);
+ X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext);
+
+ void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx);
+ int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit,
+ unsigned long flags);
+
+ void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx);
+ int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit,
+ unsigned long flags);
+
+ void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx);
+ int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit,
+ unsigned long flags);
+
+ const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
+ const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl);
+ const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r);
+
+=head1 DESCRIPTION
+
+X509V3_get_ext_d2i() looks for an extension with OID B<nid> in the extensions
+B<x> and, if found, decodes it. If B<idx> is B<NULL> then only one
+occurrence of an extension is permissible otherwise the first extension after
+index B<*idx> is returned and B<*idx> updated to the location of the extension.
+If B<crit> is not B<NULL> then B<*crit> is set to a status value: -2 if the
+extension occurs multiple times (this is only returned if B<idx> is B<NULL>),
+-1 if the extension could not be found, 0 if the extension is found and is
+not critical and 1 if critical. A pointer to an extension specific structure
+or B<NULL> is returned.
+
+X509V3_add1_i2d() adds extension B<value> to STACK B<*x> (allocating a new
+STACK if necessary) using OID B<nid> and criticality B<crit> according
+to B<flags>.
+
+X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension
+B<ext> and returns a pointer to an extension specific structure or B<NULL>
+if the extension could not be decoded (invalid syntax or not supported).
+
+X509V3_EXT_i2d() encodes the extension specific structure B<ext>
+with OID B<ext_nid> and criticality B<crit>.
+
+X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of
+certificate B<x>, they are otherwise identical to X509V3_get_d2i() and
+X509V3_add_i2d().
+
+X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions
+of CRL B<crl>, they are otherwise identical to X509V3_get_d2i() and
+X509V3_add_i2d().
+
+X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the
+extensions of B<X509_REVOKED> structure B<r> (i.e for CRL entry extensions),
+they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d().
+
+X509_get0_extensions(), X509_CRL_get0_extensions() and
+X509_REVOKED_get0_extensions() return a stack of all the extensions
+of a certificate a CRL or a CRL entry respectively.
+
+=head1 NOTES
+
+In almost all cases an extension can occur at most once and multiple
+occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>.
+
+The B<flags> parameter may be one of the following values.
+
+B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does
+not already exist. An error is returned if the extension does already
+exist.
+
+B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension
+already exists.
+
+B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise appends
+a new extension.
+
+B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists
+otherwise returns an error.
+
+B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does
+not already exist. An error B<is not> returned if the extension does already
+exist.
+
+B<X509V3_ADD_DELETE> extension B<nid> is deleted: no new extension is added.
+
+If B<X509V3_ADD_SILENT> is ored with B<flags>: any error returned will not
+be added to the error queue.
+
+The function X509V3_get_d2i() will return B<NULL> if the extension is not
+found, occurs multiple times or cannot be decoded. It is possible to
+determine the precise reason by checking the value of B<*crit>.
+
+=head1 SUPPORTED EXTENSIONS
+
+The following sections contain a list of all supported extensions
+including their name and NID.
+
+=head2 PKIX Certificate Extensions
+
+The following certificate extensions are defined in PKIX standards such as
+RFC5280.
+
+ Basic Constraints NID_basic_constraints
+ Key Usage NID_key_usage
+ Extended Key Usage NID_ext_key_usage
+
+ Subject Key Identifier NID_subject_key_identifier
+ Authority Key Identifier NID_authority_key_identifier
+
+ Private Key Usage Period NID_private_key_usage_period
+
+ Subject Alternative Name NID_subject_alt_name
+ Issuer Alternative Name NID_issuer_alt_name
+
+ Authority Information Access NID_info_access
+ Subject Information Access NID_sinfo_access
+
+ Name Constraints NID_name_constraints
+
+ Certificate Policies NID_certificate_policies
+ Policy Mappings NID_policy_mappings
+ Policy Constraints NID_policy_constraints
+ Inhibit Any Policy NID_inhibit_any_policy
+
+ TLS Feature NID_tlsfeature
+
+=head2 Netscape Certificate Extensions
+
+The following are (largely obsolete) Netscape certificate extensions.
+
+ Netscape Cert Type NID_netscape_cert_type
+ Netscape Base Url NID_netscape_base_url
+ Netscape Revocation Url NID_netscape_revocation_url
+ Netscape CA Revocation Url NID_netscape_ca_revocation_url
+ Netscape Renewal Url NID_netscape_renewal_url
+ Netscape CA Policy Url NID_netscape_ca_policy_url
+ Netscape SSL Server Name NID_netscape_ssl_server_name
+ Netscape Comment NID_netscape_comment
+
+=head2 Miscellaneous Certificate Extensions
+
+ Strong Extranet ID NID_sxnet
+ Proxy Certificate Information NID_proxyCertInfo
+
+=head2 PKIX CRL Extensions
+
+The following are CRL extensions from PKIX standards such as RFC5280.
+
+ CRL Number NID_crl_number
+ CRL Distribution Points NID_crl_distribution_points
+ Delta CRL Indicator NID_delta_crl
+ Freshest CRL NID_freshest_crl
+ Invalidity Date NID_invalidity_date
+ Issuing Distribution Point NID_issuing_distribution_point
+
+The following are CRL entry extensions from PKIX standards such as RFC5280.
+
+ CRL Reason Code NID_crl_reason
+ Certificate Issuer NID_certificate_issuer
+
+=head2 OCSP Extensions
+
+ OCSP Nonce NID_id_pkix_OCSP_Nonce
+ OCSP CRL ID NID_id_pkix_OCSP_CrlID
+ Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses
+ OCSP No Check NID_id_pkix_OCSP_noCheck
+ OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff
+ OCSP Service Locator NID_id_pkix_OCSP_serviceLocator
+ Hold Instruction Code NID_hold_instruction_code
+
+=head2 Certificate Transparency Extensions
+
+The following extensions are used by certificate transparency, RFC6962
+
+ CT Precertificate SCTs NID_ct_precert_scts
+ CT Certificate SCTs NID_ct_cert_scts
+
+=head1 RETURN VALUES
+
+X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension
+specific structure of B<NULL> if an error occurs.
+
+X509V3_EXT_i2d() returns a pointer to an B<X509_EXTENSION> structure
+or B<NULL> if an error occurs.
+
+X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it
+fails due to a non-fatal error (extension not found, already exists,
+cannot be encoded) or -1 due to a fatal error such as a memory allocation
+failure.
+
+X509_get0_extensions(), X509_CRL_get0_extensions() and
+X509_REVOKED_get0_extensions() return a stack of extensions. They return
+NULL if no extensions are present.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0, X509_ALGOR_set_md, X509_ALGOR_cmp - AlgorithmIdentifier functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_ALGOR *X509_ALGOR_dup(X509_ALGOR *alg);
+ int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *aobj, int ptype, void *pval);
+ void X509_ALGOR_get0(const ASN1_OBJECT **paobj, int *pptype,
+ const void **ppval, const X509_ALGOR *alg);
+ void X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md);
+ int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b);
+
+=head1 DESCRIPTION
+
+X509_ALGOR_dup() returns a copy of B<alg>.
+
+X509_ALGOR_set0() sets the algorithm OID of B<alg> to B<aobj> and the
+associated parameter type to B<ptype> with value B<pval>. If B<ptype> is
+B<V_ASN1_UNDEF> the parameter is omitted, otherwise B<ptype> and B<pval> have
+the same meaning as the B<type> and B<value> parameters to ASN1_TYPE_set().
+All the supplied parameters are used internally so must B<NOT> be freed after
+this call.
+
+X509_ALGOR_get0() is the inverse of X509_ALGOR_set0(): it returns the
+algorithm OID in B<*paobj> and the associated parameter in B<*pptype>
+and B<*ppval> from the B<AlgorithmIdentifier> B<alg>.
+
+X509_ALGOR_set_md() sets the B<AlgorithmIdentifier> B<alg> to appropriate
+values for the message digest B<md>.
+
+X509_ALGOR_cmp() compares B<a> and B<b> and returns 0 if they have identical
+encodings and non-zero otherwise.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_CRL_get0_by_serial, X509_CRL_get0_by_cert, X509_CRL_get_REVOKED,
+X509_REVOKED_get0_serialNumber, X509_REVOKED_get0_revocationDate,
+X509_REVOKED_set_serialNumber, X509_REVOKED_set_revocationDate,
+X509_CRL_add0_revoked, X509_CRL_sort - CRL revoked entry utility
+functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_CRL_get0_by_serial(X509_CRL *crl,
+ X509_REVOKED **ret, ASN1_INTEGER *serial);
+ int X509_CRL_get0_by_cert(X509_CRL *crl, X509_REVOKED **ret, X509 *x);
+
+ STACK_OF(X509_REVOKED) *X509_CRL_get_REVOKED(X509_CRL *crl);
+
+ const ASN1_INTEGER *X509_REVOKED_get0_serialNumber(const X509_REVOKED *r);
+ const ASN1_TIME *X509_REVOKED_get0_revocationDate(const X509_REVOKED *r);
+
+ int X509_REVOKED_set_serialNumber(X509_REVOKED *r, ASN1_INTEGER *serial);
+ int X509_REVOKED_set_revocationDate(X509_REVOKED *r, ASN1_TIME *tm);
+
+ int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
+
+ int X509_CRL_sort(X509_CRL *crl);
+
+=head1 DESCRIPTION
+
+X509_CRL_get0_by_serial() attempts to find a revoked entry in B<crl> for
+serial number B<serial>. If it is successful it sets B<*ret> to the internal
+pointer of the matching entry, as a result B<*ret> must not be freed up
+after the call.
+
+X509_CRL_get0_by_cert() is similar to X509_get0_by_serial() except it
+looks for a revoked entry using the serial number of certificate B<x>.
+
+X509_CRL_get_REVOKED() returns an internal pointer to a stack of all
+revoked entries for B<crl>.
+
+X509_REVOKED_get0_serialNumber() returns an internal pointer to the
+serial number of B<r>.
+
+X509_REVOKED_get0_revocationDate() returns an internal pointer to the
+revocation date of B<r>.
+
+X509_REVOKED_set_serialNumber() sets the serial number of B<r> to B<serial>.
+The supplied B<serial> pointer is not used internally so it should be
+freed up after use.
+
+X509_REVOKED_set_revocationDate() sets the revocation date of B<r> to
+B<tm>. The supplied B<tm> pointer is not used internally so it should be
+freed up after use.
+
+X509_CRL_add0_revoked() appends revoked entry B<rev> to CRL B<crl>. The
+pointer B<rev> is used internally so it must not be freed up after the call:
+it is freed when the parent CRL is freed.
+
+X509_CRL_sort() sorts the revoked entries of B<crl> into ascending serial
+number order.
+
+=head1 NOTES
+
+Applications can determine the number of revoked entries returned by
+X509_CRL_get_revoked() using sk_X509_REVOKED_num() and examine each one
+in turn using sk_X509_REVOKED_value().
+
+=head1 RETURN VALUES
+
+X509_CRL_get0_by_serial(), X509_CRL_get0_by_cert(),
+X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(),
+X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for
+failure.
+
+X509_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> pointer.
+
+X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> value.
+
+X509_CRL_get_REVOKED() returns a STACK of revoked entries.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_EXTENSION_set_object, X509_EXTENSION_set_critical,
+X509_EXTENSION_set_data, X509_EXTENSION_create_by_NID,
+X509_EXTENSION_create_by_OBJ, X509_EXTENSION_get_object,
+X509_EXTENSION_get_critical, X509_EXTENSION_get_data - extension utility
+functions
+
+=head1 SYNOPSIS
+
+ int X509_EXTENSION_set_object(X509_EXTENSION *ex, const ASN1_OBJECT *obj);
+ int X509_EXTENSION_set_critical(X509_EXTENSION *ex, int crit);
+ int X509_EXTENSION_set_data(X509_EXTENSION *ex, ASN1_OCTET_STRING *data);
+
+ X509_EXTENSION *X509_EXTENSION_create_by_NID(X509_EXTENSION **ex,
+ int nid, int crit,
+ ASN1_OCTET_STRING *data);
+ X509_EXTENSION *X509_EXTENSION_create_by_OBJ(X509_EXTENSION **ex,
+ const ASN1_OBJECT *obj, int crit,
+ ASN1_OCTET_STRING *data);
+
+ ASN1_OBJECT *X509_EXTENSION_get_object(X509_EXTENSION *ex);
+ int X509_EXTENSION_get_critical(const X509_EXTENSION *ex);
+ ASN1_OCTET_STRING *X509_EXTENSION_get_data(X509_EXTENSION *ne);
+
+=head1 DESCRIPTION
+
+X509_EXTENSION_set_object() sets the extension type of B<ex> to B<obj>. The
+B<obj> pointer is duplicated internally so B<obj> should be freed up after use.
+
+X509_EXTENSION_set_critical() sets the criticality of B<ex> to B<crit>. If
+B<crit> is zero the extension in non-critical otherwise it is critical.
+
+X509_EXTENSION_set_data() sets the data in extension B<ex> to B<data>. The
+B<data> pointer is duplicated internally.
+
+X509_EXTENSION_create_by_NID() creates an extension of type B<nid>,
+criticality B<crit> using data B<data>. The created extension is returned and
+written to B<*ex> reusing or allocating a new extension if necessary so B<*ex>
+should either be B<NULL> or a valid B<X509_EXTENSION> structure it must
+B<not> be an uninitialised pointer.
+
+X509_EXTENSION_create_by_OBJ() is identical to X509_EXTENSION_create_by_NID()
+except it creates and extension using B<obj> instead of a NID.
+
+X509_EXTENSION_get_object() returns the extension type of B<ex> as an
+B<ASN1_OBJECT> pointer. The returned pointer is an internal value which must
+not be freed up.
+
+X509_EXTENSION_get_critical() returns the criticality of extension B<ex> it
+returns B<1> for critical and B<0> for non-critical.
+
+X509_EXTENSION_get_data() returns the data of extension B<ex>. The returned
+pointer is an internal value which must not be freed up.
+
+=head1 NOTES
+
+These functions manipulate the contents of an extension directly. Most
+applications will want to parse or encode and add an extension: they should
+use the extension encode and decode functions instead such as
+X509_add1_ext_i2d() and X509_get_ext_d2i().
+
+The B<data> associated with an extension is the extension encoding in an
+B<ASN1_OCTET_STRING> structure.
+
+=head1 RETURN VALUES
+
+X509_EXTENSION_set_object() X509_EXTENSION_set_critical() and
+X509_EXTENSION_set_data() return B<1> for success and B<0> for failure.
+
+X509_EXTENSION_create_by_NID() and X509_EXTENSION_create_by_OBJ() return
+an B<X509_EXTENSION> pointer or B<NULL> if an error occurs.
+
+X509_EXTENSION_get_object() returns an B<ASN1_OBJECT> pointer.
+
+X509_EXTENSION_get_critical() returns B<0> for non-critical and B<1> for
+critical.
+
+X509_EXTENSION_get_data() returns an B<ASN1_OCTET_STRING> pointer.
+
+=head1 SEE ALSO
+
+L<X509V3_get_d2i(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_LOOKUP_hash_dir, X509_LOOKUP_file,
+X509_load_cert_file,
+X509_load_crl_file,
+X509_load_cert_crl_file - Default OpenSSL certificate
+lookup methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
+ X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
+
+ int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
+ int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
+ int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
+
+=head1 DESCRIPTION
+
+B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate
+lookup methods to use with B<X509_STORE>, provided by OpenSSL library.
+
+Users of the library typically do not need to create instances of these
+methods manually, they would be created automatically by
+L<X509_STORE_load_locations(3)> or
+L<SSL_CTX_load_verify_locations(3)>
+functions.
+
+Internally loading of certificates and CRLs is implemented via functions
+B<X509_load_cert_crl_file>, B<X509_load_cert_file> and
+B<X509_load_crl_file>. These functions support parameter I<type>, which
+can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and
+B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified
+file into memory cache of B<X509_STORE> objects which given B<ctx>
+parameter is associated with.
+
+Functions B<X509_load_cert_file> and
+B<X509_load_crl_file> can load both PEM and DER formats depending of
+type value. Because DER format cannot contain more than one certificate
+or CRL object (while PEM can contain several concatenated PEM objects)
+B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to
+B<X509_load_cert_file>.
+
+Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions
+to load default certificate store file (see
+L<X509_STORE_set_default_paths(3)>.
+
+
+Functions return number of objects loaded from file or 0 in case of
+error.
+
+Both methods support adding several certificate locations into one
+B<X509_STORE>.
+
+This page documents certificate store formats used by these methods and
+caching policy.
+
+=head2 File Method
+
+The B<X509_LOOKUP_file> method loads all the certificates or CRLs
+present in a file into memory at the time the file is added as a
+lookup source.
+
+File format is ASCII text which contains concatenated PEM certificates
+and CRLs.
+
+This method should be used by applications which work with a small
+set of CAs.
+
+=head2 Hashed Directory Method
+
+B<X509_LOOKUP_hash_dir> is a more advanced method, which loads
+certificates and CRLs on demand, and caches them in memory once
+they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs
+upon each lookup, so that newer CRLs are as soon as they appear in
+the directory.
+
+The directory should contain one certificate or CRL per file in PEM format,
+with a file name of the form I<hash>.I<N> for a certificate, or
+I<hash>.B<r>I<N> for a CRL.
+The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied
+to the subject name for certificates or issuer name for CRLs.
+The hash can also be obtained via the B<-hash> option of the L<x509(1)> or
+L<crl(1)> commands.
+
+The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is
+incremented consecutively for each certificate or CRL with the same I<hash>
+value.
+Gaps in the sequence numbers are not supported, it is assumed that there are no
+more objects with the same hash beyond the first missing number in the
+sequence.
+
+Sequence numbers make it possible for the directory to contain multiple
+certificates with same subject name hash value.
+For example, it is possible to have in the store several certificates with same
+subject or several CRLs with same issuer (and, for example, different validity
+period).
+
+When checking for new CRLs once one CRL for given hash value is
+loaded, hash_dir lookup method checks only for certificates with
+sequence number greater than that of the already cached CRL.
+
+Note that the hash algorithm used for subject name hashing changed in OpenSSL
+1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
+0.9.8 to 1.0.0.
+
+OpenSSL includes a L<c_rehash(1)> utility which creates symlinks with correct
+hashed names for all files with .pem suffix in a given directory.
+
+=head1 SEE ALSO
+
+L<PEM_read_PrivateKey(3)>,
+L<d2i_X509_bio(3)>,
+L<X509_STORE_load_locations(3)>,
+L<X609_store_add_lookup(3)>,
+L<SSL_CTX_load_verify_locations(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data,
+X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data,
+X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID,
+X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ ASN1_OBJECT * X509_NAME_ENTRY_get_object(const X509_NAME_ENTRY *ne);
+ ASN1_STRING * X509_NAME_ENTRY_get_data(const X509_NAME_ENTRY *ne);
+
+ int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, const ASN1_OBJECT *obj);
+ int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len);
+
+ X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len);
+ X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type, const unsigned char *bytes, int len);
+ X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len);
+
+=head1 DESCRIPTION
+
+X509_NAME_ENTRY_get_object() retrieves the field name of B<ne> in
+and B<ASN1_OBJECT> structure.
+
+X509_NAME_ENTRY_get_data() retrieves the field value of B<ne> in
+and B<ASN1_STRING> structure.
+
+X509_NAME_ENTRY_set_object() sets the field name of B<ne> to B<obj>.
+
+X509_NAME_ENTRY_set_data() sets the field value of B<ne> to string type
+B<type> and value determined by B<bytes> and B<len>.
+
+X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID()
+and X509_NAME_ENTRY_create_by_OBJ() create and return an
+B<X509_NAME_ENTRY> structure.
+
+=head1 NOTES
+
+X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be
+used to examine an B<X509_NAME_ENTRY> function as returned by
+X509_NAME_get_entry() for example.
+
+X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(),
+and X509_NAME_ENTRY_create_by_OBJ() create and return an
+
+X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(),
+X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data()
+are seldom used in practice because B<X509_NAME_ENTRY> structures
+are almost always part of B<X509_NAME> structures and the
+corresponding B<X509_NAME> functions are typically used to
+create and add new entries in a single operation.
+
+The arguments of these functions support similar options to the similarly
+named ones of the corresponding B<X509_NAME> functions such as
+X509_NAME_add_entry_by_txt(). So for example B<type> can be set to
+B<MBSTRING_ASC> but in the case of X509_set_data() the field name must be
+set first so the relevant field information can be looked up internally.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>,
+L<OBJ_nid2obj(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
+X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set);
+
+ int X509_NAME_add_entry_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len, int loc, int set);
+
+ int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, const unsigned char *bytes, int len, int loc, int set);
+
+ int X509_NAME_add_entry(X509_NAME *name, const X509_NAME_ENTRY *ne, int loc, int set);
+
+ X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc);
+
+=head1 DESCRIPTION
+
+X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and
+X509_NAME_add_entry_by_NID() add a field whose name is defined
+by a string B<field>, an object B<obj> or a NID B<nid> respectively.
+The field value to be added is in B<bytes> of length B<len>. If
+B<len> is -1 then the field length is calculated internally using
+strlen(bytes).
+
+The type of field is determined by B<type> which can either be a
+definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a
+standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is
+added to a position determined by B<loc> and B<set>.
+
+X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne>
+to B<name>. The new entry is added to a position determined by B<loc>
+and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after
+the call.
+
+X509_NAME_delete_entry() deletes an entry from B<name> at position
+B<loc>. The deleted entry is returned and must be freed up.
+
+=head1 NOTES
+
+The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8>
+is strongly recommended for the B<type> parameter. This allows the
+internal code to correctly determine the type of the field and to
+apply length checks according to the relevant standards. This is
+done using ASN1_STRING_set_by_NID().
+
+If instead an ASN1 type is used no checks are performed and the
+supplied data in B<bytes> is used directly.
+
+In X509_NAME_add_entry_by_txt() the B<field> string represents
+the field name using OBJ_txt2obj(field, 0).
+
+The B<loc> and B<set> parameters determine where a new entry should
+be added. For almost all applications B<loc> can be set to -1 and B<set>
+to 0. This adds a new entry to the end of B<name> as a single valued
+RelativeDistinguishedName (RDN).
+
+B<loc> actually determines the index where the new entry is inserted:
+if it is -1 it is appended.
+
+B<set> determines how the new type is added. If it is zero a
+new RDN is created.
+
+If B<set> is -1 or 1 it is added to the previous or next RDN
+structure respectively. This will then be a multivalued RDN:
+since multivalues RDNs are very seldom used B<set> is almost
+always set to zero.
+
+=head1 EXAMPLES
+
+Create an B<X509_NAME> structure:
+
+"C=UK, O=Disorganized Organization, CN=Joe Bloggs"
+
+ X509_NAME *nm;
+ nm = X509_NAME_new();
+ if (nm == NULL)
+ /* Some error */
+ if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC,
+ "UK", -1, -1, 0))
+ /* Error */
+ if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC,
+ "Disorganized Organization", -1, -1, 0))
+ /* Error */
+ if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC,
+ "Joe Bloggs", -1, -1, 0))
+ /* Error */
+
+=head1 RETURN VALUES
+
+X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
+X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
+success of 0 if an error occurred.
+
+X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
+structure of B<NULL> if an error occurred.
+
+=head1 BUGS
+
+B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a
+different algorithm to determine field types. Since this form does
+not understand multicharacter types, performs no length checks and
+can result in invalid field types its use is strongly discouraged.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_NAME_get0_der - get X509_NAME DER encoding
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_NAME_get0_der(X509_NAME *nm, const unsigned char **pder,
+ size_t *pderlen)
+
+
+=head1 DESCRIPTION
+
+The function X509_NAME_get0_der() returns an internal pointer to the
+encoding of an B<X509_NAME> structure in B<*pder> and consisting of
+B<*pderlen> bytes. It is useful for applications that wish to examine
+the encoding of an B<X509_NAME> structure without copying it.
+
+=head1 RETURN VALUES
+
+The function X509_NAME_get0_der() returns 1 for success and 0 if an error
+occurred.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
+X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ -
+X509_NAME lookup and enumeration functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_NAME_get_index_by_NID(X509_NAME *name, int nid, int lastpos);
+ int X509_NAME_get_index_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int lastpos);
+
+ int X509_NAME_entry_count(const X509_NAME *name);
+ X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc);
+
+ int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf, int len);
+ int X509_NAME_get_text_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, char *buf, int len);
+
+=head1 DESCRIPTION
+
+These functions allow an B<X509_NAME> structure to be examined. The
+B<X509_NAME> structure is the same as the B<Name> type defined in
+RFC2459 (and elsewhere) and used for example in certificate subject
+and issuer names.
+
+X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve
+the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>
+should initially be set to -1. If there are no more entries -1 is returned.
+If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned.
+
+X509_NAME_entry_count() returns the total number of entries in B<name>.
+
+X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name>
+corresponding to index B<loc>. Acceptable values for B<loc> run from
+0 to (X509_NAME_entry_count(name) - 1). The value returned is an
+internal pointer which must not be freed.
+
+X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve
+the "text" from the first entry in B<name> which matches B<nid> or
+B<obj>, if no such entry exists -1 is returned. At most B<len> bytes
+will be written and the text written to B<buf> will be null
+terminated. The length of the output string written is returned
+excluding the terminating null. If B<buf> is <NULL> then the amount
+of space needed in B<buf> (excluding the final null) is returned.
+
+=head1 NOTES
+
+X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are
+legacy functions which have various limitations which make them
+of minimal use in practice. They can only find the first matching
+entry and will copy the contents of the field verbatim: this can
+be highly confusing if the target is a multicharacter string type
+like a BMPString or a UTF8String.
+
+For a more general solution X509_NAME_get_index_by_NID() or
+X509_NAME_get_index_by_OBJ() should be used followed by
+X509_NAME_get_entry() on any matching indices and then the
+various B<X509_NAME_ENTRY> utility functions on the result.
+
+The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in
+the source code header files E<lt>openssl/obj_mac.hE<gt> and/or
+E<lt>openssl/objects.hE<gt>.
+
+Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
+should check for the return value of -2. Alternatively the NID validity
+can be determined first by checking OBJ_nid2obj(nid) is not NULL.
+
+=head1 EXAMPLES
+
+Process all entries:
+
+ int i;
+ X509_NAME_ENTRY *e;
+
+ for (i = 0; i < X509_NAME_entry_count(nm); i++)
+ {
+ e = X509_NAME_get_entry(nm, i);
+ /* Do something with e */
+ }
+
+Process all commonName entries:
+
+ int 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_get_index_by_NID() can also return -2 if the supplied
+NID is invalid.
+
+X509_NAME_entry_count() returns the total number of entries.
+
+X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
+requested entry or B<NULL> if the index is invalid.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print,
+X509_NAME_oneline - X509_NAME printing routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_NAME_print_ex(BIO *out, const X509_NAME *nm, int indent, unsigned long flags);
+ int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm, int indent, unsigned long flags);
+ char * X509_NAME_oneline(const X509_NAME *a, char *buf, int size);
+ int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase);
+
+=head1 DESCRIPTION
+
+X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each
+line (for multiline formats) is indented by B<indent> spaces. The output format
+can be extensively customised by use of the B<flags> parameter.
+
+X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is
+written to FILE pointer B<fp>.
+
+X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. 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)> manual page
+for UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example
+B<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used.
+
+The complete set of the flags supported by X509_NAME_print_ex() is listed below.
+
+Several options can be ored together.
+
+The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>,
+B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators
+to use. Two distinct separators are used between distinct RelativeDistinguishedName
+components and separate values in the same RDN for a multi-valued RDN. Multi-valued
+RDNs are currently very rare so the second separator will hardly ever be used.
+
+B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC>
+uses comma and plus with spaces: this is more readable that plain comma and plus.
+B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses
+spaced newline and plus respectively.
+
+If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order.
+
+The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>,
+B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will
+use the short name (e.g. CN) the long name (e.g. commonName) always
+use OID numerical form (normally OIDs are only used if the field name is not
+recognised) and no field name respectively.
+
+If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character
+separating field names and values.
+
+If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is
+printed instead of the values.
+
+If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this
+is only of use for multiline format.
+
+Additionally all the options supported by ASN1_STRING_print_ex() can be used to
+control how each field value is displayed.
+
+In addition a number options can be set for commonly used formats.
+
+B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it
+is equivalent to:
+ B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS>
+
+
+B<XN_FLAG_ONELINE> is a more readable one line format which is the same as:
+ B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN>
+
+B<XN_FLAG_MULTILINE> is a multiline format which is the same as:
+ B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN>
+
+B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally.
+
+=head1 SEE ALSO
+
+L<ASN1_STRING_print_ex(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0,
+X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp,
+i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param,
+X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_PUBKEY *X509_PUBKEY_new(void);
+ void X509_PUBKEY_free(X509_PUBKEY *a);
+
+ int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey);
+ EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key);
+ EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key);
+
+ EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length);
+ int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp);
+
+ EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a);
+ EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a);
+
+ int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey);
+ int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey);
+
+ int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj,
+ int ptype, void *pval,
+ unsigned char *penc, int penclen);
+ int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg,
+ const unsigned char **pk, int *ppklen,
+ X509_ALGOR **pa, X509_PUBKEY *pub);
+
+=head1 DESCRIPTION
+
+The B<X509_PUBKEY> structure represents the ASN.1 B<SubjectPublicKeyInfo>
+structure defined in RFC5280 and used in certificates and certificate requests.
+
+X509_PUBKEY_new() allocates and initializes an B<X509_PUBKEY> structure.
+
+X509_PUBKEY_free() frees up B<X509_PUBKEY> structure B<a>. If B<a> is NULL
+nothing is done.
+
+X509_PUBKEY_set() sets the public key in B<*x> to the public key contained
+in the B<EVP_PKEY> structure B<pkey>. If B<*x> is not NULL any existing
+public key structure will be freed.
+
+X509_PUBKEY_get0() returns the public key contained in B<key>. The returned
+value is an internal pointer which B<MUST NOT> be freed after use.
+
+X509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference
+count on the returned key is incremented so it B<MUST> be freed using
+EVP_PKEY_free() after use.
+
+d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B<EVP_PKEY> structure
+using B<SubjectPublicKeyInfo> format. They otherwise follow the conventions of
+other ASN.1 functions such as d2i_X509().
+
+d2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are
+similar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a
+B<BIO> or B<FILE> pointer.
+
+X509_PUBKEY_set0_param() sets the public key parameters of B<pub>. The
+OID associated with the algorithm is set to B<aobj>. The type of the
+algorithm parameters is set to B<type> using the structure B<pval>.
+The encoding of the public key itself is set to the B<penclen>
+bytes contained in buffer B<penc>. On success ownership of all the supplied
+parameters is passed to B<pub> so they must not be freed after the
+call.
+
+X509_PUBKEY_get0_param() retrieves the public key parameters from B<pub>,
+B<*ppkalg> is set to the associated OID and the encoding consists of
+B<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated
+AlgorithmIdentifier for the public key. If the value of any of these
+parameters is not required it can be set to B<NULL>. All of the
+retrieved pointers are internal and must not be freed after the
+call.
+
+=head1 NOTES
+
+The B<X509_PUBKEY> functions can be used to encode and decode public keys
+in a standard format.
+
+In many cases applications will not call the B<X509_PUBKEY> functions
+directly: they will instead call wrapper functions such as X509_get0_pubkey().
+
+=head1 RETURN VALUES
+
+If the allocation fails, X509_PUBKEY_new() returns B<NULL> and sets an error
+code that can be obtained by L<ERR_get_error(3)>.
+
+Otherwise it returns a pointer to the newly allocated structure.
+
+X509_PUBKEY_free() does not return a value.
+
+X509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B<EVP_PKEY>
+structure or B<NULL> if an error occurs.
+
+X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param()
+return 1 for success and 0 if an error occurred.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_get_pubkey(3)>,
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_SIG_get0, X509_SIG_getm - DigestInfo functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ void X509_SIG_get0(const X509_SIG *sig, const X509_ALGOR **palg,
+ const ASN1_OCTET_STRING **pdigest);
+ void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **palg,
+ ASN1_OCTET_STRING **pdigest,
+
+=head1 DESCRIPTION
+
+X509_SIG_get0() returns pointers to the algorithm identifier and digest
+value in B<sig>. X509_SIG_getm() is identical to X509_SIG_get0()
+except the pointers returned are not constant and can be modified:
+for example to initialise them.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_STORE_CTX_get_error, X509_STORE_CTX_set_error,
+X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth,
+X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert,
+X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain,
+X509_verify_cert_error_string - get or set certificate verification status
+information
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s);
+ int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_set_error_depth(X509_STORE_CTX *ctx, int depth);
+ X509 *X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x);
+ X509 *X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx);
+
+ STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx);
+
+ const char *X509_verify_cert_error_string(long n);
+
+=head1 DESCRIPTION
+
+These functions are typically called after X509_verify_cert() has indicated
+an error or in a verification callback to determine the nature of an error.
+
+X509_STORE_CTX_get_error() returns the error code of B<ctx>, see
+the B<ERROR CODES> section for a full description of all error codes.
+
+X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example
+it might be used in a verification callback to set an error based on additional
+checks.
+
+X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a
+non-negative integer representing where in the certificate chain the error
+occurred. If it is zero it occurred in the end entity certificate, one if
+it is the certificate which signed the end entity certificate and so on.
+
+X509_STORE_CTX_set_error_depth() sets the error B<depth>.
+This can be used in combination with X509_STORE_CTX_set_error() to set the
+depth at which an error condition was detected.
+
+X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which
+caused the error or B<NULL> if no certificate is relevant.
+
+X509_STORE_CTX_set_current_cert() sets the certificate B<x> in B<ctx> which
+caused the error.
+This value is not intended to remain valid for very long, and remains owned by
+the caller.
+It may be examined by a verification callback invoked to handle each error
+encountered during chain verification and is no longer required after such a
+callback.
+If a callback wishes the save the certificate for use after it returns, it
+needs to increment its reference count via L<X509_up_ref(3)>.
+Once such a I<saved> certificate is no longer needed it can be freed with
+L<X509_free(3)>.
+
+X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
+certificate being verified by the B<ctx>.
+
+X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous
+call to X509_verify_cert() is successful. If the call to X509_verify_cert()
+is B<not> successful the returned chain may be incomplete or invalid. The
+returned chain persists after the B<ctx> structure is freed, when it is
+no longer needed it should be free up using:
+
+ sk_X509_pop_free(chain, X509_free);
+
+X509_verify_cert_error_string() returns a human readable error string for
+verification error B<n>.
+
+=head1 RETURN VALUES
+
+X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code.
+
+X509_STORE_CTX_get_error_depth() returns a non-negative error depth.
+
+X509_STORE_CTX_get_current_cert() returns the certificate which caused the
+error or B<NULL> if no certificate is relevant to the error.
+
+X509_verify_cert_error_string() returns a human readable error string for
+verification error B<n>.
+
+=head1 ERROR CODES
+
+A list of error codes and messages is shown below. Some of the
+error codes are defined but currently never returned: these are described as
+"unused".
+
+=over 4
+
+=item B<X509_V_OK: ok>
+
+the operation was successful.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
+
+the issuer certificate could not be found: this occurs if the issuer certificate
+of an untrusted certificate cannot be found.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
+
+the CRL of a certificate could not be found.
+
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
+
+the certificate signature could not be decrypted. This means that the actual
+signature value could not be determined rather than it not matching the
+expected value, this is only meaningful for RSA keys.
+
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
+
+the CRL signature could not be decrypted: this means that the actual signature
+value could not be determined rather than it not matching the expected value.
+Unused.
+
+=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
+
+the public key in the certificate SubjectPublicKeyInfo could not be read.
+
+=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
+
+the signature of the certificate is invalid.
+
+=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
+
+the signature of the certificate is invalid.
+
+=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
+
+the certificate is not yet valid: the notBefore date is after the current time.
+
+=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
+
+the certificate has expired: that is the notAfter date is before the current time.
+
+=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
+
+the CRL is not yet valid.
+
+=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
+
+the CRL has expired.
+
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
+
+the certificate notBefore field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
+
+the certificate notAfter field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
+
+the CRL lastUpdate field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
+
+the CRL nextUpdate field contains an invalid time.
+
+=item B<X509_V_ERR_OUT_OF_MEM: out of memory>
+
+an error occurred trying to allocate memory. This should never happen.
+
+=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
+
+the passed certificate is self signed and the same certificate cannot be found
+in the list of trusted certificates.
+
+=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
+
+the certificate chain could be built up using the untrusted certificates but
+the root could not be found locally.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
+
+the issuer certificate of a locally looked up certificate could not be found.
+This normally means the list of trusted certificates is not complete.
+
+=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
+
+no signatures could be verified because the chain contains only one certificate
+and it is not self signed.
+
+=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
+
+the certificate chain length is greater than the supplied maximum depth. Unused.
+
+=item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
+
+the certificate has been revoked.
+
+=item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
+
+a CA certificate is invalid. Either it is not a CA or its extensions are not
+consistent with the supplied purpose.
+
+=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
+
+the basicConstraints path-length parameter has been exceeded.
+
+=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
+
+the supplied certificate cannot be used for the specified purpose.
+
+=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
+
+the root CA is not marked as trusted for the specified purpose.
+
+=item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
+
+the root CA is marked to reject the specified purpose.
+
+=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
+
+the current candidate issuer certificate was rejected because its subject name
+did not match the issuer name of the current certificate. This is only set
+if issuer check debugging is enabled it is used for status notification and
+is B<not> in itself an error.
+
+=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
+
+the current candidate issuer certificate was rejected because its subject key
+identifier was present and did not match the authority key identifier current
+certificate. This is only set if issuer check debugging is enabled it is used
+for status notification and is B<not> in itself an error.
+
+=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
+
+the current candidate issuer certificate was rejected because its issuer name
+and serial number was present and did not match the authority key identifier of
+the current certificate. This is only set if issuer check debugging is enabled
+it is used for status notification and is B<not> in itself an error.
+
+=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
+
+the current candidate issuer certificate was rejected because its keyUsage
+extension does not permit certificate signing. This is only set if issuer check
+debugging is enabled it is used for status notification and is B<not> in itself
+an error.
+
+=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension>
+
+A certificate extension had an invalid value (for example an incorrect
+encoding) or some value inconsistent with other extensions.
+
+
+=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension>
+
+A certificate policies extension had an invalid value (for example an incorrect
+encoding) or some value inconsistent with other extensions. This error only
+occurs if policy processing is enabled.
+
+=item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy>
+
+The verification flags were set to require and explicit policy but none was
+present.
+
+=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope>
+
+The only CRLs that could be found did not match the scope of the certificate.
+
+=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature>
+
+Some feature of a certificate extension is not supported. Unused.
+
+=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
+
+A name constraint violation occurred in the permitted subtrees.
+
+=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
+
+A name constraint violation occurred in the excluded subtrees.
+
+=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported>
+
+A certificate name constraints extension included a minimum or maximum field:
+this is not supported.
+
+=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type>
+
+An unsupported name constraint type was encountered. OpenSSL currently only
+supports directory name, DNS name, email and URI types.
+
+=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax>
+
+The format of the name constraint is not recognised: for example an email
+address format of a form not mentioned in RFC3280. This could be caused by
+a garbage extension or some new feature not currently supported.
+
+=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
+
+An error occurred when attempting to verify the CRL path. This error can only
+happen if extended CRL checking is enabled.
+
+=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
+
+an application specific error. This will never be returned unless explicitly
+set by an application.
+
+=back
+
+=head1 NOTES
+
+The above functions should be used instead of directly referencing the fields
+in the B<X509_VERIFY_CTX> structure.
+
+In versions of OpenSSL before 1.0 the current certificate returned by
+X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should
+check the return value before printing out any debugging information relating
+to the current certificate.
+
+If an unrecognised error code is passed to X509_verify_cert_error_string() the
+numerical value of the unknown code is returned in a static buffer. This is not
+thread safe but will never happen unless an invalid code is passed.
+
+=head1 SEE ALSO
+
+L<X509_verify_cert(3)>,
+L<X509_up_ref(3)>,
+L<X509_free(3)>.
+
+=head1 COPYRIGHT
+
+Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free,
+X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert,
+X509_STORE_CTX_set0_crls,
+X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
+X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param,
+X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted,
+X509_STORE_CTX_get_num_untrusted,
+X509_STORE_CTX_set_default,
+X509_STORE_CTX_set_verify
+- X509_STORE_CTX initialisation
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ X509_STORE_CTX *X509_STORE_CTX_new(void);
+ void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
+
+ int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store,
+ X509 *x509, STACK_OF(X509) *chain);
+
+ void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
+
+ void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);
+ STACK_OF(X509) *X509_STORE_CTX_get0_chain(X609_STORE_CTX *ctx);
+ void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
+ void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
+
+ X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
+ int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
+
+ STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
+
+ int X509_STORE_CTX_get_num_untrusted(X509_STORE_CTX *ctx);
+
+ typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
+ void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
+
+=head1 DESCRIPTION
+
+These functions initialise an B<X509_STORE_CTX> structure for subsequent use
+by X509_verify_cert().
+
+X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure.
+
+X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure.
+The context can then be reused with an new call to X509_STORE_CTX_init().
+
+X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx>
+is no longer valid.
+If B<ctx> is NULL nothing is done.
+
+X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation.
+It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only
+good for one call to X509_verify_cert(); if you want to verify a second
+certificate with the same B<ctx> then you must call X509_XTORE_CTX_cleanup()
+and then X509_STORE_CTX_init() again before the second call to
+X509_verify_cert(). The trusted certificate store is set to B<store>, the end
+entity certificate to be verified is set to B<x509> and a set of additional
+certificates (which will be untrusted but may be used to build the chain) in
+B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be
+B<NULL>.
+
+X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of
+B<ctx> to B<sk>. This is an alternative way of specifying trusted certificates
+instead of using an B<X509_STORE>.
+
+X509_STORE_CTX_set_cert() sets the certificate to be verified in B<ctx> to
+B<x>.
+
+X509_STORE_CTX_set0_verified_chain() sets the validated chain used
+by B<ctx> to be B<chain>.
+Ownership of the chain is transferred to B<ctx> and should not be
+free'd by the caller.
+X509_STORE_CTX_get0_chain() returns a the internal pointer used by the
+B<ctx> that contains the validated chain.
+
+X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate
+verification to B<sk>. These CRLs will only be used if CRL verification is
+enabled in the associated B<X509_VERIFY_PARAM> structure. This might be
+used where additional "useful" CRLs are supplied as part of a protocol,
+for example in a PKCS#7 structure.
+
+X509_STORE_CTX_get0_param() retrieves an internal pointer
+to the verification parameters associated with B<ctx>.
+
+X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the
+stack of untrusted certificates associated with B<ctx>.
+
+X509_STORE_CTX_set0_untrusted() sets the internal point to the stack
+of untrusted certificates associated with B<ctx> to B<sk>.
+
+X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
+to B<param>. After this call B<param> should not be used.
+
+X509_STORE_CTX_set_default() looks up and sets the default verification
+method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to
+find an appropriate set of parameters from B<name>.
+
+X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
+that were used in building the chain following a call to X509_verify_cert().
+
+X509_STORE_CTX_set_verify() provides the capability for overriding the default
+verify function. This function is responsible for verifying chain signatures and
+expiration times.
+
+A verify function is defined as an X509_STORE_CTX_verify type which has the
+following signature:
+
+ int (*verify)(X509_STORE_CTX *);
+
+This function should receive the current X509_STORE_CTX as a parameter and
+return 1 on success or 0 on failure.
+
+=head1 NOTES
+
+The certificates and CRLs in a store are used internally and should B<not>
+be freed up until after the associated B<X509_STORE_CTX> is freed.
+
+=head1 BUGS
+
+The certificates and CRLs in a context are used internally and should B<not>
+be freed up until after the associated B<X509_STORE_CTX> is freed. Copies
+should be made or reference counts increased instead.
+
+=head1 RETURN VALUES
+
+X509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an
+error occurred.
+
+X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred.
+
+X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM>
+structure or B<NULL> if an error occurred.
+
+X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(),
+X509_STORE_CTX_set0_trusted_stack(),
+X509_STORE_CTX_set_cert(),
+X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return
+values.
+
+X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred.
+
+X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
+used.
+
+=head1 SEE ALSO
+
+L<X509_verify_cert(3)>
+L<X509_VERIFY_PARAM_set_flags(3)>
+
+=head1 HISTORY
+
+X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0
+X509_STORE_CTX_get_num_untrusted() was first added to OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_STORE_CTX_get_cleanup,
+X509_STORE_CTX_get_lookup_crls,
+X509_STORE_CTX_get_lookup_certs,
+X509_STORE_CTX_get_check_policy,
+X509_STORE_CTX_get_cert_crl,
+X509_STORE_CTX_get_check_crl,
+X509_STORE_CTX_get_get_crl,
+X509_STORE_CTX_get_check_revocation,
+X509_STORE_CTX_get_check_issued,
+X509_STORE_CTX_get_get_issuer,
+X509_STORE_CTX_get_verify_cb,
+X509_STORE_CTX_set_verify_cb - get and set verification callback
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *);
+
+ X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx);
+
+ void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx,
+ X509_STORE_CTX_verify_cb verify_cb);
+
+ X509_STORE_CTX_get_issuer_fn X509_STORE_CTX_get_get_issuer(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_check_issued_fn X509_STORE_CTX_get_check_issued(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_check_revocation_fn X509_STORE_CTX_get_check_revocation(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_get_crl_fn X509_STORE_CTX_get_get_crl(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_check_crl_fn X509_STORE_CTX_get_check_crl(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_cert_crl_fn X509_STORE_CTX_get_cert_crl(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_check_policy_fn X509_STORE_CTX_get_check_policy(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_lookup_certs_fn X509_STORE_CTX_get_lookup_certs(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_lookup_crls_fn X509_STORE_CTX_get_lookup_crls(X509_STORE_CTX *ctx);
+ X509_STORE_CTX_cleanup_fn X509_STORE_CTX_get_cleanup(X509_STORE_CTX *ctx);
+
+=head1 DESCRIPTION
+
+X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to
+B<verify_cb> overwriting any existing callback.
+
+The verification callback can be used to customise the operation of certificate
+verification, either by overriding error conditions or logging errors for
+debugging purposes.
+
+However a verification callback is B<not> essential and the default operation
+is often sufficient.
+
+The B<ok> parameter to the callback indicates the value the callback should
+return to retain the default behaviour. If it is zero then an error condition
+is indicated. If it is 1 then no error occurred. If the flag
+B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the
+policy checking is complete.
+
+The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that
+is performing the verification operation. A callback can examine this
+structure and receive additional information about the error, for example
+by calling X509_STORE_CTX_get_current_cert(). Additional application data can
+be passed to the callback via the B<ex_data> mechanism.
+
+X509_STORE_CTX_get_verify_cb() returns the value of the current callback
+for the specific B<ctx>.
+
+X509_STORE_CTX_get_get_issuer(),
+X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
+X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
+X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
+X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
+and X509_STORE_CTX_get_cleanup() return the function pointers cached
+from the corresponding B<X509_STORE>, please see
+L<X509_STORE_set_verify(3)> for more information.
+
+
+=head1 WARNING
+
+In general a verification callback should B<NOT> unconditionally return 1 in
+all circumstances because this will allow verification to succeed no matter
+what the error. This effectively removes all security from the application
+because B<any> certificate (including untrusted generated ones) will be
+accepted.
+
+=head1 NOTES
+
+The verification callback can be set and inherited from the parent structure
+performing the operation. In some cases (such as S/MIME verification) the
+B<X509_STORE_CTX> structure is created and destroyed internally and the
+only way to set a custom verification callback is by inheriting it from the
+associated B<X509_STORE>.
+
+=head1 RETURN VALUES
+
+X509_STORE_CTX_set_verify_cb() does not return a value.
+
+=head1 EXAMPLES
+
+Default callback operation:
+
+ int verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
+ return ok;
+ }
+
+Simple example, suppose a certificate in the chain is expired and we wish
+to continue after this error:
+
+ int verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
+ /* Tolerate certificate expiration */
+ if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED)
+ return 1;
+ /* Otherwise don't override */
+ return ok;
+ }
+
+More complex example, we don't wish to continue after B<any> certificate has
+expired just one specific case:
+
+ int verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
+ int err = X509_STORE_CTX_get_error(ctx);
+ X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);
+ if (err == X509_V_ERR_CERT_HAS_EXPIRED)
+ {
+ if (check_is_acceptable_expired_cert(err_cert)
+ return 1;
+ }
+ return ok;
+ }
+
+Full featured logging callback. In this case the B<bio_err> is assumed to be
+a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using
+B<ex_data>.
+
+ int verify_callback(int ok, X509_STORE_CTX *ctx)
+ {
+ X509 *err_cert;
+ int err, depth;
+
+ err_cert = X509_STORE_CTX_get_current_cert(ctx);
+ err = X509_STORE_CTX_get_error(ctx);
+ depth = X509_STORE_CTX_get_error_depth(ctx);
+
+ BIO_printf(bio_err, "depth=%d ", depth);
+ if (err_cert)
+ {
+ X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert),
+ 0, XN_FLAG_ONELINE);
+ BIO_puts(bio_err, "\n");
+ }
+ else
+ BIO_puts(bio_err, "<no cert>\n");
+ if (!ok)
+ BIO_printf(bio_err, "verify error:num=%d:%s\n", err,
+ X509_verify_cert_error_string(err));
+ switch (err)
+ {
+ case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
+ BIO_puts(bio_err, "issuer= ");
+ X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert),
+ 0, XN_FLAG_ONELINE);
+ BIO_puts(bio_err, "\n");
+ break;
+ case X509_V_ERR_CERT_NOT_YET_VALID:
+ case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
+ BIO_printf(bio_err, "notBefore=");
+ ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert));
+ BIO_printf(bio_err, "\n");
+ break;
+ case X509_V_ERR_CERT_HAS_EXPIRED:
+ case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
+ BIO_printf(bio_err, "notAfter=");
+ ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert));
+ BIO_printf(bio_err, "\n");
+ break;
+ case X509_V_ERR_NO_EXPLICIT_POLICY:
+ policies_print(bio_err, ctx);
+ break;
+ }
+ if (err == X509_V_OK && ok == 2)
+ /* print out policies */
+
+ BIO_printf(bio_err, "verify return:%d\n", ok);
+ return(ok);
+ }
+
+=head1 SEE ALSO
+
+L<X509_STORE_CTX_get_error(3)>
+L<X509_STORE_set_verify_cb_func(3)>
+L<X509_STORE_CTX_get_ex_new_index(3)>
+
+=head1 HISTORY
+
+X509_STORE_CTX_get_get_issuer(),
+X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
+X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
+X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
+X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
+and X509_STORE_CTX_get_cleanup() were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_STORE_get0_param, X509_STORE_set1_param,
+X509_STORE_get0_objects - X509_STORE setter and getter functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ X509_VERIFY_PARAM *X509_STORE_get0_param(X509_STORE *ctx);
+ int X509_STORE_set1_param(X509_STORE *ctx, X509_VERIFY_PARAM *pm);
+ STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(X509_STORE *ctx);
+
+=head1 DESCRIPTION
+
+X509_STORE_set1_param() sets the verification parameters
+to B<pm> for B<ctx>.
+
+X509_STORE_get0_param() retrieves an internal pointer to the verification
+parameters for B<ctx>. The returned pointer must not be freed by the
+calling application
+
+X509_STORE_get0_objects() retrieve an internal pointer to the store's
+X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The
+returned pointer must not be freed by the calling application.
+
+
+=head1 RETURN VALUES
+
+X509_STORE_get0_param() returns a pointer to an
+B<X509_VERIFY_PARAM> structure.
+
+X509_STORE_set1_param() returns 1 for success and 0 for failure.
+
+X509_STORE_get0_objects() returns a pointer to a stack of B<X509_OBJECT>.
+
+=head1 SEE ALSO
+
+L<X509_STORE_new(3)>
+
+=head1 HISTORY
+
+B<X509_STORE_get0_param> and B<X509_STORE_get0_objects> were added in
+OpenSSL version 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_STORE_new, X509_STORE_up_ref, X509_STORE_free, X509_STORE_lock,
+X509_STORE_unlock - X509_STORE allocation, freeing and locking functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ X509_STORE *X509_STORE_new(void);
+ void X509_STORE_free(X509_STORE *v);
+ int X509_STORE_lock(X509_STORE *v);
+ int X509_STORE_unlock(X509_STORE *v);
+ int X509_STORE_up_ref(X509_STORE *v);
+
+=head1 DESCRIPTION
+
+The X509_STORE_new() function returns a new X509_STORE.
+
+X509_STORE_up_ref() increments the reference count associated with the
+X509_STORE object.
+
+X509_STORE_lock() locks the store from modification by other threads,
+X509_STORE_unlock() locks it.
+
+X509_STORE_free() frees up a single X509_STORE object.
+
+=head1 RETURN VALUES
+
+X509_STORE_new() returns a newly created X509_STORE or NULL if the call fails.
+
+X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() return
+1 for success and 0 for failure.
+
+X509_STORE_free() does not return values.
+
+=head1 SEE ALSO
+
+L<X509_STORE_set_verify_cb_func(3)>
+L<X509_STORE_get0_param(3)>
+
+=head1 HISTORY
+
+The X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock()
+functions were added in OpenSSL 1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_STORE_set_lookup_crls_cb,
+X509_STORE_set_verify_func,
+X509_STORE_get_cleanup,
+X509_STORE_set_cleanup,
+X509_STORE_get_lookup_crls,
+X509_STORE_set_lookup_crls,
+X509_STORE_get_lookup_certs,
+X509_STORE_set_lookup_certs,
+X509_STORE_get_check_policy,
+X509_STORE_set_check_policy,
+X509_STORE_get_cert_crl,
+X509_STORE_set_cert_crl,
+X509_STORE_get_check_crl,
+X509_STORE_set_check_crl,
+X509_STORE_get_get_crl,
+X509_STORE_set_get_crl,
+X509_STORE_get_check_revocation,
+X509_STORE_set_check_revocation,
+X509_STORE_get_check_issued,
+X509_STORE_set_check_issued,
+X509_STORE_get_get_issuer,
+X509_STORE_set_get_issuer,
+X509_STORE_CTX_get_verify,
+X509_STORE_set_verify,
+X509_STORE_get_verify_cb,
+X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb
+- set verification callback
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ typedef int (*X509_STORE_CTX_verify_cb)(int ok, X509_STORE_CTX *ctx);
+ typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *ctx);
+ typedef int (*X509_STORE_CTX_get_issuer_fn)(X509 **issuer,
+ X509_STORE_CTX *ctx, X509 *x);
+ typedef int (*X509_STORE_CTX_check_issued_fn)(X509_STORE_CTX *ctx,
+ X509 *x, X509 *issuer);
+ typedef int (*X509_STORE_CTX_check_revocation_fn)(X509_STORE_CTX *ctx);
+ typedef int (*X509_STORE_CTX_get_crl_fn)(X509_STORE_CTX *ctx,
+ X509_CRL **crl, X509 *x);
+ typedef int (*X509_STORE_CTX_check_crl_fn)(X509_STORE_CTX *ctx, X509_CRL *crl);
+ typedef int (*X509_STORE_CTX_cert_crl_fn)(X509_STORE_CTX *ctx,
+ X509_CRL *crl, X509 *x);
+ typedef int (*X509_STORE_CTX_check_policy_fn)(X509_STORE_CTX *ctx);
+ typedef STACK_OF(X509) *(*X509_STORE_CTX_lookup_certs_fn)(X509_STORE_CTX *ctx,
+ X509_NAME *nm);
+ typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(X509_STORE_CTX *ctx,
+ X509_NAME *nm);
+ typedef int (*X509_STORE_CTX_cleanup_fn)(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_verify_cb(X509_STORE *ctx,
+ X509_STORE_CTX_verify_cb verify_cb);
+ X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify_fn verify);
+ X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_get_issuer(X509_STORE *ctx,
+ X509_STORE_CTX_get_issuer_fn get_issuer);
+ X509_STORE_CTX_get_issuer_fn X509_STORE_get_get_issuer(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_check_issued(X509_STORE *ctx,
+ X509_STORE_CTX_check_issued_fn check_issued);
+ X509_STORE_CTX_check_issued_fn X509_STORE_get_check_issued(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_check_revocation(X509_STORE *ctx,
+ X509_STORE_CTX_check_revocation_fn check_revocation);
+ X509_STORE_CTX_check_revocation_fn X509_STORE_get_check_revocation(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_get_crl(X509_STORE *ctx,
+ X509_STORE_CTX_get_crl_fn get_crl);
+ X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_check_crl(X509_STORE *ctx,
+ X509_STORE_CTX_check_crl_fn check_crl);
+ X509_STORE_CTX_check_crl_fn X509_STORE_get_check_crl(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_cert_crl(X509_STORE *ctx,
+ X509_STORE_CTX_cert_crl_fn cert_crl);
+ X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_check_policy(X509_STORE *ctx,
+ X509_STORE_CTX_check_policy_fn check_policy);
+ X509_STORE_CTX_check_policy_fn X509_STORE_get_check_policy(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_lookup_certs(X509_STORE *ctx,
+ X509_STORE_CTX_lookup_certs_fn lookup_certs);
+ X509_STORE_CTX_lookup_certs_fn X509_STORE_get_lookup_certs(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_lookup_crls(X509_STORE *ctx,
+ X509_STORE_CTX_lookup_crls_fn lookup_crls);
+ X509_STORE_CTX_lookup_crls_fn X509_STORE_get_lookup_crls(X509_STORE_CTX *ctx);
+
+ void X509_STORE_set_cleanup(X509_STORE *ctx,
+ X509_STORE_CTX_cleanup_fn cleanup);
+ X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(X509_STORE_CTX *ctx);
+
+ /* Aliases */
+ void X509_STORE_set_verify_cb_func(X509_STORE *st,
+ X509_STORE_CTX_verify_cb verify_cb);
+ void X509_STORE_set_verify_func(X509_STORE *ctx,
+ X509_STORE_CTX_verify_fn verify);
+ void X509_STORE_set_lookup_crls_cb(X509_STORE *ctx,
+ X509_STORE_CTX_lookup_crls_fn lookup_crls);
+
+=head1 DESCRIPTION
+
+X509_STORE_set_verify_cb() sets the verification callback of B<ctx> to
+B<verify_cb> overwriting the previous callback.
+The callback assigned with this function becomes a default for the one
+that can be assigned directly to the corresponding B<X509_STORE_CTX>,
+please see L<X509_STORE_CTX_set_verify_cb(3)> for further information.
+
+X509_STORE_set_verify() sets the final chain verification function for
+B<ctx> to B<verify>.
+Its purpose is to go through the chain of certificates and check that
+all signatures are valid and that the current time is within the
+limits of each certificate's first and last validity time.
+The final chain verification functions must return 0 on failure and 1
+on success.
+I<If no chain verification function is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_get_issuer() sets the function to get the issuer
+certificate that verifies the given certificate B<x>.
+When found, the issuer certificate must be assigned to B<*issuer>.
+This function must return 0 on failure and 1 on success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_check_issued() sets the function to check that a given
+certificate B<x> is issued with the issuer certificate B<issuer>.
+This function must return 0 on failure (among others if B<x> hasn't
+been issued with B<issuer>) and 1 on success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_check_revocation() sets the revocation checking
+function.
+Its purpose is to look through the final chain and check the
+revocation status for each certificate.
+It must return 0 on failure and 1 on success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_get_crl() sets the function to get the crl for a given
+certificate B<x>.
+When found, the crl must be assigned to B<*crl>.
+This function must return 0 on failure and 1 on success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_check_crl() sets the function to check the validity of
+the given B<crl>.
+This function must return 0 on failure and 1 on success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_cert_crl() sets the function to check the revocation
+status of the given certificate B<x> against the given B<crl>.
+This function must return 0 on failure and 1 on success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_check_policy() sets the function to check the policies
+of all the certificates in the final chain..
+This function must return 0 on failure and 1 on success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_lookup_certs() and X509_STORE_set_lookup_crls() set the
+functions to look up all the certs or all the CRLs that match the
+given name B<nm>.
+These functions return NULL on failure and a pointer to a stack of
+certificates (B<X509>) or to a stack of CRLs (B<X509_CRL>) on
+success.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_set_cleanup() sets the final cleanup function, which is
+called when the context (B<X509_STORE_CTX>) is being torn down.
+This function doesn't return any value.
+I<If no function to get the issuer is provided, the internal default
+function will be used instead.>
+
+X509_STORE_get_verify_cb(), X509_STORE_CTX_get_verify(),
+X509_STORE_get_get_issuer(), X509_STORE_get_check_issued(),
+X509_STORE_get_check_revocation(), X509_STORE_get_get_crl(),
+X509_STORE_get_check_crl(), X509_STORE_set_verify(),
+X509_STORE_set_get_issuer(), X509_STORE_get_cert_crl(),
+X509_STORE_get_check_policy(), X509_STORE_get_lookup_certs(),
+X509_STORE_get_lookup_crls() and X509_STORE_get_cleanup() all return
+the function pointer assigned with X509_STORE_set_check_issued(),
+X509_STORE_set_check_revocation(), X509_STORE_set_get_crl(),
+X509_STORE_set_check_crl(), X509_STORE_set_cert_crl(),
+X509_STORE_set_check_policy(), X509_STORE_set_lookup_certs(),
+X509_STORE_set_lookup_crls() and X509_STORE_set_cleanup(), or NULL if
+no assignment has been made.
+
+X509_STORE_set_verify_cb_func(), X509_STORE_set_verify_func() and
+X509_STORE_set_lookup_crls_cb() are aliases for
+X509_STORE_set_verify_cb(), X509_STORE_set_verify() and
+X509_STORE_set_lookup_crls, available as macros for backward
+compatibility.
+
+=head1 NOTES
+
+All the callbacks from a B<X509_STORE> are inherited by the
+corresponding B<X509_STORE_CTX> structure when it is initialized.
+See L<X509_STORE_CTX_set_verify_cb(3)> for further details.
+
+=head1 BUGS
+
+The macro version of this function was the only one available before
+OpenSSL 1.0.0.
+
+=head1 RETURN VALUES
+
+The X509_STORE_set_*() functions do not return a value.
+
+The X509_STORE_get_*() functions return a pointer of the appropriate
+function type.
+
+=head1 SEE ALSO
+
+L<X509_STORE_CTX_set_verify_cb(3)>, L<X509_STORE_CTX_get0_chain(3)>,
+L<CMS_verify(3)>
+
+=head1 HISTORY
+
+X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0.
+
+X509_STORE_set_verify_cb(), X509_STORE_get_verify_cb(),
+X509_STORE_set_verify(), X509_STORE_CTX_get_verify(),
+X509_STORE_set_get_issuer(), X509_STORE_get_get_issuer(),
+X509_STORE_set_check_issued(), X509_STORE_get_check_issued(),
+X509_STORE_set_check_revocation(), X509_STORE_get_check_revocation(),
+X509_STORE_set_get_crl(), X509_STORE_get_get_crl(),
+X509_STORE_set_check_crl(), X509_STORE_get_check_crl(),
+X509_STORE_set_cert_crl(), X509_STORE_get_cert_crl(),
+X509_STORE_set_check_policy(), X509_STORE_get_check_policy(),
+X509_STORE_set_lookup_certs(), X509_STORE_get_lookup_certs(),
+X509_STORE_set_lookup_crls(), X509_STORE_get_lookup_crls(),
+X509_STORE_set_cleanup() and X509_STORE_get_cleanup() were added in
+OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param,
+ unsigned long flags);
+ int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param,
+ unsigned long flags);
+ unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param);
+
+ int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose);
+ int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust);
+
+ void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t);
+
+ int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param,
+ ASN1_OBJECT *policy);
+ int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param,
+ STACK_OF(ASN1_OBJECT) *policies);
+
+ void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth);
+ int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param);
+
+ void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param,
+ int auth_level);
+ int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param);
+
+ int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param,
+ const char *name, size_t namelen);
+ int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param,
+ const char *name, size_t namelen);
+ void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
+ unsigned int flags);
+ char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
+ int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
+ const char *email, size_t emaillen);
+ int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
+ const unsigned char *ip, size_t iplen);
+ int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc);
+
+=head1 DESCRIPTION
+
+These functions manipulate the B<X509_VERIFY_PARAM> structure associated with
+a certificate verification operation.
+
+The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring
+it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete
+description of values the B<flags> parameter can take.
+
+X509_VERIFY_PARAM_get_flags() returns the flags in B<param>.
+
+X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>.
+
+X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param>
+to B<purpose>. This determines the acceptable purpose of the certificate
+chain, for example SSL client or SSL server.
+
+X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to
+B<trust>.
+
+X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to
+B<t>. Normally the current time is used.
+
+X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled
+by default) and adds B<policy> to the acceptable policy set.
+
+X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled
+by default) and sets the acceptable policy set to B<policies>. Any existing
+policy set is cleared. The B<policies> parameter can be B<NULL> to clear
+an existing policy set.
+
+X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>.
+That is the maximum number of intermediate CA certificates that can appear in a
+chain.
+A maximal depth chain contains 2 more certificates than the limit, since
+neither the end-entity certificate nor the trust-anchor count against this
+limit.
+Thus a B<depth> limit of 0 only allows the end-entity certificate to be signed
+directly by the trust-anchor, while with a B<depth> limit of 1 there can be one
+intermediate CA certificate between the trust-anchor and the end-entity
+certificate.
+
+X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to
+B<auth_level>.
+The authentication security level determines the acceptable signature and public
+key strength when verifying certificate chains.
+For a certificate chain to validate, the public keys of all the certificates
+must meet the specified security level.
+The signature algorithm security level is not enforced for the chain's I<trust
+anchor> certificate, which is either directly trusted or validated by means other
+than its signature.
+See L<SSL_CTX_set_security_level(3)> for the definitions of the available
+levels.
+The default security level is -1, or "not set".
+At security level 0 or lower all algorithms are acceptable.
+Security level 1 requires at least 80-bit-equivalent security and is broadly
+interoperable, though it will, for example, reject MD5 signatures or RSA keys
+shorter than 1024 bits.
+
+X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to
+B<name> clearing any previously specified host name or names. If
+B<name> is NULL, or empty the list of hostnames is cleared, and
+name checks are not performed on the peer certificate. If B<name>
+is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>
+must be set to the length of B<name>. When a hostname is specified,
+certificate verification automatically invokes L<X509_check_host(3)>
+with flags equal to the B<flags> argument given to
+X509_VERIFY_PARAM_set_hostflags() (default zero). Applications
+are strongly advised to use this interface in preference to explicitly
+calling L<X509_check_host(3)>, hostname checks are out of scope
+with the DANE-EE(3) certificate usage, and the internal check will
+be suppressed as appropriate when DANE support is added to OpenSSL.
+
+X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference
+identifier that can match the peer's certificate. Any previous names
+set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host()
+are retained, no change is made if B<name> is NULL or empty. When
+multiple names are configured, the peer is considered verified when
+any name matches.
+
+X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject
+CommonName from the peer certificate that matched one of the reference
+identifiers. When wildcard matching is not disabled, or when a
+reference identifier specifies a parent domain (starts with ".")
+rather than a hostname, the peer name may be a wildcard name or a
+sub-domain of the reference identifier respectively. The return
+string is allocated by the library and is no longer valid once the
+associated B<param> argument is freed. Applications must not free
+the return value.
+
+X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to
+B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise
+B<emaillen> must be set to the length of B<email>. When an email address
+is specified, certificate verification automatically invokes
+L<X509_check_email(3)>.
+
+X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>.
+The B<ip> argument is in binary format, in network byte-order and
+B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
+address is specified, certificate verification automatically invokes
+L<X509_check_ip(3)>.
+
+X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to
+B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string:
+dotted decimal quad for IPv4 and colon-separated hexadecimal for
+IPv6. The condensed "::" notation is supported for IPv6 addresses.
+
+=head1 RETURN VALUES
+
+X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),
+X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(),
+X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(),
+X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(),
+X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and
+X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for
+failure.
+
+X509_VERIFY_PARAM_get_flags() returns the current verification flags.
+
+X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return
+values.
+
+X509_VERIFY_PARAM_get_depth() returns the current verification depth.
+
+X509_VERIFY_PARAM_get_auth_level() returns the current authentication security
+level.
+
+=head1 VERIFICATION FLAGS
+
+The verification flags consists of zero or more of the following flags
+ored together.
+
+B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf
+certificate. An error occurs if a suitable CRL cannot be found.
+
+B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate
+chain.
+
+B<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default
+any unhandled critical extensions in certificates or (if checked) CRLs results
+in a fatal error. If this flag is set unhandled critical extensions are
+ignored. B<WARNING> setting this option for anything other than debugging
+purposes can be a security risk. Finer control over which extensions are
+supported can be performed in the verification callback.
+
+The B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken
+certificates and makes the verification strictly apply B<X509> rules.
+
+B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification.
+
+B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default
+no policy checking is performed. Additional information is sent to the
+verification callback relating to policy checking.
+
+B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and
+B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any
+policy> and B<inhibit policy mapping> flags respectively as defined in
+B<RFC3280>. Policy checking is automatically enabled if any of these flags
+are set.
+
+If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful
+a special status code is set to the verification callback. This permits it
+to examine the valid policy tree and perform additional checks or simply
+log it for debugging purposes.
+
+By default some additional features such as indirect CRLs and CRLs signed by
+different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set
+they are enabled.
+
+If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to
+determine certificate status. If not set deltas are ignored.
+
+B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed
+certificate signature. By default this check is disabled because it doesn't
+add any additional security but in some cases applications might want to
+check the signature anyway. A side effect of not checking the root CA
+signature is that disabled or unsupported message digests on the root CA
+are not treated as fatal errors.
+
+If B<X509_V_FLAG_TRUSTED_FIRST> is set, when constructing the certificate chain,
+L<X509_verify_cert(3)> will search the trust store for issuer certificates before
+searching the provided untrusted certificates.
+As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
+
+The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
+chains.
+By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a
+certificate chain, if the first certificate chain found is not trusted, then
+OpenSSL will attempt to replace untrusted certificates supplied by the peer
+with certificates from the trust store to see if an alternative chain can be
+found that is trusted.
+As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
+has no effect.
+
+The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period
+of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time()
+is used to specify a verification time, the check is not suppressed.
+
+=head1 NOTES
+
+The above functions should be used to manipulate verification parameters
+instead of legacy functions which work in specific structures such as
+X509_STORE_CTX_set_flags().
+
+=head1 BUGS
+
+Delta CRL checking is currently primitive. Only a single delta can be used and
+(partly due to limitations of B<X509_STORE>) constructed CRLs are not
+maintained.
+
+If CRLs checking is enable CRLs are expected to be available in the
+corresponding B<X509_STORE> structure. No attempt is made to download
+CRLs from the CRL distribution points extension.
+
+=head1 EXAMPLE
+
+Enable CRL checking when performing certificate verification during SSL
+connections associated with an B<SSL_CTX> structure B<ctx>:
+
+ X509_VERIFY_PARAM *param;
+ param = X509_VERIFY_PARAM_new();
+ X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK);
+ SSL_CTX_set1_param(ctx, param);
+ X509_VERIFY_PARAM_free(param);
+
+=head1 SEE ALSO
+
+L<X509_verify_cert(3)>,
+L<X509_check_host(3)>,
+L<X509_check_email(3)>,
+L<X509_check_ip(3)>
+
+=head1 HISTORY
+
+The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0
+The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of
+OpenSSL 1.1.0, and has no effect.
+
+=head1 COPYRIGHT
+
+Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_check_ca - check if given certificate is CA certificate
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509v3.h>
+
+ int X509_check_ca(X509 *cert);
+
+=head1 DESCRIPTION
+
+This function checks if given certificate is CA certificate (can be used
+to sign other certificates).
+
+=head1 RETURN VALUE
+
+Function return 0, if it is not CA certificate, 1 if it is proper X509v3
+CA certificate with B<basicConstraints> extension CA:TRUE,
+3, if it is self-signed X509 v1 certificate, 4, if it is certificate with
+B<keyUsage> extension with bit B<keyCertSign> set, but without
+B<basicConstraints>, and 5 if it has outdated Netscape Certificate Type
+extension telling that it is CA certificate.
+
+Actually, any non-zero value means that this certificate could have been
+used to sign other certificates.
+
+=head1 SEE ALSO
+
+L<X509_verify_cert(3)>,
+L<X509_check_issued(3)>,
+L<X509_check_purpose(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_check_host(X509 *, const char *name, size_t namelen,
+ unsigned int flags, char **peername);
+ int X509_check_email(X509 *, const char *address, size_t addresslen,
+ unsigned int flags);
+ int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen,
+ unsigned int flags);
+ int X509_check_ip_asc(X509 *, const char *address, unsigned int flags);
+
+=head1 DESCRIPTION
+
+The certificate matching functions are used to check whether a
+certificate matches a given host name, email address, or IP address.
+The validity of the certificate and its trust level has to be checked by
+other means.
+
+X509_check_host() checks if the certificate Subject Alternative
+Name (SAN) or Subject CommonName (CN) matches the specified host
+name, which must be encoded in the preferred name syntax described
+in section 3.5 of RFC 1034. By default, wildcards are supported
+and they match only in the left-most label; but they may match
+part of that label with an explicit prefix or suffix. For example,
+by default, the host B<name> "www.example.com" would match a
+certificate with a SAN or CN value of "*.example.com", "w*.example.com"
+or "*w.example.com".
+
+Per section 6.4.2 of RFC 6125, B<name> values representing international
+domain names must be given in A-label form. The B<namelen> argument
+must be the number of characters in the name string or zero in which
+case the length is calculated with strlen(B<name>). When B<name> starts
+with a dot (e.g ".example.com"), it will be matched by a certificate
+valid for any sub-domain of B<name>, (see also
+B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below).
+
+When the certificate is matched, and B<peername> is not NULL, a
+pointer to a copy of the matching SAN or CN from the peer certificate
+is stored at the address passed in B<peername>. The application
+is responsible for freeing the peername via OPENSSL_free() when it
+is no longer needed.
+
+X509_check_email() checks if the certificate matches the specified
+email B<address>. Only the mailbox syntax of RFC 822 is supported,
+comments are not allowed, and no attempt is made to normalize quoted
+characters. The B<addresslen> argument must be the number of
+characters in the address string or zero in which case the length
+is calculated with strlen(B<address>).
+
+X509_check_ip() checks if the certificate matches a specified IPv4 or
+IPv6 address. The B<address> array is in binary format, in network
+byte order. The length is either 4 (IPv4) or 16 (IPv6). Only
+explicitly marked addresses in the certificates are considered; IP
+addresses stored in DNS names and Common Names are ignored.
+
+X509_check_ip_asc() is similar, except that the NUL-terminated
+string B<address> is first converted to the internal representation.
+
+The B<flags> argument is usually 0. It can be the bitwise OR of the
+flags:
+
+=over 4
+
+=item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>,
+
+=item B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT>,
+
+=item B<X509_CHECK_FLAG_NO_WILDCARDS>,
+
+=item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>,
+
+=item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>.
+
+=item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>.
+
+=back
+
+The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function
+to consider the subject DN even if the certificate contains at least
+one subject alternative name of the right type (DNS name or email
+address as appropriate); the default is to ignore the subject DN
+when at least one corresponding subject alternative names is present.
+
+The B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT> flag causes the function to never
+consider the subject DN even if the certificate contains no subject alternative
+names of the right type (DNS name or email address as appropriate); the default
+is to use the subject DN when no corresponding subject alternative names are
+present.
+
+If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard
+expansion; this only applies to B<X509_check_host>.
+
+If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support
+for "*" as wildcard pattern in labels that have a prefix or suffix,
+such as: "www*" or "*www"; this only applies to B<X509_check_host>.
+
+If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that
+constitutes the complete label of a DNS name (e.g. "*.example.com")
+to match more than one label in B<name>; this flag only applies
+to B<X509_check_host>.
+
+If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name>
+values which start with ".", that would otherwise match any sub-domain
+in the peer certificate, to only match direct child sub-domains.
+Thus, for instance, with this flag set a B<name> of ".example.com"
+would match a peer certificate with a DNS name of "www.example.com",
+but would not match a peer certificate with a DNS name of
+"www.sub.example.com"; this flag only applies to B<X509_check_host>.
+
+=head1 RETURN VALUES
+
+The functions return 1 for a successful match, 0 for a failed match
+and -1 for an internal error: typically a memory allocation failure
+or an ASN.1 decoding error.
+
+All functions can also return -2 if the input is malformed. For example,
+X509_check_host() returns -2 if the provided B<name> contains embedded
+NULs.
+
+=head1 NOTES
+
+Applications are encouraged to use X509_VERIFY_PARAM_set1_host()
+rather than explicitly calling L<X509_check_host(3)>. Host name
+checks are out of scope with the DANE-EE(3) certificate usage,
+and the internal checks will be suppressed as appropriate when
+DANE support is added to OpenSSL.
+
+=head1 SEE ALSO
+
+L<SSL_get_verify_result(3)>,
+L<X509_VERIFY_PARAM_set1_host(3)>,
+L<X509_VERIFY_PARAM_add1_host(3)>,
+L<X509_VERIFY_PARAM_set1_email(3)>,
+L<X509_VERIFY_PARAM_set1_ip(3)>,
+L<X509_VERIFY_PARAM_set1_ipasc(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.0.2.
+
+=head1 COPYRIGHT
+
+Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_check_issued - checks if certificate is issued by another
+certificate
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509v3.h>
+
+ int X509_check_issued(X509 *issuer, X509 *subject);
+
+
+=head1 DESCRIPTION
+
+This function checks if certificate I<subject> was issued using CA
+certificate I<issuer>. This function takes into account not only
+matching of issuer field of I<subject> with subject field of I<issuer>,
+but also compares B<authorityKeyIdentifier> extension of I<subject> with
+B<subjectKeyIdentifier> of I<issuer> if B<authorityKeyIdentifier>
+present in the I<subject> certificate and checks B<keyUsage> field of
+I<issuer>.
+
+=head1 RETURN VALUE
+
+Function return B<X509_V_OK> if certificate I<subject> is issued by
+I<issuer> or some B<X509_V_ERR*> constant to indicate an error.
+
+=head1 SEE ALSO
+
+L<X509_verify_cert(3)>,
+L<X509_check_ca(3)>,
+L<verify(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+DECLARE_ASN1_FUNCTIONS,
+IMPLEMENT_ASN1_FUNCTIONS,
+ASN1_ITEM,
+ACCESS_DESCRIPTION_free,
+ACCESS_DESCRIPTION_new,
+ASIdOrRange_free,
+ASIdOrRange_new,
+ASIdentifierChoice_free,
+ASIdentifierChoice_new,
+ASIdentifiers_free,
+ASIdentifiers_new,
+ASRange_free,
+ASRange_new,
+AUTHORITY_INFO_ACCESS_free,
+AUTHORITY_INFO_ACCESS_new,
+AUTHORITY_KEYID_free,
+AUTHORITY_KEYID_new,
+BASIC_CONSTRAINTS_free,
+BASIC_CONSTRAINTS_new,
+CERTIFICATEPOLICIES_free,
+CERTIFICATEPOLICIES_new,
+CMS_ContentInfo_free,
+CMS_ContentInfo_new,
+CMS_ContentInfo_print_ctx,
+CMS_ReceiptRequest_free,
+CMS_ReceiptRequest_new,
+CRL_DIST_POINTS_free,
+CRL_DIST_POINTS_new,
+DIRECTORYSTRING_free,
+DIRECTORYSTRING_new,
+DISPLAYTEXT_free,
+DISPLAYTEXT_new,
+DIST_POINT_NAME_free,
+DIST_POINT_NAME_new,
+DIST_POINT_free,
+DIST_POINT_new,
+DSAparams_dup,
+ECPARAMETERS_free,
+ECPARAMETERS_new,
+ECPKPARAMETERS_free,
+ECPKPARAMETERS_new,
+EDIPARTYNAME_free,
+EDIPARTYNAME_new,
+ESS_CERT_ID_dup,
+ESS_CERT_ID_free,
+ESS_CERT_ID_new,
+ESS_ISSUER_SERIAL_dup,
+ESS_ISSUER_SERIAL_free,
+ESS_ISSUER_SERIAL_new,
+ESS_SIGNING_CERT_dup,
+ESS_SIGNING_CERT_free,
+ESS_SIGNING_CERT_new,
+EXTENDED_KEY_USAGE_free,
+EXTENDED_KEY_USAGE_new,
+GENERAL_NAMES_free,
+GENERAL_NAMES_new,
+GENERAL_NAME_dup,
+GENERAL_NAME_free,
+GENERAL_NAME_new,
+GENERAL_SUBTREE_free,
+GENERAL_SUBTREE_new,
+IPAddressChoice_free,
+IPAddressChoice_new,
+IPAddressFamily_free,
+IPAddressFamily_new,
+IPAddressOrRange_free,
+IPAddressOrRange_new,
+IPAddressRange_free,
+IPAddressRange_new,
+ISSUING_DIST_POINT_free,
+ISSUING_DIST_POINT_new,
+NAME_CONSTRAINTS_free,
+NAME_CONSTRAINTS_new,
+NETSCAPE_CERT_SEQUENCE_free,
+NETSCAPE_CERT_SEQUENCE_new,
+NETSCAPE_SPKAC_free,
+NETSCAPE_SPKAC_new,
+NETSCAPE_SPKI_free,
+NETSCAPE_SPKI_new,
+NOTICEREF_free,
+NOTICEREF_new,
+OCSP_BASICRESP_free,
+OCSP_BASICRESP_new,
+OCSP_CERTID_dup,
+OCSP_CERTID_new,
+OCSP_CERTSTATUS_free,
+OCSP_CERTSTATUS_new,
+OCSP_CRLID_free,
+OCSP_CRLID_new,
+OCSP_ONEREQ_free,
+OCSP_ONEREQ_new,
+OCSP_REQINFO_free,
+OCSP_REQINFO_new,
+OCSP_RESPBYTES_free,
+OCSP_RESPBYTES_new,
+OCSP_RESPDATA_free,
+OCSP_RESPDATA_new,
+OCSP_RESPID_free,
+OCSP_RESPID_new,
+OCSP_RESPONSE_new,
+OCSP_REVOKEDINFO_free,
+OCSP_REVOKEDINFO_new,
+OCSP_SERVICELOC_free,
+OCSP_SERVICELOC_new,
+OCSP_SIGNATURE_free,
+OCSP_SIGNATURE_new,
+OCSP_SINGLERESP_free,
+OCSP_SINGLERESP_new,
+OTHERNAME_free,
+OTHERNAME_new,
+PBE2PARAM_free,
+PBE2PARAM_new,
+PBEPARAM_free,
+PBEPARAM_new,
+PBKDF2PARAM_free,
+PBKDF2PARAM_new,
+PKCS12_BAGS_free,
+PKCS12_BAGS_new,
+PKCS12_MAC_DATA_free,
+PKCS12_MAC_DATA_new,
+PKCS12_SAFEBAG_free,
+PKCS12_SAFEBAG_new,
+PKCS12_free,
+PKCS12_new,
+PKCS7_DIGEST_free,
+PKCS7_DIGEST_new,
+PKCS7_ENCRYPT_free,
+PKCS7_ENCRYPT_new,
+PKCS7_ENC_CONTENT_free,
+PKCS7_ENC_CONTENT_new,
+PKCS7_ENVELOPE_free,
+PKCS7_ENVELOPE_new,
+PKCS7_ISSUER_AND_SERIAL_free,
+PKCS7_ISSUER_AND_SERIAL_new,
+PKCS7_RECIP_INFO_free,
+PKCS7_RECIP_INFO_new,
+PKCS7_SIGNED_free,
+PKCS7_SIGNED_new,
+PKCS7_SIGNER_INFO_free,
+PKCS7_SIGNER_INFO_new,
+PKCS7_SIGN_ENVELOPE_free,
+PKCS7_SIGN_ENVELOPE_new,
+PKCS7_dup,
+PKCS7_free,
+PKCS7_new,
+PKCS7_print_ctx,
+PKCS8_PRIV_KEY_INFO_free,
+PKCS8_PRIV_KEY_INFO_new,
+PKEY_USAGE_PERIOD_free,
+PKEY_USAGE_PERIOD_new,
+POLICYINFO_free,
+POLICYINFO_new,
+POLICYQUALINFO_free,
+POLICYQUALINFO_new,
+POLICY_CONSTRAINTS_free,
+POLICY_CONSTRAINTS_new,
+POLICY_MAPPING_free,
+POLICY_MAPPING_new,
+PROXY_CERT_INFO_EXTENSION_free,
+PROXY_CERT_INFO_EXTENSION_new,
+PROXY_POLICY_free,
+PROXY_POLICY_new,
+RSAPrivateKey_dup,
+RSAPublicKey_dup,
+RSA_OAEP_PARAMS_free,
+RSA_OAEP_PARAMS_new,
+RSA_PSS_PARAMS_free,
+RSA_PSS_PARAMS_new,
+SXNETID_free,
+SXNETID_new,
+SXNET_free,
+SXNET_new,
+TLS_FEATURE_free,
+TLS_FEATURE_new,
+TS_ACCURACY_dup,
+TS_ACCURACY_free,
+TS_ACCURACY_new,
+TS_MSG_IMPRINT_dup,
+TS_MSG_IMPRINT_free,
+TS_MSG_IMPRINT_new,
+TS_REQ_dup,
+TS_REQ_free,
+TS_REQ_new,
+TS_RESP_dup,
+TS_RESP_free,
+TS_RESP_new,
+TS_STATUS_INFO_dup,
+TS_STATUS_INFO_free,
+TS_STATUS_INFO_new,
+TS_TST_INFO_dup,
+TS_TST_INFO_free,
+TS_TST_INFO_new,
+USERNOTICE_free,
+USERNOTICE_new,
+X509_ALGOR_free,
+X509_ALGOR_new,
+X509_ATTRIBUTE_dup,
+X509_ATTRIBUTE_free,
+X509_ATTRIBUTE_new,
+X509_CERT_AUX_free,
+X509_CERT_AUX_new,
+X509_CINF_free,
+X509_CINF_new,
+X509_CRL_INFO_free,
+X509_CRL_INFO_new,
+X509_CRL_METHOD_free,
+X509_CRL_METHOD_new,
+X509_CRL_dup,
+X509_CRL_free,
+X509_CRL_new,
+X509_EXTENSION_dup,
+X509_EXTENSION_free,
+X509_EXTENSION_new,
+X509_NAME_ENTRY_dup,
+X509_NAME_ENTRY_free,
+X509_NAME_ENTRY_new,
+X509_NAME_dup,
+X509_NAME_free,
+X509_NAME_new,
+X509_REQ_INFO_free,
+X509_REQ_INFO_new,
+X509_REQ_dup,
+X509_REQ_free,
+X509_REQ_new,
+X509_REVOKED_dup,
+X509_REVOKED_free,
+X509_REVOKED_new,
+X509_SIG_free,
+X509_SIG_new,
+X509_VAL_free,
+X509_VAL_new,
+X509_dup,
+- ASN1 object utilities
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ #include <openssl/asn1t.h>
+
+ DECLARE_ASN1_FUNCTIONS(type)
+ IMPLEMENT_ASN1_FUNCTIONS(stname)
+
+ typedef struct ASN1_ITEM_st ASN1_ITEM;
+
+ extern const ASN1_ITEM TYPE_it;
+ TYPE *TYPE_new(void);
+ TYPE *TYPE_dup(TYPE *a);
+ void TYPE_free(TYPE *a);
+ int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx);
+
+=head1 DESCRIPTION
+
+In the description below, I<TYPE> is used
+as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
+
+The OpenSSL ASN1 parsing library templates are like a data-driven bytecode
+interpreter.
+Every ASN1 object as a global variable, TYPE_it, that describes the item
+such as its fields. (On systems which cannot export variables from shared
+libraries, the global is instead a function which returns a pointer to a
+static variable.
+
+The macro DECLARE_ASN1_FUNCTIONS() is typically used in header files
+to generate the function declarations.
+
+The macro IMPLEMENT_ASN1_FUNCTIONS() is used once in a source file
+to generate the function bodies.
+
+
+TYPE_new() allocates an empty object of the indicated type.
+The object returned must be released by calling TYPE_free().
+
+TYPE_dup() copies an existing object.
+
+TYPE_free() releases the object and all pointers and sub-objects
+within it.
+
+TYPE_print_ctx() prints the object B<a> on the specified BIO B<out>.
+Each line will be prefixed with B<indent> spaces.
+The B<pctx> specifies the printing context and is for internal
+use; use NULL to get the default behavior. If a print function is
+user-defined, then pass in any B<pctx> down to any nested calls.
+
+=head1 RETURN VALUES
+
+TYPE_new() and TYPE_dup() return a pointer to the object or NULL on failure.
+
+TYPE_print_ctx() returns 1 on success or zero on failure.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get0_signature, X509_get_signature_nid, X509_get0_tbs_sigalg,
+X509_REQ_get0_signature, X509_REQ_get_signature_nid, X509_CRL_get0_signature,
+X509_CRL_get_signature_nid - signature information
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ void X509_get0_signature(const ASN1_BIT_STRING **psig,
+ const X509_ALGOR **palg,
+ const X509 *x);
+ int X509_get_signature_nid(const X509 *x);
+ const X509_ALGOR *X509_get0_tbs_sigalg(const X509 *x);
+
+ void X509_REQ_get0_signature(const X509_REQ *crl,
+ const ASN1_BIT_STRING **psig,
+ const X509_ALGOR **palg);
+ int X509_REQ_get_signature_nid(const X509_REQ *crl);
+
+ void X509_CRL_get0_signature(const X509_CRL *crl,
+ const ASN1_BIT_STRING **psig,
+ const X509_ALGOR **palg);
+ int X509_CRL_get_signature_nid(const X509_CRL *crl);
+
+=head1 DESCRIPTION
+
+X509_get0_signature() sets B<*psig> to the signature of B<x> and B<*palg>
+to the signature algorithm of B<x>. The values returned are internal
+pointers which B<MUST NOT> be freed up after the call.
+
+X509_get0_tbs_sigalg() returns the signature algorithm in the signed
+portion of B<x>.
+
+X509_get_signature_nid() returns the NID corresponding to the signature
+algorithm of B<x>.
+
+X509_REQ_get0_signature(), X509_REQ_get_signature_nid()
+X509_CRL_get0_signature() and X509_CRL_get_signature_nid() perform the
+same function for certificate requests and CRLs.
+
+=head1 NOTES
+
+These functions provide lower level access to signatures in certificates
+where an application wishes to analyse or generate a signature in a form
+where X509_sign() et al is not appropriate (for example a non standard
+or unsupported format).
+
+=head1 RETURN VALUES
+
+X509_get_signature_nid(), X509_REQ_get_signature_nid() and
+X509_CRL_get_signature_nid() return a NID.
+
+X509_get0_signature(), X509_REQ_get0_signature() and
+X509_CRL_get0_signature() do not return values.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 HISTORY
+
+X509_get0_signature() and X509_get_signature_nid() were first added to
+OpenSSL 1.0.2.
+
+X509_REQ_get0_signature(), X509_REQ_get_signature_nid(),
+X509_CRL_get0_signature() and X509_CRL_get_signature_nid() were first added
+to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get0_uids - get certificate unique identifiers
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ void X509_get0_uids(const X509 *x, const ASN1_BIT_STRING **piuid,
+ const ASN1_BIT_STRING **psuid);
+
+=head1 DESCRIPTION
+
+X509_get0_uids() sets B<*piuid> and B<*psuid> to the issuer and subject unique
+identifiers of certificate B<x> or NULL if the fields are not present.
+
+=head1 NOTES
+
+The issuer and subject unique identifier fields are very rarely encountered in
+practice outside test cases.
+
+=head1 RETURN VALUES
+
+X509_get0_uids() does not return a value.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get0_subject_key_id,
+X509_get_pathlen,
+X509_get_extension_flags,
+X509_get_key_usage,
+X509_get_extended_key_usage,
+X509_set_proxy_flag,
+X509_set_proxy_pathlen,
+X509_get_proxy_pathlen - retrieve certificate extension data
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509v3.h>
+
+ long X509_get_pathlen(X509 *x);
+ uint32_t X509_get_extension_flags(X509 *x);
+ uint32_t X509_get_key_usage(X509 *x);
+ uint32_t X509_get_extended_key_usage(X509 *x);
+ const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
+ void X509_set_proxy_flag(X509 *x);
+ void X509_set_proxy_pathlen(int l);
+ long X509_get_proxy_pathlen(X509 *x);
+
+=head1 DESCRIPTION
+
+These functions retrieve information related to commonly used certificate extensions.
+
+X509_get_pathlen() retrieves the path length extension from a certificate.
+This extension is used to limit the length of a cert chain that may be
+issued from that CA.
+
+X509_get_extension_flags() retrieves general information about a certificate,
+it will return one or more of the following flags ored together.
+
+=over 4
+
+=item B<EXFLAG_V1>
+
+The certificate is an obsolete version 1 certificate.
+
+=item B<EXFLAG_BCONS>
+
+The certificate contains a basic constraints extension.
+
+=item B<EXFLAG_CA>
+
+The certificate contains basic constraints and asserts the CA flag.
+
+=item B<EXFLAG_PROXY>
+
+The certificate is a valid proxy certificate.
+
+=item B<EXFLAG_SI>
+
+The certificate is self issued (that is subject and issuer names match).
+
+=item B<EXFLAG_SS>
+
+The subject and issuer names match and extension values imply it is self
+signed.
+
+=item B<EXFLAG_FRESHEST>
+
+The freshest CRL extension is present in the certificate.
+
+=item B<EXFLAG_CRITICAL>
+
+The certificate contains an unhandled critical extension.
+
+=item B<EXFLAG_INVALID>
+
+Some certificate extension values are invalid or inconsistent. The
+certificate should be rejected.
+
+=item B<EXFLAG_KUSAGE>
+
+The certificate contains a key usage extension. The value can be retrieved
+using X509_get_key_usage().
+
+=item B<EXFLAG_XKUSAGE>
+
+The certificate contains an extended key usage extension. The value can be
+retrieved using X509_get_extended_key_usage().
+
+=back
+
+X509_get_key_usage() returns the value of the key usage extension. If key
+usage is present will return zero or more of the flags:
+B<KU_DIGITAL_SIGNATURE>, B<KU_NON_REPUDIATION>, B<KU_KEY_ENCIPHERMENT>,
+B<KU_DATA_ENCIPHERMENT>, B<KU_KEY_AGREEMENT>, B<KU_KEY_CERT_SIGN>,
+B<KU_CRL_SIGN>, B<KU_ENCIPHER_ONLY> or B<KU_DECIPHER_ONLY> corresponding to
+individual key usage bits. If key usage is absent then B<UINT32_MAX> is
+returned.
+
+X509_get_extended_key_usage() returns the value of the extended key usage
+extension. If extended key usage is present it will return zero or more of the
+flags: B<XKU_SSL_SERVER>, B<XKU_SSL_CLIENT>, B<XKU_SMIME>, B<XKU_CODE_SIGN>
+B<XKU_OCSP_SIGN>, B<XKU_TIMESTAMP>, B<XKU_DVCS> or B<XKU_ANYEKU>. These
+correspond to the OIDs B<id-kp-serverAuth>, B<id-kp-clientAuth>,
+B<id-kp-emailProtection>, B<id-kp-codeSigning>, B<id-kp-OCSPSigning>,
+B<id-kp-timeStamping>, B<id-kp-dvcs> and B<anyExtendedKeyUsage> respectively.
+Additionally B<XKU_SGC> is set if either Netscape or Microsoft SGC OIDs are
+present.
+
+X509_get_extended_key_usage() return an internal pointer to the subject key
+identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension
+is not present or cannot be parsed.
+
+X509_set_proxy_flag() marks the certificate with the B<EXFLAG_PROXY> flag.
+This is for the users who need to mark non-RFC3820 proxy certificates as
+such, as OpenSSL only detects RFC3820 compliant ones.
+
+X509_set_proxy_pathlen() sets the proxy certificate path length for the given
+certificate B<x>. This is for the users who need to mark non-RFC3820 proxy
+certificates as such, as OpenSSL only detects RFC3820 compliant ones.
+
+X509_get_proxy_pathlen() returns the proxy certificate path length for the
+given certificate B<x> if it is a proxy certificate.
+
+=head1 NOTES
+
+The value of the flags correspond to extension values which are cached
+in the B<X509> structure. If the flags returned do not provide sufficient
+information an application should examine extension values directly
+for example using X509_get_ext_d2i().
+
+If the key usage or extended key usage extension is absent then typically usage
+is unrestricted. For this reason X509_get_key_usage() and
+X509_get_extended_key_usage() return B<UINT32_MAX> when the corresponding
+extension is absent. Applications can additionally check the return value of
+X509_get_extension_flags() and take appropriate action is an extension is
+absent.
+
+If X509_get0_subject_key_id() returns B<NULL> then the extension may be
+absent or malformed. Applications can determine the precise reason using
+X509_get_ext_d2i().
+
+=head1 RETURN VALUE
+
+X509_get_pathlen() returns the path length value, or -1 if the extension
+is not present.
+
+X509_get_extension_flags(), X509_get_key_usage() and
+X509_get_extended_key_usage() return sets of flags corresponding to the
+certificate extension values.
+
+X509_get0_subject_key_id() returns the subject key identifier as a
+pointer to an B<ASN1_OCTET_STRING> structure or B<NULL> if the extension
+is absent or an error occurred during parsing.
+
+X509_get_proxy_pathlen() returns the path length value if the given
+certificate is a proxy one and has a path length set, and -1 otherwise.
+
+=head1 SEE ALSO
+
+L<X509_check_purpose(3)>
+
+=head1 HISTORY
+
+X509_get_pathlen(), X509_set_proxy_flag(), X509_set_proxy_pathlen() and
+X509_get_proxy_pathlen() were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get0_notBefore, X509_getm_notBefore, X509_get0_notAfter,
+X509_getm_notAfter, X509_set1_notBefore, X509_set1_notAfter,
+X509_CRL_get0_lastUpdate, X509_CRL_get0_nextUpdate, X509_CRL_set1_lastUpdate,
+X509_CRL_set1_nextUpdate - get or set certificate or CRL dates
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ const ASN1_TIME *X509_get0_notBefore(const X509 *x);
+ const ASN1_TIME *X509_get0_notAfter(const X509 *x);
+
+ ASN1_TIME *X509_getm_notBefore(const X509 *x);
+ ASN1_TIME *X509_getm_notAfter(const X509 *x);
+
+ int X509_set1_notBefore(X509 *x, const ASN1_TIME *tm);
+ int X509_set1_notAfter(X509 *x, const ASN1_TIME *tm);
+
+ const ASN1_TIME *X509_CRL_get0_lastUpdate(const X509_CRL *crl);
+ const ASN1_TIME *X509_CRL_get0_nextUpdate(const X509_CRL *crl);
+
+ int X509_CRL_set1_lastUpdate(X509_CRL *x, const ASN1_TIME *tm);
+ int X509_CRL_set1_nextUpdate(X509_CRL *x, const ASN1_TIME *tm);
+
+=head1 DESCRIPTION
+
+X509_get0_notBefore() and X509_get0_notAfter() return the B<notBefore>
+and B<notAfter> fields of certificate B<x> respectively. The value
+returned is an internal pointer which must not be freed up after
+the call.
+
+X509_getm_notBefore() and X509_getm_notAfter() are similar to
+X509_get0_notBefore() and X509_get0_notAfter() except they return
+non-constant mutable references to the associated date field of
+the certficate.
+
+X509_set1_notBefore() and X509_set1_notAfter() set the B<notBefore>
+and B<notAfter> fields of B<x> to B<tm>. Ownership of the passed
+parameter B<tm> is not transferred by these functions so it must
+be freed up after the call.
+
+X509_CRL_get0_lastUpdate() and X509_CRL_get0_nextUpdate() return the
+B<lastUpdate> and B<nextUpdate> fields of B<crl>. The value
+returned is an internal pointer which must not be freed up after
+the call. If the B<nextUpdate> field is absent from B<crl> then
+B<NULL> is returned.
+
+X509_CRL_set1_lastUpdate() and X509_CRL_set1_nextUpdate() set the B<lastUpdate>
+and B<nextUpdate> fields of B<crl> to B<tm>. Ownership of the passed parameter
+B<tm> is not transferred by these functions so it must be freed up after the
+call.
+
+=head1 RETURN VALUES
+
+X509_get0_notBefore(), X509_get0_notAfter() and X509_CRL_get0_lastUpdate()
+return a pointer to an B<ASN1_TIME> structure.
+
+X509_CRL_get0_lastUpdate() return a pointer to an B<ASN1_TIME> structure
+or NULL if the B<lastUpdate> field is absent.
+
+X509_set1_notBefore(), X509_set1_notAfter(), X509_CRL_set1_lastUpdate() and
+X509_CRL_set1_nextUpdate() return 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 HISTORY
+
+These functions are available in all versions of OpenSSL.
+
+X509_get_notBefore() and X509_get_notAfter() were deprecated in OpenSSL
+1.1.0
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get_pubkey, X509_get0_pubkey, X509_set_pubkey, X509_get_X509_PUBKEY,
+X509_REQ_get_pubkey, X509_REQ_get0_pubkey, X509_REQ_set_pubkey,
+X509_REQ_get_X509_PUBKEY - get or set certificate or certificate request
+public key
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ EVP_PKEY *X509_get_pubkey(X509 *x);
+ EVP_PKEY *X509_get0_pubkey(const X509 *x);
+ int X509_set_pubkey(X509 *x, EVP_PKEY *pkey);
+ X509_PUBKEY *X509_get_X509_PUBKEY(X509 *x);
+
+ EVP_PKEY *X509_REQ_get_pubkey(X509_REQ *req);
+ EVP_PKEY *X509_REQ_get0_pubkey(X509_REQ *req);
+ int X509_REQ_set_pubkey(X509_REQ *x, EVP_PKEY *pkey);
+ X509_PUBKEY *X509_REQ_get_X509_PUBKEY(X509_REQ *x);
+
+=head1 DESCRIPTION
+
+X509_get_pubkey() attempts to decode the public key for certificate B<x>. If
+successful it returns the public key as an B<EVP_PKEY> pointer with its
+reference count incremented: this means the returned key must be freed up
+after use. X509_get0_pubkey() is similar except it does B<not> increment
+the reference count of the returned B<EVP_PKEY> so it must not be freed up
+after use.
+
+X509_get_X509_PUBKEY() returns an internal pointer to the B<X509_PUBKEY>
+structure which encodes the certificate of B<x>. The returned value
+must not be freed up after use.
+
+X509_set_pubkey() attempts to set the public key for certificate B<x> to
+B<pkey>. The key B<pkey> should be freed up after use.
+
+X509_REQ_get_pubkey(), X509_REQ_get0_pubkey(), X509_REQ_set_pubkey() and
+X509_REQ_get_X509_PUBKEY() are similar but operate on certificate request B<req>.
+
+=head1 NOTES
+
+The first time a public key is decoded the B<EVP_PKEY> structure is
+cached in the certificate or certificate request itself. Subsequent calls
+return the cached structure with its reference count incremented to
+improve performance.
+
+=head1 RETURN VALUES
+
+X509_get_pubkey(), X509_get0_pubkey(), X509_get_X509_PUBKEY(),
+X509_REQ_get_pubkey() and X509_REQ_get_X509_PUBKEY() return a public key or
+B<NULL> if an error occurred.
+
+X509_set_pubkey() and X509_REQ_set_pubkey() return 1 for success and 0
+for failure.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get_serialNumber,
+X509_get0_serialNumber,
+X509_set_serialNumber
+- get or set certificate serial number
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ ASN1_INTEGER *X509_get_serialNumber(X509 *x);
+ const ASN1_INTEGER *X509_get0_serialNumber(const X509 *x);
+ int X509_set_serialNumber(X509 *x, ASN1_INTEGER *serial);
+
+=head1 DESCRIPTION
+
+X509_get_serialNumber() returns the serial number of certificate B<x> as an
+B<ASN1_INTEGER> structure which can be examined or initialised. The value
+returned is an internal pointer which B<MUST NOT> be freed up after the call.
+
+X509_get0_serialNumber() is the same as X509_get_serialNumber() except it
+accepts a const parameter and returns a const result.
+
+X509_set_serialNumber() sets the serial number of certificate B<x> to
+B<serial>. A copy of the serial number is used internally so B<serial> should
+be freed up after use.
+
+=head1 RETURN VALUES
+
+X509_get_serialNumber() and X509_get0_serialNumber() return an B<ASN1_INTEGER>
+structure.
+
+X509_set_serialNumber() returns 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 HISTORY
+
+X509_get_serialNumber() and X509_set_serialNumber() are available in
+all versions of OpenSSL. X509_get0_serialNumber() was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get_subject_name, X509_set_subject_name, X509_get_issuer_name,
+X509_set_issuer_name, X509_REQ_get_subject_name, X509_REQ_set_subject_name,
+X509_CRL_get_issuer, X509_CRL_set_issuer_name - get and set issuer or
+subject names
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509_NAME *X509_get_subject_name(const X509 *x);
+ int X509_set_subject_name(X509 *x, X509_NAME *name);
+
+ X509_NAME *X509_get_issuer_name(const X509 *x);
+ int X509_set_issuer_name(X509 *x, X509_NAME *name);
+
+ X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req);
+ int X509_REQ_set_subject_name(X509_REQ *req, X509_NAME *name);
+
+ X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl);
+ int X509_CRL_set_issuer_name(X509_CRL *x, X509_NAME *name);
+
+=head1 DESCRIPTION
+
+X509_get_subject_name() returns the subject name of certificate B<x>. The
+returned value is an internal pointer which B<MUST NOT> be freed.
+
+X509_set_subject_name() sets the issuer name of certificate B<x> to
+B<name>. The B<name> parameter is copied internally and should be freed
+up when it is no longer needed.
+
+X509_get_issuer_name() and X509_set_issuer_name() are identical to
+X509_get_subject_name() and X509_set_subject_name() except the get and
+set the issuer name of B<x>.
+
+Similarly X509_REQ_get_subject_name(), X509_REQ_set_subject_name(),
+ X509_CRL_get_issuer() and X509_CRL_set_issuer_name() get or set the subject
+or issuer names of certificate requests of CRLs respectively.
+
+=head1 RETURN VALUES
+
+X509_get_subject_name(), X509_get_issuer_name(), X509_REQ_get_subject_name()
+and X509_CRL_get_issuer() return an B<X509_NAME> pointer.
+
+X509_set_subject_name(), X509_set_issuer_name(), X509_REQ_set_subject_name()
+and X509_CRL_set_issuer_name() return 1 for success and 0 for failure.
+
+=head1 HISTORY
+
+X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in
+earlier versions.
+
+X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was first added
+to OpenSSL 1.0.0 as a macro.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>, L<d2i_X509(3)>
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_get_version, X509_set_version, X509_REQ_get_version, X509_REQ_set_version,
+X509_CRL_get_version, X509_CRL_set_version - get or set certificate,
+certificate request or CRL version
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ long X509_get_version(const X509 *x);
+ int X509_set_version(X509 *x, long version);
+
+ long X509_REQ_get_version(const X509_REQ *req);
+ int X509_REQ_set_version(X509_REQ *x, long version);
+
+ long X509_CRL_get_version(const X509_CRL *crl);
+ int X509_CRL_set_version(X509_CRL *x, long version);
+
+=head1 DESCRIPTION
+
+X509_get_version() returns the numerical value of the version field of
+certificate B<x>. Note: this is defined by standards (X.509 et al) to be one
+less than the certificate version. So a version 3 certificate will return 2 and
+a version 1 certificate will return 0.
+
+X509_set_version() sets the numerical value of the version field of certificate
+B<x> to B<version>.
+
+Similarly X509_REQ_get_version(), X509_REQ_set_version(),
+X509_CRL_get_version() and X509_CRL_set_version() get and set the version
+number of certificate requests and CRLs.
+
+=head1 NOTES
+
+The version field of certificates, certificate requests and CRLs has a
+DEFAULT value of B<v1(0)> meaning the field should be omitted for version
+1. This is handled transparently by these functions.
+
+=head1 RETURN VALUES
+
+X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version()
+return the numerical value of the version field.
+
+X509_set_version(), X509_REQ_set_version() and X509_CRL_set_version()
+return 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 HISTORY
+
+X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version() are
+functions in OpenSSL 1.1.0, in previous versions they were macros.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_chain_up_ref,
+X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509 *X509_new(void);
+ void X509_free(X509 *a);
+ int X509_up_ref(X509 *a);
+ STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
+
+=head1 DESCRIPTION
+
+The X509 ASN1 allocation routines, allocate and free an
+X509 structure, which represents an X509 certificate.
+
+X509_new() allocates and initializes a X509 structure with reference count
+B<1>.
+
+X509_free() decrements the reference count of B<X509> structure B<a> and
+frees it up if the reference count is zero. If B<a> is NULL nothing is done.
+
+X509_up_ref() increments the reference count of B<a>.
+
+X509_chain_up_ref() increases the reference count of all certificates in
+chain B<x> and returns a copy of the stack.
+
+=head1 NOTES
+
+The function X509_up_ref() if useful if a certificate structure is being
+used by several different operations each of which will free it up after
+use: this avoids the need to duplicate the entire certificate structure.
+
+The function X509_chain_up_ref() doesn't just up the reference count of
+each certificate it also returns a copy of the stack, using sk_X509_dup(),
+but it serves a similar purpose: the returned chain persists after the
+original has been freed.
+
+=head1 RETURN VALUES
+
+If the allocation fails, X509_new() returns B<NULL> and sets an error
+code that can be obtained by L<ERR_get_error(3)>.
+Otherwise it returns a pointer to the newly allocated structure.
+
+X509_up_ref() returns 1 for success and 0 for failure.
+
+X509_chain_up_ref() returns a copy of the stack or B<NULL> if an error
+occurred.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_sign, X509_sign_ctx, X509_verify, X509_REQ_sign, X509_REQ_sign_ctx,
+X509_REQ_verify, X509_CRL_sign, X509_CRL_sign_ctx, X509_CRL_verify -
+sign or verify certificate, certificate request or CRL signature
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_sign(X509 *x, EVP_PKEY *pkey, const EVP_MD *md);
+ int X509_sign_ctx(X509 *x, EVP_MD_CTX *ctx);
+ int X509_verify(X509 *a, EVP_PKEY *r);
+
+ int X509_REQ_sign(X509_REQ *x, EVP_PKEY *pkey, const EVP_MD *md);
+ int X509_REQ_sign_ctx(X509_REQ *x, EVP_MD_CTX *ctx);
+ int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r);
+
+ int X509_CRL_sign(X509_CRL *x, EVP_PKEY *pkey, const EVP_MD *md);
+ int X509_CRL_sign_ctx(X509_CRL *x, EVP_MD_CTX *ctx);
+ int X509_CRL_verify(X509_CRL *a, EVP_PKEY *r);
+
+=head1 DESCRIPTION
+
+X509_sign() signs certificate B<x> using private key B<pkey> and message
+digest B<md> and sets the signature in B<x>. X509_sign_ctx() also signs
+certificate B<x> but uses the parameters contained in digest context B<ctx>.
+
+X509_verify() verifies the signature of certificate B<x> using public key
+B<pkey>. Only the signature is checked: no other checks (such as certificate
+chain validity) are performed.
+
+X509_REQ_sign(), X509_REQ_sign_ctx(), X509_REQ_verify(),
+X509_CRL_sign(), X509_CRL_sign_ctx() and X509_CRL_verify() sign and verify
+certificate requests and CRLs respectively.
+
+=head1 NOTES
+
+X509_sign_ctx() is used where the default parameters for the corresponding
+public key and digest are not suitable. It can be used to sign keys using
+RSA-PSS for example.
+
+For efficiency reasons and to work around ASN.1 encoding issues the encoding
+of the signed portion of a certificate, certificate request and CRL is cached
+internally. If the signed portion of the structure is modified the encoding
+is not always updated meaning a stale version is sometimes used. This is not
+normally a problem because modifying the signed portion will invalidate the
+signature and signing will always update the encoding.
+
+=head1 RETURN VALUES
+
+X509_sign(), X509_sign_ctx(), X509_REQ_sign(), X509_REQ_sign_ctx(),
+X509_CRL_sign() and X509_CRL_sign_ctx() return the size of the signature
+in bytes for success and zero for failure.
+
+X509_verify(), X509_REQ_verify() and X509_CRL_verify() return 1 if the
+signature is valid and 0 if the signature check fails. If the signature
+could not be checked at all because it was invalid or some other error
+occurred then -1 is returned.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>,
+L<ERR_get_error(3)>,
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 HISTORY
+
+X509_sign(), X509_REQ_sign() and X509_CRL_sign() are available in all
+versions of OpenSSL.
+
+X509_sign_ctx(), X509_REQ_sign_ctx() and X509_CRL_sign_ctx() were first added
+to OpenSSL 1.0.1.
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509_verify_cert - discover and verify X509 certificate chain
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_verify_cert(X509_STORE_CTX *ctx);
+
+=head1 DESCRIPTION
+
+The X509_verify_cert() function attempts to discover and validate a
+certificate chain based on parameters in B<ctx>. A complete description of
+the process is contained in the L<verify(1)> manual page.
+
+=head1 RETURN VALUES
+
+If a complete chain can be built and validated this function returns 1,
+otherwise it return zero, in exceptional circumstances it can also
+return a negative code.
+
+If the function fails additional error information can be obtained by
+examining B<ctx> using, for example X509_STORE_CTX_get_error().
+
+=head1 NOTES
+
+Applications rarely call this function directly but it is used by
+OpenSSL internally for certificate validation, in both the S/MIME and
+SSL/TLS code.
+
+A negative return value from X509_verify_cert() can occur if it is invoked
+incorrectly, such as with no certificate set in B<ctx>, or when it is called
+twice in succession without reinitialising B<ctx> for the second call.
+A negative return value can also happen due to internal resource problems or if
+a retry operation is requested during internal lookups (which never happens
+with standard lookup methods).
+Applications must check for <= 0 return value on error.
+
+=head1 BUGS
+
+This function uses the header B<x509.h> as opposed to most chain verification
+functions which use B<x509_vfy.h>.
+
+=head1 SEE ALSO
+
+L<X509_STORE_CTX_get_error(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID,
+X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext,
+X509v3_add_ext, X509_get_ext_count, X509_get_ext,
+X509_get_ext_by_NID, X509_get_ext_by_OBJ, X509_get_ext_by_critical,
+X509_delete_ext, X509_add_ext, X509_CRL_get_ext_count, X509_CRL_get_ext,
+X509_CRL_get_ext_by_NID, X509_CRL_get_ext_by_OBJ, X509_CRL_get_ext_by_critical,
+X509_CRL_delete_ext, X509_CRL_add_ext, X509_REVOKED_get_ext_count,
+X509_REVOKED_get_ext, X509_REVOKED_get_ext_by_NID, X509_REVOKED_get_ext_by_OBJ,
+X509_REVOKED_get_ext_by_critical, X509_REVOKED_delete_ext,
+X509_REVOKED_add_ext - extension stack utility functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x);
+ X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc);
+
+ int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x,
+ int nid, int lastpos);
+ int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x,
+ const ASN1_OBJECT *obj, int lastpos);
+ int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x,
+ int crit, int lastpos);
+ X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc);
+ STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x,
+ X509_EXTENSION *ex, int loc);
+
+ int X509_get_ext_count(const X509 *x);
+ X509_EXTENSION *X509_get_ext(const X509 *x, int loc);
+ int X509_get_ext_by_NID(const X509 *x, int nid, int lastpos);
+ int X509_get_ext_by_OBJ(const X509 *x, const ASN1_OBJECT *obj, int lastpos);
+ int X509_get_ext_by_critical(const X509 *x, int crit, int lastpos);
+ X509_EXTENSION *X509_delete_ext(X509 *x, int loc);
+ int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc);
+
+ int X509_CRL_get_ext_count(const X509_CRL *x);
+ X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc);
+ int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos);
+ int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, int lastpos);
+ int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos);
+ X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc);
+ int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc);
+
+ int X509_REVOKED_get_ext_count(const X509_REVOKED *x);
+ X509_EXTENSION *X509_REVOKED_get_ext(const X509_REVOKED *x, int loc);
+ int X509_REVOKED_get_ext_by_NID(const X509_REVOKED *x, int nid, int lastpos);
+ int X509_REVOKED_get_ext_by_OBJ(const X509_REVOKED *x, const ASN1_OBJECT *obj,
+ int lastpos);
+ int X509_REVOKED_get_ext_by_critical(const X509_REVOKED *x, int crit, int lastpos);
+ X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc);
+ int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc);
+
+=head1 DESCRIPTION
+
+X509v3_get_ext_count() retrieves the number of extensions in B<x>.
+
+X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc>
+can take any value from B<0> to X509_get_ext_count(x) - 1. The returned
+extension is an internal pointer which B<must not> be freed up by the
+application.
+
+X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension
+with B<nid> or B<obj> from extension stack B<x>. The search starts from the
+extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If
+the extension is found its index is returned otherwise B<-1> is returned.
+
+X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it
+looks for an extension of criticality B<crit>. A zero value for B<crit>
+looks for a non-critical extension a non-zero value looks for a critical
+extension.
+
+X509v3_delete_ext() deletes the extension with index B<loc> from B<x>. The
+deleted extension is returned and must be freed by the caller. If B<loc>
+is in invalid index value B<NULL> is returned.
+
+X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If
+B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL>
+a new stack will be allocated. The passed extension B<ex> is duplicated
+internally so it must be freed after use.
+
+X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(),
+X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext()
+and X509_add_ext() operate on the extensions of certificate B<x> they are
+otherwise identical to the X509v3 functions.
+
+X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(),
+X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(),
+X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of
+CRL B<x> they are otherwise identical to the X509v3 functions.
+
+X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(),
+X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(),
+X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and
+X509_REVOKED_add_ext() operate on the extensions of CRL entry B<x>
+they are otherwise identical to the X509v3 functions.
+
+=head1 NOTES
+
+These functions are used to examine stacks of extensions directly. Many
+applications will want to parse or encode and add an extension: they should
+use the extension encode and decode functions instead such as
+X509_add1_ext_i2d() and X509_get_ext_d2i().
+
+Extension indices start from zero, so a zero index return value is B<not> an
+error. These search functions start from the extension B<after> the B<lastpos>
+parameter so it should initially be set to B<-1>, if it is set to zero the
+initial extension will not be checked.
+
+=head1 RETURN VALUES
+
+X509v3_get_ext_count() returns the extension count.
+
+X509v3_get_ext() and X509v3_delete_ext() return an B<X509_EXTENSION> pointer
+or B<NULL> if an error occurs.
+
+X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and
+X509v3_get_ext_by_critical() return the an extension index or B<-1> if an
+error occurs.
+
+X509v3_add_ext() returns a stack of extensions or B<NULL> on error.
+
+=head1 SEE ALSO
+
+L<X509V3_get_d2i(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ DH *d2i_DHparams(DH **a, unsigned char **pp, long length);
+ int i2d_DHparams(DH *a, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode PKCS#3 DH parameters using the
+DHparameter structure described in PKCS#3.
+
+Otherwise these behave in a similar way to d2i_X509() and i2d_X509()
+described in the L<d2i_X509(3)> manual page.
+
+=head1 SEE ALSO
+
+L<d2i_X509(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+i2d_Netscape_RSA,
+d2i_Netscape_RSA
+- insecure RSA public and private key encoding functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());
+ RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)());
+
+=head1 DESCRIPTION
+
+These functions decode and encode an RSA private
+key in NET format. These functions are present to provide compatibility
+with very old software. This format has some severe security weaknesses
+and should be avoided if possible.
+
+These functions are similar to the B<d2i_RSAPrivateKey> functions.
+
+=head1 SEE ALSO
+
+L<d2i_RSAPrivateKey(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp,
+i2d_PKCS8PrivateKey_bio, i2d_PKCS8PrivateKey_fp,
+i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8 format private key functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u);
+ EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+ int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid,
+ char *kstr, int klen,
+ pem_password_cb *cb, void *u);
+
+=head1 DESCRIPTION
+
+The PKCS#8 functions encode and decode private keys in PKCS#8 format using both
+PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms.
+
+Other than the use of DER as opposed to PEM these functions are identical to the
+corresponding B<PEM> function as described in L<PEM_read_PrivateKey(3)>.
+
+=head1 NOTES
+
+These functions are currently the only way to store encrypted private keys using DER format.
+
+Currently all the functions use BIOs or FILE pointers, there are no functions which
+work directly on memory: this can be readily worked around by converting the buffers
+to memory BIOs, see L<BIO_s_mem(3)> for details.
+
+=head1 SEE ALSO
+
+L<PEM_read_PrivateKey(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+d2i_PrivateKey, d2i_AutoPrivateKey, i2d_PrivateKey,
+d2i_PrivateKey_bio, d2i_PrivateKey_fp
+- decode and encode functions for reading and saving EVP_PKEY structures
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp,
+ long length);
+ EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp,
+ long length);
+ int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp);
+
+ EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a);
+ EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a)
+
+=head1 DESCRIPTION
+
+d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to
+use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The
+B<type> parameter should be a public key algorithm constant such as
+B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>.
+
+d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to
+automatically detect the private key format.
+
+i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is
+defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format.
+
+These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>.
+
+=head1 NOTES
+
+All these functions use DER format and unencrypted keys. Applications wishing
+to encrypt or decrypt private keys should use other functions such as
+d2i_PKC8PrivateKey() instead.
+
+If the B<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey()
+(i.e. an existing structure is being reused) and the key format is PKCS#8
+then B<*a> will be freed and replaced on a successful call.
+
+=head1 RETURN VALUES
+
+d2i_PrivateKey() and d2i_AutoPrivateKey() return a valid B<EVP_KEY> structure
+or B<NULL> if an error occurs. The error code can be obtained by calling
+L<ERR_get_error(3)>.
+
+i2d_PrivateKey() returns the number of bytes successfully encoded or a
+negative value if an error occurs. The error code can be obtained by calling
+L<ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<crypto(3)>,
+L<d2i_PKCS8PrivateKey(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length);
+ int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+These functions decode and encode an SSL_SESSION object.
+For encoding details see L<d2i_X509(3)>.
+
+SSL_SESSION objects keep internal link information about the session cache
+list, when being inserted into one SSL_CTX object's session cache.
+One SSL_SESSION object, regardless of its reference count, must therefore
+only be used with one SSL_CTX object (and the SSL objects created
+from this SSL_CTX object).
+
+=head1 RETURN VALUES
+
+d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION
+object. In case of failure the NULL-pointer is returned and the error message
+can be retrieved from the error stack.
+
+i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes.
+When the session is not valid, B<0> is returned and no operation is performed.
+
+=head1 SEE ALSO
+
+L<ssl(3)>, L<SSL_SESSION_free(3)>,
+L<SSL_CTX_sess_set_get_cb(3)>,
+L<d2i_X509(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+d2i_ACCESS_DESCRIPTION,
+d2i_ASIdOrRange,
+d2i_ASIdentifierChoice,
+d2i_ASIdentifiers,
+d2i_ASN1_BIT_STRING,
+d2i_ASN1_BMPSTRING,
+d2i_ASN1_ENUMERATED,
+d2i_ASN1_GENERALIZEDTIME,
+d2i_ASN1_GENERALSTRING,
+d2i_ASN1_IA5STRING,
+d2i_ASN1_INTEGER,
+d2i_ASN1_NULL,
+d2i_ASN1_OBJECT,
+d2i_ASN1_OCTET_STRING,
+d2i_ASN1_PRINTABLE,
+d2i_ASN1_PRINTABLESTRING,
+d2i_ASN1_SEQUENCE_ANY,
+d2i_ASN1_SET_ANY,
+d2i_ASN1_T61STRING,
+d2i_ASN1_TIME,
+d2i_ASN1_TYPE,
+d2i_ASN1_UINTEGER,
+d2i_ASN1_UNIVERSALSTRING,
+d2i_ASN1_UTCTIME,
+d2i_ASN1_UTF8STRING,
+d2i_ASN1_VISIBLESTRING,
+d2i_ASRange,
+d2i_AUTHORITY_INFO_ACCESS,
+d2i_AUTHORITY_KEYID,
+d2i_BASIC_CONSTRAINTS,
+d2i_CERTIFICATEPOLICIES,
+d2i_CMS_ContentInfo,
+d2i_CMS_ReceiptRequest,
+d2i_CMS_bio,
+d2i_CRL_DIST_POINTS,
+d2i_DHxparams,
+d2i_DIRECTORYSTRING,
+d2i_DISPLAYTEXT,
+d2i_DIST_POINT,
+d2i_DIST_POINT_NAME,
+d2i_DSAPrivateKey,
+d2i_DSAPrivateKey_bio,
+d2i_DSAPrivateKey_fp,
+d2i_DSAPublicKey,
+d2i_DSA_PUBKEY_bio,
+d2i_DSA_PUBKEY_fp,
+d2i_DSA_SIG,
+d2i_DSAparams,
+d2i_ECPKParameters,
+d2i_ECParameters,
+d2i_ECPrivateKey,
+d2i_ECPrivateKey_bio,
+d2i_ECPrivateKey_fp,
+d2i_EC_PUBKEY,
+d2i_EC_PUBKEY_bio,
+d2i_EC_PUBKEY_fp,
+d2i_EDIPARTYNAME,
+d2i_ESS_CERT_ID,
+d2i_ESS_ISSUER_SERIAL,
+d2i_ESS_SIGNING_CERT,
+d2i_EXTENDED_KEY_USAGE,
+d2i_GENERAL_NAME,
+d2i_GENERAL_NAMES,
+d2i_IPAddressChoice,
+d2i_IPAddressFamily,
+d2i_IPAddressOrRange,
+d2i_IPAddressRange,
+d2i_ISSUING_DIST_POINT,
+d2i_NETSCAPE_CERT_SEQUENCE,
+d2i_NETSCAPE_SPKAC,
+d2i_NETSCAPE_SPKI,
+d2i_NOTICEREF,
+d2i_OCSP_BASICRESP,
+d2i_OCSP_CERTID,
+d2i_OCSP_CERTSTATUS,
+d2i_OCSP_CRLID,
+d2i_OCSP_ONEREQ,
+d2i_OCSP_REQINFO,
+d2i_OCSP_REQUEST,
+d2i_OCSP_RESPBYTES,
+d2i_OCSP_RESPDATA,
+d2i_OCSP_RESPID,
+d2i_OCSP_RESPONSE,
+d2i_OCSP_REVOKEDINFO,
+d2i_OCSP_SERVICELOC,
+d2i_OCSP_SIGNATURE,
+d2i_OCSP_SINGLERESP,
+d2i_OTHERNAME,
+d2i_PBE2PARAM,
+d2i_PBEPARAM,
+d2i_PBKDF2PARAM,
+d2i_PKCS12,
+d2i_PKCS12_BAGS,
+d2i_PKCS12_MAC_DATA,
+d2i_PKCS12_SAFEBAG,
+d2i_PKCS12_bio,
+d2i_PKCS12_fp,
+d2i_PKCS7,
+d2i_PKCS7_DIGEST,
+d2i_PKCS7_ENCRYPT,
+d2i_PKCS7_ENC_CONTENT,
+d2i_PKCS7_ENVELOPE,
+d2i_PKCS7_ISSUER_AND_SERIAL,
+d2i_PKCS7_RECIP_INFO,
+d2i_PKCS7_SIGNED,
+d2i_PKCS7_SIGNER_INFO,
+d2i_PKCS7_SIGN_ENVELOPE,
+d2i_PKCS7_bio,
+d2i_PKCS7_fp,
+d2i_PKCS8_PRIV_KEY_INFO,
+d2i_PKCS8_PRIV_KEY_INFO_bio,
+d2i_PKCS8_PRIV_KEY_INFO_fp,
+d2i_PKCS8_bio,
+d2i_PKCS8_fp,
+d2i_PKEY_USAGE_PERIOD,
+d2i_POLICYINFO,
+d2i_POLICYQUALINFO,
+d2i_PROXY_CERT_INFO_EXTENSION,
+d2i_PROXY_POLICY,
+d2i_PublicKey,
+d2i_RSAPrivateKey,
+d2i_RSAPrivateKey_bio,
+d2i_RSAPrivateKey_fp,
+d2i_RSAPublicKey,
+d2i_RSAPublicKey_bio,
+d2i_RSAPublicKey_fp,
+d2i_RSA_OAEP_PARAMS,
+d2i_RSA_PSS_PARAMS,
+d2i_RSA_PUBKEY,
+d2i_RSA_PUBKEY_bio,
+d2i_RSA_PUBKEY_fp,
+d2i_SCT_LIST,
+d2i_SXNET,
+d2i_SXNETID,
+d2i_TS_ACCURACY,
+d2i_TS_MSG_IMPRINT,
+d2i_TS_MSG_IMPRINT_bio,
+d2i_TS_MSG_IMPRINT_fp,
+d2i_TS_REQ,
+d2i_TS_REQ_bio,
+d2i_TS_REQ_fp,
+d2i_TS_RESP,
+d2i_TS_RESP_bio,
+d2i_TS_RESP_fp,
+d2i_TS_STATUS_INFO,
+d2i_TS_TST_INFO,
+d2i_TS_TST_INFO_bio,
+d2i_TS_TST_INFO_fp,
+d2i_USERNOTICE,
+d2i_X509,
+d2i_X509_ALGOR,
+d2i_X509_ALGORS,
+d2i_X509_ATTRIBUTE,
+d2i_X509_CERT_AUX,
+d2i_X509_CINF,
+d2i_X509_CRL,
+d2i_X509_CRL_INFO,
+d2i_X509_CRL_bio,
+d2i_X509_CRL_fp,
+d2i_X509_EXTENSION,
+d2i_X509_EXTENSIONS,
+d2i_X509_NAME,
+d2i_X509_NAME_ENTRY,
+d2i_X509_PUBKEY,
+d2i_X509_REQ,
+d2i_X509_REQ_INFO,
+d2i_X509_REQ_bio,
+d2i_X509_REQ_fp,
+d2i_X509_REVOKED,
+d2i_X509_SIG,
+d2i_X509_VAL,
+i2d_ACCESS_DESCRIPTION,
+i2d_ASIdOrRange,
+i2d_ASIdentifierChoice,
+i2d_ASIdentifiers,
+i2d_ASN1_BIT_STRING,
+i2d_ASN1_BMPSTRING,
+i2d_ASN1_ENUMERATED,
+i2d_ASN1_GENERALIZEDTIME,
+i2d_ASN1_GENERALSTRING,
+i2d_ASN1_IA5STRING,
+i2d_ASN1_INTEGER,
+i2d_ASN1_NULL,
+i2d_ASN1_OBJECT,
+i2d_ASN1_OCTET_STRING,
+i2d_ASN1_PRINTABLE,
+i2d_ASN1_PRINTABLESTRING,
+i2d_ASN1_SEQUENCE_ANY,
+i2d_ASN1_SET_ANY,
+i2d_ASN1_T61STRING,
+i2d_ASN1_TIME,
+i2d_ASN1_TYPE,
+i2d_ASN1_UNIVERSALSTRING,
+i2d_ASN1_UTCTIME,
+i2d_ASN1_UTF8STRING,
+i2d_ASN1_VISIBLESTRING,
+i2d_ASN1_bio_stream,
+i2d_ASRange,
+i2d_AUTHORITY_INFO_ACCESS,
+i2d_AUTHORITY_KEYID,
+i2d_BASIC_CONSTRAINTS,
+i2d_CERTIFICATEPOLICIES,
+i2d_CMS_ContentInfo,
+i2d_CMS_ReceiptRequest,
+i2d_CMS_bio,
+i2d_CRL_DIST_POINTS,
+i2d_DHxparams,
+i2d_DIRECTORYSTRING,
+i2d_DISPLAYTEXT,
+i2d_DIST_POINT,
+i2d_DIST_POINT_NAME,
+i2d_DSAPrivateKey,
+i2d_DSAPrivateKey_bio,
+i2d_DSAPrivateKey_fp,
+i2d_DSAPublicKey,
+i2d_DSA_PUBKEY_bio,
+i2d_DSA_PUBKEY_fp,
+i2d_DSA_SIG,
+i2d_DSAparams,
+i2d_ECPKParameters,
+i2d_ECParameters,
+i2d_ECPrivateKey,
+i2d_ECPrivateKey_bio,
+i2d_ECPrivateKey_fp,
+i2d_EC_PUBKEY,
+i2d_EC_PUBKEY_bio,
+i2d_EC_PUBKEY_fp,
+i2d_EDIPARTYNAME,
+i2d_ESS_CERT_ID,
+i2d_ESS_ISSUER_SERIAL,
+i2d_ESS_SIGNING_CERT,
+i2d_EXTENDED_KEY_USAGE,
+i2d_GENERAL_NAME,
+i2d_GENERAL_NAMES,
+i2d_IPAddressChoice,
+i2d_IPAddressFamily,
+i2d_IPAddressOrRange,
+i2d_IPAddressRange,
+i2d_ISSUING_DIST_POINT,
+i2d_NETSCAPE_CERT_SEQUENCE,
+i2d_NETSCAPE_SPKAC,
+i2d_NETSCAPE_SPKI,
+i2d_NOTICEREF,
+i2d_OCSP_BASICRESP,
+i2d_OCSP_CERTID,
+i2d_OCSP_CERTSTATUS,
+i2d_OCSP_CRLID,
+i2d_OCSP_ONEREQ,
+i2d_OCSP_REQINFO,
+i2d_OCSP_REQUEST,
+i2d_OCSP_RESPBYTES,
+i2d_OCSP_RESPDATA,
+i2d_OCSP_RESPID,
+i2d_OCSP_RESPONSE,
+i2d_OCSP_REVOKEDINFO,
+i2d_OCSP_SERVICELOC,
+i2d_OCSP_SIGNATURE,
+i2d_OCSP_SINGLERESP,
+i2d_OTHERNAME,
+i2d_PBE2PARAM,
+i2d_PBEPARAM,
+i2d_PBKDF2PARAM,
+i2d_PKCS12,
+i2d_PKCS12_BAGS,
+i2d_PKCS12_MAC_DATA,
+i2d_PKCS12_SAFEBAG,
+i2d_PKCS12_bio,
+i2d_PKCS12_fp,
+i2d_PKCS7,
+i2d_PKCS7_DIGEST,
+i2d_PKCS7_ENCRYPT,
+i2d_PKCS7_ENC_CONTENT,
+i2d_PKCS7_ENVELOPE,
+i2d_PKCS7_ISSUER_AND_SERIAL,
+i2d_PKCS7_NDEF,
+i2d_PKCS7_RECIP_INFO,
+i2d_PKCS7_SIGNED,
+i2d_PKCS7_SIGNER_INFO,
+i2d_PKCS7_SIGN_ENVELOPE,
+i2d_PKCS7_bio,
+i2d_PKCS7_fp,
+i2d_PKCS8PrivateKeyInfo_bio,
+i2d_PKCS8PrivateKeyInfo_fp,
+i2d_PKCS8_PRIV_KEY_INFO,
+i2d_PKCS8_PRIV_KEY_INFO_bio,
+i2d_PKCS8_PRIV_KEY_INFO_fp,
+i2d_PKCS8_bio,
+i2d_PKCS8_fp,
+i2d_PKEY_USAGE_PERIOD,
+i2d_POLICYINFO,
+i2d_POLICYQUALINFO,
+i2d_PROXY_CERT_INFO_EXTENSION,
+i2d_PROXY_POLICY,
+i2d_PublicKey,
+i2d_RSAPrivateKey,
+i2d_RSAPrivateKey_bio,
+i2d_RSAPrivateKey_fp,
+i2d_RSAPublicKey,
+i2d_RSAPublicKey_bio,
+i2d_RSAPublicKey_fp,
+i2d_RSA_OAEP_PARAMS,
+i2d_RSA_PSS_PARAMS,
+i2d_RSA_PUBKEY,
+i2d_RSA_PUBKEY_bio,
+i2d_RSA_PUBKEY_fp,
+i2d_SCT_LIST,
+i2d_SXNET,
+i2d_SXNETID,
+i2d_TS_ACCURACY,
+i2d_TS_MSG_IMPRINT,
+i2d_TS_MSG_IMPRINT_bio,
+i2d_TS_MSG_IMPRINT_fp,
+i2d_TS_REQ,
+i2d_TS_REQ_bio,
+i2d_TS_REQ_fp,
+i2d_TS_RESP,
+i2d_TS_RESP_bio,
+i2d_TS_RESP_fp,
+i2d_TS_STATUS_INFO,
+i2d_TS_TST_INFO,
+i2d_TS_TST_INFO_bio,
+i2d_TS_TST_INFO_fp,
+i2d_USERNOTICE,
+i2d_X509,
+i2d_X509_ALGOR,
+i2d_X509_ALGORS,
+i2d_X509_ATTRIBUTE,
+i2d_X509_CERT_AUX,
+i2d_X509_CINF,
+i2d_X509_CRL,
+i2d_X509_CRL_INFO,
+i2d_X509_CRL_bio,
+i2d_X509_CRL_fp,
+i2d_X509_EXTENSION,
+i2d_X509_EXTENSIONS,
+i2d_X509_NAME,
+i2d_X509_NAME_ENTRY,
+i2d_X509_PUBKEY,
+i2d_X509_REQ,
+i2d_X509_REQ_INFO,
+i2d_X509_REQ_bio,
+i2d_X509_REQ_fp,
+i2d_X509_REVOKED,
+i2d_X509_SIG,
+i2d_X509_VAL,
+- convert objects from/to ASN.1/DER representation
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length);
+ TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
+ TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
+
+ int i2d_TYPE(TYPE *a, unsigned char **pp);
+ int i2d_TYPE_fp(FILE *fp, TYPE *a);
+ int i2d_TYPE_bio(BIO *bp, TYPE *a);
+
+=head1 DESCRIPTION
+
+In the description here, I<TYPE> is used a placeholder
+for any of the OpenSSL datatypes, such as I<X509_CRL>.
+
+These functions convert OpenSSL objects to and from their ASN.1/DER
+encoding. Unlike the C structures which can have pointers to sub-objects
+within, the DER is a serialized encoding, suitable for sending over the
+network, writing to a file, and so on.
+
+d2i_TYPE() attempts to decode B<len> bytes at B<*in>. If successful a
+pointer to the B<TYPE> structure is returned and B<*in> is incremented to
+the byte following the parsed data. If B<a> is not B<NULL> then a pointer
+to the returned structure is also written to B<*a>. If an error occurred
+then B<NULL> is returned.
+
+On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
+contains a valid B<TYPE> structure and an attempt is made to reuse it. This
+"reuse" capability is present for historical compatibility but its use is
+B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
+VALUES section).
+
+d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
+to parse data from BIO B<bp>.
+
+d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
+to parse data from FILE pointer B<fp>.
+
+i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
+If B<out> is not B<NULL>, it writes the DER encoded data to the buffer
+at B<*out>, and increments it to point after the data just written.
+If the return value is negative an error occurred, otherwise it
+returns the length of the encoded data.
+
+If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded
+data written to it. In this case B<*out> is not incremented and it points
+to the start of the data just written.
+
+i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
+the encoding of the structure B<a> to BIO B<bp> and it
+returns 1 for success and 0 for failure.
+
+i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
+the encoding of the structure B<a> to BIO B<bp> and it
+returns 1 for success and 0 for failure.
+
+These routines do not encrypt private keys and therefore offer no
+security; use L<PEM_write_PrivateKey(3)> or similar for writing to files.
+
+=head1 NOTES
+
+The letters B<i> and B<d> in B<i2d_TYPE> stand for
+"internal" (that is, an internal C structure) and "DER" respectively.
+So B<i2d_TYPE> converts from internal to DER.
+
+The functions can also understand B<BER> forms.
+
+The actual TYPE structure passed to i2d_TYPE() must be a valid
+populated B<TYPE> structure -- it B<cannot> simply be fed with an
+empty structure such as that returned by TYPE_new().
+
+The encoded data is in binary form and may contain embedded zeroes.
+Therefore any FILE pointers or BIOs should be opened in binary mode.
+Functions such as strlen() will B<not> return the correct length
+of the encoded structure.
+
+The ways that B<*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 this-auto increment behaviour is to reflect a typical
+usage of ASN1 functions: after one structure is encoded or decoded
+another will be processed after it.
+
+The following points about the data types might be useful:
+
+=over
+
+=item B<ASN1_OBJECT>
+
+Represents an ASN1 OBJECT IDENTIFIER.
+
+=item B<DHparams>
+
+Represents a PKCS#3 DH parameters structure.
+
+=item B<DHparamx>
+
+Represents a ANSI X9.42 DH parameters structure.
+
+=item B<DSA_PUBKEY>
+
+Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
+
+=item B<DSAPublicKey, DSAPrivateKey>
+
+Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
+B<PEM_write_PrivateKey(3)>, or similar instead.
+
+=item B<RSAPublicKey>
+
+Represents a PKCS#1 RSA public key structure.
+
+=item B<X509_ALGOR>
+
+Represents an B<AlogrithmIdentifier> structure as used in IETF RFC 6960 and
+elsewhere.
+
+=item B<X509_Name>
+
+Represents a B<Name> type as used for subject and issuer names in
+IETF RFC 6960 and elsewhere.
+
+=item B<X509_REQ>
+
+Represents a PKCS#10 certificate request.
+
+=item B<X509_SIG>
+
+Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
+
+=back
+
+=head1 EXAMPLES
+
+Allocate and encode the DER encoding of an X509 structure:
+
+ int len;
+ unsigned char *buf;
+
+ buf = NULL;
+ len = i2d_X509(x, &buf);
+ if (len < 0)
+ /* error */
+
+Attempt to decode a buffer:
+
+ X509 *x;
+ unsigned char *buf, *p;
+ int len;
+
+ /* Set up buf and len to point to the input buffer. */
+ p = buf;
+ x = d2i_X509(NULL, &p, len);
+ if (x == NULL)
+ /* error */
+
+Alternative technique:
+
+ X509 *x;
+ unsigned char *buf, *p;
+ int len;
+
+ /* Set up buf and len to point to the input buffer. */
+ p = buf;
+ x = NULL;
+
+ if (d2i_X509(&x, &p, len) == NULL)
+ /* error */
+
+=head1 WARNINGS
+
+Using a temporary variable is mandatory. A common
+mistake is to attempt to use a buffer directly as follows:
+
+ int len;
+ unsigned char *buf;
+
+ len = i2d_X509(x, NULL);
+ buf = OPENSSL_malloc(len);
+ ...
+ i2d_X509(x, &buf);
+ ...
+ OPENSSL_free(buf);
+
+This code will result in B<buf> apparently containing garbage because
+it was incremented after the call to point after the data just written.
+Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
+and the subsequent call to OPENSSL_free() is likely to crash.
+
+Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
+
+ X509 *x;
+
+ if (d2i_X509(&x, &p, len) == NULL)
+ /* error */
+
+This will probably crash somewhere in d2i_X509(). The reason for this
+is that the variable B<x> is uninitialized and an attempt will be made to
+interpret its (invalid) value as an B<X509> structure, typically causing
+a segmentation violation. If B<x> is set to NULL first then this will not
+happen.
+
+=head1 BUGS
+
+In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
+B<*px> is valid is broken and some parts of the reused structure may
+persist if they are not present in the new one. As a result the use
+of this "reuse" behaviour is strongly discouraged.
+
+i2d_TYPE() will not return an error in many versions of OpenSSL,
+if mandatory fields are not initialized due to a programming error
+then the encoded structure may contain invalid data or omit the
+fields entirely and will not be parsed by d2i_TYPE(). This may be
+fixed in future so code should not assume that i2d_TYPE() will
+always succeed.
+
+Any function which encodes a structure (i2d_TYPE(),
+i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
+structure has been modified after deserialization or previous
+serialization. This is because some objects cache the encoding for
+efficiency reasons.
+
+=head1 RETURN VALUES
+
+d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
+or B<NULL> if an error occurs. If the "reuse" capability has been used with
+a valid structure being passed in via B<a>, then the object is not freed in
+the event of error but may be in a potentially invalid or inconsistent state.
+
+i2d_TYPE() returns the number of bytes successfully encoded or a negative
+value if an error occurs.
+
+i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
+occurs.
+
+=head1 COPYRIGHT
+
+Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format.
+
+It is otherwise identical to the function SMIME_write_CMS().
+
+=head1 NOTES
+
+This function is effectively a version of the i2d_CMS_bio() supporting
+streaming.
+
+=head1 BUGS
+
+The prefix "i2d" is arguably wrong because the function outputs BER format.
+
+=head1 RETURN VALUES
+
+i2d_CMS_bio_stream() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<CMS_sign(3)>,
+L<CMS_verify(3)>, L<CMS_encrypt(3)>
+L<CMS_decrypt(3)>,
+L<SMIME_write_CMS(3)>,
+L<PEM_write_bio_CMS_stream(3)>
+
+=head1 HISTORY
+
+i2d_CMS_bio_stream() was added to OpenSSL 1.0.0
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+i2d_PKCS7_bio_stream - output PKCS7 structure in BER format
+
+=head1 SYNOPSIS
+
+ #include <openssl/pkcs7.h>
+
+ int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags);
+
+=head1 DESCRIPTION
+
+i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format.
+
+It is otherwise identical to the function SMIME_write_PKCS7().
+
+=head1 NOTES
+
+This function is effectively a version of the d2i_PKCS7_bio() supporting
+streaming.
+
+=head1 BUGS
+
+The prefix "i2d" is arguably wrong because the function outputs BER format.
+
+=head1 RETURN VALUES
+
+i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure.
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>, L<PKCS7_sign(3)>,
+L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)>
+L<PKCS7_decrypt(3)>,
+L<SMIME_write_PKCS7(3)>,
+L<PEM_write_bio_PKCS7_stream(3)>
+
+=head1 HISTORY
+
+i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0
+
+=head1 COPYRIGHT
+
+Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+d2i_X509_AUX, i2d_X509_AUX,
+i2d_re_X509_tbs, i2d_re_X509_CRL_tbs, i2d_re_X509_REQ_tbs
+- X509 encode and decode functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len);
+ int i2d_X509_AUX(X509 *x, unsigned char **out);
+ int i2d_re_X509_tbs(X509 *x, unsigned char **out);
+ int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **pp);
+ int i2d_re_X509_REQ_tbs(X509_REQ *req, unsigned char **pp);
+
+=head1 DESCRIPTION
+
+The X509 encode and decode routines encode and parse an
+B<X509> structure, which represents an X509 certificate.
+
+d2i_X509_AUX() is similar to L<d2i_X509(3)> but the input is expected to
+consist of an X509 certificate followed by auxiliary trust information.
+This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects.
+This function should not be called on untrusted input.
+
+i2d_X509_AUX() is similar to L<i2d_X509(3)>, but the encoded output
+contains both the certificate and any auxiliary trust information.
+This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects.
+Note that this is a non-standard OpenSSL-specific data format.
+
+i2d_re_X509_tbs() is similar to L<i2d_X509(3)> except it encodes only
+the TBSCertificate portion of the certificate. i2d_re_X509_CRL_tbs()
+and i2d_re_X509_REQ_tbs() are analogous for CRL and certificate request,
+respectively. The "re" in B<i2d_re_X509_tbs> stands for "re-encode",
+and ensures that a fresh encoding is generated in case the object has been
+modified after creation (see the BUGS section).
+
+The encoding of the TBSCertificate portion of a certificate is cached
+in the B<X509> structure internally to improve encoding performance
+and to ensure certificate signatures are verified correctly in some
+certificates with broken (non-DER) encodings.
+
+If, after modification, the B<X509> object is re-signed with X509_sign(),
+the encoding is automatically renewed. Otherwise, the encoding of the
+TBSCertificate portion of the B<X509> can be manually renewed by calling
+i2d_re_X509_tbs().
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)>
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+o2i_SCT_LIST, i2o_SCT_LIST, o2i_SCT, i2o_SCT -
+decode and encode Signed Certificate Timestamp lists in TLS wire format
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+ STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp, size_t len);
+ int i2o_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp);
+ SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len);
+ int i2o_SCT(const SCT *sct, unsigned char **out);
+
+=head1 DESCRIPTION
+
+The SCT_LIST and SCT functions are very similar to the i2d and d2i family of
+functions, except that they convert to and from TLS wire format, as described in
+RFC 6962. See L<d2i_SCT_LIST> for more information about how the parameters are
+treated and the return values.
+
+=head1 RETURN VALUES
+
+All of the functions have return values consistent with those stated for
+L<d2i_SCT_LIST> and L<i2d_SCT_LIST>.
+
+=head1 SEE ALSO
+
+L<ct(3)>,
+L<d2i_SCT_LIST(3)>,
+L<i2d_SCT_LIST(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+config - OpenSSL CONF library configuration files
+
+=head1 DESCRIPTION
+
+The OpenSSL CONF library can be used to read configuration files.
+It is used for the OpenSSL master configuration file B<openssl.cnf>
+and in a few other places like B<SPKAC> files and certificate extension
+files for the B<x509> utility. OpenSSL applications can also use the
+CONF library for their own purposes.
+
+A configuration file is divided into a number of sections. Each section
+starts with a line B<[ section_name ]> and ends when a new section is
+started or end of file is reached. A section name can consist of
+alphanumeric characters and underscores.
+
+The first section of a configuration file is special and is referred
+to as the B<default> section this is usually unnamed and is from the
+start of file until the first named section. When a name is being looked up
+it is first looked up in a named section (if any) and then the
+default section.
+
+The environment is mapped onto a section called B<ENV>.
+
+Comments can be included by preceding them with the B<#> character
+
+Each section in a configuration file consists of a number of name and
+value pairs of the form B<name=value>
+
+The B<name> string can contain any alphanumeric characters as well as
+a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
+
+The B<value> string consists of the string following the B<=> character
+until end of line with any leading and trailing white space removed.
+
+The value string undergoes variable expansion. This can be done by
+including the form B<$var> or B<${var}>: this will substitute the value
+of the named variable in the current section. It is also possible to
+substitute a value from another section using the syntax B<$section::name>
+or B<${section::name}>. By using the form B<$ENV::name> environment
+variables can be substituted. It is also possible to assign values to
+environment variables by using the name B<ENV::name>, this will work
+if the program looks up environment variables using the B<CONF> library
+instead of calling getenv() directly.
+
+It is possible to escape certain characters by using any kind of quote
+or the B<\> character. By making the last character of a line a B<\>
+a B<value> string can be spread across multiple lines. In addition
+the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
+
+=head1 OPENSSL LIBRARY CONFIGURATION
+
+Applications can automatically configure certain
+aspects of OpenSSL using the master OpenSSL configuration file, or optionally
+an alternative configuration file. The B<openssl> utility includes this
+functionality: any sub command uses the master OpenSSL configuration file
+unless an option is used in the sub command to use an alternative configuration
+file.
+
+To enable library configuration the default section needs to contain an
+appropriate line which points to the main configuration section. The default
+name is B<openssl_conf> which is used by the B<openssl> utility. Other
+applications may use an alternative name such as B<myapplicaton_conf>.
+
+The configuration section should consist of a set of name value pairs which
+contain specific module configuration information. The B<name> represents
+the name of the I<configuration module> the meaning of the B<value> is
+module specific: it may, for example, represent a further configuration
+section containing configuration module specific information. E.g.
+
+ openssl_conf = openssl_init
+
+ [openssl_init]
+
+ oid_section = new_oids
+ engines = engine_section
+
+ [new_oids]
+
+ ... new oids here ...
+
+ [engine_section]
+
+ ... engine stuff here ...
+
+The features of each configuration module are described below.
+
+=head2 ASN1 Object Configuration Module
+
+This module has the name B<oid_section>. The value of this variable points
+to a section containing name value pairs of OIDs: the name is the OID short
+and long name, the value is the numerical form of the OID. Although some of
+the B<openssl> utility sub commands already have their own ASN1 OBJECT section
+functionality not all do. By using the ASN1 OBJECT configuration module
+B<all> the B<openssl> utility sub commands can see the new objects as well
+as any compliant applications. For example:
+
+ [new_oids]
+
+ some_new_oid = 1.2.3.4
+ some_other_oid = 1.2.3.5
+
+It is also possible to set the value to the long name followed
+by a comma and the numerical OID form. For example:
+
+ shortName = some object long name, 1.2.3.4
+
+=head2 Engine Configuration Module
+
+This ENGINE configuration module has the name B<engines>. The value of this
+variable points to a section containing further ENGINE configuration
+information.
+
+The section pointed to by B<engines> is a table of engine names (though see
+B<engine_id> below) and further sections containing configuration information
+specific to each ENGINE.
+
+Each ENGINE specific section is used to set default algorithms, load
+dynamic, perform initialization and send ctrls. The actual operation performed
+depends on the I<command> name which is the name of the name value pair. The
+currently supported commands are listed below.
+
+For example:
+
+ [engine_section]
+
+ # Configure ENGINE named "foo"
+ foo = foo_section
+ # Configure ENGINE named "bar"
+ bar = bar_section
+
+ [foo_section]
+ ... foo ENGINE specific commands ...
+
+ [bar_section]
+ ... "bar" ENGINE specific commands ...
+
+The command B<engine_id> is used to give the ENGINE name. If used this
+command must be first. For example:
+
+ [engine_section]
+ # This would normally handle an ENGINE named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Override default name and use "myfoo" instead.
+ engine_id = myfoo
+
+The command B<dynamic_path> loads and adds an ENGINE from the given path. It
+is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
+by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
+not the required behaviour then alternative ctrls can be sent directly
+to the dynamic ENGINE using ctrl commands.
+
+The command B<init> determines whether to initialize the ENGINE. If the value
+is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
+initialized the ENGINE immediately. If the B<init> command is not present
+then an attempt will be made to initialize the ENGINE after all commands in
+its section have been processed.
+
+The command B<default_algorithms> sets the default algorithms an ENGINE will
+supply using the functions ENGINE_set_default_string().
+
+If the name matches none of the above command names it is assumed to be a
+ctrl command which is sent to the ENGINE. The value of the command is the
+argument to the ctrl command. If the value is the string B<EMPTY> then no
+value is sent to the command.
+
+For example:
+
+
+ [engine_section]
+
+ # Configure ENGINE named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Load engine from DSO
+ dynamic_path = /some/path/fooengine.so
+ # A foo specific ctrl.
+ some_ctrl = some_value
+ # Another ctrl that doesn't take a value.
+ other_ctrl = EMPTY
+ # Supply all default algorithms
+ default_algorithms = ALL
+
+=head2 EVP Configuration Module
+
+This modules has the name B<alg_section> which points to a section containing
+algorithm commands.
+
+Currently the only algorithm command supported is B<fips_mode> whose
+value should be a boolean string such as B<on> or B<off>. If the value is
+B<on> this attempt to enter FIPS mode. If the call fails or the library is
+not FIPS capable then an error occurs.
+
+For example:
+
+ alg_section = evp_settings
+
+ [evp_settings]
+
+ fips_mode = on
+
+=head2 SSL Configuration Module
+
+This module has the name B<ssl_conf> which points to a section containing
+SSL configurations.
+
+Each line in the SSL configuration section contains the name of the
+configuration and the section containing it.
+
+Each configuration section consists of command value pairs for B<SSL_CONF>.
+Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls
+SSL_CTX_config() or SSL_config() with the appropriate configuration name.
+
+Note: any characters before an initial dot in the configuration section are
+ignored so the same command can be used multiple times.
+
+For example:
+
+ ssl_conf = ssl_sect
+
+ [ssl_sect]
+
+ server = server_section
+
+ [server_section]
+
+ RSA.Certificate = server-rsa.pem
+ ECDSA.Certificate = server-ecdsa.pem
+ Ciphers = ALL:!RC4
+
+=head1 NOTES
+
+If a configuration file attempts to expand a variable that doesn't exist
+then an error is flagged and the file will not load. This can happen
+if an attempt is made to expand an environment variable that doesn't
+exist. For example in a previous version of OpenSSL the default OpenSSL
+master configuration file used the value of B<HOME> which may not be
+defined on non Unix systems and would cause an error.
+
+This can be worked around by including a B<default> section to provide
+a default value: then if the environment lookup fails the default value
+will be used instead. For this to work properly the default value must
+be defined earlier in the configuration file than the expansion. See
+the B<EXAMPLES> section for an example of how to do this.
+
+If the same variable exists in the same section then all but the last
+value will be silently ignored. In certain circumstances such as with
+DNs the same field may occur multiple times. This is usually worked
+around by ignoring any characters before an initial B<.> e.g.
+
+ 1.OU="My first OU"
+ 2.OU="My Second OU"
+
+=head1 EXAMPLES
+
+Here is a sample configuration file using some of the features
+mentioned above.
+
+ # This is the default section.
+
+ HOME=/temp
+ RANDFILE= ${ENV::HOME}/.rnd
+ configdir=$ENV::HOME/config
+
+ [ section_one ]
+
+ # We are now in section one.
+
+ # Quotes permit leading and trailing whitespace
+ any = " any variable name "
+
+ other = A string that can \
+ cover several lines \
+ by including \\ characters
+
+ message = Hello World\n
+
+ [ section_two ]
+
+ greeting = $section_one::message
+
+This next example shows how to expand environment variables safely.
+
+Suppose you want a variable called B<tmpfile> to refer to a
+temporary filename. The directory it is placed in can determined by
+the B<TEMP> or B<TMP> environment variables but they may not be
+set to any value at all. If you just include the environment variable
+names and the variable doesn't exist then this will cause an error when
+an attempt is made to load the configuration file. By making use of the
+default section both values can be looked up with B<TEMP> taking
+priority and B</tmp> used if neither is defined:
+
+ TMP=/tmp
+ # The above value is used if TMP isn't in the environment
+ TEMP=$ENV::TMP
+ # The above value is used if TEMP isn't in the environment
+ tmpfile=${ENV::TEMP}/tmp.filename
+
+Simple OpenSSL library configuration example to enter FIPS mode:
+
+ # Default appname: should match "appname" parameter (if any)
+ # supplied to CONF_modules_load_file et al.
+ openssl_conf = openssl_conf_section
+
+ [openssl_conf_section]
+ # Configuration module list
+ alg_section = evp_sect
+
+ [evp_sect]
+ # Set to "yes" to enter FIPS mode if supported
+ fips_mode = yes
+
+Note: in the above example you will get an error in non FIPS capable versions
+of OpenSSL.
+
+More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
+
+ # Default appname: should match "appname" parameter (if any)
+ # supplied to CONF_modules_load_file et al.
+ openssl_conf = openssl_conf_section
+
+ [openssl_conf_section]
+ # Configuration module list
+ alg_section = evp_sect
+ oid_section = new_oids
+
+ [evp_sect]
+ # This will have no effect as FIPS mode is off by default.
+ # Set to "yes" to enter FIPS mode, if supported
+ fips_mode = no
+
+ [new_oids]
+ # New OID, just short name
+ newoid1 = 1.2.3.4.1
+ # New OID shortname and long name
+ newoid2 = New OID 2 long name, 1.2.3.4.2
+
+The above examples can be used with any application supporting library
+configuration if "openssl_conf" is modified to match the appropriate "appname".
+
+For example if the second sample file above is saved to "example.cnf" then
+the command line:
+
+ OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
+
+will output:
+
+ 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
+
+showing that the OID "newoid1" has been added as "1.2.3.4.1".
+
+=head1 BUGS
+
+Currently there is no way to include characters using the octal B<\nnn>
+form. Strings are all null terminated so nulls cannot form part of
+the value.
+
+The escaping isn't quite right: if you want to use sequences like B<\n>
+you can't use any quote escaping on the same line.
+
+Files are loaded in a single pass. This means that an variable expansion
+will only work if the variables referenced are defined earlier in the
+file.
+
+=head1 SEE ALSO
+
+L<x509(1)>, L<req(1)>, L<ca(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+x509v3_config - X509 V3 certificate extension configuration format
+
+=head1 DESCRIPTION
+
+Several of the OpenSSL utilities can add extensions to a certificate or
+certificate request based on the contents of a configuration file.
+
+Typically the application will contain an option to point to an extension
+section. Each line of the extension section takes the form:
+
+ extension_name=[critical,] extension_options
+
+If B<critical> is present then the extension will be critical.
+
+The format of B<extension_options> depends on the value of B<extension_name>.
+
+There are four main types of extension: I<string> extensions, I<multi-valued>
+extensions, I<raw> and I<arbitrary> extensions.
+
+String extensions simply have a string which contains either the value itself
+or how it is obtained.
+
+For example:
+
+ nsComment="This is a Comment"
+
+Multi-valued extensions have a short form and a long form. The short form
+is a list of names and values:
+
+ basicConstraints=critical,CA:true,pathlen:1
+
+The long form allows the values to be placed in a separate section:
+
+ basicConstraints=critical,@bs_section
+
+ [bs_section]
+
+ CA=true
+ pathlen=1
+
+Both forms are equivalent.
+
+The syntax of raw extensions is governed by the extension code: it can
+for example contain data in multiple sections. The correct syntax to
+use is defined by the extension code itself: check out the certificate
+policies extension for an example.
+
+If an extension type is unsupported then the I<arbitrary> extension syntax
+must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details.
+
+=head1 STANDARD EXTENSIONS
+
+The following sections describe each supported extension in detail.
+
+=head2 Basic Constraints.
+
+This is a multi valued extension which indicates whether a certificate is
+a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
+B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an
+non-negative value can be included.
+
+For example:
+
+ basicConstraints=CA:TRUE
+
+ basicConstraints=CA:FALSE
+
+ basicConstraints=critical,CA:TRUE, pathlen:0
+
+A CA certificate B<must> include the basicConstraints value with the CA field
+set to TRUE. An end user certificate must either set CA to FALSE or exclude the
+extension entirely. Some software may require the inclusion of basicConstraints
+with CA set to FALSE for end entity certificates.
+
+The pathlen parameter indicates the maximum number of CAs that can appear
+below this one in a chain. So if you have a CA with a pathlen of zero it can
+only be used to sign end user certificates and not further CAs.
+
+
+=head2 Key Usage.
+
+Key usage is a multi valued extension consisting of a list of names of the
+permitted key usages.
+
+The supported names are: digitalSignature, nonRepudiation, keyEncipherment,
+dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
+and decipherOnly.
+
+Examples:
+
+ keyUsage=digitalSignature, nonRepudiation
+
+ keyUsage=critical, keyCertSign
+
+
+=head2 Extended Key Usage.
+
+This extensions consists of a list of usages indicating purposes for which
+the certificate public key can be used for,
+
+These can either be object short names or the dotted numerical form of OIDs.
+While any OID can be used only certain values make sense. In particular the
+following PKIX, NS and MS values are meaningful:
+
+ Value Meaning
+ ----- -------
+ serverAuth SSL/TLS Web Server Authentication.
+ clientAuth SSL/TLS Web Client Authentication.
+ codeSigning Code signing.
+ emailProtection E-mail Protection (S/MIME).
+ timeStamping Trusted Timestamping
+ OCSPSigning OCSP Signing
+ ipsecIKE ipsec Internet Key Exchange
+ msCodeInd Microsoft Individual Code Signing (authenticode)
+ msCodeCom Microsoft Commercial Code Signing (authenticode)
+ msCTLSign Microsoft Trust List Signing
+ msEFS Microsoft Encrypted File System
+
+Examples:
+
+ extendedKeyUsage=critical,codeSigning,1.2.3.4
+ extendedKeyUsage=serverAuth,clientAuth
+
+
+=head2 Subject Key Identifier.
+
+This is really a string extension and can take two possible values. Either
+the word B<hash> which will automatically follow the guidelines in RFC3280
+or a hex string giving the extension value to include. The use of the hex
+string is strongly discouraged.
+
+Example:
+
+ subjectKeyIdentifier=hash
+
+
+=head2 Authority Key Identifier.
+
+The authority key identifier extension permits two options. keyid and issuer:
+both can take the optional value "always".
+
+If the keyid option is present an attempt is made to copy the subject key
+identifier from the parent certificate. If the value "always" is present
+then an error is returned if the option fails.
+
+The issuer option copies the issuer and serial number from the issuer
+certificate. This will only be done if the keyid option fails or
+is not included unless the "always" flag will always include the value.
+
+Example:
+
+ authorityKeyIdentifier=keyid,issuer
+
+
+=head2 Subject Alternative Name.
+
+The subject alternative name extension allows various literal values to be
+included in the configuration file. These include B<email> (an email address)
+B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
+registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
+(a distinguished name) and otherName.
+
+The email option include a special 'copy' value. This will automatically
+include and email addresses contained in the certificate subject name in
+the extension.
+
+The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
+
+The value of B<dirName> should point to a section containing the distinguished
+name to use as a set of name value pairs. Multi values AVAs can be formed by
+prefacing the name with a B<+> character.
+
+otherName can include arbitrary data associated with an OID: the value
+should be the OID followed by a semicolon and the content in standard
+L<ASN1_generate_nconf(3)> format.
+
+Examples:
+
+ subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
+ subjectAltName=IP:192.168.7.1
+ subjectAltName=IP:13::17
+ subjectAltName=email:my@other.address,RID:1.2.3.4
+ subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
+
+ subjectAltName=dirName:dir_sect
+
+ [dir_sect]
+ C=UK
+ O=My Organization
+ OU=My Unit
+ CN=My Name
+
+
+=head2 Issuer Alternative Name.
+
+The issuer alternative name option supports all the literal options of
+subject alternative name. It does B<not> support the email:copy option because
+that would not make sense. It does support an additional issuer:copy option
+that will copy all the subject alternative name values from the issuer
+certificate (if possible).
+
+Example:
+
+ issuserAltName = issuer:copy
+
+
+=head2 Authority Info Access.
+
+The authority information access extension gives details about how to access
+certain information relating to the CA. Its syntax is accessOID;location
+where I<location> has the same syntax as subject alternative name (except
+that email:copy is not supported). accessOID can be any valid OID but only
+certain values are meaningful, for example OCSP and caIssuers.
+
+Example:
+
+ authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
+ authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
+
+
+=head2 CRL distribution points
+
+This is a multi-valued extension whose options can be either in name:value pair
+using the same form as subject alternative name or a single value representing
+a section name containing all the distribution point fields.
+
+For a name:value pair a new DistributionPoint with the fullName field set to
+the given value both the cRLissuer and reasons fields are omitted in this case.
+
+In the single option case the section indicated contains values for each
+field. In this section:
+
+If the name is "fullname" the value field should contain the full name
+of the distribution point in the same format as subject alternative name.
+
+If the name is "relativename" then the value field should contain a section
+name whose contents represent a DN fragment to be placed in this field.
+
+The name "CRLIssuer" if present should contain a value for this field in
+subject alternative name format.
+
+If the name is "reasons" the value field should consist of a comma
+separated field containing the reasons. Valid reasons are: "keyCompromise",
+"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation",
+"certificateHold", "privilegeWithdrawn" and "AACompromise".
+
+
+Simple examples:
+
+ crlDistributionPoints=URI:http://myhost.com/myca.crl
+ crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
+
+Full distribution point example:
+
+ crlDistributionPoints=crldp1_section
+
+ [crldp1_section]
+
+ fullname=URI:http://myhost.com/myca.crl
+ CRLissuer=dirName:issuer_sect
+ reasons=keyCompromise, CACompromise
+
+ [issuer_sect]
+ C=UK
+ O=Organisation
+ CN=Some Name
+
+=head2 Issuing Distribution Point
+
+This extension should only appear in CRLs. It is a multi valued extension
+whose syntax is similar to the "section" pointed to by the CRL distribution
+points extension with a few differences.
+
+The names "reasons" and "CRLissuer" are not recognized.
+
+The name "onlysomereasons" is accepted which sets this field. The value is
+in the same format as the CRL distribution point "reasons" field.
+
+The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted
+the values should be a boolean value (TRUE or FALSE) to indicate the value of
+the corresponding field.
+
+Example:
+
+ issuingDistributionPoint=critical, @idp_section
+
+ [idp_section]
+
+ fullname=URI:http://myhost.com/myca.crl
+ indirectCRL=TRUE
+ onlysomereasons=keyCompromise, CACompromise
+
+ [issuer_sect]
+ C=UK
+ O=Organisation
+ CN=Some Name
+
+
+=head2 Certificate Policies.
+
+This is a I<raw> extension. All the fields of this extension can be set by
+using the appropriate syntax.
+
+If you follow the PKIX recommendations and just using one OID then you just
+include the value of that OID. Multiple OIDs can be set separated by commas,
+for example:
+
+ certificatePolicies= 1.2.4.5, 1.1.3.4
+
+If you wish to include qualifiers then the policy OID and qualifiers need to
+be specified in a separate section: this is done by using the @section syntax
+instead of a literal OID value.
+
+The section referred to must include the policy OID using the name
+policyIdentifier, cPSuri qualifiers can be included using the syntax:
+
+ CPS.nnn=value
+
+userNotice qualifiers can be set using the syntax:
+
+ userNotice.nnn=@notice
+
+The value of the userNotice qualifier is specified in the relevant section.
+This section can include explicitText, organization and noticeNumbers
+options. explicitText and organization are text strings, noticeNumbers is a
+comma separated list of numbers. The organization and noticeNumbers options
+(if included) must BOTH be present. If you use the userNotice option with IE5
+then you need the 'ia5org' option at the top level to modify the encoding:
+otherwise it will not be interpreted properly.
+
+Example:
+
+ certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
+
+ [polsect]
+
+ policyIdentifier = 1.3.5.8
+ CPS.1="http://my.host.name/"
+ CPS.2="http://my.your.name/"
+ userNotice.1=@notice
+
+ [notice]
+
+ explicitText="Explicit Text Here"
+ organization="Organisation Name"
+ noticeNumbers=1,2,3,4
+
+The B<ia5org> option changes the type of the I<organization> field. In RFC2459
+it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible.
+Some software (for example some versions of MSIE) may require ia5org.
+
+=head2 Policy Constraints
+
+This is a multi-valued extension which consisting of the names
+B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
+value. At least one component must be present.
+
+Example:
+
+ policyConstraints = requireExplicitPolicy:3
+
+
+=head2 Inhibit Any Policy
+
+This is a string extension whose value must be a non negative integer.
+
+Example:
+
+ inhibitAnyPolicy = 2
+
+
+=head2 Name Constraints
+
+The name constraints extension is a multi-valued extension. The name should
+begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
+the name and the value follows the syntax of subjectAltName except email:copy
+is not supported and the B<IP> form should consist of an IP addresses and
+subnet mask separated by a B</>.
+
+Examples:
+
+ nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
+
+ nameConstraints=permitted;email:.somedomain.com
+
+ nameConstraints=excluded;email:.com
+
+
+=head2 OCSP No Check
+
+The OCSP No Check extension is a string extension but its value is ignored.
+
+Example:
+
+ noCheck = ignored
+
+
+=head2 TLS Feature (aka Must Staple)
+
+This is a multi-valued extension consisting of a list of TLS extension
+identifiers. Each identifier may be a number (0..65535) or a supported name.
+When a TLS client sends a listed extension, the TLS server is expected to
+include that extension in its reply.
+
+The supported names are: B<status_request> and B<status_request_v2>.
+
+Example:
+
+ tlsfeature = status_request
+
+
+=head1 DEPRECATED EXTENSIONS
+
+The following extensions are non standard, Netscape specific and largely
+obsolete. Their use in new applications is discouraged.
+
+=head2 Netscape String extensions.
+
+Netscape Comment (B<nsComment>) is a string extension containing a comment
+which will be displayed when the certificate is viewed in some browsers.
+
+Example:
+
+ nsComment = "Some Random Comment"
+
+Other supported extensions in this category are: B<nsBaseUrl>,
+B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
+and B<nsSslServerName>.
+
+
+=head2 Netscape Certificate Type
+
+This is a multi-valued extensions which consists of a list of flags to be
+included. It was used to indicate the purposes for which a certificate could
+be used. The basicConstraints, keyUsage and extended key usage extensions are
+now used instead.
+
+Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
+B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
+
+
+=head1 ARBITRARY EXTENSIONS
+
+If an extension is not supported by the OpenSSL code then it must be encoded
+using the arbitrary extension format. It is also possible to use the arbitrary
+format for supported extensions. Extreme care should be taken to ensure that
+the data is formatted correctly for the given extension type.
+
+There are two ways to encode arbitrary extensions.
+
+The first way is to use the word ASN1 followed by the extension content
+using the same syntax as L<ASN1_generate_nconf(3)>.
+For example:
+
+ 1.2.3.4=critical,ASN1:UTF8String:Some random data
+
+ 1.2.3.4=ASN1:SEQUENCE:seq_sect
+
+ [seq_sect]
+
+ field1 = UTF8:field1
+ field2 = UTF8:field2
+
+It is also possible to use the word DER to include the raw encoded data in any
+extension.
+
+ 1.2.3.4=critical,DER:01:02:03:04
+ 1.2.3.4=DER:01020304
+
+The value following DER is a hex dump of the DER encoding of the extension
+Any extension can be placed in this form to override the default behaviour.
+For example:
+
+ basicConstraints=critical,DER:00:01:02:03
+
+=head1 WARNING
+
+There is no guarantee that a specific implementation will process a given
+extension. It may therefore be sometimes possible to use certificates for
+purposes prohibited by their extensions because a specific application does
+not recognize or honour the values of the relevant extensions.
+
+The DER and ASN1 options should be used with caution. It is possible to create
+totally invalid extensions if they are not used carefully.
+
+
+=head1 NOTES
+
+If an extension is multi-value and a field value must contain a comma the long
+form must be used otherwise the comma would be misinterpreted as a field
+separator. For example:
+
+ subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
+
+will produce an error but the equivalent form:
+
+ subjectAltName=@subject_alt_section
+
+ [subject_alt_section]
+ subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
+
+is valid.
+
+Due to the behaviour of the OpenSSL B<conf> library the same field name
+can only occur once in a section. This means that:
+
+ subjectAltName=@alt_section
+
+ [alt_section]
+
+ email=steve@here
+ email=steve@there
+
+will only recognize the last value. This can be worked around by using the form:
+
+ [alt_section]
+
+ email.1=steve@here
+ email.2=steve@there
+
+=head1 SEE ALSO
+
+L<req(1)>, L<ca(1)>, L<x509(1)>,
+L<ASN1_generate_nconf(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+bio - Basic I/O abstraction
+
+=for comment generic
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+=head1 DESCRIPTION
+
+A BIO is an I/O abstraction, it hides many of the underlying I/O
+details from an application. If an application uses a BIO for its
+I/O it can transparently handle SSL connections, unencrypted network
+connections and file I/O.
+
+There are two type of BIO, a source/sink BIO and a filter BIO.
+
+As its name implies a source/sink BIO is a source and/or sink of data,
+examples include a socket BIO and a file BIO.
+
+A filter BIO takes data from one BIO and passes it through to
+another, or the application. The data may be left unmodified (for
+example a message digest BIO) or translated (for example an
+encryption BIO). The effect of a filter BIO may change according
+to the I/O operation it is performing: for example an encryption
+BIO will encrypt data if it is being written to and decrypt data
+if it is being read from.
+
+BIOs can be joined together to form a chain (a single BIO is a chain
+with one component). A chain normally consist of one source/sink
+BIO and one or more filter BIOs. Data read from or written to the
+first BIO then traverses the chain to the end (normally a source/sink
+BIO).
+
+
+Some BIOs (such as memory BIOs) can be used immediately after calling
+BIO_new(). Others (such as file BIOs) need some additional initialization,
+and frequently a utility function exists to create and initialize such BIOs.
+
+If BIO_free() is called on a BIO chain it will only free one BIO resulting
+in a memory leak.
+
+Calling BIO_free_all() a single BIO has the same effect as calling BIO_free()
+on it other than the discarded return value.
+
+Normally the B<type> argument is supplied by a function which returns a
+pointer to a BIO_METHOD. There is a naming convention for such functions:
+a source/sink BIO is normally called BIO_s_*() and a filter BIO
+BIO_f_*();
+
+=head1 EXAMPLE
+
+Create a memory BIO:
+
+ BIO *mem = BIO_new(BIO_s_mem());
+
+=head1 SEE ALSO
+
+L<BIO_ctrl(3)>,
+L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>,
+L<BIO_f_cipher(3)>, L<BIO_f_md(3)>,
+L<BIO_f_null(3)>, L<BIO_f_ssl(3)>,
+L<BIO_find_type(3)>, L<BIO_new(3)>,
+L<BIO_new_bio_pair(3)>,
+L<BIO_push(3)>, L<BIO_read(3)>,
+L<BIO_s_accept(3)>, L<BIO_s_bio(3)>,
+L<BIO_s_connect(3)>, L<BIO_s_fd(3)>,
+L<BIO_s_file(3)>, L<BIO_s_mem(3)>,
+L<BIO_s_mem(3)>,
+L<BIO_s_null(3)>, L<BIO_s_socket(3)>,
+L<BIO_set_callback(3)>,
+L<BIO_should_retry(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
+
--- /dev/null
+=pod
+
+=head1 NAME
+
+crypto - OpenSSL cryptographic library
+
+=head1 SYNOPSIS
+
+See the individual manual pages for details.
+
+=head1 DESCRIPTION
+
+The OpenSSL B<crypto> library implements a wide range of cryptographic
+algorithms used in various Internet standards. The services provided
+by this library are used by the OpenSSL implementations of SSL, TLS
+and S/MIME, and they have also been used to implement SSH, OpenPGP, and
+other cryptographic standards.
+
+B<libcrypto> consists of a number of sub-libraries that implement the
+individual algorithms.
+
+The functionality includes symmetric encryption, public key
+cryptography and key agreement, certificate handling, cryptographic
+hash functions, cryptographic pseudo-random number generator, and
+various utilities.
+
+=head1 NOTES
+
+Some of the newer functions follow a naming convention using the numbers
+B<0> and B<1>. For example the functions:
+
+ int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev);
+ int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj);
+
+The B<0> version uses the supplied structure pointer directly
+in the parent and it will be freed up when the parent is freed.
+In the above example B<crl> would be freed but B<rev> would not.
+
+The B<1> function uses a copy of the supplied structure pointer
+(or in some cases increases its link count) in the parent and
+so both (B<x> and B<obj> above) should be freed up.
+
+=head1 RETURN VALUES
+
+See the individual manual pages for details.
+
+=head1 SEE ALSO
+
+L<openssl(1)>, L<ssl(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+ct - Certificate Transparency
+
+=head1 SYNOPSIS
+
+ #include <openssl/ct.h>
+
+=head1 DESCRIPTION
+
+This library implements Certificate Transparency (CT) verification for TLS
+clients, as defined in RFC 6962. This verification can provide some confidence
+that a certificate has been publicly logged in a set of CT logs.
+
+By default, these checks are disabled. They can be enabled using
+SSL_CTX_ct_enable() or SSL_ct_enable().
+
+This library can also be used to parse and examine CT data structures, such as
+Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are
+functions for:
+- decoding and encoding SCTs in DER and TLS wire format.
+- printing SCTs.
+- verifying the authenticity of SCTs.
+- loading a CT log list from a CONF file.
+
+=head1 SEE ALSO
+
+L<d2i_SCT_LIST(3)>,
+L<CTLOG_STORE_new(3)>,
+L<CTLOG_STORE_get0_log_by_id(3)>,
+L<SCT_new(3)>,
+L<SCT_print(3)>,
+L<SCT_verify(3)>,
+L<SCT_validate(3)>,
+L<CT_POLICY_EVAL_CTX(3)>,
+L<SSL_CTX_set_ct_validation_callback(3)>
+
+=head1 HISTORY
+
+This library was added in OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+des_modes - the variants of DES and other crypto algorithms of OpenSSL
+
+=head1 DESCRIPTION
+
+Several crypto algorithms for OpenSSL can be used in a number of modes. Those
+are used for using block ciphers in a way similar to stream ciphers, among
+other things.
+
+=head1 OVERVIEW
+
+=head2 Electronic Codebook Mode (ECB)
+
+Normally, this is found as the function I<algorithm>_ecb_encrypt().
+
+=over 2
+
+=item *
+
+64 bits are enciphered at a time.
+
+=item *
+
+The order of the blocks can be rearranged without detection.
+
+=item *
+
+The same plaintext block always produces the same ciphertext block
+(for the same key) making it vulnerable to a 'dictionary attack'.
+
+=item *
+
+An error will only affect one ciphertext block.
+
+=back
+
+=head2 Cipher Block Chaining Mode (CBC)
+
+Normally, this is found as the function I<algorithm>_cbc_encrypt().
+Be aware that des_cbc_encrypt() is not really DES CBC (it does
+not update the IV); use des_ncbc_encrypt() instead.
+
+=over 2
+
+=item *
+
+a multiple of 64 bits are enciphered at a time.
+
+=item *
+
+The CBC mode produces the same ciphertext whenever the same
+plaintext is encrypted using the same key and starting variable.
+
+=item *
+
+The chaining operation makes the ciphertext blocks dependent on the
+current and all preceding plaintext blocks and therefore blocks can not
+be rearranged.
+
+=item *
+
+The use of different starting variables prevents the same plaintext
+enciphering to the same ciphertext.
+
+=item *
+
+An error will affect the current and the following ciphertext blocks.
+
+=back
+
+=head2 Cipher Feedback Mode (CFB)
+
+Normally, this is found as the function I<algorithm>_cfb_encrypt().
+
+=over 2
+
+=item *
+
+a number of bits (j) <= 64 are enciphered at a time.
+
+=item *
+
+The CFB mode produces the same ciphertext whenever the same
+plaintext is encrypted using the same key and starting variable.
+
+=item *
+
+The chaining operation makes the ciphertext variables dependent on the
+current and all preceding variables and therefore j-bit variables are
+chained together and can not be rearranged.
+
+=item *
+
+The use of different starting variables prevents the same plaintext
+enciphering to the same ciphertext.
+
+=item *
+
+The strength of the CFB mode depends on the size of k (maximal if
+j == k). In my implementation this is always the case.
+
+=item *
+
+Selection of a small value for j will require more cycles through
+the encipherment algorithm per unit of plaintext and thus cause
+greater processing overheads.
+
+=item *
+
+Only multiples of j bits can be enciphered.
+
+=item *
+
+An error will affect the current and the following ciphertext variables.
+
+=back
+
+=head2 Output Feedback Mode (OFB)
+
+Normally, this is found as the function I<algorithm>_ofb_encrypt().
+
+=over 2
+
+
+=item *
+
+a number of bits (j) <= 64 are enciphered at a time.
+
+=item *
+
+The OFB mode produces the same ciphertext whenever the same
+plaintext enciphered using the same key and starting variable. More
+over, in the OFB mode the same key stream is produced when the same
+key and start variable are used. Consequently, for security reasons
+a specific start variable should be used only once for a given key.
+
+=item *
+
+The absence of chaining makes the OFB more vulnerable to specific attacks.
+
+=item *
+
+The use of different start variables values prevents the same
+plaintext enciphering to the same ciphertext, by producing different
+key streams.
+
+=item *
+
+Selection of a small value for j will require more cycles through
+the encipherment algorithm per unit of plaintext and thus cause
+greater processing overheads.
+
+=item *
+
+Only multiples of j bits can be enciphered.
+
+=item *
+
+OFB mode of operation does not extend ciphertext errors in the
+resultant plaintext output. Every bit error in the ciphertext causes
+only one bit to be in error in the deciphered plaintext.
+
+=item *
+
+OFB mode is not self-synchronizing. If the two operation of
+encipherment and decipherment get out of synchronism, the system needs
+to be re-initialized.
+
+=item *
+
+Each re-initialization should use a value of the start variable
+different from the start variable values used before with the same
+key. The reason for this is that an identical bit stream would be
+produced each time from the same parameters. This would be
+susceptible to a 'known plaintext' attack.
+
+=back
+
+=head2 Triple ECB Mode
+
+Normally, this is found as the function I<algorithm>_ecb3_encrypt().
+
+=over 2
+
+=item *
+
+Encrypt with key1, decrypt with key2 and encrypt with key3 again.
+
+=item *
+
+As for ECB encryption but increases the key length to 168 bits.
+There are theoretic attacks that can be used that make the effective
+key length 112 bits, but this attack also requires 2^56 blocks of
+memory, not very likely, even for the NSA.
+
+=item *
+
+If both keys are the same it is equivalent to encrypting once with
+just one key.
+
+=item *
+
+If the first and last key are the same, the key length is 112 bits.
+There are attacks that could reduce the effective key strength
+to only slightly more than 56 bits, but these require a lot of memory.
+
+=item *
+
+If all 3 keys are the same, this is effectively the same as normal
+ecb mode.
+
+=back
+
+=head2 Triple CBC Mode
+
+Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt().
+
+=over 2
+
+
+=item *
+
+Encrypt with key1, decrypt with key2 and then encrypt with key3.
+
+=item *
+
+As for CBC encryption but increases the key length to 168 bits with
+the same restrictions as for triple ecb mode.
+
+=back
+
+=head1 NOTES
+
+This text was been written in large parts by Eric Young in his original
+documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed
+it to:
+
+ AS 2805.5.2
+ Australian Standard
+ Electronic funds transfer - Requirements for interfaces,
+ Part 5.2: Modes of operation for an n-bit block cipher algorithm
+ Appendix A
+
+=head1 SEE ALSO
+
+L<blowfish(3)>, L<des(3)>, L<idea(3)>,
+L<rc2(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+evp - high-level cryptographic functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+=head1 DESCRIPTION
+
+The EVP library provides a high-level interface to cryptographic
+functions.
+
+L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and L<B<EVP_Open>I<...>|EVP_OpenInit(3)>
+provide public key encryption and decryption to implement digital "envelopes".
+
+The L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> and
+L<B<EVP_DigestVerify>I<...>|EVP_DigestVerifyInit(3)> functions implement
+digital signatures and Message Authentication Codes (MACs). Also see the older
+L<B<EVP_Sign>I<...>|EVP_SignInit(3)> and L<B<EVP_Verify>I<...>|EVP_VerifyInit(3)>
+functions.
+
+Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)>
+functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests.
+
+The B<EVP_PKEY>I<...> functions provide a high level interface to
+asymmetric algorithms. To create a new EVP_PKEY see
+L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated
+with a private key of a particular algorithm by using the functions
+described on the L<EVP_PKEY_set1_RSA(3)> page, or
+new keys can be generated using L<EVP_PKEY_keygen(3)>.
+EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using
+L<EVP_PKEY_print_private(3)>.
+
+The EVP_PKEY functions support the full range of asymmetric algorithm operations:
+
+=over
+
+=item For key agreement see L<EVP_PKEY_derive(3)>
+
+=item For signing and verifying see L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>.
+However, note that
+these functions do not perform a digest of the data to be signed. Therefore
+normally you would use the L<EVP_DigestSignInit(3)>
+functions for this purpose.
+
+=item For encryption and decryption see L<EVP_PKEY_encrypt(3)>
+and L<EVP_PKEY_decrypt(3)> respectively. However, note that
+these functions perform encryption and decryption only. As public key
+encryption is an expensive operation, normally you would wrap
+an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and
+L<EVP_OpenInit(3)> functions.
+
+=back
+
+The L<EVP_BytesToKey(3)> function provides some limited support for password
+based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible
+implementation. However, new applications should not typically use this (preferring, for example,
+PBKDF2 from PCKS#5).
+
+The L<B<EVP_Encode>I<...>|EVP_EncodeInit(3)> and
+L<B<EVP_Decode>I<...>|EVP_EncodeInit(3)> functions implement base 64 encoding
+and decoding.
+
+All the symmetric algorithms (ciphers), digests and asymmetric algorithms
+(public key algorithms) can be replaced by L<engine(3)> modules providing alternative
+implementations. If ENGINE implementations of ciphers or digests are registered
+as defaults, then the various EVP functions will automatically use those
+implementations automatically in preference to built in software
+implementations. For more information, consult the engine(3) man page.
+
+Although low level algorithm specific functions exist for many algorithms
+their use is discouraged. They cannot be used with an ENGINE and ENGINE
+versions of new algorithms cannot be accessed using the low level functions.
+Also makes code harder to adapt to new algorithms and some options are not
+cleanly supported at the low level and some operations are more efficient
+using the high level interface.
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>,
+L<EVP_EncryptInit(3)>,
+L<EVP_OpenInit(3)>,
+L<EVP_SealInit(3)>,
+L<EVP_DigestSignInit(3)>,
+L<EVP_SignInit(3)>,
+L<EVP_VerifyInit(3)>,
+L<EVP_EncodeInit(3)>,
+L<EVP_PKEY_new(3)>,
+L<EVP_PKEY_set1_RSA(3)>,
+L<EVP_PKEY_keygen(3)>,
+L<EVP_PKEY_print_private(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>,
+L<EVP_BytesToKey(3)>,
+L<engine(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+SSL - OpenSSL SSL/TLS library
+
+=head1 SYNOPSIS
+
+See the individual manual pages for details.
+
+=head1 DESCRIPTION
+
+The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
+Transport Layer Security (TLS v1) protocols. It provides a rich API which is
+documented here.
+
+Then an B<SSL_CTX> object is created as a framework to establish
+TLS/SSL enabled connections (see L<SSL_CTX_new(3)>).
+Various options regarding certificates, algorithms etc. can be set
+in this object.
+
+When a network connection has been created, it can be assigned to an
+B<SSL> object. After the B<SSL> object has been created using
+L<SSL_new(3)>, L<SSL_set_fd(3)> or
+L<SSL_set_bio(3)> can be used to associate the network
+connection with the object.
+
+Then the TLS/SSL handshake is performed using
+L<SSL_accept(3)> or L<SSL_connect(3)>
+respectively.
+L<SSL_read(3)> and L<SSL_write(3)> are used
+to read and write data on the TLS/SSL connection.
+L<SSL_shutdown(3)> can be used to shut down the
+TLS/SSL connection.
+
+=head1 DATA STRUCTURES
+
+Currently the OpenSSL B<ssl> library functions deals with the following data
+structures:
+
+=over 4
+
+=item B<SSL_METHOD> (SSL Method)
+
+That's a dispatch structure describing the internal B<ssl> library
+methods/functions which implement the various protocol versions (SSLv3
+TLSv1, ...). It's needed to create an B<SSL_CTX>.
+
+=item B<SSL_CIPHER> (SSL Cipher)
+
+This structure holds the algorithm information for a particular cipher which
+are a core part of the SSL/TLS protocol. The available ciphers are configured
+on a B<SSL_CTX> basis and the actually used ones are then part of the
+B<SSL_SESSION>.
+
+=item B<SSL_CTX> (SSL Context)
+
+That's the global context structure which is created by a server or client
+once per program life-time and which holds mainly default values for the
+B<SSL> structures which are later created for the connections.
+
+=item B<SSL_SESSION> (SSL Session)
+
+This is a structure containing the current TLS/SSL session details for a
+connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
+
+=item B<SSL> (SSL Connection)
+
+That's the main SSL/TLS structure which is created by a server or client per
+established connection. This actually is the core structure in the SSL API.
+Under run-time the application usually deals with this structure which has
+links to mostly all other structures.
+
+=back
+
+
+=head1 HEADER FILES
+
+Currently the OpenSSL B<ssl> library provides the following C header files
+containing the prototypes for the data structures and functions:
+
+=over 4
+
+=item B<ssl.h>
+
+That's the common header file for the SSL/TLS API. Include it into your
+program to make the API of the B<ssl> library available. It internally
+includes both more private SSL headers and headers from the B<crypto> library.
+Whenever you need hard-core details on the internals of the SSL API, look
+inside this header file.
+
+=item B<ssl2.h>
+
+Unused. Present for backwards compatibility only.
+
+=item B<ssl3.h>
+
+That's the sub header file dealing with the SSLv3 protocol only.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=item B<tls1.h>
+
+That's the sub header file dealing with the TLSv1 protocol only.
+I<Usually you don't have to include it explicitly because
+it's already included by ssl.h>.
+
+=back
+
+=head1 API FUNCTIONS
+
+Currently the OpenSSL B<ssl> library exports 214 API functions.
+They are documented in the following:
+
+=head2 Dealing with Protocol Methods
+
+Here we document the various API functions which deal with the SSL/TLS
+protocol methods defined in B<SSL_METHOD> structures.
+
+=over 4
+
+=item const SSL_METHOD *B<TLS_method>(void);
+
+Constructor for the I<version-flexible> SSL_METHOD structure for clients,
+servers or both.
+See L<SSL_CTX_new(3)> for details.
+
+=item const SSL_METHOD *B<TLS_client_method>(void);
+
+Constructor for the I<version-flexible> SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<TLS_server_method>(void);
+
+Constructor for the I<version-flexible> SSL_METHOD structure for servers.
+
+=item const SSL_METHOD *B<TLSv1_2_method>(void);
+
+Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<TLSv1_2_client_method>(void);
+
+Constructor for the TLSv1.2 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<TLSv1_2_server_method>(void);
+
+Constructor for the TLSv1.2 SSL_METHOD structure for servers.
+
+=item const SSL_METHOD *B<TLSv1_1_method>(void);
+
+Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<TLSv1_1_client_method>(void);
+
+Constructor for the TLSv1.1 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<TLSv1_1_server_method>(void);
+
+Constructor for the TLSv1.1 SSL_METHOD structure for servers.
+
+=item const SSL_METHOD *B<TLSv1_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<TLSv1_client_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<TLSv1_server_method>(void);
+
+Constructor for the TLSv1 SSL_METHOD structure for servers.
+
+=item const SSL_METHOD *B<SSLv3_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both.
+
+=item const SSL_METHOD *B<SSLv3_client_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for clients.
+
+=item const SSL_METHOD *B<SSLv3_server_method>(void);
+
+Constructor for the SSLv3 SSL_METHOD structure for servers.
+
+=back
+
+=head2 Dealing with Ciphers
+
+Here we document the various API functions which deal with the SSL/TLS
+ciphers defined in B<SSL_CIPHER> structures.
+
+=over 4
+
+=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len);
+
+Write a string to I<buf> (with a maximum size of I<len>) containing a human
+readable description of I<cipher>. Returns I<buf>.
+
+=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits);
+
+Determine the number of bits in I<cipher>. Because of export crippled ciphers
+there are two bits: The bits the algorithm supports in general (stored to
+I<alg_bits>) and the bits which are actually used (the return value).
+
+=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher);
+
+Return the internal name of I<cipher> as a string. These are the various
+strings defined by the I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx>
+definitions in the header files.
+
+=item const char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher);
+
+Returns a string like "C<SSLv3>" or "C<TLSv1.2>" which indicates the
+SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined
+in the specification the first time).
+
+=back
+
+=head2 Dealing with Protocol Contexts
+
+Here we document the various API functions which deal with the SSL/TLS
+protocol context defined in the B<SSL_CTX> structure.
+
+=over 4
+
+=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x);
+
+=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509);
+
+=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c);
+
+=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx);
+
+=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg);
+
+=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t);
+
+=item void B<SSL_CTX_free>(SSL_CTX *a);
+
+=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx);
+
+=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx);
+
+=item STACK *B<SSL_CTX_get_ciphers>(const SSL_CTX *ctx);
+
+=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx);
+
+=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
+
+=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx);
+
+=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx);
+
+=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);
+
+=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx);
+
+=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx);
+
+=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx);
+
+=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);
+
+=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, const char *CAfile, const char *CApath);
+
+=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth);
+
+=item int SSL_CTX_up_ref(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c);
+
+=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx);
+
+=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);
+
+=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);
+
+=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);
+
+=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx);
+
+=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx, t);
+
+=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));
+
+=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));
+
+=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));
+
+=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx);
+
+=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx);
+
+=item int B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg);
+
+=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
+
+=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg)
+
+=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str);
+
+=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list);
+
+=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
+
+=item int B<SSL_CTX_set_ct_validation_callback>(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg);
+
+=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void))
+
+=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m);
+
+=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx);
+
+Use the default paths to locate trusted CA certificates. There is one default
+directory path and one default file path. Both are set via this call.
+
+=item int B<SSL_CTX_set_default_verify_dir>(SSL_CTX *ctx)
+
+Use the default directory path to locate trusted CA certificates.
+
+=item int B<SSL_CTX_set_default_verify_file>(SSL_CTX *ctx)
+
+Use the file path to locate trusted CA certificates.
+
+=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg);
+
+=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));
+
+=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+
+=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg);
+
+=item unsigned long B<SSL_CTX_clear_options>(SSL_CTX *ctx, unsigned long op);
+
+=item unsigned long B<SSL_CTX_get_options>(SSL_CTX *ctx);
+
+=item unsigned long B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op);
+
+=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode);
+
+=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m);
+
+=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode);
+
+=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth);
+
+=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t);
+
+=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh);
+
+=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void));
+
+=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void))
+
+=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey);
+
+=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len);
+
+=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
+
+=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa);
+
+=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len);
+
+=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
+
+=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x);
+
+=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d);
+
+=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, const char *file, int type);
+
+=item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx);
+
+=item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx);
+
+=item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
+
+=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint);
+
+=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
+
+
+=back
+
+=head2 Dealing with Sessions
+
+Here we document the various API functions which deal with the SSL/TLS
+sessions defined in the B<SSL_SESSION> structures.
+
+=over 4
+
+=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b);
+
+=item void B<SSL_SESSION_free>(SSL_SESSION *ss);
+
+=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s);
+
+=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx);
+
+=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s);
+
+=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s);
+
+=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a);
+
+=item SSL_SESSION *B<SSL_SESSION_new>(void);
+
+=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x);
+
+=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x);
+
+=item int B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a);
+
+=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg);
+
+=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t);
+
+=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t);
+
+=back
+
+=head2 Dealing with Connections
+
+Here we document the various API functions which deal with the SSL/TLS
+connection defined in the B<SSL> structure.
+
+=over 4
+
+=item int B<SSL_accept>(SSL *ssl);
+
+=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir);
+
+=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file);
+
+=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x);
+
+=item char *B<SSL_alert_desc_string>(int value);
+
+=item char *B<SSL_alert_desc_string_long>(int value);
+
+=item char *B<SSL_alert_type_string>(int value);
+
+=item char *B<SSL_alert_type_string_long>(int value);
+
+=item int B<SSL_check_private_key>(const SSL *ssl);
+
+=item void B<SSL_clear>(SSL *ssl);
+
+=item long B<SSL_clear_num_renegotiations>(SSL *ssl);
+
+=item int B<SSL_connect>(SSL *ssl);
+
+=item int B<SSL_copy_session_id>(SSL *t, const SSL *f);
+
+Sets the session details for B<t> to be the same as in B<f>. Returns 1 on
+success or 0 on failure.
+
+=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg);
+
+=item int B<SSL_do_handshake>(SSL *ssl);
+
+=item SSL *B<SSL_dup>(SSL *ssl);
+
+SSL_dup() allows applications to configure an SSL handle for use
+in multiple SSL connections, and then duplicate it prior to initiating
+each connection with the duplicated handle.
+Use of SSL_dup() avoids the need to repeat the configuration of the
+handles for each connection.
+This is used internally by L<BIO_s_accept(3)> to construct
+per-connection SSL handles after L<accept(2)>.
+
+For SSL_dup() to work, the connection MUST be in its initial state
+and MUST NOT have not yet have started the SSL handshake.
+For connections that are not in their initial state SSL_dup() just
+increments an internal reference count and returns the I<same>
+handle.
+It may be possible to use L<SSL_clear(3)> to recycle an SSL handle
+that is not in its initial state for re-use, but this is best
+avoided.
+Instead, save and restore the session, if desired, and construct a
+fresh handle for each connection.
+
+=item STACK *B<SSL_dup_CA_list>(STACK *sk);
+
+=item void B<SSL_free>(SSL *ssl);
+
+=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl);
+
+=item char *B<SSL_get_app_data>(SSL *ssl);
+
+=item X509 *B<SSL_get_certificate>(const SSL *ssl);
+
+=item const char *B<SSL_get_cipher>(const SSL *ssl);
+
+=item int B<SSL_is_dtls>(const SSL *ssl);
+
+=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits);
+
+=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n);
+
+=item char *B<SSL_get_cipher_name>(const SSL *ssl);
+
+=item char *B<SSL_get_cipher_version>(const SSL *ssl);
+
+=item STACK *B<SSL_get_ciphers>(const SSL *ssl);
+
+=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl);
+
+=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl);
+
+=item long B<SSL_get_default_timeout>(const SSL *ssl);
+
+=item int B<SSL_get_error>(const SSL *ssl, int i);
+
+=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx);
+
+=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void);
+
+=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
+
+=item int B<SSL_get_fd>(const SSL *ssl);
+
+=item void (*B<SSL_get_info_callback>(const SSL *ssl);)()
+
+=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl);
+
+=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl);
+
+=item const STACK_OF(SCT) *B<SSL_get0_peer_scts>(SSL *s);
+
+=item EVP_PKEY *B<SSL_get_privatekey>(const SSL *ssl);
+
+=item int B<SSL_get_quiet_shutdown>(const SSL *ssl);
+
+=item BIO *B<SSL_get_rbio>(const SSL *ssl);
+
+=item int B<SSL_get_read_ahead>(const SSL *ssl);
+
+=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl);
+
+=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len);
+
+=item int B<SSL_get_shutdown>(const SSL *ssl);
+
+=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl);
+
+=item int B<SSL_get_state>(const SSL *ssl);
+
+=item long B<SSL_get_time>(const SSL *ssl);
+
+=item long B<SSL_get_timeout>(const SSL *ssl);
+
+=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int, X509_STORE_CTX *)
+
+=item int B<SSL_get_verify_mode>(const SSL *ssl);
+
+=item long B<SSL_get_verify_result>(const SSL *ssl);
+
+=item char *B<SSL_get_version>(const SSL *ssl);
+
+=item BIO *B<SSL_get_wbio>(const SSL *ssl);
+
+=item int B<SSL_in_accept_init>(SSL *ssl);
+
+=item int B<SSL_in_before>(SSL *ssl);
+
+=item int B<SSL_in_connect_init>(SSL *ssl);
+
+=item int B<SSL_in_init>(SSL *ssl);
+
+=item int B<SSL_is_init_finished>(SSL *ssl);
+
+=item STACK *B<SSL_load_client_CA_file>(const char *file);
+
+=item SSL *B<SSL_new>(SSL_CTX *ctx);
+
+=item int SSL_up_ref(SSL *s);
+
+=item long B<SSL_num_renegotiations>(SSL *ssl);
+
+=item int B<SSL_peek>(SSL *ssl, void *buf, int num);
+
+=item int B<SSL_pending>(const SSL *ssl);
+
+=item int B<SSL_read>(SSL *ssl, void *buf, int num);
+
+=item int B<SSL_renegotiate>(SSL *ssl);
+
+=item char *B<SSL_rstate_string>(SSL *ssl);
+
+=item char *B<SSL_rstate_string_long>(SSL *ssl);
+
+=item long B<SSL_session_reused>(SSL *ssl);
+
+=item void B<SSL_set_accept_state>(SSL *ssl);
+
+=item void B<SSL_set_app_data>(SSL *ssl, char *arg);
+
+=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio);
+
+=item int B<SSL_set_cipher_list>(SSL *ssl, char *str);
+
+=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list);
+
+=item void B<SSL_set_connect_state>(SSL *ssl);
+
+=item int B<SSL_set_ct_validation_callback>(SSL *ssl, ssl_ct_validation_cb callback, void *arg);
+
+=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg);
+
+=item int B<SSL_set_fd>(SSL *ssl, int fd);
+
+=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void))
+
+=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
+
+=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg);
+
+=item unsigned long B<SSL_clear_options>(SSL *ssl, unsigned long op);
+
+=item unsigned long B<SSL_get_options>(SSL *ssl);
+
+=item unsigned long B<SSL_set_options>(SSL *ssl, unsigned long op);
+
+=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode);
+
+=item void B<SSL_set_read_ahead>(SSL *ssl, int yes);
+
+=item int B<SSL_set_rfd>(SSL *ssl, int fd);
+
+=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session);
+
+=item void B<SSL_set_shutdown>(SSL *ssl, int mode);
+
+=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth);
+
+=item void B<SSL_set_time>(SSL *ssl, long t);
+
+=item void B<SSL_set_timeout>(SSL *ssl, long t);
+
+=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void))
+
+=item void B<SSL_set_verify_result>(SSL *ssl, long arg);
+
+=item int B<SSL_set_wfd>(SSL *ssl, int fd);
+
+=item int B<SSL_shutdown>(SSL *ssl);
+
+=item OSSL_HANDSHAKE_STATE B<SSL_get_state>(const SSL *ssl);
+
+Returns the current handshake state.
+
+=item char *B<SSL_state_string>(const SSL *ssl);
+
+=item char *B<SSL_state_string_long>(const SSL *ssl);
+
+=item long B<SSL_total_renegotiations>(SSL *ssl);
+
+=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey);
+
+=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len);
+
+=item int B<SSL_use_PrivateKey_file>(SSL *ssl, const char *file, int type);
+
+=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa);
+
+=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len);
+
+=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, const char *file, int type);
+
+=item int B<SSL_use_certificate>(SSL *ssl, X509 *x);
+
+=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d);
+
+=item int B<SSL_use_certificate_file>(SSL *ssl, const char *file, int type);
+
+=item int B<SSL_version>(const SSL *ssl);
+
+=item int B<SSL_want>(const SSL *ssl);
+
+=item int B<SSL_want_nothing>(const SSL *ssl);
+
+=item int B<SSL_want_read>(const SSL *ssl);
+
+=item int B<SSL_want_write>(const SSL *ssl);
+
+=item int B<SSL_want_x509_lookup>(const SSL *ssl);
+
+=item int B<SSL_write>(SSL *ssl, const void *buf, int num);
+
+=item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
+
+=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint);
+
+=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
+
+=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl);
+
+=item const char *B<SSL_get_psk_identity>(SSL *ssl);
+
+=back
+
+=head1 RETURN VALUES
+
+See the individual manual pages for details.
+
+=head1 SEE ALSO
+
+L<openssl(1)>, L<crypto(3)>,
+L<CRYPTO_get_ex_new_index(3)>,
+L<SSL_accept(3)>, L<SSL_clear(3)>,
+L<SSL_connect(3)>,
+L<SSL_CIPHER_get_name(3)>,
+L<SSL_COMP_add_compression_method(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_add_session(3)>,
+L<SSL_CTX_ctrl(3)>,
+L<SSL_CTX_flush_sessions(3)>,
+L<SSL_CTX_get_verify_mode(3)>,
+L<SSL_CTX_load_verify_locations(3)>
+L<SSL_CTX_new(3)>,
+L<SSL_CTX_sess_number(3)>,
+L<SSL_CTX_sess_set_cache_size(3)>,
+L<SSL_CTX_sess_set_get_cb(3)>,
+L<SSL_CTX_sessions(3)>,
+L<SSL_CTX_set_cert_store(3)>,
+L<SSL_CTX_set_cert_verify_callback(3)>,
+L<SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_client_CA_list(3)>,
+L<SSL_CTX_set_client_cert_cb(3)>,
+L<SSL_CTX_set_default_passwd_cb(3)>,
+L<SSL_CTX_set_generate_session_id(3)>,
+L<SSL_CTX_set_info_callback(3)>,
+L<SSL_CTX_set_max_cert_list(3)>,
+L<SSL_CTX_set_mode(3)>,
+L<SSL_CTX_set_msg_callback(3)>,
+L<SSL_CTX_set_options(3)>,
+L<SSL_CTX_set_quiet_shutdown(3)>,
+L<SSL_CTX_set_read_ahead(3)>,
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_CTX_set_session_id_context(3)>,
+L<SSL_CTX_set_ssl_version(3)>,
+L<SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)>,
+L<SSL_CTX_set_verify(3)>,
+L<SSL_CTX_use_certificate(3)>,
+L<SSL_alert_type_string(3)>,
+L<SSL_do_handshake(3)>,
+L<SSL_enable_ct(3)>,
+L<SSL_get_SSL_CTX(3)>,
+L<SSL_get_ciphers(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_get_default_timeout(3)>,
+L<SSL_get_error(3)>,
+L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
+L<SSL_get_fd(3)>,
+L<SSL_get_peer_cert_chain(3)>,
+L<SSL_get_rbio(3)>,
+L<SSL_get_session(3)>,
+L<SSL_get_verify_result(3)>,
+L<SSL_get_version(3)>,
+L<SSL_load_client_CA_file(3)>,
+L<SSL_new(3)>,
+L<SSL_pending(3)>,
+L<SSL_read(3)>,
+L<SSL_rstate_string(3)>,
+L<SSL_session_reused(3)>,
+L<SSL_set_bio(3)>,
+L<SSL_set_connect_state(3)>,
+L<SSL_set_fd(3)>,
+L<SSL_set_session(3)>,
+L<SSL_set_shutdown(3)>,
+L<SSL_shutdown(3)>,
+L<SSL_state_string(3)>,
+L<SSL_want(3)>,
+L<SSL_write(3)>,
+L<SSL_SESSION_free(3)>,
+L<SSL_SESSION_get_time(3)>,
+L<d2i_SSL_SESSION(3)>,
+L<SSL_CTX_set_psk_client_callback(3)>,
+L<SSL_CTX_use_psk_identity_hint(3)>,
+L<SSL_get_psk_identity(3)>,
+L<DTLSv1_listen(3)>
+
+=head1 HISTORY
+
+B<SSLv2_client_method>, B<SSLv2_server_method> and B<SSLv2_method> where removed
+in OpenSSL 1.1.0.
+
+The return type of B<SSL_copy_session_id> was changed from void to int in
+OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+x509 - X.509 certificate handling
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+=head1 DESCRIPTION
+
+A X.509 certificate is a structured grouping of information about
+an individual, a device, or anything one can imagine. A X.509 CRL
+(certificate revocation list) is a tool to help determine if a
+certificate is still valid. The exact definition of those can be
+found in the X.509 document from ITU-T, or in RFC3280 from PKIX.
+In OpenSSL, the type X509 is used to express such a certificate, and
+the type X509_CRL is used to express a CRL.
+
+A related structure is a certificate request, defined in PKCS#10 from
+RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type
+X509_REQ is used to express such a certificate request.
+
+To handle some complex parts of a certificate, there are the types
+X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express
+a certificate attributes), X509_EXTENSION (to express a certificate
+extension) and a few more.
+
+Finally, there's the supertype X509_INFO, which can contain a CRL, a
+certificate and a corresponding private key.
+
+B<X509_>I<...>, B<d2i_X509_>I<...> and B<i2d_X509_>I<...> handle X.509
+certificates, with some exceptions, shown below.
+
+B<X509_CRL_>I<...>, B<d2i_X509_CRL_>I<...> and B<i2d_X509_CRL_>I<...>
+handle X.509 CRLs.
+
+B<X509_REQ_>I<...>, B<d2i_X509_REQ_>I<...> and B<i2d_X509_REQ_>I<...>
+handle PKCS#10 certificate requests.
+
+B<X509_NAME_>I<...> handle certificate names.
+
+B<X509_ATTRIBUTE_>I<...> handle certificate attributes.
+
+B<X509_EXTENSION_>I<...> handle certificate extensions.
+
+=head1 SEE ALSO
+
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_add_entry_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_NAME_new(3)>,
+L<d2i_X509(3)>,
+L<d2i_X509_ALGOR(3)>,
+L<d2i_X509_CRL(3)>,
+L<d2i_X509_NAME(3)>,
+L<d2i_X509_REQ(3)>,
+L<d2i_X509_SIG(3)>,
+L<crypto(3)>,
+L<x509v3(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-DTLSv1_listen - listen for incoming DTLS connections
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);
-
-=head1 DESCRIPTION
-
-DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is
-received that does not contain a cookie, then DTLSv1_listen() responds with a
-HelloVerifyRequest. If a ClientHello is received with a cookie that is verified
-then control is returned to user code to enable the handshake to be completed
-(for example by using SSL_accept()).
-
-=head1 NOTES
-
-Datagram based protocols can be susceptible to Denial of Service attacks. A
-DTLS attacker could, for example, submit a series of handshake initiation
-requests that cause the server to allocate state (and possibly perform
-cryptographic operations) thus consuming server resources. The attacker could
-also (with UDP) quite simply forge the source IP address in such an attack.
-
-As a counter measure to that DTLS includes a stateless cookie mechanism. The
-idea is that when a client attempts to connect to a server it sends a
-ClientHello message. The server responds with a HelloVerifyRequest which
-contains a unique cookie. The client then resends the ClientHello, but this time
-includes the cookie in the message thus proving that the client is capable of
-receiving messages sent to that address. All of this can be done by the server
-without allocating any state, and thus without consuming expensive resources.
-
-OpenSSL implements this capability via the DTLSv1_listen() function. The B<ssl>
-parameter should be a newly allocated SSL object with its read and write BIOs
-set, in the same way as might be done for a call to SSL_accept(). Typically the
-read BIO will be in an "unconnected" state and thus capable of receiving
-messages from any peer.
-
-When a ClientHello is received that contains a cookie that has been verified,
-then DTLSv1_listen() will return with the B<ssl> parameter updated into a state
-where the handshake can be continued by a call to (for example) SSL_accept().
-Additionally the B<BIO_ADDR> pointed to by B<peer> will be filled in with
-details of the peer that sent the ClientHello. If the underlying BIO is unable
-to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not
-support this), then B<*peer> will be cleared and the family set to AF_UNSPEC.
-Typically user code is expected to "connect" the underlying socket to the peer
-and continue the handshake in a connected state.
-
-Prior to calling DTLSv1_listen() user code must ensure that cookie generation
-and verification callbacks have been set up using
-SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
-respectively.
-
-Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
-ClientHellos it is unable to process fragmented messages (since this would
-require the allocation of state). An implication of this is that DTLSv1_listen()
-B<only> supports ClientHellos that fit inside a single datagram.
-
-=head1 RETURN VALUES
-
-From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance
-the B<peer> value will be filled in and the B<ssl> object set up ready to
-continue the handshake.
-
-A return value of 0 indicates a non-fatal error. This could (for
-example) be because of non-blocking IO, or some invalid message having been
-received from a peer. Errors may be placed on the OpenSSL error queue with
-further information if appropriate. Typically user code is expected to retry the
-call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the
-error queue will be cleared in the subsequent call.
-
-A return value of <0 indicates a fatal error. This could (for example) be
-because of a failure to allocate sufficient memory for the operation.
-
-Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes
-<= 0 (in typical implementations user code treats all errors as non-fatal),
-whilst return codes >0 indicate success.
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_accept(3)>,
-L<ssl(3)>, L<bio(3)>
-
-=head1 HISTORY
-
-DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer"
-also changed in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
-
-=head1 DESCRIPTION
-
-During normal operation OpenSSL (libssl and libcrypto) will allocate various
-resources at start up that must, subsequently, be freed on close down of the
-library. Additionally some resources are allocated on a per thread basis (if the
-application is multi-threaded), and these resources must be freed prior to the
-thread closing.
-
-As of version 1.1.0 OpenSSL will automatically allocate all resources that it
-needs so no explicit initialisation is required. Similarly it will also
-automatically deinitialise as required.
-
-However, there may be situations when explicit initialisation is desirable or
-needed, for example when some non-default initialisation is required. The
-function OPENSSL_init_ssl() can be used for this purpose. Calling
-this function will explicitly initialise BOTH libcrypto and libssl. To
-explicitly initialise ONLY libcrypto see the
-L<OPENSSL_init_crypto(3)> function.
-
-Numerous internal OpenSSL functions call OPENSSL_init_ssl().
-Therefore, in order to perform non-default initialisation,
-OPENSSL_init_ssl() MUST be called by application code prior to
-any other OpenSSL function calls.
-
-The B<opts> parameter specifies which aspects of libssl and libcrypto should be
-initialised. Valid options for libcrypto are described on the
-L<OPENSSL_init_crypto(3)> page. In addition to any libcrypto
-specific option the following libssl options can also be used:
-
-=over 4
-
-=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS
-
-Suppress automatic loading of the libssl error strings. This option is
-not a default option. Once selected subsequent calls to
-OPENSSL_init_ssl() with the option
-B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.
-
-=item OPENSSL_INIT_LOAD_SSL_STRINGS
-
-Automatic loading of the libssl error strings. This option is a
-default option. Once selected subsequent calls to
-OPENSSL_init_ssl() with the option
-B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.
-
-=back
-
-OPENSSL_init_ssl() takes a B<settings> parameter which can be used to
-set parameter values. See L<OPENSSL_init_crypto(3)> for details.
-
-=head1 RETURN VALUES
-
-The function OPENSSL_init_ssl() returns 1 on success or 0 on error.
-
-=head1 SEE ALSO
-
-L<OPENSSL_init_crypto(3)>
-
-=head1 HISTORY
-
-The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_kx_nid,
-SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead,
-SSL_CIPHER_get_name, SSL_CIPHER_get_bits,
-SSL_CIPHER_get_version, SSL_CIPHER_description
-- get SSL_CIPHER properties
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
- int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
- char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
- char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
- int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
- int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
- int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
- int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
- int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
-
-=head1 DESCRIPTION
-
-SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the
-B<cipher> is NULL, it returns "(NONE)".
-
-SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>.
-If B<cipher> is NULL, 0 is returned.
-
-SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
-version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL.
-
-SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>.
-If there is no cipher (e.g. for ciphersuites with no encryption) then
-B<NID_undef> is returned.
-
-SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC
-used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then
-B<NID_undef> is returned.
-
-SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
-used by B<c>. If there is no key exchange, then B<NID_undef> is returned. Examples (not comprehensive):
-
- NID_kx_rsa
- NID_kx_ecdhe
- NID_kx_dhe
- NID_kx_psk
-
-SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method
-used by B<c>. If there is no authentication, then B<NID_undef> is returned.
-Examples (not comprehensive):
-
- NID_auth_rsa
- NID_auth_ecdsa
- NID_auth_psk
-
-SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or
-ChaCha20/Poly1305), and 0 if it is not AEAD.
-
-SSL_CIPHER_description() returns a textual description of the cipher used
-into the buffer B<buf> of length B<len> provided. If B<buf> is provided, it
-must be at least 128 bytes, otherwise a buffer will be allocated using
-OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails,
-B<NULL> is returned.
-
-The string returned by SSL_CIPHER_description() consists of several fields
-separated by whitespace:
-
-=over 4
-
-=item <ciphername>
-
-Textual representation of the cipher name.
-
-=item <protocol version>
-
-Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
-
-=item Kx=<key exchange>
-
-Key exchange method such as B<RSA>, B<ECDHE>, etc.
-
-=item Au=<authentication>
-
-Authentication method such as B<RSA>, B<None>, etc.. None is the
-representation of anonymous ciphers.
-
-=item Enc=<symmetric encryption method>
-
-Encryption method, with number of secret bits, such as B<AESGCM(128)>.
-
-=item Mac=<message authentication code>
-
-Message digest, such as B<SHA256>.
-
-=back
-
-Some examples for the output of SSL_CIPHER_description():
-
- ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
- RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384
-
-=head1 HISTORY
-
-SSL_CIPHER_get_version() was updated to always return the correct protocol
-string in OpenSSL 1.1.
-
-SSL_CIPHER_description() was changed to return B<NULL> on error,
-rather than a fixed string, in OpenSSL 1.1
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_current_cipher(3)>,
-L<SSL_get_ciphers(3)>, L<ciphers(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_COMP_add_compression_method, SSL_COMP_free_compression_methods - handle SSL/TLS integrated compression methods
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm);
-
-Deprecated:
-
- #if OPENSSL_API_COMPAT < 0x10100000L
- void SSL_COMP_free_compression_methods(void)
- #endif
-
-=head1 DESCRIPTION
-
-SSL_COMP_add_compression_method() adds the compression method B<cm> with
-the identifier B<id> to the list of available compression methods. This
-list is globally maintained for all SSL operations within this application.
-It cannot be set for specific SSL_CTX or SSL objects.
-
-In versions of OpenSSL prior to 1.1.0 SSL_COMP_free_compression_methods() freed
-the internal table of compression methods that were built internally, and
-possibly augmented by adding SSL_COMP_add_compression_method(). However this is
-now unnecessary from version 1.1.0. No explicit initialisation or
-de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> and
-L<OPENSSL_init_ssl(3)>. From OpenSSL 1.1.0 calling this function does nothing.
-
-=head1 NOTES
-
-The TLS standard (or SSLv3) allows the integration of compression methods
-into the communication. The TLS RFC does however not specify compression
-methods or their corresponding identifiers, so there is currently no compatible
-way to integrate compression with unknown peers. It is therefore currently not
-recommended to integrate compression into applications. Applications for
-non-public use may agree on certain compression methods. Using different
-compression methods with the same identifier will lead to connection failure.
-
-An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1)
-will unconditionally send the list of all compression methods enabled with
-SSL_COMP_add_compression_method() to the server during the handshake.
-Unlike the mechanisms to set a cipher list, there is no method available to
-restrict the list of compression method on a per connection basis.
-
-An OpenSSL server will match the identifiers listed by a client against
-its own compression methods and will unconditionally activate compression
-when a matching identifier is found. There is no way to restrict the list
-of compression methods supported on a per connection basis.
-
-If enabled during compilation, the OpenSSL library will have the
-COMP_zlib() compression method available.
-
-=head1 WARNINGS
-
-Once the identities of the compression methods for the TLS protocol have
-been standardized, the compression API will most likely be changed. Using
-it in the current state is not recommended.
-
-=head1 RETURN VALUES
-
-SSL_COMP_add_compression_method() may return the following values:
-
-=over 4
-
-=item Z<>0
-
-The operation succeeded.
-
-=item Z<>1
-
-The operation failed. Check the error queue to find out the reason.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 HISTORY
-
-SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CONF_CTX_new, SSL_CONF_CTX_free - SSL configuration allocation functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- SSL_CONF_CTX *SSL_CONF_CTX_new(void);
- void SSL_CONF_CTX_free(SSL_CONF_CTX *cctx);
-
-=head1 DESCRIPTION
-
-The function SSL_CONF_CTX_new() allocates and initialises an B<SSL_CONF_CTX>
-structure for use with the SSL_CONF functions.
-
-The function SSL_CONF_CTX_free() frees up the context B<cctx>.
-If B<cctx> is NULL nothing is done.
-
-=head1 RETURN VALUES
-
-SSL_CONF_CTX_new() returns either the newly allocated B<SSL_CONF_CTX> structure
-or B<NULL> if an error occurs.
-
-SSL_CONF_CTX_free() does not return a value.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_CTX_set_flags(3)>,
-L<SSL_CONF_CTX_set_ssl_ctx(3)>,
-L<SSL_CONF_CTX_set1_prefix(3)>,
-L<SSL_CONF_cmd(3)>,
-L<SSL_CONF_cmd_argv(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2
-
-=head1 COPYRIGHT
-
-Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CONF_CTX_set1_prefix - Set configuration context command prefix
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- unsigned int SSL_CONF_CTX_set1_prefix(SSL_CONF_CTX *cctx, const char *prefix);
-
-=head1 DESCRIPTION
-
-The function SSL_CONF_CTX_set1_prefix() sets the command prefix of B<cctx>
-to B<prefix>. If B<prefix> is B<NULL> it is restored to the default value.
-
-=head1 NOTES
-
-Command prefixes alter the commands recognised by subsequent SSL_CTX_cmd()
-calls. For example for files, if the prefix "SSL" is set then command names
-such as "SSLProtocol", "SSLOptions" etc. are recognised instead of "Protocol"
-and "Options". Similarly for command lines if the prefix is "--ssl-" then
-"--ssl-no_tls1_2" is recognised instead of "-no_tls1_2".
-
-If the B<SSL_CONF_FLAG_CMDLINE> flag is set then prefix checks are case
-sensitive and "-" is the default. In the unlikely even an application
-explicitly wants to set no prefix it must be explicitly set to "".
-
-If the B<SSL_CONF_FLAG_FILE> flag is set then prefix checks are case
-insensitive and no prefix is the default.
-
-=head1 RETURN VALUES
-
-SSL_CONF_CTX_set1_prefix() returns 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_CTX_new(3)>,
-L<SSL_CONF_CTX_set_flags(3)>,
-L<SSL_CONF_CTX_set_ssl_ctx(3)>,
-L<SSL_CONF_cmd(3)>,
-L<SSL_CONF_cmd_argv(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2
-
-=head1 COPYRIGHT
-
-Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CONF_CTX_set_flags, SSL_CONF_CTX_clear_flags - Set of clear SSL configuration context flags
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- unsigned int SSL_CONF_CTX_set_flags(SSL_CONF_CTX *cctx, unsigned int flags);
- unsigned int SSL_CONF_CTX_clear_flags(SSL_CONF_CTX *cctx, unsigned int flags);
-
-=head1 DESCRIPTION
-
-The function SSL_CONF_CTX_set_flags() sets B<flags> in the context B<cctx>.
-
-The function SSL_CONF_CTX_clear_flags() clears B<flags> in the context B<cctx>.
-
-=head1 NOTES
-
-The flags set affect how subsequent calls to SSL_CONF_cmd() or
-SSL_CONF_argv() behave.
-
-Currently the following B<flags> values are recognised:
-
-=over 4
-
-=item SSL_CONF_FLAG_CMDLINE, SSL_CONF_FLAG_FILE
-
-recognise options intended for command line or configuration file use. At
-least one of these flags must be set.
-
-=item SSL_CONF_FLAG_CLIENT, SSL_CONF_FLAG_SERVER
-
-recognise options intended for use in SSL/TLS clients or servers. One or
-both of these flags must be set.
-
-=item SSL_CONF_FLAG_CERTIFICATE
-
-recognise certificate and private key options.
-
-=item SSL_CONF_FLAG_REQUIRE_PRIVATE
-
-If this option is set then if a private key is not specified for a certificate
-it will attempt to load a private key from the certificate file when
-SSL_CONF_CTX_finish() is called. If a key cannot be loaded from the certificate
-file an error occurs.
-
-=item SSL_CONF_FLAG_SHOW_ERRORS
-
-indicate errors relating to unrecognised options or missing arguments in
-the error queue. If this option isn't set such errors are only reflected
-in the return values of SSL_CONF_set_cmd() or SSL_CONF_set_argv()
-
-=back
-
-=head1 RETURN VALUES
-
-SSL_CONF_CTX_set_flags() and SSL_CONF_CTX_clear_flags() returns the new flags
-value after setting or clearing flags.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_CTX_new(3)>,
-L<SSL_CONF_CTX_set_ssl_ctx(3)>,
-L<SSL_CONF_CTX_set1_prefix(3)>,
-L<SSL_CONF_cmd(3)>,
-L<SSL_CONF_cmd_argv(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2
-
-=head1 COPYRIGHT
-
-Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CONF_CTX_set_ssl_ctx, SSL_CONF_CTX_set_ssl - set context to configure
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CONF_CTX_set_ssl_ctx(SSL_CONF_CTX *cctx, SSL_CTX *ctx);
- void SSL_CONF_CTX_set_ssl(SSL_CONF_CTX *cctx, SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_CONF_CTX_set_ssl_ctx() sets the context associated with B<cctx> to the
-B<SSL_CTX> structure B<ctx>. Any previous B<SSL> or B<SSL_CTX> associated with
-B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to
-B<ctx>.
-
-SSL_CONF_CTX_set_ssl() sets the context associated with B<cctx> to the
-B<SSL> structure B<ssl>. Any previous B<SSL> or B<SSL_CTX> associated with
-B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to
-B<ssl>.
-
-=head1 NOTES
-
-The context need not be set or it can be set to B<NULL> in which case only
-syntax checking of commands is performed, where possible.
-
-=head1 RETURN VALUES
-
-SSL_CONF_CTX_set_ssl_ctx() and SSL_CTX_set_ssl() do not return a value.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_CTX_new(3)>,
-L<SSL_CONF_CTX_set_flags(3)>,
-L<SSL_CONF_CTX_set1_prefix(3)>,
-L<SSL_CONF_cmd(3)>,
-L<SSL_CONF_cmd_argv(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2
-
-=head1 COPYRIGHT
-
-Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CONF_cmd_value_type, SSL_CONF_finish,
-SSL_CONF_cmd - send configuration command
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
- int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd);
- int SSL_CONF_finish(SSL_CONF_CTX *cctx);
-
-=head1 DESCRIPTION
-
-The function SSL_CONF_cmd() performs configuration operation B<cmd> with
-optional parameter B<value> on B<ctx>. Its purpose is to simplify application
-configuration of B<SSL_CTX> or B<SSL> structures by providing a common
-framework for command line options or configuration files.
-
-SSL_CONF_cmd_value_type() returns the type of value that B<cmd> refers to.
-
-The function SSL_CONF_finish() must be called after all configuration
-operations have been completed. It is used to finalise any operations
-or to process defaults.
-
-=head1 SUPPORTED COMMAND LINE COMMANDS
-
-Currently supported B<cmd> names for command lines (i.e. when the
-flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names
-are case sensitive. Unless otherwise stated commands can be used by
-both clients and servers and the B<value> parameter is not used. The default
-prefix for command line commands is B<-> and that is reflected below.
-
-=over 4
-
-=item B<-sigalgs>
-
-This sets the supported signature algorithms for TLS v1.2. For clients this
-value is used directly for the supported signature algorithms extension. For
-servers it is used to determine which signature algorithms to support.
-
-The B<value> argument should be a colon separated list of signature algorithms
-in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
-is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
-OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
-Note: algorithm and hash names are case sensitive.
-
-If this option is not set then all signature algorithms supported by the
-OpenSSL library are permissible.
-
-=item B<-client_sigalgs>
-
-This sets the supported signature algorithms associated with client
-authentication for TLS v1.2. For servers the value is used in the supported
-signature algorithms field of a certificate request. For clients it is
-used to determine which signature algorithm to with the client certificate.
-If a server does not request a certificate this option has no effect.
-
-The syntax of B<value> is identical to B<-sigalgs>. If not set then
-the value set for B<-sigalgs> will be used instead.
-
-=item B<-curves>
-
-This sets the supported elliptic curves. For clients the curves are
-sent using the supported curves extension. For servers it is used
-to determine which curve to use. This setting affects curves used for both
-signatures and key exchange, if applicable.
-
-The B<value> argument is a colon separated list of curves. The curve can be
-either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
-B<prime256v1>). Curve names are case sensitive.
-
-=item B<-named_curve>
-
-This sets the temporary curve used for ephemeral ECDH modes. Only used by
-servers
-
-The B<value> argument is a curve name or the special value B<auto> which
-picks an appropriate curve based on client and server preferences. The curve
-can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
-(e.g B<prime256v1>). Curve names are case sensitive.
-
-=item B<-cipher>
-
-Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
-currently not performed unless a B<SSL> or B<SSL_CTX> structure is
-associated with B<cctx>.
-
-=item B<-cert>
-
-Attempts to use the file B<value> as the certificate for the appropriate
-context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
-structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
-structure is set. This option is only supported if certificate operations
-are permitted.
-
-=item B<-key>
-
-Attempts to use the file B<value> as the private key for the appropriate
-context. This option is only supported if certificate operations
-are permitted. Note: if no B<-key> option is set then a private key is
-not loaded unless the flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
-
-=item B<-dhparam>
-
-Attempts to use the file B<value> as the set of temporary DH parameters for
-the appropriate context. This option is only supported if certificate
-operations are permitted.
-
-=item B<-min_protocol>, B<-max_protocol>
-
-Sets the minimum and maximum supported protocol.
-Currently supported protocol values are B<SSLv3>, B<TLSv1>,
-B<TLSv1.1>, B<TLSv1.2> for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS,
-and B<None> for no limit.
-If the either bound is not specified then only the other bound applies,
-if specified.
-To restrict the supported protocol versions use these commands rather
-than the deprecated alternative commands below.
-
-=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
-
-Disables protocol support for SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 by setting the
-corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1>
-and B<SSL_OP_NO_TLSv1_2> respectively.
-These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>.
-
-=item B<-bugs>
-
-Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
-
-=item B<-comp>
-
-Enables support for SSL/TLS compression, same as clearing
-B<SSL_OP_NO_COMPRESSION>.
-This command was introduced in OpenSSL 1.1.0.
-As of OpenSSL 1.1.0, compression is off by default.
-
-=item B<-no_comp>
-
-Disables support for SSL/TLS compression, same as setting
-B<SSL_OP_NO_COMPRESSION>.
-As of OpenSSL 1.1.0, compression is off by default.
-
-=item B<-no_ticket>
-
-Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
-
-=item B<-serverpref>
-
-Use server and not client preference order when determining which cipher suite,
-signature algorithm or elliptic curve to use for an incoming connection.
-Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
-
-=item B<-no_resumption_on_reneg>
-
-set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers.
-
-=item B<-legacyrenegotiation>
-
-permits the use of unsafe legacy renegotiation. Equivalent to setting
-B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
-
-=item B<-legacy_server_connect>, B<-no_legacy_server_connect>
-
-permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
-clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
-Set by default.
-
-=item B<-strict>
-
-enables strict mode protocol handling. Equivalent to setting
-B<SSL_CERT_FLAG_TLS_STRICT>.
-
-=back
-
-=head1 SUPPORTED CONFIGURATION FILE COMMANDS
-
-Currently supported B<cmd> names for configuration files (i.e. when the
-flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
-B<cmd> names are case insensitive so B<signaturealgorithms> is recognised
-as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
-are also case insensitive.
-
-Note: the command prefix (if set) alters the recognised B<cmd> values.
-
-=over 4
-
-=item B<CipherString>
-
-Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
-currently not performed unless an B<SSL> or B<SSL_CTX> structure is
-associated with B<cctx>.
-
-=item B<Certificate>
-
-Attempts to use the file B<value> as the certificate for the appropriate
-context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX>
-structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL>
-structure is set. This option is only supported if certificate operations
-are permitted.
-
-=item B<PrivateKey>
-
-Attempts to use the file B<value> as the private key for the appropriate
-context. This option is only supported if certificate operations
-are permitted. Note: if no B<PrivateKey> option is set then a private key is
-not loaded unless the B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set.
-
-=item B<ChainCAFile>, B<ChainCAPath>, B<VerifyCAFile>, B<VerifyCAPath>
-
-These options indicate a file or directory used for building certificate
-chains or verifying certificate chains. These options are only supported
-if certificate operations are permitted.
-
-=item B<ServerInfoFile>
-
-Attempts to use the file B<value> in the "serverinfo" extension using the
-function SSL_CTX_use_serverinfo_file.
-
-=item B<DHParameters>
-
-Attempts to use the file B<value> as the set of temporary DH parameters for
-the appropriate context. This option is only supported if certificate
-operations are permitted.
-
-=item B<SignatureAlgorithms>
-
-This sets the supported signature algorithms for TLS v1.2. For clients this
-value is used directly for the supported signature algorithms extension. For
-servers it is used to determine which signature algorithms to support.
-
-The B<value> argument should be a colon separated list of signature algorithms
-in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
-is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
-OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
-Note: algorithm and hash names are case sensitive.
-
-If this option is not set then all signature algorithms supported by the
-OpenSSL library are permissible.
-
-=item B<ClientSignatureAlgorithms>
-
-This sets the supported signature algorithms associated with client
-authentication for TLS v1.2. For servers the value is used in the supported
-signature algorithms field of a certificate request. For clients it is
-used to determine which signature algorithm to with the client certificate.
-
-The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
-the value set for B<SignatureAlgorithms> will be used instead.
-
-=item B<Curves>
-
-This sets the supported elliptic curves. For clients the curves are
-sent using the supported curves extension. For servers it is used
-to determine which curve to use. This setting affects curves used for both
-signatures and key exchange, if applicable.
-
-The B<value> argument is a colon separated list of curves. The curve can be
-either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
-B<prime256v1>). Curve names are case sensitive.
-
-=item B<MinProtocol>
-
-This sets the minimum supported SSL, TLS or DTLS version.
-
-Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
-B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
-The value B<None> will disable the limit.
-
-=item B<MaxProtocol>
-
-This sets the maximum supported SSL, TLS or DTLS version.
-
-Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
-B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
-The value B<None> will disable the limit.
-
-=item B<Protocol>
-
-This can be used to enable or disable certain versions of the SSL,
-TLS or DTLS protocol.
-
-The B<value> argument is a comma separated list of supported protocols
-to enable or disable.
-If a protocol is preceded by B<-> that version is disabled.
-
-All protocol versions are enabled by default.
-You need to disable at least one protocol version for this setting have any
-effect.
-Only enabling some protocol versions does not disable the other protocol
-versions.
-
-Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>,
-B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>.
-The special value B<ALL> refers to all supported versions.
-
-This can't enable protocols that are disabled using B<MinProtocol>
-or B<MaxProtocol>, but can disable protocols that are still allowed
-by them.
-
-The B<Protocol> command is fragile and deprecated; do not use it.
-Use B<MinProtocol> and B<MaxProtocol> instead.
-If you do use B<Protocol>, make sure that the resulting range of enabled
-protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make
-sure to also leave TLS 1.1 enabled.
-
-=item B<Options>
-
-The B<value> argument is a comma separated list of various flags to set.
-If a flag string is preceded B<-> it is disabled.
-See the L<SSL_CTX_set_options(3)> function for more details of
-individual options.
-
-Each option is listed below. Where an operation is enabled by default
-the B<-flag> syntax is needed to disable it.
-
-B<SessionTicket>: session ticket support, enabled by default. Inverse of
-B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting
-B<SSL_OP_NO_TICKET>.
-
-B<Compression>: SSL/TLS compression support, enabled by default. Inverse
-of B<SSL_OP_NO_COMPRESSION>.
-
-B<EmptyFragments>: use empty fragments as a countermeasure against a
-SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It
-is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>.
-
-B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
-
-B<DHSingle>: enable single use DH keys, set by default. Inverse of
-B<SSL_OP_DH_SINGLE>. Only used by servers.
-
-B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of
-B<SSL_OP_ECDH_SINGLE>. Only used by servers.
-
-B<ServerPreference> use server and not client preference order when
-determining which cipher suite, signature algorithm or elliptic curve
-to use for an incoming connection. Equivalent to
-B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
-
-B<NoResumptionOnRenegotiation> set
-B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers.
-
-B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation.
-Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
-
-B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
-for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
-Set by default.
-
-=item B<VerifyMode>
-
-The B<value> argument is a comma separated list of flags to set.
-
-B<Peer> enables peer verification: for clients only.
-
-B<Request> requests but does not require a certificate from the client.
-Servers only.
-
-B<Require> requests and requires a certificate from the client: an error
-occurs if the client does not present a certificate. Servers only.
-
-B<Once> requests a certificate from a client only on the initial connection:
-not when renegotiating. Servers only.
-
-=item B<ClientCAFile>, B<ClientCAPath>
-
-A file or directory of certificates in PEM format whose names are used as the
-set of acceptable names for client CAs. Servers only. This option is only
-supported if certificate operations are permitted.
-
-=back
-
-=head1 SUPPORTED COMMAND TYPES
-
-The function SSL_CONF_cmd_value_type() currently returns one of the following
-types:
-
-=over 4
-
-=item B<SSL_CONF_TYPE_UNKNOWN>
-
-The B<cmd> string is unrecognised, this return value can be use to flag
-syntax errors.
-
-=item B<SSL_CONF_TYPE_STRING>
-
-The value is a string without any specific structure.
-
-=item B<SSL_CONF_TYPE_FILE>
-
-The value is a file name.
-
-=item B<SSL_CONF_TYPE_DIR>
-
-The value is a directory name.
-
-=item B<SSL_CONF_TYPE_NONE>
-
-The value string is not used e.g. a command line option which doesn't take an
-argument.
-
-=back
-
-=head1 NOTES
-
-The order of operations is significant. This can be used to set either defaults
-or values which cannot be overridden. For example if an application calls:
-
- SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
- SSL_CONF_cmd(ctx, userparam, uservalue);
-
-it will disable SSLv3 support by default but the user can override it. If
-however the call sequence is:
-
- SSL_CONF_cmd(ctx, userparam, uservalue);
- SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
-
-SSLv3 is B<always> disabled and attempt to override this by the user are
-ignored.
-
-By checking the return code of SSL_CTX_cmd() it is possible to query if a
-given B<cmd> is recognised, this is useful is SSL_CTX_cmd() values are
-mixed with additional application specific operations.
-
-For example an application might call SSL_CTX_cmd() and if it returns
--2 (unrecognised command) continue with processing of application specific
-commands.
-
-Applications can also use SSL_CTX_cmd() to process command lines though the
-utility function SSL_CTX_cmd_argv() is normally used instead. One way
-to do this is to set the prefix to an appropriate value using
-SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the
-following argument to B<value> (which may be NULL).
-
-In this case if the return value is positive then it is used to skip that
-number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is
-returned then B<cmd> is not recognised and application specific arguments
-can be checked instead. If -3 is returned a required argument is missing
-and an error is indicated. If 0 is returned some other error occurred and
-this can be reported back to the user.
-
-The function SSL_CONF_cmd_value_type() can be used by applications to
-check for the existence of a command or to perform additional syntax
-checking or translation of the command value. For example if the return
-value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
-pathname to an absolute pathname.
-
-=head1 EXAMPLES
-
-Set supported signature algorithms:
-
- SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
-
-There are various ways to select the supported protocols.
-
-This set the minimum protocol version to TLSv1, and so disables SSLv3.
-This is the recommended way to disable protocols.
-
- SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1");
-
-The following also disables SSLv3:
-
- SSL_CONF_cmd(ctx, "Protocol", "-SSLv3");
-
-The following will first enable all protocols, and then disable
-SSLv3.
-If no protocol versions were disabled before this has the same effect as
-"-SSLv3", but if some versions were disables this will re-enable them before
-disabling SSLv3.
-
- SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3");
-
-Only enable TLSv1.2:
-
- SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2");
- SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2");
-
-This also only enables TLSv1.2:
-
- SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
-
-Disable TLS session tickets:
-
- SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
-
-Enable compression:
-
- SSL_CONF_cmd(ctx, "Options", "Compression");
-
-Set supported curves to P-256, P-384:
-
- SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
-
-Set automatic support for any elliptic curve for key exchange:
-
- SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
-
-=head1 RETURN VALUES
-
-SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
-B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
-returns the number of arguments processed. This is useful when processing
-command lines.
-
-A return value of -2 means B<cmd> is not recognised.
-
-A return value of -3 means B<cmd> is recognised and the command requires a
-value but B<value> is NULL.
-
-A return code of 0 indicates that both B<cmd> and B<value> are valid but an
-error occurred attempting to perform the operation: for example due to an
-error in the syntax of B<value> in this case the error queue may provide
-additional information.
-
-SSL_CONF_finish() returns 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_CTX_new(3)>,
-L<SSL_CONF_CTX_set_flags(3)>,
-L<SSL_CONF_CTX_set1_prefix(3)>,
-L<SSL_CONF_CTX_set_ssl_ctx(3)>,
-L<SSL_CONF_cmd_argv(3)>,
-L<SSL_CTX_set_options(3)>
-
-=head1 HISTORY
-
-SSL_CONF_cmd() was first added to OpenSSL 1.0.2
-
-B<SSL_OP_NO_SSL2> doesn't have effect since 1.1.0, but the macro is retained
-for backwards compatibility.
-
-B<SSL_CONF_TYPE_NONE> was first added to OpenSSL 1.1.0. In earlier versions of
-OpenSSL passing a command which didn't take an argument would return
-B<SSL_CONF_TYPE_UNKNOWN>.
-
-B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CONF_cmd_argv - SSL configuration command line processing
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CONF_cmd_argv(SSL_CONF_CTX *cctx, int *pargc, char ***pargv);
-
-=head1 DESCRIPTION
-
-The function SSL_CONF_cmd_argv() processes at most two command line
-arguments from B<pargv> and B<pargc>. The values of B<pargv> and B<pargc>
-are updated to reflect the number of command options processed. The B<pargc>
-argument can be set to B<NULL> is it is not used.
-
-=head1 RETURN VALUES
-
-SSL_CONF_cmd_argv() returns the number of command arguments processed: 0, 1, 2
-or a negative error code.
-
-If -2 is returned then an argument for a command is missing.
-
-If -1 is returned the command is recognised but couldn't be processed due
-to an error: for example a syntax error in the argument.
-
-=head1 SEE ALSO
-
-L<SSL_CONF_CTX_new(3)>,
-L<SSL_CONF_CTX_set_flags(3)>,
-L<SSL_CONF_CTX_set1_prefix(3)>,
-L<SSL_CONF_CTX_set_ssl_ctx(3)>,
-L<SSL_CONF_cmd(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2
-
-=head1 COPYRIGHT
-
-Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
-SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs,
-SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert,
-SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain,
-SSL_build_cert_chain, SSL_CTX_select_current_cert,
-SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra
-chain certificate processing
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
- int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
- int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
- int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
- int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
- int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
-
- int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
- int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
- int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
- int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
- int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
- int SSL_clear_chain_certs(SSL *ssl);
-
- int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
- int SSL_build_cert_chain(SSL *ssl, flags);
-
- int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
- int SSL_select_current_cert(SSL *ssl, X509 *x509);
- int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
- int SSL_set_current_cert(SSL *ssl, long op);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain
-associated with the current certificate of B<ctx> to B<sk>.
-
-SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single
-certificate B<x509> to the chain associated with the current certificate of
-B<ctx>.
-
-SSL_CTX_get0_chain_certs() retrieves the chain associated with the current
-certificate of B<ctx>.
-
-SSL_CTX_clear_chain_certs() clears any existing chain associated with the
-current certificate of B<ctx>. (This is implemented by calling
-SSL_CTX_set0_chain() with B<sk> set to B<NULL>).
-
-SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally
-this uses the chain store or the verify store if the chain store is not set.
-If the function is successful the built chain will replace any existing chain.
-The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use
-existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT>
-to omit the root CA from the built chain, B<SSL_BUILD_CHAIN_FLAG_CHECK> to
-use all existing chain certificates only to build the chain (effectively
-sanity checking and rearranging them if necessary), the flag
-B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification:
-if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors
-are cleared from the error queue.
-
-Each of these functions operates on the I<current> end entity
-(i.e. server or client) certificate. This is the last certificate loaded or
-selected on the corresponding B<ctx> structure.
-
-SSL_CTX_select_current_cert() selects B<x509> as the current end entity
-certificate, but only if B<x509> has already been loaded into B<ctx> using a
-function such as SSL_CTX_use_certificate().
-
-SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(),
-SSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(),
-SSL_build_cert_chain(), SSL_select_current_cert() and SSL_set_current_cert()
-are similar except they apply to SSL structure B<ssl>.
-
-SSL_CTX_set_current_cert() changes the current certificate to a value based
-on the B<op> argument. Currently B<op> can be B<SSL_CERT_SET_FIRST> to use
-the first valid certificate or B<SSL_CERT_SET_NEXT> to set the next valid
-certificate after the current certificate. These two operations can be
-used to iterate over all certificates in an B<SSL_CTX> structure.
-
-SSL_set_current_cert() also supports the option B<SSL_CERT_SET_SERVER>.
-If B<ssl> is a server and has sent a certificate to a connected client
-this option sets that certificate to the current certificate and returns 1.
-If the negotiated ciphersuite is anonymous (and thus no certificate will
-be sent) 2 is returned and the current certificate is unchanged. If B<ssl>
-is not a server or a certificate has not been sent 0 is returned and
-the current certificate is unchanged.
-
-All these functions are implemented as macros. Those containing a B<1>
-increment the reference count of the supplied certificate or chain so it must
-be freed at some point after the operation. Those containing a B<0> do
-not increment reference counts and the supplied certificate or chain
-B<MUST NOT> be freed after the operation.
-
-=head1 NOTES
-
-The chains associate with an SSL_CTX structure are copied to any SSL
-structures when SSL_new() is called. SSL structures will not be affected
-by any chains subsequently changed in the parent SSL_CTX.
-
-One chain can be set for each key type supported by a server. So, for example,
-an RSA and a DSA certificate can (and often will) have different chains.
-
-The functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can
-be used to check application configuration and to ensure any necessary
-subordinate CAs are sent in the correct order. Misconfigured applications
-sending incorrect certificate chains often cause problems with peers.
-
-For example an application can add any set of certificates using
-SSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain()
-with the option B<SSL_BUILD_CHAIN_FLAG_CHECK> to check and reorder them.
-
-Applications can issue non fatal warnings when checking chains by setting
-the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS> and checking the return
-value.
-
-Calling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more
-efficient than the automatic chain building as it is only performed once.
-Automatic chain building is performed on each new session.
-
-If any certificates are added using these functions no certificates added
-using SSL_CTX_add_extra_chain_cert() will be used.
-
-=head1 RETURN VALUES
-
-SSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if
-no server certificate is used because the ciphersuites is anonymous and 0
-for failure.
-
-SSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success
-and 0 for failure. If the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> and
-a verification error occurs then 2 is returned.
-
-All other functions return 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<SSL_CTX_add_extra_chain_cert(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2.
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_add_extra_chain_cert, SSL_CTX_clear_extra_chain_certs - add or clear
-extra chain certificates
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);
- long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the extra chain
-certificates associated with B<ctx>. Several certificates can be added one
-after another.
-
-SSL_CTX_clear_extra_chain_certs() clears all extra chain certificates
-associated with B<ctx>.
-
-These functions are implemented as macros.
-
-=head1 NOTES
-
-When sending a certificate chain, extra chain certificates are sent in order
-following the end entity certificate.
-
-If no chain is specified, the library will try to complete the chain from the
-available CA certificates in the trusted CA storage, see
-L<SSL_CTX_load_verify_locations(3)>.
-
-The B<x509> certificate provided to SSL_CTX_add_extra_chain_cert() will be
-freed by the library when the B<SSL_CTX> is destroyed. An application
-B<should not> free the B<x509> object.
-
-=head1 RESTRICTIONS
-
-Only one set of extra chain certificates can be specified per SSL_CTX
-structure. Different chains for different certificates (for example if both
-RSA and DSA certificates are specified by the same server) or different SSL
-structures with the same parent SSL_CTX cannot be specified using this
-function. For more flexibility functions such as SSL_add1_chain_cert() should
-be used instead.
-
-=head1 RETURN VALUES
-
-SSL_CTX_add_extra_chain_cert() and SSL_CTX_clear_extra_chain_certs() return
-1 on success and 0 for failure. Check out the error stack to find out the
-reason for failure.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_use_certificate(3)>,
-L<SSL_CTX_set_client_cert_cb(3)>,
-L<SSL_CTX_load_verify_locations(3)>
-L<SSL_CTX_set0_chain(3)>
-L<SSL_CTX_set1_chain(3)>
-L<SSL_CTX_add0_chain_cert(3)>
-L<SSL_CTX_add1_chain_cert(3)>
-L<SSL_set0_chain(3)>
-L<SSL_set1_chain(3)>
-L<SSL_add0_chain_cert(3)>
-L<SSL_add1_chain_cert(3)>
-L<SSL_CTX_build_cert_chain(3)>
-L<SSL_build_cert_chain(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);
- int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c);
-
- int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
- int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
-
-=head1 DESCRIPTION
-
-SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The
-reference count for session B<c> is incremented by 1. If a session with
-the same session id already exists, the old session is removed by calling
-L<SSL_SESSION_free(3)>.
-
-SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>.
-L<SSL_SESSION_free(3)> is called once for B<c>.
-
-SSL_add_session() and SSL_remove_session() are synonyms for their
-SSL_CTX_*() counterparts.
-
-=head1 NOTES
-
-When adding a new session to the internal session cache, it is examined
-whether a session with the same session id already exists. In this case
-it is assumed that both sessions are identical. If the same session is
-stored in a different SSL_SESSION object, The old session is
-removed and replaced by the new session. If the session is actually
-identical (the SSL_SESSION object is identical), SSL_CTX_add_session()
-is a no-op, and the return value is 0.
-
-If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE
-flag then the internal cache will not be populated automatically by new
-sessions negotiated by the SSL/TLS implementation, even though the internal
-cache will be searched automatically for session-resume requests (the
-latter can be suppressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the
-application can use SSL_CTX_add_session() directly to have full control
-over the sessions that can be resumed if desired.
-
-
-=head1 RETURN VALUES
-
-The following values are returned by all functions:
-
-=over 4
-
-=item Z<>0
-
- The operation failed. In case of the add operation, it was tried to add
- the same (identical) session twice. In case of the remove operation, the
- session was not found in the cache.
-
-=item Z<>1
-
- The operation succeeded.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_SESSION_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_config(SSL_CTX *ctx, const char *name);
- int SSL_config(SSL *s, const char *name);
-
-=head1 DESCRIPTION
-
-The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or
-B<SSL> structure using the configuration B<name>.
-
-=head1 NOTES
-
-By calling SSL_CTX_config() or SSL_config() an application can perform many
-complex tasks based on the contents of the configuration file: greatly
-simplifying application configuration code. A degree of future proofing
-can also be achieved: an application can support configuration features
-in newer versions of OpenSSL automatically.
-
-A configuration file must have been previously loaded, for example using
-CONF_modules_load_file(). See L<config(3)> for details of the configuration
-file syntax.
-
-=head1 RETURN VALUES
-
-SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
-occurred.
-
-=head1 EXAMPLE
-
-If the file "config.cnf" contains the following:
-
- testapp = test_sect
-
- [test_sect]
- # list of confuration modules
-
- ssl_conf = ssl_sect
-
- [ssl_sect]
-
- server = server_section
-
- [server_section]
-
- RSA.Certificate = server-rsa.pem
- ECDSA.Certificate = server-ecdsa.pem
- Ciphers = ALL:!RC4
-
-An application could call:
-
- if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) {
- fprintf(stderr, "Error processing config file\n");
- goto err;
- }
-
- ctx = SSL_CTX_new(TLS_server_method());
-
- if (SSL_CTX_config(ctx, "server") == 0) {
- fprintf(stderr, "Error configuring server.\n");
- goto err;
- }
-
-In this example two certificates and the cipher list are configured without
-the need for any additional application code.
-
-=head1 SEE ALSO
-
-L<config(3)>,
-L<SSL_CONF_cmd(3)>,
-L<CONF_modules_load_file(3)>
-
-=head1 HISTORY
-
-SSL_CTX_config() and SSL_config() were first added to OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal handling functions for SSL_CTX and SSL objects
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg);
- long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)());
-
- long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg);
- long SSL_callback_ctrl(SSL *, int cmd, void (*fp)());
-
-=head1 DESCRIPTION
-
-The SSL_*_ctrl() family of functions is used to manipulate settings of
-the SSL_CTX and SSL objects. Depending on the command B<cmd> the arguments
-B<larg>, B<parg>, or B<fp> are evaluated. These functions should never
-be called directly. All functionalities needed are made available via
-other functions or macros.
-
-=head1 RETURN VALUES
-
-The return values of the SSL*_ctrl() functions depend on the command
-supplied via the B<cmd> parameter.
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable,
-SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa
-SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags,
-SSL_dane_set_flags, SSL_dane_clear_flags -
-enable DANE TLS authentication of the remote TLS server in the local
-TLS client
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_dane_enable(SSL_CTX *ctx);
- int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md,
- uint8_t mtype, uint8_t ord);
- int SSL_dane_enable(SSL *s, const char *basedomain);
- int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector,
- uint8_t mtype, unsigned char *data, size_t dlen);
- int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki);
- int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector,
- uint8_t *mtype, unsigned const char **data,
- size_t *dlen);
- unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags);
- unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags);
- unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags);
- unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags);
-
-=head1 DESCRIPTION
-
-These functions implement support for DANE TLSA (RFC6698 and RFC7671)
-peer authentication.
-
-SSL_CTX_dane_enable() must be called first to initialize the shared state
-required for DANE support.
-Individual connections associated with the context can then enable
-per-connection DANE support as appropriate.
-DANE authentication is implemented in the L<X509_verify_cert(3)> function, and
-applications that override L<X509_verify_cert(3)> via
-L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer
-chain in whatever manner they see fit.
-
-SSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the
-supported digest algorithms.
-This must be done before any SSL handles are created for the context.
-
-The B<mtype> argument specifies a DANE TLSA matching type and the B<md>
-argument specifies the associated digest algorithm handle.
-The B<ord> argument specifies a strength ordinal.
-Algorithms with a larger strength ordinal are considered more secure.
-Strength ordinals are used to implement RFC7671 digest algorithm agility.
-Specifying a B<NULL> digest algorithm for a matching type disables
-support for that matching type.
-Matching type Full(0) cannot be modified or disabled.
-
-By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions
-of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()>
-with a strength ordinal of C<1> and matching type C<SHA2-512(2)>
-is mapped to C<EVP_sha512()> with a strength ordinal of C<2>.
-
-SSL_dane_enable() must be called before the SSL handshake is initiated with
-L<SSL_connect(3)> if (and only if) you want to enable DANE for that connection.
-(The connection must be associated with a DANE-enabled SSL context).
-The B<basedomain> argument specifies the RFC7671 TLSA base domain,
-which will be the primary peer reference identifier for certificate
-name checks.
-Additional server names can be specified via L<SSL_add1_host(3)>.
-The B<basedomain> is used as the default SNI hint if none has yet been
-specified via L<SSL_set_tlsext_host_name(3)>.
-
-SSL_dane_tlsa_add() may then be called one or more times, to load each of the
-TLSA records that apply to the remote TLS peer.
-(This too must be done prior to the beginning of the SSL handshake).
-The arguments specify the fields of the TLSA record.
-The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal
-ASCII presentation form, with an explicit length passed via B<dlen>.
-A return value of 0 indicates that "unusable" TLSA records (with invalid or
-unsupported parameters) were provided.
-A negative return value indicates an internal error in processing the record.
-
-The caller is expected to check the return value of each SSL_dane_tlsa_add()
-call and take appropriate action if none are usable or an internal error
-is encountered in processing some records.
-
-If no TLSA records are added successfully, DANE authentication is not enabled,
-and authentication will be based on any configured traditional trust-anchors;
-authentication success in this case does not mean that the peer was
-DANE-authenticated.
-
-SSL_get0_dane_authority() can be used to get more detailed information about
-the matched DANE trust-anchor after successful connection completion.
-The return value is negative if DANE verification failed (or was not enabled),
-0 if an EE TLSA record directly matched the leaf certificate, or a positive
-number indicating the depth at which a TA record matched an issuer certificate.
-The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>.
-The return value is an index into this verified chain, rather than the list of
-certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>.
-
-If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain
-certificate, a pointer to the matching certificate is returned via B<mcert>.
-The returned address is a short-term internal reference to the certificate and
-must not be freed by the application.
-Applications that want to retain access to the certificate can call
-L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via
-L<X509_free(3)> once no longer needed.
-
-If no TLSA records directly matched any elements of the certificate chain, but
-a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an
-element of the chain, then that key is returned via B<mspki> argument (if not
-NULL).
-In this case the return value is the depth of the top-most element of the
-validated certificate chain.
-As with B<mcert> this is a short-term internal reference, and
-L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and
-release long-term references respectively.
-
-SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that
-matched the peer certificate chain.
-The return value indicates the match depth or failure to match just as with
-SSL_get0_dane_authority().
-When the return value is non-negative, the storage pointed to by the B<usage>,
-B<selector>, B<mtype> and B<data> parameters is updated to the corresponding
-TLSA record fields.
-The B<data> field is in binary wire form, and is therefore not NUL-terminated,
-its length is returned via the B<dlen> parameter.
-If any of these parameters is NULL, the corresponding field is not returned.
-The B<data> parameter is set to a short-term internal-copy of the associated
-data field and must not be freed by the application.
-Applications that need long-term access to this field need to copy the content.
-
-SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable
-optional DANE verification features.
-SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable
-the same features.
-The B<flags> argument is a bitmask of the features to enable or disable.
-The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle
-associated with that context at the time the handle is created.
-Subsequent changes in the context's B<flags> have no effect on the B<flags> set
-for the handle.
-
-At present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS>
-which can be used to disable server name checks when authenticating via
-DANE-EE(3) TLSA records.
-For some applications, primarily web browsers, it is not safe to disable name
-checks due to "unknown key share" attacks, in which a malicious server can
-convince a client that a connection to a victim server is instead a secure
-connection to the malicious server.
-The malicious server may then be able to violate cross-origin scripting
-restrictions.
-Thus, despite the text of RFC7671, name checks are by default enabled for
-DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
-to do so.
-In particular, SMTP and XMPP clients should set this option as SRV and MX
-records already make it possible for a remote domain to redirect client
-connections to any server of its choice, and in any case SMTP and XMPP clients
-do not execute scripts downloaded from remote servers.
-
-=head1 RETURN VALUES
-
-The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(),
-SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success.
-Negative return values indicate resource problems (out of memory, etc.) in the
-SSL library, while a return value of B<0> indicates incorrect usage or invalid
-input, such as an unsupported TLSA record certificate usage, selector or
-matching type.
-Invalid input also includes malformed data, either a digest length that does
-not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form)
-certificate or a public key that fails to parse.
-
-The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a
-negative value when DANE authentication failed or was not enabled, a
-non-negative value indicates the chain depth at which the TLSA record matched a
-chain certificate, or the depth of the top-most certificate, when the TLSA
-record is a full public key that is its signer.
-
-The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(),
-SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect
-before they were called.
-
-=head1 EXAMPLE
-
-Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
-DNSSEC-validated TLSA records.
-The calls below will perform DANE authentication and arrange to match either
-the MX hostname or the destination domain name in the SMTP server certificate.
-Wildcards are supported, but must match the entire label.
-The actual name matched in the certificate (which might be a wildcard) is
-retrieved, and must be copied by the application if it is to be retained beyond
-the lifetime of the SSL connection.
-
- SSL_CTX *ctx;
- SSL *ssl;
- int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL;
- int num_usable = 0;
- const char *nexthop_domain = "example.com";
- const char *dane_tlsa_domain = "smtp.example.com";
- uint8_t usage, selector, mtype;
-
- if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL)
- /* handle error */
- if (SSL_CTX_dane_enable(ctx) <= 0)
- /* handle error */
-
- if ((ssl = SSL_new(ctx)) == NULL)
- /* handle error */
-
- if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0)
- /* handle error */
-
- /*
- * For many applications it is safe to skip DANE-EE(3) namechecks. Do not
- * disable the checks unless "unknown key share" attacks pose no risk for
- * your application.
- */
- SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS);
-
- if (!SSL_add1_host(ssl, nexthop_domain))
- /* handle error */
- SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
-
- for (... each TLSA record ...) {
- unsigned char *data;
- size_t len;
- int ret;
-
- /* set usage, selector, mtype, data, len */
-
- /*
- * Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3).
- * They treat all other certificate usages, and in particular PKIX-TA(0)
- * and PKIX-EE(1), as unusable.
- */
- switch (usage) {
- default:
- case 0: /* PKIX-TA(0) */
- case 1: /* PKIX-EE(1) */
- continue;
- case 2: /* DANE-TA(2) */
- case 3: /* DANE-EE(3) */
- break;
- }
-
- ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len);
- /* free data as appropriate */
-
- if (ret < 0)
- /* handle SSL library internal error */
- else if (ret == 0)
- /* handle unusable TLSA record */
- else
- ++num_usable;
- }
-
- /*
- * At this point, the verification mode is still the default SSL_VERIFY_NONE.
- * Opportunistic DANE clients use unauthenticated TLS when all TLSA records
- * are unusable, so continue the handshake even if authentication fails.
- */
- if (num_usable == 0) {
- /* Log all records unusable? */
-
- /* Optionally set verify_cb to a suitable non-NULL callback. */
- SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb);
- } else {
- /* At least one usable record. We expect to verify the peer */
-
- /* Optionally set verify_cb to a suitable non-NULL callback. */
-
- /*
- * Below we elect to fail the handshake when peer verification fails.
- * Alternatively, use the permissive SSL_VERIFY_NONE verification mode,
- * complete the handshake, check the verification status, and if not
- * verified disconnect gracefully at the application layer, especially if
- * application protocol supports informing the server that authentication
- * failed.
- */
- SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb);
- }
-
- /*
- * Load any saved session for resumption, making sure that the previous
- * session applied the same security and authentication requirements that
- * would be expected of a fresh connection.
- */
-
- /* Perform SSL_connect() handshake and handle errors here */
-
- if (SSL_session_reused(ssl)) {
- if (SSL_get_verify_result(ssl) == X509_V_OK) {
- /*
- * Resumed session was originally verified, this connection is
- * authenticated.
- */
- } else {
- /*
- * Resumed session was not originally verified, this connection is not
- * authenticated.
- */
- }
- } else if (SSL_get_verify_result(ssl) == X509_V_OK) {
- const char *peername = SSL_get0_peername(ssl);
- EVP_PKEY *mspki = NULL;
-
- int depth = SSL_get0_dane_authority(ssl, NULL, &mspki);
- if (depth >= 0) {
- (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL);
- printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype,
- (mspki != NULL) ? "TA public key verified certificate" :
- depth ? "matched TA certificate" : "matched EE certificate",
- depth);
- }
- if (peername != NULL) {
- /* Name checks were in scope and matched the peername */
- printf("Verified peername: %s\n", peername);
- }
- } else {
- /*
- * Not authenticated, presumably all TLSA rrs unusable, but possibly a
- * callback suppressed connection termination despite the presence of
- * usable TLSA RRs none of which matched. Do whatever is appropriate for
- * fresh unauthenticated connections.
- */
- }
-
-=head1 NOTES
-
-It is expected that the majority of clients employing DANE TLS will be doing
-"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435.
-That is, they will use DANE authentication when DNSSEC-validated TLSA records
-are published for a given peer, and otherwise will use unauthenticated TLS or
-even cleartext.
-
-Such applications should generally treat any TLSA records published by the peer
-with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include
-them among the TLSA records used to authenticate peer connections.
-In addition, some TLSA records with supported usages may be "unusable" as a
-result of invalid or unsupported parameters.
-
-When a peer has TLSA records, but none are "usable", an opportunistic
-application must avoid cleartext, but cannot authenticate the peer,
-and so should generally proceed with an unauthenticated connection.
-Opportunistic applications need to note the return value of each
-call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid
-or unsupported parameters) disable peer authentication by calling
-L<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>.
-
-=head1 SEE ALSO
-
-L<SSL_new(3)>,
-L<SSL_add1_host(3)>,
-L<SSL_set_hostflags(3)>,
-L<SSL_set_tlsext_host_name(3)>,
-L<SSL_set_verify(3)>,
-L<SSL_CTX_set_cert_verify_callback(3)>,
-L<SSL_get0_verified_chain(3)>,
-L<SSL_get_peer_cert_chain(3)>,
-L<SSL_get_verify_result(3)>,
-L<SSL_connect(3)>,
-L<SSL_get0_peername(3)>,
-L<X509_verify_cert(3)>,
-L<X509_up_ref(3)>,
-L<X509_free(3)>,
-L<EVP_get_digestbyname(3)>,
-L<EVP_PKEY_up_ref(3)>,
-L<EVP_PKEY_free(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm);
- void SSL_flush_sessions(SSL_CTX *ctx, long tm);
-
-=head1 DESCRIPTION
-
-SSL_CTX_flush_sessions() causes a run through the session cache of
-B<ctx> to remove sessions expired at time B<tm>.
-
-SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions().
-
-=head1 NOTES
-
-If enabled, the internal session cache will collect all sessions established
-up to the specified maximum number (see SSL_CTX_sess_set_cache_size()).
-As sessions will not be reused ones they are expired, they should be
-removed from the cache to save resources. This can either be done
- automatically whenever 255 new sessions were established (see
-L<SSL_CTX_set_session_cache_mode(3)>)
-or manually by calling SSL_CTX_flush_sessions().
-
-The parameter B<tm> specifies the time which should be used for the
-expiration test, in most cases the actual time given by time(0)
-will be used.
-
-SSL_CTX_flush_sessions() will only check sessions stored in the internal
-cache. When a session is found and removed, the remove_session_cb is however
-called to synchronize with the external cache (see
-L<SSL_CTX_sess_set_get_cb(3)>).
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_CTX_set_timeout(3)>,
-L<SSL_CTX_sess_set_get_cb(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_free - free an allocated SSL_CTX object
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_free(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_free() decrements the reference count of B<ctx>, and removes the
-SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the reference count has reached 0.
-
-It also calls the free()ing procedures for indirectly affected items, if
-applicable: the session cache, the list of ciphers, the list of Client CAs,
-the certificates and keys.
-
-If B<ctx> is NULL nothing is done.
-
-=head1 WARNINGS
-
-If a session-remove callback is set (SSL_CTX_sess_set_remove_cb()), this
-callback will be called for each session being freed from B<ctx>'s
-session cache. This implies, that all corresponding sessions from an
-external session cache are removed as well. If this is not desired, the user
-should explicitly unset the callback by calling
-SSL_CTX_sess_set_remove_cb(B<ctx>, NULL) prior to calling SSL_CTX_free().
-
-=head1 RETURN VALUES
-
-SSL_CTX_free() does not provide diagnostic information.
-
-=head1 SEE ALSO
-
-L<SSL_CTX_new(3)>, L<ssl(3)>,
-L<SSL_CTX_sess_set_get_cb(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param -
-get and set verification parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx)
- X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl)
- int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm)
- int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm)
-
-=head1 DESCRIPTION
-
-SSL_CTX_get0_param() and SSL_get0_param() retrieve an internal pointer to
-the verification parameters for B<ctx> or B<ssl> respectively. The returned
-pointer must not be freed by the calling application.
-
-SSL_CTX_set1_param() and SSL_set1_param() set the verification parameters
-to B<vpm> for B<ctx> or B<ssl>.
-
-=head1 NOTES
-
-Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure
-using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
-them to suit its needs: for example to add a hostname check.
-
-=head1 EXAMPLE
-
-Check hostname matches "www.foo.com" in peer certificate:
-
- X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
- X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
-
-=head1 RETURN VALUES
-
-SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
-B<X509_VERIFY_PARAM> structure.
-
-SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
-for failure.
-
-=head1 SEE ALSO
-
-L<X509_VERIFY_PARAM_set_flags(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_get_verify_mode(const SSL_CTX *ctx);
- int SSL_get_verify_mode(const SSL *ssl);
- int SSL_CTX_get_verify_depth(const SSL_CTX *ctx);
- int SSL_get_verify_depth(const SSL *ssl);
- int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *);
- int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *);
-
-=head1 DESCRIPTION
-
-SSL_CTX_get_verify_mode() returns the verification mode currently set in
-B<ctx>.
-
-SSL_get_verify_mode() returns the verification mode currently set in
-B<ssl>.
-
-SSL_CTX_get_verify_depth() returns the verification depth limit currently set
-in B<ctx>. If no limit has been explicitly set, -1 is returned and the
-default value will be used.
-
-SSL_get_verify_depth() returns the verification depth limit currently set
-in B<ssl>. If no limit has been explicitly set, -1 is returned and the
-default value will be used.
-
-SSL_CTX_get_verify_callback() returns a function pointer to the verification
-callback currently set in B<ctx>. If no callback was explicitly set, the
-NULL pointer is returned and the default callback will be used.
-
-SSL_get_verify_callback() returns a function pointer to the verification
-callback currently set in B<ssl>. If no callback was explicitly set, the
-NULL pointer is returned and the default callback will be used.
-
-=head1 RETURN VALUES
-
-See DESCRIPTION
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_set_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular
-client extension type
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type);
-
-=head1 DESCRIPTION
-
-SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a
-client extension of type B<ext_type> using SSL_CTX_add_client_custom_ext().
-
-=head1 RETURN VALUES
-
-Returns 1 if a handler has been set, 0 otherwise.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_add_client_custom_ext(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_load_verify_locations, SSL_CTX_set_default_verify_paths,
-SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file - set
-default locations for trusted CA certificates
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
- const char *CApath);
-
- int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
-
- int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx);
-
- int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at
-which CA certificates for verification purposes are located. The certificates
-available via B<CAfile> and B<CApath> are trusted.
-
-SSL_CTX_set_default_verify_paths() specifies that the default locations from
-which CA certificates are loaded should be used. There is one default directory
-and one default file. The default CA certificates directory is called "certs" in
-the default OpenSSL directory. Alternatively the SSL_CERT_DIR environment
-variable can be defined to override this location. The default CA certificates
-file is called "cert.pem" in the default OpenSSL directory. Alternatively the
-SSL_CERT_FILE environment variable can be defined to override this location.
-
-SSL_CTX_set_default_verify_dir() is similar to
-SSL_CTX_set_default_verify_paths() except that just the default directory is
-used.
-
-SSL_CTX_set_default_verify_file() is similar to
-SSL_CTX_set_default_verify_paths() except that just the default file is
-used.
-
-=head1 NOTES
-
-If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
-format. The file can contain several CA certificates identified by
-
- -----BEGIN CERTIFICATE-----
- ... (CA certificate in base64 encoding) ...
- -----END CERTIFICATE-----
-
-sequences. Before, between, and after the certificates text is allowed
-which can be used e.g. for descriptions of the certificates.
-
-The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()
-function.
-
-If B<CApath> is not NULL, it points to a directory containing CA certificates
-in PEM format. The files each contain one CA certificate. The files are
-looked up by the CA subject name hash value, which must hence be available.
-If more than one CA certificate with the same name hash value exist, the
-extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
-is performed in the ordering of the extension number, regardless of other
-properties of the certificates.
-Use the B<c_rehash> utility to create the necessary links.
-
-The certificates in B<CApath> are only looked up when required, e.g. when
-building the certificate chain or when actually performing the verification
-of a peer certificate.
-
-When looking up CA certificates, the OpenSSL library will first search the
-certificates in B<CAfile>, then those in B<CApath>. Certificate matching
-is done based on the subject name, the key identifier (if present), and the
-serial number as taken from the certificate to be verified. If these data
-do not match, the next certificate will be tried. If a first certificate
-matching the parameters is found, the verification process will be performed;
-no other certificates for the same parameters will be searched in case of
-failure.
-
-In server mode, when requesting a client certificate, the server must send
-the list of CAs of which it will accept client certificates. This list
-is not influenced by the contents of B<CAfile> or B<CApath> and must
-explicitly be set using the
-L<SSL_CTX_set_client_CA_list(3)>
-family of functions.
-
-When building its own certificate chain, an OpenSSL client/server will
-try to fill in missing certificates from B<CAfile>/B<CApath>, if the
-certificate chain was not explicitly specified (see
-L<SSL_CTX_add_extra_chain_cert(3)>,
-L<SSL_CTX_use_certificate(3)>.
-
-=head1 WARNINGS
-
-If several CA certificates matching the name, key identifier, and serial
-number condition are available, only the first one will be examined. This
-may lead to unexpected results if the same CA certificate is available
-with different expiration dates. If a "certificate expired" verification
-error occurs, no other certificate will be searched. Make sure to not
-have expired certificates mixed with valid ones.
-
-=head1 EXAMPLES
-
-Generate a CA certificate file with descriptive text from the CA certificates
-ca1.pem ca2.pem ca3.pem:
-
- #!/bin/sh
- rm CAfile.pem
- for i in ca1.pem ca2.pem ca3.pem ; do
- openssl x509 -in $i -text >> CAfile.pem
- done
-
-Prepare the directory /some/where/certs containing several CA certificates
-for use as B<CApath>:
-
- cd /some/where/certs
- c_rehash .
-
-=head1 RETURN VALUES
-
-For SSL_CTX_load_verify_locations the following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The operation failed because B<CAfile> and B<CApath> are NULL or the
-processing at one of the locations specified failed. Check the error
-stack to find out the reason.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
-SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
-missing default location is still treated as a success.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_client_CA_list(3)>,
-L<SSL_get_client_CA_list(3)>,
-L<SSL_CTX_use_certificate(3)>,
-L<SSL_CTX_add_extra_chain_cert(3)>,
-L<SSL_CTX_set_cert_store(3)>,
-L<SSL_CTX_set_client_CA_list(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method,
-SSL_CTX_new, SSL_CTX_up_ref, SSLv3_method, SSLv3_server_method,
-SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method,
-TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method,
-TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method,
-SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method,
-DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method,
-DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method
-- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled
-functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
- int SSL_CTX_up_ref(SSL_CTX *ctx);
-
- const SSL_METHOD *TLS_method(void);
- const SSL_METHOD *TLS_server_method(void);
- const SSL_METHOD *TLS_client_method(void);
-
- const SSL_METHOD *SSLv23_method(void);
- const SSL_METHOD *SSLv23_server_method(void);
- const SSL_METHOD *SSLv23_client_method(void);
-
- #ifndef OPENSSL_NO_SSL3_METHOD
- const SSL_METHOD *SSLv3_method(void);
- const SSL_METHOD *SSLv3_server_method(void);
- const SSL_METHOD *SSLv3_client_method(void);
- #endif
-
- #ifndef OPENSSL_NO_TLS1_METHOD
- const SSL_METHOD *TLSv1_method(void);
- const SSL_METHOD *TLSv1_server_method(void);
- const SSL_METHOD *TLSv1_client_method(void);
- #endif
-
- #ifndef OPENSSL_NO_TLS1_1_METHOD
- const SSL_METHOD *TLSv1_1_method(void);
- const SSL_METHOD *TLSv1_1_server_method(void);
- const SSL_METHOD *TLSv1_1_client_method(void);
- #endif
-
- #ifndef OPENSSL_NO_TLS1_2_METHOD
- const SSL_METHOD *TLSv1_2_method(void);
- const SSL_METHOD *TLSv1_2_server_method(void);
- const SSL_METHOD *TLSv1_2_client_method(void);
- #endif
-
- const SSL_METHOD *DTLS_method(void);
- const SSL_METHOD *DTLS_server_method(void);
- const SSL_METHOD *DTLS_client_method(void);
-
- #ifndef OPENSSL_NO_DTLS1_METHOD
- const SSL_METHOD *DTLSv1_method(void);
- const SSL_METHOD *DTLSv1_server_method(void);
- const SSL_METHOD *DTLSv1_client_method(void);
- #endif
-
- #ifndef OPENSSL_NO_DTLS1_2_METHOD
- const SSL_METHOD *DTLSv1_2_method(void);
- const SSL_METHOD *DTLSv1_2_server_method(void);
- const SSL_METHOD *DTLSv1_2_client_method(void);
- #endif
-
-=head1 DESCRIPTION
-
-SSL_CTX_new() creates a new B<SSL_CTX> object as framework to
-establish TLS/SSL or DTLS enabled connections. An B<SSL_CTX> object is
-reference counted. Creating an B<SSL_CTX> object for the first time increments
-the reference count. Freeing it (using SSL_CTX_free) decrements it. When the
-reference count drops to zero, any memory or resources allocated to the
-B<SSL_CTX> object are freed. SSL_CTX_up_ref() increments the reference count for
-an existing B<SSL_CTX> structure.
-
-=head1 NOTES
-
-The SSL_CTX object uses B<method> as connection method.
-The methods exist in a generic type (for client and server use), a server only
-type, and a client only type.
-B<method> can be of the following types:
-
-=over 4
-
-=item TLS_method(), TLS_server_method(), TLS_client_method()
-
-These are the general-purpose I<version-flexible> SSL/TLS methods.
-The actual protocol version used will be negotiated to the highest version
-mutually supported by the client and the server.
-The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2.
-Applications should use these methods, and avoid the version-specific
-methods described below.
-
-=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
-
-Use of these functions is deprecated. They have been replaced with the above
-TLS_method(), TLS_server_method() and TLS_client_method() respectively. New
-code should use those functions instead.
-
-=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
-
-A TLS/SSL connection established with these methods will only understand the
-TLSv1.2 protocol.
-
-=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
-
-A TLS/SSL connection established with these methods will only understand the
-TLSv1.1 protocol.
-
-=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
-
-A TLS/SSL connection established with these methods will only understand the
-TLSv1 protocol.
-
-=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
-
-A TLS/SSL connection established with these methods will only understand the
-SSLv3 protocol.
-The SSLv3 protocol is deprecated and should not be used.
-
-=item DTLS_method(), DTLS_server_method(), DTLS_client_method()
-
-These are the version-flexible DTLS methods.
-Currently supported protocols are DTLS 1.0 and DTLS 1.2.
-
-=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
-
-These are the version-specific methods for DTLSv1.2.
-
-=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
-
-These are the version-specific methods for DTLSv1.
-
-=back
-
-SSL_CTX_new() initializes the list of ciphers, the session cache setting, the
-callbacks, the keys and certificates and the options to their default values.
-
-TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(),
-DTLS_server_method() and DTLS_client_method() are the I<version-flexible>
-methods.
-All other methods only support one specific protocol version.
-Use the I<version-flexible> methods instead of the version specific methods.
-
-If you want to limit the supported protocols for the version flexible
-methods you can use L<SSL_CTX_set_min_proto_version(3)>,
-L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and
-LSSL_set_max_proto_version(3)> functions.
-Using these functions it is possible to choose e.g. TLS_server_method()
-and be able to negotiate with all possible clients, but to only
-allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2.
-
-The list of protocols available can also be limited using the
-B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and
-B<SSL_OP_NO_TLSv1_2> options of the L<SSL_CTX_set_options(3)> or
-L<SSL_set_options(3)> functions, but this approach is not recommended.
-Clients should avoid creating "holes" in the set of protocols they support.
-When disabling a protocol, make sure that you also disable either all previous
-or all subsequent protocol versions.
-In clients, when a protocol version is disabled without disabling I<all>
-previous protocol versions, the effect is to also disable all subsequent
-protocol versions.
-
-The SSLv3 protocol is deprecated and should generally not be used.
-Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set
-the minimum protocol to at least B<TLS1_VERSION>.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item NULL
-
-The creation of a new SSL_CTX object failed. Check the error stack to find out
-the reason.
-
-=item Pointer to an SSL_CTX object
-
-The return value points to an allocated SSL_CTX object.
-
-SSL_CTX_up_ref() returns 1 for success and 0 for failure.
-
-=back
-
-=head1 HISTORY
-
-Support for SSLv2 and the corresponding SSLv2_method(),
-SSLv2_server_method() and SSLv2_client_method() functions where
-removed in OpenSSL 1.1.0.
-
-SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
-were deprecated and the preferred TLS_method(), TLS_server_method()
-and TLS_client_method() functions were introduced in OpenSSL 1.1.0.
-
-All version-specific methods were deprecated in OpenSSL 1.1.0.
-
-=head1 SEE ALSO
-
-L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
-L<SSL_CTX_set_min_proto_version(3)>, L<ssl(3)>, L<SSL_set_connect_state(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_sess_number(SSL_CTX *ctx);
- long SSL_CTX_sess_connect(SSL_CTX *ctx);
- long SSL_CTX_sess_connect_good(SSL_CTX *ctx);
- long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx);
- long SSL_CTX_sess_accept(SSL_CTX *ctx);
- long SSL_CTX_sess_accept_good(SSL_CTX *ctx);
- long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx);
- long SSL_CTX_sess_hits(SSL_CTX *ctx);
- long SSL_CTX_sess_cb_hits(SSL_CTX *ctx);
- long SSL_CTX_sess_misses(SSL_CTX *ctx);
- long SSL_CTX_sess_timeouts(SSL_CTX *ctx);
- long SSL_CTX_sess_cache_full(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_sess_number() returns the current number of sessions in the internal
-session cache.
-
-SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in
-client mode.
-
-SSL_CTX_sess_connect_good() returns the number of successfully established
-SSL/TLS sessions in client mode.
-
-SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations
-in client mode.
-
-SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in
-server mode.
-
-SSL_CTX_sess_accept_good() returns the number of successfully established
-SSL/TLS sessions in server mode.
-
-SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations
-in server mode.
-
-SSL_CTX_sess_hits() returns the number of successfully reused sessions.
-In client mode a session set with L<SSL_set_session(3)>
-successfully reused is counted as a hit. In server mode a session successfully
-retrieved from internal or external cache is counted as a hit.
-
-SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions
-from the external session cache in server mode.
-
-SSL_CTX_sess_misses() returns the number of sessions proposed by clients
-that were not found in the internal session cache in server mode.
-
-SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients
-and either found in the internal or external session cache in server mode,
- but that were invalid due to timeout. These sessions are not included in
-the SSL_CTX_sess_hits() count.
-
-SSL_CTX_sess_cache_full() returns the number of sessions that were removed
-because the maximum session cache size was exceeded.
-
-=head1 RETURN VALUES
-
-The functions return the values indicated in the DESCRIPTION section.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_set_session(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>
-L<SSL_CTX_sess_set_cache_size(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t);
- long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_sess_set_cache_size() sets the size of the internal session cache
-of context B<ctx> to B<t>.
-This value is a hint and not an absolute; see the notes below.
-
-SSL_CTX_sess_get_cache_size() returns the currently valid session cache size.
-
-=head1 NOTES
-
-The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT,
-currently 1024*20, so that up to 20000 sessions can be held. This size
-can be modified using the SSL_CTX_sess_set_cache_size() call. A special
-case is the size 0, which is used for unlimited size.
-
-If adding the session makes the cache exceed its size, then unused
-sessions are dropped from the end of the cache.
-Cache space may also be reclaimed by calling
-L<SSL_CTX_flush_sessions(3)> to remove
-expired sessions.
-
-If the size of the session cache is reduced and more sessions are already
-in the session cache, old session will be removed at the next time a
-session shall be added. This removal is not synchronized with the
-expiration of sessions.
-
-=head1 RETURN VALUES
-
-SSL_CTX_sess_set_cache_size() returns the previously valid size.
-
-SSL_CTX_sess_get_cache_size() returns the currently valid size.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_CTX_sess_number(3)>,
-L<SSL_CTX_flush_sessions(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
- int (*new_session_cb)(SSL *, SSL_SESSION *));
- void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
- void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
- void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
- SSL_SESSION (*get_session_cb)(SSL *, const unsigned char *, int, int *));
-
- int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
- void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
- SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, const unsigned char *data, int len, int *copy);
-
- int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
- void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
- SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
- int len, int *copy);
-
-=head1 DESCRIPTION
-
-SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
-called whenever a new session was negotiated.
-
-SSL_CTX_sess_set_remove_cb() sets the callback function, which is
-automatically called whenever a session is removed by the SSL engine,
-because it is considered faulty or the session has become obsolete because
-of exceeding the timeout value.
-
-SSL_CTX_sess_set_get_cb() sets the callback function which is called,
-whenever a SSL/TLS client proposed to resume a session but the session
-could not be found in the internal session cache (see
-L<SSL_CTX_set_session_cache_mode(3)>).
-(SSL/TLS server only.)
-
-SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
-SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the
-provided callback functions. If a callback function has not been set,
-the NULL pointer is returned.
-
-=head1 NOTES
-
-In order to allow external session caching, synchronization with the internal
-session cache is realized via callback functions. Inside these callback
-functions, session can be saved to disk or put into a database using the
-L<d2i_SSL_SESSION(3)> interface.
-
-The new_session_cb() is called, whenever a new session has been negotiated
-and session caching is enabled (see
-L<SSL_CTX_set_session_cache_mode(3)>).
-The new_session_cb() is passed the B<ssl> connection and the ssl session
-B<sess>. If the callback returns B<0>, the session will be immediately
-removed again.
-
-The remove_session_cb() is called, whenever the SSL engine removes a session
-from the internal cache. This happens when the session is removed because
-it is expired or when a connection was not shutdown cleanly. It also happens
-for all sessions in the internal session cache when
-L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed
-the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
-
-The get_session_cb() is only called on SSL/TLS servers with the session id
-proposed by the client. The get_session_cb() is always called, also when
-session caching was disabled. The get_session_cb() is passed the
-B<ssl> connection, the session id of length B<length> at the memory location
-B<data>. With the parameter B<copy> the callback can require the
-SSL engine to increment the reference count of the SSL_SESSION object,
-Normally the reference count is not incremented and therefore the
-session must not be explicitly freed with
-L<SSL_SESSION_free(3)>.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<d2i_SSL_SESSION(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_CTX_flush_sessions(3)>,
-L<SSL_SESSION_free(3)>,
-L<SSL_CTX_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_sessions - access internal session cache
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_sessions() returns a pointer to the lhash databases containing the
-internal session cache for B<ctx>.
-
-=head1 NOTES
-
-The sessions in the internal session cache are kept in an
-L<lhash(3)> type database. It is possible to directly
-access this database e.g. for searching. In parallel, the sessions
-form a linked list which is maintained separately from the
-L<lhash(3)> operations, so that the database must not be
-modified directly but by using the
-L<SSL_CTX_add_session(3)> family of functions.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<lhash(3)>,
-L<SSL_CTX_add_session(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves,
-SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve - EC supported curve functions
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen);
- int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list);
-
- int SSL_set1_curves(SSL *ssl, int *clist, int clistlen);
- int SSL_set1_curves_list(SSL *ssl, char *list);
-
- int SSL_get1_curves(SSL *ssl, int *curves);
- int SSL_get_shared_curve(SSL *s, int n);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set1_curves() sets the supported curves for B<ctx> to B<clistlen>
-curves in the array B<clist>. The array consist of all NIDs of curves in
-preference order. For a TLS client the curves are used directly in the
-supported curves extension. For a TLS server the curves are used to
-determine the set of shared curves.
-
-SSL_CTX_set1_curves_list() sets the supported curves for B<ctx> to
-string B<list>. The string is a colon separated list of curve NIDs or
-names, for example "P-521:P-384:P-256".
-
-SSL_set1_curves() and SSL_set1_curves_list() are similar except they set
-supported curves for the SSL structure B<ssl>.
-
-SSL_get1_curves() returns the set of supported curves sent by a client
-in the supported curves extension. It returns the total number of
-supported curves. The B<curves> parameter can be B<NULL> to simply
-return the number of curves for memory allocation purposes. The
-B<curves> array is in the form of a set of curve NIDs in preference
-order. It can return zero if the client did not send a supported curves
-extension.
-
-SSL_get_shared_curve() returns shared curve B<n> for a server-side
-SSL B<ssl>. If B<n> is -1 then the total number of shared curves is
-returned, which may be zero. Other than for diagnostic purposes,
-most applications will only be interested in the first shared curve
-so B<n> is normally set to zero. If the value B<n> is out of range,
-NID_undef is returned.
-
-All these functions are implemented as macros.
-
-=head1 NOTES
-
-If an application wishes to make use of several of these functions for
-configuration purposes either on a command line or in a file it should
-consider using the SSL_CONF interface instead of manually parsing options.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves() and
-SSL_set1_curves_list(), return 1 for success and 0 for failure.
-
-SSL_get1_curves() returns the number of curves, which may be zero.
-
-SSL_get_shared_curve() returns the NID of shared curve B<n> or NID_undef if there
-is no shared curve B<n>; or the total number of shared curves if B<n>
-is -1.
-
-When called on a client B<ssl>, SSL_get_shared_curve() has no meaning and
-returns -1.
-
-=head1 SEE ALSO
-
-L<SSL_CTX_add_extra_chain_cert(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2.
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list,
-SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs,
-SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list,
-SSL_set1_client_sigalgs_list - set supported signature algorithms
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen);
- long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen);
- long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str);
- long SSL_set1_sigalgs_list(SSL *ssl, const char *str);
-
- long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen);
- long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen);
- long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str);
- long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set1_sigalgs() and SSL_set1_sigalgs() set the supported signature
-algorithms for B<ctx> or B<ssl>. The array B<slist> of length B<slistlen>
-must consist of pairs of NIDs corresponding to digest and public key
-algorithms.
-
-SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported
-signature algorithms for B<ctx> or B<ssl>. The B<str> parameter
-must be a null terminated string consisting or a colon separated list of
-public key algorithms and digests separated by B<+>.
-
-SSL_CTX_set1_client_sigalgs(), SSL_set1_client_sigalgs(),
-SSL_CTX_set1_client_sigalgs_list() and SSL_set1_client_sigalgs_list() set
-signature algorithms related to client authentication, otherwise they are
-identical to SSL_CTX_set1_sigalgs(), SSL_set1_sigalgs(),
-SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list().
-
-All these functions are implemented as macros. The signature algorithm
-parameter (integer array or string) is not freed: the application should
-free it, if necessary.
-
-=head1 NOTES
-
-If an application wishes to allow the setting of signature algorithms
-as one of many user configurable options it should consider using the more
-flexible SSL_CONF API instead.
-
-The signature algorithms set by a client are used directly in the supported
-signature algorithm in the client hello message.
-
-The supported signature algorithms set by a server are not sent to the
-client but are used to determine the set of shared signature algorithms
-and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE)
-their order.
-
-The client authentication signature algorithms set by a server are sent
-in a certificate request message if client authentication is enabled,
-otherwise they are unused.
-
-Similarly client authentication signature algorithms set by a client are
-used to determined the set of client authentication shared signature
-algorithms.
-
-Signature algorithms will neither be advertised nor used if the security level
-prohibits them (for example SHA1 if the security level is 4 or more).
-
-Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and
-NID_sha512 digest NIDs are supported and the public key algorithm NIDs
-EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC.
-
-The short or long name values for digests can be used in a string (for
-example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and
-the public key algorithm strings "RSA", "DSA" or "ECDSA".
-
-The use of MD5 as a digest is strongly discouraged due to security weaknesses.
-
-=head1 EXAMPLES
-
-Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
-using an array:
-
- const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA};
-
- SSL_CTX_set1_sigalgs(ctx, slist, 4);
-
-Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
-using a string:
-
- SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256");
-
-=head1 RETURN VALUES
-
-All these functions return 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_shared_sigalgs(3)>,
-L<SSL_CONF_CTX_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store,
-SSL_CTX_set0_chain_cert_store, SSL_CTX_set1_chain_cert_store,
-SSL_set0_verify_cert_store, SSL_set1_verify_cert_store,
-SSL_set0_chain_cert_store, SSL_set1_chain_cert_store - set certificate
-verification or chain store
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st);
- int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st);
- int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st);
- int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st);
-
- int SSL_set0_verify_cert_store(SSL *ctx, X509_STORE *st);
- int SSL_set1_verify_cert_store(SSL *ctx, X509_STORE *st);
- int SSL_set0_chain_cert_store(SSL *ctx, X509_STORE *st);
- int SSL_set1_chain_cert_store(SSL *ctx, X509_STORE *st);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store()
-set the certificate store used for certificate verification to B<st>.
-
-SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store()
-set the certificate store used for certificate chain building to B<st>.
-
-SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(),
-SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar
-except they apply to SSL structure B<ssl>.
-
-All these functions are implemented as macros. Those containing a B<1>
-increment the reference count of the supplied store so it must
-be freed at some point after the operation. Those containing a B<0> do
-not increment reference counts and the supplied store B<MUST NOT> be freed
-after the operation.
-
-=head1 NOTES
-
-The stores pointers associated with an SSL_CTX structure are copied to any SSL
-structures when SSL_new() is called. As a result SSL structures will not be
-affected if the parent SSL_CTX store pointer is set to a new value.
-
-The verification store is used to verify the certificate chain sent by the
-peer: that is an SSL/TLS client will use the verification store to verify
-the server's certificate chain and a SSL/TLS server will use it to verify
-any client certificate chain.
-
-The chain store is used to build the certificate chain.
-
-If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set or a certificate chain is
-configured already (for example using the functions such as
-L<SSL_CTX_add1_chain_cert(3)> or
-L<SSL_CTX_add_extra_chain_cert(3)>) then
-automatic chain building is disabled.
-
-If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set then automatic chain building
-is disabled.
-
-If the chain or the verification store is not set then the store associated
-with the parent SSL_CTX is used instead to retain compatibility with previous
-versions of OpenSSL.
-
-=head1 RETURN VALUES
-
-All these functions return 1 for success and 0 for failure.
-
-=head1 SEE ALSO
-
-L<SSL_CTX_add_extra_chain_cert(3)>
-L<SSL_CTX_set0_chain(3)>
-L<SSL_CTX_set1_chain(3)>
-L<SSL_CTX_add0_chain_cert(3)>
-L<SSL_CTX_add1_chain_cert(3)>
-L<SSL_set0_chain(3)>
-L<SSL_set1_chain(3)>
-L<SSL_add0_chain_cert(3)>
-L<SSL_add1_chain_cert(3)>
-L<SSL_CTX_build_cert_chain(3)>
-L<SSL_build_cert_chain(3)>
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.0.2.
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
-SSL_select_next_proto, SSL_get0_alpn_selected - handle application layer
-protocol negotiation (ALPN)
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
- unsigned int protos_len);
- int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
- unsigned int protos_len);
- void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
- int (*cb) (SSL *ssl,
- const unsigned char **out,
- unsigned char *outlen,
- const unsigned char *in,
- unsigned int inlen,
- void *arg), void *arg);
- int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
- const unsigned char *server,
- unsigned int server_len,
- const unsigned char *client,
- unsigned int client_len)
- void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
- unsigned int *len);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
-set the list of protocols available to be negotiated. The B<protos> must be in
-protocol-list format, described below. The length of B<protos> is specified in
-B<protos_len>.
-
-SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
-server to select which protocol to use for the incoming connection. When B<cb>
-is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
-the application callback.
-
-B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
-vector in protocol-list format. The value of the B<out>, B<outlen> vector
-should be set to the value of a single protocol selected from the B<in>,
-B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
-buffer that outlives the handshake. The B<arg> parameter is the pointer set via
-SSL_CTX_set_alpn_select_cb().
-
-SSL_select_next_proto() is a helper function used to select protocols. It
-implements the standard protocol selection. It is expected that this function
-is called from the application callback B<cb>. The protocol data in B<server>,
-B<server_len> and B<client>, B<client_len> must be in the protocol-list format
-described below. The first item in the B<server>, B<server_len> list that
-matches an item in the B<client>, B<client_len> list is selected, and returned
-in B<out>, B<outlen>. The B<out> value will point into either B<server> or
-B<client>, so it should be copied immediately. If no match is found, the first
-item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This
-function can also be used in the NPN callback.
-
-SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
-with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
-is set to 0 if no protocol has been selected. B<data> must not be freed.
-
-=head1 NOTES
-
-The protocol-lists must be in wire-format, which is defined as a vector of
-non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
-included in the length. Each string is limited to 255 bytes. A byte-string
-length of 0 is invalid. A truncated byte-string is invalid. The length of the
-vector is not in the vector itself, but in a separate variable.
-
-Example:
-
- unsigned char vector[] = {
- 6, 's', 'p', 'd', 'y', '/', '1',
- 8, 'h', 't', 't', 'p', '/', '1', '.', '1'
- };
- unsigned int length = sizeof(vector);
-
-The ALPN callback is executed after the servername callback; as that servername
-callback may update the SSL_CTX, and subsequently, the ALPN callback.
-
-If there is no ALPN proposed in the ClientHello, the ALPN callback is not
-invoked.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
-non-0 on failure. WARNING: these functions reverse the return value convention.
-
-SSL_select_next_proto() returns one of the following:
-
-=over 4
-
-=item OPENSSL_NPN_NEGOTIATED
-
-A match was found and is returned in B<out>, B<outlen>.
-
-=item OPENSSL_NPN_NO_OVERLAP
-
-No match was found. The first item in B<client>, B<client_len> is returned in
-B<out>, B<outlen>.
-
-=back
-
-The ALPN select callback B<cb>, must return one of the following:
-
-=over 4
-
-=item SSL_TLSEXT_ERR_OK
-
-ALPN protocol selected.
-
-=item SSL_TLSEXT_ERR_NOACK
-
-ALPN protocol not selected.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
-L<SSL_CTX_set_tlsext_servername_arg(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg);
- void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg);
-
- int (*cert_cb)(SSL *ssl, void *arg);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb() callback,
-B<arg> value is pointer which is passed to the application callback.
-
-When cert_cb() is NULL, no callback function is used.
-
-cert_cb() is the application defined callback. It is called before a
-certificate will be used by a client or server. The callback can then inspect
-the passed B<ssl> structure and set or clear any appropriate certificates. If
-the callback is successful it B<MUST> return 1 even if no certificates have
-been set. A zero is returned on error which will abort the handshake with a
-fatal internal error alert. A negative return value will suspend the handshake
-and the handshake function will return immediately.
-L<SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to
-indicate, that the handshake was suspended. The next call to the handshake
-function will again lead to the call of cert_cb(). It is the job of the
-cert_cb() to store information about the state of the last call,
-if required to continue.
-
-=head1 NOTES
-
-An application will typically call SSL_use_certificate() and
-SSL_use_PrivateKey() to set the end entity certificate and private key.
-It can add intermediate and optionally the root CA certificates using
-SSL_add1_chain_cert().
-
-It might also call SSL_certs_clear() to delete any certificates associated
-with the B<SSL> object.
-
-The certificate callback functionality supersedes the (largely broken)
-functionality provided by the old client certificate callback interface.
-It is B<always> called even is a certificate is already set so the callback
-can modify or delete the existing certificate.
-
-A more advanced callback might examine the handshake parameters and set
-whatever chain is appropriate. For example a legacy client supporting only
-TLS v1.0 might receive a certificate chain signed using SHA1 whereas a
-TLS v1.2 client which advertises support for SHA256 could receive a chain
-using SHA256.
-
-Normal server sanity checks are performed on any certificates set
-by the callback. So if an EC chain is set for a curve the client does not
-support it will B<not> be used.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_use_certificate(3)>,
-L<SSL_add1_chain_cert(3)>,
-L<SSL_get_client_CA_list(3)>,
-L<SSL_clear(3)>, L<SSL_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate verification storage
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store);
- X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_cert_store() sets/replaces the certificate verification storage
-of B<ctx> to/with B<store>. If another X509_STORE object is currently
-set in B<ctx>, it will be X509_STORE_free()ed.
-
-SSL_CTX_get_cert_store() returns a pointer to the current certificate
-verification storage.
-
-=head1 NOTES
-
-In order to verify the certificates presented by the peer, trusted CA
-certificates must be accessed. These CA certificates are made available
-via lookup methods, handled inside the X509_STORE. From the X509_STORE
-the X509_STORE_CTX used when verifying certificates is created.
-
-Typically the trusted certificate store is handled indirectly via using
-L<SSL_CTX_load_verify_locations(3)>.
-Using the SSL_CTX_set_cert_store() and SSL_CTX_get_cert_store() functions
-it is possible to manipulate the X509_STORE object beyond the
-L<SSL_CTX_load_verify_locations(3)>
-call.
-
-Currently no detailed documentation on how to use the X509_STORE
-object is available. Not all members of the X509_STORE are used when
-the verification takes place. So will e.g. the verify_callback() be
-overridden with the verify_callback() set via the
-L<SSL_CTX_set_verify(3)> family of functions.
-This document must therefore be updated when documentation about the
-X509_STORE object and its handling becomes available.
-
-=head1 RESTRICTIONS
-
-The X509_STORE structure used by an SSL_CTX is used for verifying peer
-certificates and building certificate chains, it is also shared by
-every child SSL structure. Applications wanting finer control can use
-functions such as SSL_CTX_set1_verify_cert_store() instead.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_cert_store() does not return diagnostic output.
-
-SSL_CTX_get_cert_store() returns the current setting.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_load_verify_locations(3)>,
-L<SSL_CTX_set_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *, void *), void *arg);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_cert_verify_callback() sets the verification callback function for
-I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at
-the time when L<SSL_new(3)> is called.
-
-=head1 NOTES
-
-Whenever a certificate is verified during a SSL/TLS handshake, a verification
-function is called. If the application does not explicitly specify a
-verification callback function, the built-in verification function is used.
-If a verification callback I<callback> is specified via
-SSL_CTX_set_cert_verify_callback(), the supplied callback function is called
-instead. By setting I<callback> to NULL, the default behaviour is restored.
-
-When the verification must be performed, I<callback> will be called with
-the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The
-argument I<arg> is specified by the application when setting I<callback>.
-
-I<callback> should return 1 to indicate verification success and 0 to
-indicate verification failure. If SSL_VERIFY_PEER is set and I<callback>
-returns 0, the handshake will fail. As the verification procedure may
-allow to continue the connection in case of failure (by always returning 1)
-the verification result must be set in any case using the B<error>
-member of I<x509_store_ctx> so that the calling application will be informed
-about the detailed result of the verification procedure!
-
-Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback>
-function set using L<SSL_CTX_set_verify(3)>.
-
-=head1 WARNINGS
-
-Do not mix the verification callback described in this function with the
-B<verify_callback> function called during the verification process. The
-latter is set using the L<SSL_CTX_set_verify(3)>
-family of functions.
-
-Providing a complete verification procedure including certificate purpose
-settings etc is a complex task. The built-in procedure is quite powerful
-and in most cases it should be sufficient to modify its behaviour using
-the B<verify_callback> function.
-
-=head1 BUGS
-
-SSL_CTX_set_cert_verify_callback() does not provide diagnostic information.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_set_verify(3)>,
-L<SSL_get_verify_result(3)>,
-L<SSL_CTX_load_verify_locations(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
- int SSL_set_cipher_list(SSL *ssl, const char *str);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx>
-using the control string B<str>. The format of the string is described
-in L<ciphers(1)>. The list of ciphers is inherited by all
-B<ssl> objects created from B<ctx>.
-
-SSL_set_cipher_list() sets the list of ciphers only for B<ssl>.
-
-=head1 NOTES
-
-The control string B<str> should be universally usable and not depend
-on details of the library configuration (ciphers compiled in). Thus no
-syntax checking takes place. Items that are not recognized, because the
-corresponding ciphers are not compiled in or because they are mistyped,
-are simply ignored. Failure is only flagged if no ciphers could be collected
-at all.
-
-It should be noted, that inclusion of a cipher to be used into the list is
-a necessary condition. On the client side, the inclusion into the list is
-also sufficient unless the security level excludes it. On the server side,
-additional restrictions apply. All ciphers have additional requirements.
-ADH ciphers don't need a certificate, but DH-parameters must have been set.
-All other ciphers need a corresponding certificate and key.
-
-A RSA cipher can only be chosen, when a RSA certificate is available.
-RSA ciphers using DHE need a certificate and key and additional DH-parameters
-(see L<SSL_CTX_set_tmp_dh_callback(3)>).
-
-A DSA cipher can only be chosen, when a DSA certificate is available.
-DSA ciphers always use DH key exchange and therefore need DH-parameters
-(see L<SSL_CTX_set_tmp_dh_callback(3)>).
-
-When these conditions are not met for any cipher in the list (e.g. a
-client only supports export RSA ciphers with an asymmetric key length
-of 512 bits and the server is not configured to use temporary RSA
-keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
-and the handshake will fail.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
-could be selected and 0 on complete failure.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_ciphers(3)>,
-L<SSL_CTX_use_certificate(3)>,
-L<SSL_CTX_set_tmp_dh_callback(3)>,
-L<ciphers(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
-SSL_add_client_CA - set list of CAs sent to the client when requesting a
-client certificate
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
- void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
- int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
- int SSL_add_client_CA(SSL *ssl, X509 *cacert);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
-requesting a client certificate for B<ctx>.
-
-SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
-requesting a client certificate for the chosen B<ssl>, overriding the
-setting valid for B<ssl>'s SSL_CTX object.
-
-SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
-list of CAs sent to the client when requesting a client certificate for
-B<ctx>.
-
-SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
-list of CAs sent to the client when requesting a client certificate for
-the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
-
-=head1 NOTES
-
-When a TLS/SSL server requests a client certificate (see
-B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
-it will accept certificates, to the client.
-
-This list must explicitly be set using SSL_CTX_set_client_CA_list() for
-B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
-specified overrides the previous setting. The CAs listed do not become
-trusted (B<list> only contains the names, not the complete certificates); use
-L<SSL_CTX_load_verify_locations(3)>
-to additionally load them for verification.
-
-If the list of acceptable CAs is compiled in a file, the
-L<SSL_load_client_CA_file(3)>
-function can be used to help importing the necessary data.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
-items the list of client CAs. If no list was specified before using
-SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
-CA list for B<ctx> or B<ssl> (as appropriate) is opened.
-
-These functions are only useful for TLS/SSL servers.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
-diagnostic information.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
-values:
-
-=over 4
-
-=item Z<>0
-
-A failure while manipulating the STACK_OF(X509_NAME) object occurred or
-the X509_NAME could not be extracted from B<cacert>. Check the error stack
-to find out the reason.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-=head1 EXAMPLES
-
-Scan all certificates in B<CAfile> and list them as acceptable CAs:
-
- SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_get_client_CA_list(3)>,
-L<SSL_load_client_CA_file(3)>,
-L<SSL_CTX_load_verify_locations(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
- int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
- int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_client_cert_cb() sets the client_cert_cb() callback, that is
-called when a client certificate is requested by a server and no certificate
-was yet set for the SSL object.
-
-When client_cert_cb() is NULL, no callback function is used.
-
-SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback
-function.
-
-client_cert_cb() is the application defined callback. If it wants to
-set a certificate, a certificate/private key combination must be set
-using the B<x509> and B<pkey> arguments and "1" must be returned. The
-certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
-If no certificate should be set, "0" has to be returned and no certificate
-will be sent. A negative return value will suspend the handshake and the
-handshake function will return immediately. L<SSL_get_error(3)>
-will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
-suspended. The next call to the handshake function will again lead to the call
-of client_cert_cb(). It is the job of the client_cert_cb() to store information
-about the state of the last call, if required to continue.
-
-=head1 NOTES
-
-During a handshake (or renegotiation) a server may request a certificate
-from the client. A client certificate must only be sent, when the server
-did send the request.
-
-When a certificate was set using the
-L<SSL_CTX_use_certificate(3)> family of functions,
-it will be sent to the server. The TLS standard requires that only a
-certificate is sent, if it matches the list of acceptable CAs sent by the
-server. This constraint is violated by the default behavior of the OpenSSL
-library. Using the callback function it is possible to implement a proper
-selection routine or to allow a user interaction to choose the certificate to
-be sent.
-
-If a callback function is defined and no certificate was yet defined for the
-SSL object, the callback function will be called.
-If the callback function returns a certificate, the OpenSSL library
-will try to load the private key and certificate data into the SSL
-object using the SSL_use_certificate() and SSL_use_private_key() functions.
-Thus it will permanently install the certificate and key for this SSL
-object. It will not be reset by calling L<SSL_clear(3)>.
-If the callback returns no certificate, the OpenSSL library will not send
-a certificate.
-
-=head1 BUGS
-
-The client_cert_cb() cannot return a complete certificate chain, it can
-only return one client certificate. If the chain only has a length of 2,
-the root CA certificate may be omitted according to the TLS standard and
-thus a standard conforming answer can be sent to the server. For a
-longer chain, the client must send the complete chain (with the option
-to leave out the root CA certificate). This can only be accomplished by
-either adding the intermediate CA certificates into the trusted
-certificate store for the SSL_CTX object (resulting in having to add
-CA certificates that otherwise maybe would not be trusted), or by adding
-the chain certificates using the
-L<SSL_CTX_add_extra_chain_cert(3)>
-function, which is only available for the SSL_CTX object as a whole and that
-therefore probably can only apply for one client certificate, making
-the concept of the callback function (to allow the choice from several
-certificates) questionable.
-
-Once the SSL object has been used in conjunction with the callback function,
-the certificate will be set for the SSL object and will not be cleared
-even when L<SSL_clear(3)> is being called. It is therefore
-mandatory to destroy the SSL object using L<SSL_free(3)>
-and create a new one to return to the previous state.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_use_certificate(3)>,
-L<SSL_CTX_add_extra_chain_cert(3)>,
-L<SSL_get_client_CA_list(3)>,
-L<SSL_clear(3)>, L<SSL_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct,
-SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback,
-SSL_ct_is_enabled, SSL_CTX_ct_is_enabled -
-control Certificate Transparency policy
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_enable_ct(SSL *s, int validation_mode);
- int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode);
- int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback,
- void *arg);
- int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx,
- ssl_ct_validation_cb callback,
- void *arg);
- void SSL_disable_ct(SSL *s);
- void SSL_CTX_disable_ct(SSL_CTX *ctx);
- int SSL_ct_is_enabled(const SSL *s);
- int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed
-certificate timestamps (SCTs) either for a given SSL connection or for all
-connections that share the given SSL context, respectively.
-This is accomplished by setting a built-in CT validation callback.
-The behaviour of the callback is determined by the B<validation_mode> argument,
-which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or
-B<SSL_CT_VALIDATION_STRICT> as described below.
-
-If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full
-TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer
-presents no valid SCTs the handshake will be aborted.
-If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue
-despite lack of valid SCTs.
-However, in that case if the verification status before the built-in callback
-was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the
-callback.
-Applications can call L<SSL_get_verify_result(3)> to check the status at
-handshake completion, even after session resumption since the verification
-status is part of the saved session state.
-See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>.
-
-If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the
-handshake continues, and the verification status is not modified, regardless of
-the validation status of any SCTs.
-The application can still inspect the validation status of the SCTs at
-handshake completion.
-Note that with session resumption there will not be any SCTs presented during
-the handshake.
-Therefore, in applications that delay SCT policy enforcement until after
-handshake completion, such delayed SCT checks should only be performed when the
-session is not resumed.
-
-SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback()
-register a custom callback that may implement a different policy than either of
-the above.
-This callback can examine the peer's SCTs and determine whether they are
-sufficient to allow the connection to continue.
-The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE>
-and the callback returns a non-positive result.
-
-An arbitrary callback context argument, B<arg>, can be passed in when setting
-the callback.
-This will be passed to the callback whenever it is invoked.
-Ownership of this context remains with the caller.
-
-If no callback is set, SCTs will not be requested and Certificate Transparency
-validation will not occur.
-
-No callback will be invoked when the peer presents no certificate, e.g. by
-employing an anonymous (aNULL) ciphersuite.
-In that case the handshake continues as it would had no callback been
-requested.
-Callbacks are also not invoked when the peer certificate chain is invalid or
-validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509
-PKI, or no X.509 PKI at all, respectively.
-Clients that require SCTs are expected to not have enabled any aNULL ciphers
-nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA
-records.
-
-SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether
-enabled via the built-in or the custom callbacks, by setting a NULL callback.
-These may be implemented as macros.
-
-SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is
-enabled via either SSL_enable_ct() or a non-null custom callback, and 0
-otherwise.
-
-=head1 NOTES
-
-When SCT processing is enabled, OCSP stapling will be enabled. This is because
-one possible source of SCTs is the OCSP response from a server.
-
-=head1 RESTRICTIONS
-
-Certificate Transparency validation cannot be enabled and so a callback cannot
-be set if a custom client extension handler has been registered to handle SCT
-extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>).
-
-=head1 RETURN VALUES
-
-SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and
-SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully
-set.
-They return 0 if an error occurs, e.g. a custom client extension handler has
-been setup to handle SCTs.
-
-SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result.
-
-SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT
-validation callback is set, or 0 if no callback (or equivalently a NULL
-callback) is set.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-<SSL_get_verify_result(3)>,
-L<SSL_session_reused(3)>,
-L<SSL_set_verify(3)>,
-L<SSL_CTX_set_verify(3)>,
-L<ssl_ct_validation_cb(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file -
-load a Certificate Transparency log list from a file
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx);
- int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency
-(CT) logs from the default file location, "ct_log_list.cnf", found in the
-directory where OpenSSL is installed.
-
-SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a specific path.
-See L<CTLOG_STORE_new(3)> for the file format.
-
-=head1 NOTES
-
-These functions will not clear the existing CT log list - it will be appended
-to. To replace the existing list, use L<SSL_CTX_set0_ctlog_store> first.
-
-If an error occurs whilst parsing a particular log entry in the file, that log
-entry will be skipped.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file()
-return 1 if the log list is successfully loaded, and 0 if an error occurs. In
-the case of an error, the log list may have been partially loaded.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_ct_validation_callback(3)>,
-L<CTLOG_STORE_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata,
-SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata,
-SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata,
-SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata - set or
-get passwd callback for encrypted PEM file handling
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);
- void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);
- pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx);
- void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx);
-
- void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb);
- void SSL_set_default_passwd_cb_userdata(SSL *s, void *u);
- pem_password_cb *SSL_get_default_passwd_cb(SSL *s);
- void *SSL_get_default_passwd_cb_userdata(SSL *s);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_default_passwd_cb() sets the default password callback called
-when loading/storing a PEM certificate with encryption.
-
-SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to userdata, B<u>,
-which will be provided to the password callback on invocation.
-
-SSL_CTX_get_default_passwd_cb() returns a function pointer to the password
-callback currently set in B<ctx>. If no callback was explicitly set, the
-NULL pointer is returned.
-
-SSL_CTX_get_default_passwd_cb_userdata() returns a pointer to the userdata
-currently set in B<ctx>. If no userdata was explicitly set, the NULL pointer
-is returned.
-
-SSL_set_default_passwd_cb(), SSL_set_default_passwd_cb_userdata(),
-SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform
-the same function as their SSL_CTX counterparts, but using an SSL object.
-
-The password callback, which must be provided by the application, hands back the
-password to be used during decryption.
-On invocation a pointer to userdata
-is provided. The function must store the password into the provided buffer
-B<buf> which is of size B<size>. The actual length of the password must
-be returned to the calling function. B<rwflag> indicates whether the
-callback is used for reading/decryption (rwflag=0) or writing/encryption
-(rwflag=1).
-For more details, see L<pem_password_cb(3)>.
-
-=head1 NOTES
-
-When loading or storing private keys, a password might be supplied to
-protect the private key. The way this password can be supplied may depend
-on the application. If only one private key is handled, it can be practical
-to have the callback handle the password dialog interactively. If several
-keys have to be handled, it can be practical to ask for the password once,
-then keep it in memory and use it several times. In the last case, the
-password could be stored into the userdata storage and the
-callback only returns the password already stored.
-
-When asking for the password interactively, the callback can use
-B<rwflag> to check, whether an item shall be encrypted (rwflag=1).
-In this case the password dialog may ask for the same password twice
-for comparison in order to catch typos, that would make decryption
-impossible.
-
-Other items in PEM formatting (certificates) can also be encrypted, it is
-however not usual, as certificate information is considered public.
-
-=head1 RETURN VALUES
-
-These functions do not provide diagnostic information.
-
-=head1 EXAMPLES
-
-The following example returns the password provided as userdata to the
-calling function. The password is considered to be a '\0' terminated
-string. If the password does not fit into the buffer, the password is
-truncated.
-
- int my_cb(char *buf, int size, int rwflag, void *u)
- {
- strncpy(buf, (char *)u, size);
- buf[size - 1] = '\0';
- return strlen(buf);
- }
-
-=head1 HISTORY
-
-SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(),
-SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were
-first added to OpenSSL 1.1.0
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_use_certificate(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=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 between 1 and 32 bytes. The session id is not
-security critical but must be unique for the server. Additionally, the session id is
-transmitted in the clear when reusing the session so it must not contain
-sensitive information.
-
-Without a callback being set, an OpenSSL server will generate a unique
-session id from pseudo random numbers of the maximum possible length.
-Using the callback function, the session id can be changed to contain
-additional information like e.g. a host id in order to improve load balancing
-or external caching techniques.
-
-The callback function receives a pointer to the memory location to put
-B<id> into and a pointer to the maximum allowed length B<id_len>. The
-buffer at location B<id> is only guaranteed to have the size B<id_len>.
-The callback is only allowed to generate a shorter id and reduce B<id_len>;
-the callback B<must never> increase B<id_len> or write to the location
-B<id> exceeding the given limit.
-
-The location B<id> is filled with 0x00 before the callback is called, so the
-callback may only fill part of the possible length and leave B<id_len>
-untouched while maintaining reproducibility.
-
-Since the sessions must be distinguished, session ids must be unique.
-Without the callback a random number is used, so that the probability
-of generating the same session id is extremely small (2^256 for SSLv3/TLSv1).
-In order to assure the uniqueness of the generated session id, the callback must call
-SSL_has_matching_session_id() and generate another id if a conflict occurs.
-If an id conflict is not resolved, the handshake will fail.
-If the application codes e.g. a unique host id, a unique process number, and
-a unique sequence number into the session id, uniqueness could easily be
-achieved without randomness added (it should however be taken care that
-no confidential information is leaked this way). If the application can not
-guarantee uniqueness, it is recommended to use the maximum B<id_len> and
-fill in the bytes not used to code special information with random data
-to avoid collisions.
-
-SSL_has_matching_session_id() will only query the internal session cache,
-not the external one. Since the session id is generated before the
-handshake is completed, it is not immediately added to the cache. If
-another thread is using the same internal session cache, a race condition
-can occur in that another thread generates the same session id.
-Collisions can also occur when using an external session cache, since
-the external cache is not tested with SSL_has_matching_session_id()
-and the same race condition applies.
-
-The callback must return 0 if it cannot generate a session id for whatever
-reason and return 1 on success.
-
-=head1 EXAMPLES
-
-The callback function listed will generate a session id with the
-server id given, and will fill the rest with pseudo random bytes:
-
- const char session_id_prefix = "www-18";
-
- #define MAX_SESSION_ID_ATTEMPTS 10
- static int generate_session_id(const SSL *ssl, unsigned char *id,
- unsigned int *id_len)
- {
- unsigned int count = 0;
- do {
- RAND_pseudo_bytes(id, *id_len);
- /*
- * Prefix the session_id with the required prefix. NB: If our
- * prefix is too long, clip it - but there will be worse effects
- * anyway, eg. the server could only possibly create 1 session
- * ID (ie. the prefix!) so all future session negotiations will
- * fail due to conflicts.
- */
- memcpy(id, session_id_prefix,
- (strlen(session_id_prefix) < *id_len) ?
- strlen(session_id_prefix) : *id_len);
- }
- while (SSL_has_matching_session_id(ssl, id, *id_len) &&
- (++count < MAX_SESSION_ID_ATTEMPTS));
- if (count >= MAX_SESSION_ID_ATTEMPTS)
- return 0;
- return 1;
- }
-
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
-always return 1.
-
-SSL_has_matching_session_id() returns 1 if another session with the
-same id is already in the cache.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_version(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
- void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
-
- void SSL_set_info_callback(SSL *ssl, void (*callback)());
- void (*SSL_get_info_callback(const SSL *ssl))();
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
-obtain state information for SSL objects created from B<ctx> during connection
-setup and use. The setting for B<ctx> is overridden from the setting for
-a specific SSL object, if specified.
-When B<callback> is NULL, no callback function is used.
-
-SSL_set_info_callback() sets the B<callback> function, that can be used to
-obtain state information for B<ssl> during connection setup and use.
-When B<callback> is NULL, the callback setting currently valid for
-B<ctx> is used.
-
-SSL_CTX_get_info_callback() returns a pointer to the currently set information
-callback function for B<ctx>.
-
-SSL_get_info_callback() returns a pointer to the currently set information
-callback function for B<ssl>.
-
-=head1 NOTES
-
-When setting up a connection and during use, it is possible to obtain state
-information from the SSL/TLS engine. When set, an information callback function
-is called whenever the state changes, an alert appears, or an error occurs.
-
-The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
-The B<where> argument specifies information about where (in which context)
-the callback function was called. If B<ret> is 0, an error condition occurred.
-If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
-information.
-
-B<where> is a bitmask made up of the following bits:
-
-=over 4
-
-=item SSL_CB_LOOP
-
-Callback has been called to indicate state change inside a loop.
-
-=item SSL_CB_EXIT
-
-Callback has been called to indicate error exit of a handshake function.
-(May be soft error with retry option for non-blocking setups.)
-
-=item SSL_CB_READ
-
-Callback has been called during read operation.
-
-=item SSL_CB_WRITE
-
-Callback has been called during write operation.
-
-=item SSL_CB_ALERT
-
-Callback has been called due to an alert being sent or received.
-
-=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ)
-
-=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE)
-
-=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP)
-
-=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT)
-
-=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP)
-
-=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT)
-
-=item SSL_CB_HANDSHAKE_START
-
-Callback has been called because a new handshake is started.
-
-=item SSL_CB_HANDSHAKE_DONE 0x20
-
-Callback has been called because a handshake is finished.
-
-=back
-
-The current state information can be obtained using the
-L<SSL_state_string(3)> family of functions.
-
-The B<ret> information can be evaluated using the
-L<SSL_alert_type_string(3)> family of functions.
-
-=head1 RETURN VALUES
-
-SSL_set_info_callback() does not provide diagnostic information.
-
-SSL_get_info_callback() returns the current setting.
-
-=head1 EXAMPLES
-
-The following example callback function prints state strings, information
-about alerts being handled and error messages to the B<bio_err> BIO.
-
- void apps_ssl_info_callback(SSL *s, int where, int ret)
- {
- const char *str;
- int w;
-
- w = where & ~SSL_ST_MASK;
-
- if (w & SSL_ST_CONNECT) str = "SSL_connect";
- else if (w & SSL_ST_ACCEPT) str = "SSL_accept";
- else str = "undefined";
-
- if (where & SSL_CB_LOOP)
- {
- BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s));
- }
- else if (where & SSL_CB_ALERT)
- {
- str = (where & SSL_CB_READ) ? "read" : "write";
- BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n",
- str,
- SSL_alert_type_string_long(ret),
- SSL_alert_desc_string_long(ret));
- }
- else if (where & SSL_CB_EXIT)
- {
- if (ret == 0)
- BIO_printf(bio_err, "%s:failed in %s\n",
- str, SSL_state_string_long(s));
- else if (ret < 0)
- {
- BIO_printf(bio_err, "%s:error in %s\n",
- str, SSL_state_string_long(s));
- }
- }
- }
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_state_string(3)>,
-L<SSL_alert_type_string(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list - manipulate allowed size for the peer's certificate chain
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size);
- long SSL_CTX_get_max_cert_list(SSL_CTX *ctx);
-
- long SSL_set_max_cert_list(SSL *ssl, long size);
- long SSL_get_max_cert_list(SSL *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's
-certificate chain for all SSL objects created from B<ctx> to be <size> bytes.
-The SSL objects inherit the setting valid for B<ctx> at the time
-L<SSL_new(3)> is being called.
-
-SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>.
-
-SSL_set_max_cert_list() sets the maximum size allowed for the peer's
-certificate chain for B<ssl> to be <size> bytes. This setting stays valid
-until a new value is set.
-
-SSL_get_max_cert_list() returns the currently set maximum size for B<ssl>.
-
-=head1 NOTES
-
-During the handshake process, the peer may send a certificate chain.
-The TLS/SSL standard does not give any maximum size of the certificate chain.
-The OpenSSL library handles incoming data by a dynamically allocated buffer.
-In order to prevent this buffer from growing without bounds due to data
-received from a faulty or malicious peer, a maximum size for the certificate
-chain is set.
-
-The default value for the maximum certificate chain size is 100kB (30kB
-on the 16bit DOS platform). This should be sufficient for usual certificate
-chains (OpenSSL's default maximum chain length is 10, see
-L<SSL_CTX_set_verify(3)>, and certificates
-without special extensions have a typical size of 1-2kB).
-
-For special applications it can be necessary to extend the maximum certificate
-chain size allowed to be sent by the peer, see e.g. the work on
-"Internet X.509 Public Key Infrastructure Proxy Certificate Profile"
-and "TLS Delegation Protocol" at http://www.ietf.org/ and
-http://www.globus.org/ .
-
-Under normal conditions it should never be necessary to set a value smaller
-than the default, as the buffer is handled dynamically and only uses the
-memory actually required by the data sent by the peer.
-
-If the maximum certificate chain size allowed is exceeded, the handshake will
-fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously
-set value.
-
-SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently
-set value.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_new(3)>,
-L<SSL_CTX_set_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version,
-SSL_set_min_proto_version, SSL_set_max_proto_version - Set minimum
-and maximum supported protocol version
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version);
- int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version);
- int SSL_set_min_proto_version(SSL *ssl, int version);
- int SSL_set_max_proto_version(SSL *ssl, int version);
-
-=head1 DESCRIPTION
-
-The functions set the minimum and maximum supported protocol versions
-for the B<ctx> or B<ssl>.
-This works in combination with the options set via
-L<SSL_CTX_set_options(3)> that also make it possible to disable
-specific protocol versions.
-Use these functions instead of disabling specific protocol versions.
-
-Setting the minimum or maximum version to 0, will enable protocol
-versions down to the lowest version, or up to the highest version
-supported by the library, respectively.
-
-Currently supported versions are B<SSL3_VERSION>, B<TLS1_VERSION>,
-B<TLS1_1_VERSION>, B<TLS1_2_VERSION> for TLS and B<DTLS1_VERSION>,
-B<DTLS1_2_VERSION> for DTLS.
-
-=head1 RETURN VALUES
-
-These functions return 1 on success and 0 on failure.
-
-=head1 NOTES
-
-All these functions are implemented using macros.
-
-=head1 HISTORY
-
-The functions were added in OpenSSL 1.1.0
-
-=head1 SEE ALSO
-
-L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
- long SSL_set_mode(SSL *ssl, long mode);
-
- long SSL_CTX_get_mode(SSL_CTX *ctx);
- long SSL_get_mode(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
-Options already set before are not cleared.
-
-SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
-Options already set before are not cleared.
-
-SSL_CTX_get_mode() returns the mode set for B<ctx>.
-
-SSL_get_mode() returns the mode set for B<ssl>.
-
-=head1 NOTES
-
-The following mode changes are available:
-
-=over 4
-
-=item SSL_MODE_ENABLE_PARTIAL_WRITE
-
-Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
-when just a single record has been written). When not set (the default),
-SSL_write() will only report success once the complete chunk was written.
-Once SSL_write() returns with r, r bytes have been successfully written
-and the next call to SSL_write() must only send the n-r bytes left,
-imitating the behaviour of write().
-
-=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
-
-Make it possible to retry SSL_write() with changed buffer location
-(the buffer contents must stay the same). This is not the default to avoid
-the misconception that non-blocking SSL_write() behaves like
-non-blocking write().
-
-=item SSL_MODE_AUTO_RETRY
-
-Never bother the application with retries if the transport is blocking.
-If a renegotiation take place during normal operation, a
-L<SSL_read(3)> or L<SSL_write(3)> would return
-with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.
-In a non-blocking environment applications must be prepared to handle
-incomplete read/write operations.
-In a blocking environment, applications are not always prepared to
-deal with read/write operations returning without success report. The
-flag SSL_MODE_AUTO_RETRY will cause read/write operations to only
-return after the handshake and successful completion.
-
-=item SSL_MODE_RELEASE_BUFFERS
-
-When we no longer need a read buffer or a write buffer for a given SSL,
-then release the memory we were using to hold it.
-Using this flag can
-save around 34k per idle SSL connection.
-This flag has no effect on SSL v2 connections, or on DTLS connections.
-
-=item SSL_MODE_SEND_FALLBACK_SCSV
-
-Send TLS_FALLBACK_SCSV in the ClientHello.
-To be set only by applications that reconnect with a downgraded protocol
-version; see draft-ietf-tls-downgrade-scsv-00 for details.
-
-DO NOT ENABLE THIS if your application attempts a normal handshake.
-Only use this in explicit fallback retries, following the guidance
-in draft-ietf-tls-downgrade-scsv-00.
-
-=item SSL_MODE_ASYNC
-
-Enable asynchronous processing. TLS I/O operations may indicate a retry with
-SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is
-used to perform cryptographic operations. See L<SSL_get_error(3)>.
-
-=back
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
-after adding B<mode>.
-
-SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)>
-
-=head1 HISTORY
-
-SSL_MODE_ASYNC was first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_set_msg_callback_arg - install callback for observing protocol messages
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
- void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
-
- void SSL_set_msg_callback(SSL *ssl, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
- void SSL_set_msg_callback_arg(SSL *ssl, void *arg);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to
-define a message callback function I<cb> for observing all SSL/TLS
-protocol messages (such as handshake messages) that are received or
-sent. SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
-can be used to set argument I<arg> to the callback function, which is
-available for arbitrary application use.
-
-SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
-default settings that will be copied to new B<SSL> objects by
-L<SSL_new(3)>. SSL_set_msg_callback() and
-SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
-object. Using a B<0> pointer for I<cb> disables the message callback.
-
-When I<cb> is called by the SSL/TLS library for a protocol message,
-the function arguments have the following meaning:
-
-=over 4
-
-=item I<write_p>
-
-This flag is B<0> when a protocol message has been received and B<1>
-when a protocol message has been sent.
-
-=item I<version>
-
-The protocol version according to which the protocol message is
-interpreted by the library. Currently, this is one of
-B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL
-3.0 and TLS 1.0, respectively).
-
-=item I<content_type>
-
-In the case of SSL 2.0, this is always B<0>. In the case of SSL 3.0
-or TLS 1.0, this is one of the B<ContentType> values defined in the
-protocol specification (B<change_cipher_spec(20)>, B<alert(21)>,
-B<handshake(22)>; but never B<application_data(23)> because the
-callback will only be called for protocol messages).
-
-=item I<buf>, I<len>
-
-I<buf> points to a buffer containing the protocol message, which
-consists of I<len> bytes. The buffer is no longer valid after the
-callback function has returned.
-
-=item I<ssl>
-
-The B<SSL> object that received or sent the message.
-
-=item I<arg>
-
-The user-defined argument optionally defined by
-SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg().
-
-=back
-
-=head1 NOTES
-
-Protocol messages are passed to the callback function after decryption
-and fragment collection where applicable. (Thus record boundaries are
-not visible.)
-
-If processing a received protocol message results in an error,
-the callback function may not be called. For example, the callback
-function will never see messages that are considered too large to be
-processed.
-
-Due to automatic protocol version negotiation, I<version> is not
-necessarily the protocol version used by the sender of the message: If
-a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
-I<version> will be B<SSL3_VERSION>.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options,
-SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
-SSL_get_secure_renegotiation_support - manipulate SSL options
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_set_options(SSL_CTX *ctx, long options);
- long SSL_set_options(SSL *ssl, long options);
-
- long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
- long SSL_clear_options(SSL *ssl, long options);
-
- long SSL_CTX_get_options(SSL_CTX *ctx);
- long SSL_get_options(SSL *ssl);
-
- long SSL_get_secure_renegotiation_support(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
-Options already set before are not cleared!
-
-SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
-Options already set before are not cleared!
-
-SSL_CTX_clear_options() clears the options set via bitmask in B<options>
-to B<ctx>.
-
-SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.
-
-SSL_CTX_get_options() returns the options set for B<ctx>.
-
-SSL_get_options() returns the options set for B<ssl>.
-
-SSL_get_secure_renegotiation_support() indicates whether the peer supports
-secure renegotiation.
-Note, this is implemented via a macro.
-
-=head1 NOTES
-
-The behaviour of the SSL library can be changed by setting several options.
-The options are coded as bitmasks and can be combined by a bitwise B<or>
-operation (|).
-
-SSL_CTX_set_options() and SSL_set_options() affect the (external)
-protocol behaviour of the SSL library. The (internal) behaviour of
-the API can be changed by using the similar
-L<SSL_CTX_set_mode(3)> and SSL_set_mode() functions.
-
-During a handshake, the option settings of the SSL object are used. When
-a new SSL object is created from a context using SSL_new(), the current
-option setting is copied. Changes to B<ctx> do not affect already created
-SSL objects. SSL_clear() does not affect the settings.
-
-The following B<bug workaround> options are available:
-
-=over 4
-
-=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
-
-...
-
-=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
-
-...
-
-=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG
-
-Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
-OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
-
-=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG
-
-...
-
-=item SSL_OP_TLS_D5_BUG
-
-...
-
-=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
-
-Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol
-vulnerability affecting CBC ciphers, which cannot be handled by some
-broken SSL implementations. This option has no effect for connections
-using other ciphers.
-
-=item SSL_OP_TLSEXT_PADDING
-
-Adds a padding extension to ensure the ClientHello size is never between
-256 and 511 bytes in length. This is needed as a workaround for some
-implementations.
-
-=item SSL_OP_ALL
-
-All of the above bug workarounds.
-
-=back
-
-It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround
-options if compatibility with somewhat broken implementations is
-desired.
-
-The following B<modifying> options are available:
-
-=over 4
-
-=item SSL_OP_TLS_ROLLBACK_BUG
-
-Disable version rollback attack detection.
-
-During the client key exchange, the client must send the same information
-about acceptable SSL/TLS protocol levels as during the first hello. Some
-clients violate this rule by adapting to the server's answer. (Example:
-the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
-only understands up to SSLv3. In this case the client must still use the
-same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
-to the server's answer and violate the version rollback protection.)
-
-=item SSL_OP_SINGLE_DH_USE
-
-Always create a new key when using temporary/ephemeral DH parameters
-(see L<SSL_CTX_set_tmp_dh_callback(3)>).
-This option must be used to prevent small subgroup attacks, when
-the DH parameters were not generated using "strong" primes
-(e.g. when using DSA-parameters, see L<dhparam(1)>).
-If "strong" primes were used, it is not strictly necessary to generate
-a new DH key during each handshake but it is also recommended.
-B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever
-temporary/ephemeral DH parameters are used.
-
-=item SSL_OP_EPHEMERAL_RSA
-
-This option is no longer implemented and is treated as no op.
-
-=item SSL_OP_CIPHER_SERVER_PREFERENCE
-
-When choosing a cipher, use the server's preferences instead of the client
-preferences. When not set, the SSL server will always follow the clients
-preferences. When set, the SSL/TLS server will choose following its
-own preferences.
-
-=item SSL_OP_PKCS1_CHECK_1
-
-...
-
-=item SSL_OP_PKCS1_CHECK_2
-
-...
-
-
-=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1,
-SSL_OP_NO_TLSv1_2, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2
-
-These options turn off the SSLv3, TLSv1, TLSv1.1 or TLSv1.2 protocol
-versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
-respectively.
-As of OpenSSL 1.1.0, these options are deprecated, use
-L<SSL_CTX_set_min_proto_version(3)> and
-L<SSL_CTX_set_max_proto_version(3)> instead.
-
-=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
-
-When performing renegotiation as a server, always start a new session
-(i.e., session resumption requests are only accepted in the initial
-handshake). This option is not needed for clients.
-
-=item SSL_OP_NO_TICKET
-
-Normally clients and servers will, where possible, transparently make use
-of RFC4507bis tickets for stateless session resumption.
-
-If this option is set this functionality is disabled and tickets will
-not be used by clients or servers.
-
-=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
-
-Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
-servers. See the B<SECURE RENEGOTIATION> section for more details.
-
-=item SSL_OP_LEGACY_SERVER_CONNECT
-
-Allow legacy insecure renegotiation between OpenSSL and unpatched servers
-B<only>: this option is currently set by default. See the
-B<SECURE RENEGOTIATION> section for more details.
-
-=item SSL_OP_NO_ENCRYPT_THEN_MAC
-
-Normally clients and servers will transparently attempt to negotiate the
-RFC7366 Encrypt-then-MAC option on TLS and DTLS connection.
-
-If this option is set, Encrypt-then-MAC is disabled. Clients will not
-propose, and servers will not accept the extension.
-
-=back
-
-=head1 SECURE RENEGOTIATION
-
-OpenSSL always attempts to use secure renegotiation as
-described in RFC5746. This counters the prefix attack described in
-CVE-2009-3555 and elsewhere.
-
-This attack has far reaching consequences which application writers should be
-aware of. In the description below an implementation supporting secure
-renegotiation is referred to as I<patched>. A server not supporting secure
-renegotiation is referred to as I<unpatched>.
-
-The following sections describe the operations permitted by OpenSSL's secure
-renegotiation implementation.
-
-=head2 Patched client and server
-
-Connections and renegotiation are always permitted by OpenSSL implementations.
-
-=head2 Unpatched client and patched OpenSSL server
-
-The initial connection succeeds but client renegotiation is denied by the
-server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal
-B<handshake_failure> alert in SSL v3.0.
-
-If the patched OpenSSL server attempts to renegotiate a fatal
-B<handshake_failure> alert is sent. This is because the server code may be
-unaware of the unpatched nature of the client.
-
-If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
-renegotiation B<always> succeeds.
-
-=head2 Patched OpenSSL client and unpatched server.
-
-If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
-B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
-and renegotiation between patched OpenSSL clients and unpatched servers
-succeeds. If neither option is set then initial connections to unpatched
-servers will fail.
-
-The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even
-though it has security implications: otherwise it would be impossible to
-connect to unpatched servers (i.e. all of them initially) and this is clearly
-not acceptable. Renegotiation is permitted because this does not add any
-additional security issues: during an attack clients do not see any
-renegotiations anyway.
-
-As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
-B<not> be set by default in a future version of OpenSSL.
-
-OpenSSL client applications wishing to ensure they can connect to unpatched
-servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
-
-OpenSSL client applications that want to ensure they can B<not> connect to
-unpatched servers (and thus avoid any security issues) should always B<clear>
-B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or
-SSL_clear_options().
-
-The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and
-B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that
-B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure
-renegotiation between OpenSSL clients and unpatched servers B<only>, while
-B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections
-and renegotiation between OpenSSL and unpatched clients or servers.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
-after adding B<options>.
-
-SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
-after clearing B<options>.
-
-SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
-
-SSL_get_secure_renegotiation_support() returns 1 is the peer supports
-secure renegotiation and 0 if it does not.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>,
-L<SSL_CTX_set_tmp_dh_callback(3)>,
-L<SSL_CTX_set_min_proto_version(3)>,
-L<dhparam(1)>
-
-=head1 HISTORY
-
-The attempt to always try to use secure renegotiation was added in
-Openssl 0.9.8m.
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx,
- unsigned int (*callback)(SSL *ssl, const char *hint,
- char *identity, unsigned int max_identity_len,
- unsigned char *psk, unsigned int max_psk_len));
- void SSL_set_psk_client_callback(SSL *ssl,
- unsigned int (*callback)(SSL *ssl, const char *hint,
- char *identity, unsigned int max_identity_len,
- unsigned char *psk, unsigned int max_psk_len));
-
-
-=head1 DESCRIPTION
-
-A client application must provide a callback function which is called
-when the client is sending the ClientKeyExchange message to the server.
-
-The purpose of the callback function is to select the PSK identity and
-the pre-shared key to use during the connection setup phase.
-
-The callback is set using functions SSL_CTX_set_psk_client_callback()
-or SSL_set_psk_client_callback(). The callback function is given the
-connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint
-sent by the server in parameter B<hint>, a buffer B<identity> of
-length B<max_identity_len> bytes where the resulting
-B<NULL>-terminated identity is to be stored, and a buffer B<psk> of
-length B<max_psk_len> bytes where the resulting pre-shared key is to
-be stored.
-
-=head1 NOTES
-
-Note that parameter B<hint> given to the callback may be B<NULL>.
-
-=head1 RETURN VALUES
-
-Return values from the client callback are interpreted as follows:
-
-On success (callback found a PSK identity and a pre-shared key to use)
-the length (> 0) of B<psk> in bytes is returned.
-
-Otherwise or on errors callback should return 0. In this case
-the connection setup fails.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-Copyright 2005 Nokia.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, SSL_get_quiet_shutdown - manipulate shutdown behaviour
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode);
- int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx);
-
- void SSL_set_quiet_shutdown(SSL *ssl, int mode);
- int SSL_get_quiet_shutdown(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ctx> to be
-B<mode>. SSL objects created from B<ctx> inherit the B<mode> valid at the time
-L<SSL_new(3)> is called. B<mode> may be 0 or 1.
-
-SSL_CTX_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ctx>.
-
-SSL_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ssl> to be
-B<mode>. The setting stays valid until B<ssl> is removed with
-L<SSL_free(3)> or SSL_set_quiet_shutdown() is called again.
-It is not changed when L<SSL_clear(3)> is called.
-B<mode> may be 0 or 1.
-
-SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>.
-
-=head1 NOTES
-
-Normally when a SSL connection is finished, the parties must send out
-"close notify" alert messages using L<SSL_shutdown(3)>
-for a clean shutdown.
-
-When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)>
-will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.
-(L<SSL_shutdown(3)> then behaves like
-L<SSL_set_shutdown(3)> called with
-SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.)
-The session is thus considered to be shutdown, but no "close notify" alert
-is sent to the peer. This behaviour violates the TLS standard.
-
-The default is normal shutdown behaviour as described by the TLS standard.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_quiet_shutdown() and SSL_set_quiet_shutdown() do not return
-diagnostic information.
-
-SSL_CTX_get_quiet_shutdown() and SSL_get_quiet_shutdown return the current
-setting.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_shutdown(3)>,
-L<SSL_set_shutdown(3)>, L<SSL_new(3)>,
-L<SSL_clear(3)>, L<SSL_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead,
-SSL_set_read_ahead, SSL_get_read_ahead,
-SSL_CTX_get_default_read_ahead
-- manage whether to read as many input bytes as possible
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_set_read_ahead(SSL *s, int yes);
- int SSL_get_read_ahead(const SSL *s);
-
- SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes);
- long SSL_CTX_get_read_ahead(SSL_CTX *ctx);
- long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as
-many input bytes as possible (for non-blocking reads) or not. For example if
-B<x> bytes are currently required by OpenSSL, but B<y> bytes are available from
-the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes
-into its buffer (providing that the buffer is large enough) if reading ahead is
-on, or B<x> bytes otherwise. The parameter B<yes> or B<m> should be 0 to ensure
-reading ahead is off, or non zero otherwise.
-SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead().
-
-SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading
-ahead has been set or not.
-
-=head1 NOTES
-
-These functions have no impact when used with DTLS. The return values for
-SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting
-B<read_ahead> can impact the behaviour of the SSL_pending() function
-(see L<SSL_pending(3)>).
-
-=head1 RETURN VALUES
-
-SSL_get_read_ahead() and SSL_CTX_get_read_ahead() return 0 if reading ahead is off,
-and non zero otherwise.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_pending(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_security_level(SSL_CTX *ctx, int level);
- void SSL_set_security_level(SSL *s, int level);
-
- int SSL_CTX_get_security_level(const SSL_CTX *ctx);
- int SSL_get_security_level(const SSL *s);
-
- void SSL_CTX_set_security_callback(SSL_CTX *ctx,
- int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid,
- void *other, void *ex));
-
- void SSL_set_security_callback(SSL *s,
- int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid,
- void *other, void *ex));
-
- int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex);
- int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex);
-
- void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex);
- void SSL_set0_security_ex_data(SSL *s, void *ex);
-
- void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx);
- void *SSL_get0_security_ex_data(const SSL *s);
-
-=head1 DESCRIPTION
-
-The functions SSL_CTX_set_security_level() and SSL_set_security_level() set
-the security level to B<level>. If not set the library default security level
-is used.
-
-The functions SSL_CTX_get_security_level() and SSL_get_security_level()
-retrieve the current security level.
-
-SSL_CTX_set_security_callback(), SSL_set_security_callback(),
-SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set
-the security callback associated with B<ctx> or B<s>. If not set a default
-security callback is used. The meaning of the parameters and the behaviour
-of the default callbacks is described below.
-
-SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(),
-SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the
-extra data pointer passed to the B<ex> parameter of the callback. This
-value is passed to the callback verbatim and can be set to any convenient
-application specific value.
-
-=head1 DEFAULT CALLBACK BEHAVIOUR
-
-If an application doesn't set its own security callback the default
-callback is used. It is intended to provide sane defaults. The meaning
-of each level is described below.
-
-=over 4
-
-=item B<Level 0>
-
-Everything is permitted. This retains compatibility with previous versions of
-OpenSSL.
-
-=item B<Level 1>
-
-The security level corresponds to a minimum of 80 bits of security. Any
-parameters offering below 80 bits of security are excluded. As a result RSA,
-DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits
-are prohibited. All export ciphersuites are prohibited since they all offer
-less than 80 bits of security. SSL version 2 is prohibited. Any ciphersuite
-using MD5 for the MAC is also prohibited.
-
-=item B<Level 2>
-
-Security level set to 112 bits of security. As a result RSA, DSA and DH keys
-shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited.
-In addition to the level 1 exclusions any ciphersuite using RC4 is also
-prohibited. SSL version 3 is also not allowed. Compression is disabled.
-
-=item B<Level 3>
-
-Security level set to 128 bits of security. As a result RSA, DSA and DH keys
-shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited.
-In addition to the level 2 exclusions ciphersuites not offering forward
-secrecy are prohibited. TLS versions below 1.1 are not permitted. Session
-tickets are disabled.
-
-=item B<Level 4>
-
-Security level set to 192 bits of security. As a result RSA, DSA and DH keys
-shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited.
-Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are
-not permitted.
-
-=item B<Level 5>
-
-Security level set to 256 bits of security. As a result RSA, DSA and DH keys
-shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited.
-
-=back
-
-=head1 APPLICATION DEFINED SECURITY CALLBACKS
-
-I<Documentation to be provided.>
-
-=head1 NOTES
-
-B<WARNING> at this time setting the security level higher than 1 for
-general internet use is likely to cause B<considerable> interoperability
-issues and is not recommended. This is because the B<SHA1> algorithm
-is very widely used in certificates and will be rejected at levels
-higher than 1 because it only offers 80 bits of security.
-
-The default security level can be configured when OpenSSL is compiled by
-setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used.
-
-The security framework disables or reject parameters inconsistent with the
-set security level. In the past this was difficult as applications had to set
-a number of distinct parameters (supported ciphers, supported curves supported
-signature algorithms) to achieve this end and some cases (DH parameter size
-for example) could not be checked at all.
-
-By setting an appropriate security level much of this complexity can be
-avoided.
-
-The bits of security limits affect all relevant parameters including
-ciphersuite encryption algorithms, supported ECC curves, supported
-signature algorithms, DH parameter sizes, certificate key sizes and
-signature algorithms. This limit applies no matter what other custom
-settings an application has set: so if the ciphersuite is set to B<ALL>
-then only ciphersuites consistent with the security level are permissible.
-
-See SP800-57 for how the security limits are related to individual
-algorithms.
-
-Some security levels require large key sizes for non-ECC public key
-algorithms which can severely degrade performance. For example 256 bits
-of security requires the use of RSA keys of at least 15360 bits in size.
-
-Some restrictions can be gracefully handled: for example ciphersuites
-offering insufficient security are not sent by the client and will not
-be selected by the server. Other restrictions such as the peer certificate
-key size or the DH parameter size will abort the handshake with a fatal
-alert.
-
-Attempts to set certificates or parameters with insufficient security are
-also blocked. For example trying to set a certificate using a 512 bit RSA
-key using SSL_CTX_use_certificate() at level 1. Applications which do not
-check the return values for errors will misbehave: for example it might
-appear that a certificate is not set at all because it had been rejected.
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
- long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_session_cache_mode() enables/disables session caching
-by setting the operational mode for B<ctx> to <mode>.
-
-SSL_CTX_get_session_cache_mode() returns the currently used cache mode.
-
-=head1 NOTES
-
-The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
-The sessions can be held in memory for each B<ctx>, if more than one
-SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
-object.
-
-In order to reuse a session, a client must send the session's id to the
-server. It can only send exactly one id. The server then either
-agrees to reuse the session or it starts a full handshake (to create a new
-session).
-
-A server will 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
-L<SSL_CTX_set_session_id_context(3)>).
-
-The following session cache modes and modifiers are available:
-
-=over 4
-
-=item SSL_SESS_CACHE_OFF
-
-No session caching for client or server takes place.
-
-=item SSL_SESS_CACHE_CLIENT
-
-Client sessions are added to the session cache. As there is no reliable way
-for the OpenSSL library to know whether a session should be reused or which
-session to choose (due to the abstract BIO layer the SSL engine does not
-have details about the connection), the application must select the session
-to be reused by using the L<SSL_set_session(3)>
-function. This option is not activated by default.
-
-=item SSL_SESS_CACHE_SERVER
-
-Server sessions are added to the session cache. When a client proposes a
-session to be reused, the server looks for the corresponding session in (first)
-the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set),
-then (second) in the external cache if available. If the session is found, the
-server will try to reuse the session. This is the default.
-
-=item SSL_SESS_CACHE_BOTH
-
-Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
-
-=item SSL_SESS_CACHE_NO_AUTO_CLEAR
-
-Normally the session cache is checked for expired sessions every
-255 connections using the
-L<SSL_CTX_flush_sessions(3)> function. Since
-this may lead to a delay which cannot be controlled, the automatic
-flushing may be disabled and
-L<SSL_CTX_flush_sessions(3)> can be called
-explicitly by the application.
-
-=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
-
-By setting this flag, session-resume operations in an SSL/TLS server will not
-automatically look up sessions in the internal cache, even if sessions are
-automatically stored there. If external session caching callbacks are in use,
-this flag guarantees that all lookups are directed to the external cache.
-As automatic lookup only applies for SSL/TLS servers, the flag has no effect on
-clients.
-
-=item SSL_SESS_CACHE_NO_INTERNAL_STORE
-
-Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER,
-sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
-Normally a new session is added to the internal cache as well as any external
-session caching (callback) that is configured for the SSL_CTX. This flag will
-prevent sessions being stored in the internal cache (though the application can
-add them manually using L<SSL_CTX_add_session(3)>). Note:
-in any SSL/TLS servers where external caching is configured, any successful
-session lookups in the external cache (ie. for session-resume requests) would
-normally be copied into the local cache before processing continues - this flag
-prevents these additions to the internal cache as well.
-
-=item SSL_SESS_CACHE_NO_INTERNAL
-
-Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and
-SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time.
-
-
-=back
-
-The default mode is SSL_SESS_CACHE_SERVER.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_session_cache_mode() returns the previously set cache mode.
-
-SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
-
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_set_session(3)>,
-L<SSL_session_reused(3)>,
-L<SSL_CTX_add_session(3)>,
-L<SSL_CTX_sess_number(3)>,
-L<SSL_CTX_sess_set_cache_size(3)>,
-L<SSL_CTX_sess_set_get_cb(3)>,
-L<SSL_CTX_set_session_id_context(3)>,
-L<SSL_CTX_set_timeout(3)>,
-L<SSL_CTX_flush_sessions(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only)
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx,
- unsigned int sid_ctx_len);
- int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
- unsigned int sid_ctx_len);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length
-B<sid_ctx_len> within which a session can be reused for the B<ctx> object.
-
-SSL_set_session_id_context() sets the context B<sid_ctx> of length
-B<sid_ctx_len> within which a session can be reused for the B<ssl> object.
-
-=head1 NOTES
-
-Sessions are generated within a certain context. When exporting/importing
-sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible,
-to re-import a session generated from another context (e.g. another
-application), which might lead to malfunctions. Therefore each application
-must set its own session id context B<sid_ctx> which is used to distinguish
-the contexts and is stored in exported sessions. The B<sid_ctx> can be
-any kind of binary data with a given length, it is therefore possible
-to use e.g. the name of the application and/or the hostname and/or service
-name ...
-
-The session id context becomes part of the session. The session id context
-is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and
-SSL_set_session_id_context() functions are therefore only useful on the
-server side.
-
-OpenSSL clients will check the session id context returned by the server
-when reusing a session.
-
-The maximum length of the B<sid_ctx> is limited to
-B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
-
-=head1 WARNINGS
-
-If the session id context is not set on an SSL/TLS server and client
-certificates are used, stored sessions
-will not be reused but a fatal error will be flagged and the handshake
-will fail.
-
-If a server returns a different session id context to an OpenSSL client
-when reusing a session, an error will be flagged and the handshake will
-fail. OpenSSL servers will always return the correct session id context,
-as an OpenSSL server checks the session id context itself before reusing
-a session as described above.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_session_id_context() and SSL_set_session_id_context()
-return the following values:
-
-=over 4
-
-=item Z<>0
-
-The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded
-the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error
-is logged to the error stack.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment,
-SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment,
-SSL_CTX_set_max_pipelines, SSL_set_max_pipelines,
-SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control
-fragment sizes and pipelining operations
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
- long SSL_set_max_send_fragment(SSL *ssl, long m);
-
- long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
- long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
-
- long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
- long SSL_set_split_send_fragment(SSL *ssl, long m);
-
- void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
- void SSL_set_default_read_buffer_len(SSL *s, size_t len);
-
-=head1 DESCRIPTION
-
-Some engines are able to process multiple simultaneous crypto operations. This
-capability could be utilised to parallelise the processing of a single
-connection. For example a single write can be split into multiple records and
-each one encrypted independently and in parallel. Note: this will only work in
-TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This
-capability is known as "pipelining" within OpenSSL.
-
-In order to benefit from the pipelining capability. You need to have an engine
-that provides ciphers that support this. The OpenSSL "dasync" engine provides
-AES128-SHA based ciphers that have this capability. However these are for
-development and test purposes only.
-
-SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the
-B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This
-value restricts the amount of plaintext bytes that will be sent in any one
-SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These
-functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH.
-
-SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number
-of pipelines that will be used at any one time. This value applies to both
-"read" pipelining and "write" pipelining. By default only one pipeline will be
-used (i.e. normal non-parallel operation). The number of pipelines set must be
-in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also
-automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is
-explained further below. OpenSSL will only every use more than one pipeline if
-a ciphersuite is negotiated that uses a pipeline capable cipher provided by an
-engine.
-
-Pipelining operates slightly differently for reading encrypted data compared to
-writing encrypted data. SSL_CTX_set_split_send_fragment() and
-SSL_set_split_send_fragment() define how data is split up into pipelines when
-writing encrypted data. The number of pipelines used will be determined by the
-amount of data provided to the SSL_write() call divided by
-B<split_send_fragment>.
-
-For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
-then:
-
-SSL_write called with 0-2000 bytes == 1 pipeline used
-
-SSL_write called with 2001-4000 bytes == 2 pipelines used
-
-SSL_write called with 4001-6000 bytes == 3 pipelines used
-
-SSL_write called with 6001+ bytes == 4 pipelines used
-
-B<split_send_fragment> must always be less than or equal to
-B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
-This will mean that the same number of records will always be created as would
-have been created in the non-parallel case, although the data will be
-apportioned differently. In the parallel case data will be spread equally
-between the pipelines.
-
-Read pipelining is controlled in a slightly different way than with write
-pipelining. While reading we are constrained by the number of records that the
-peer (and the network) can provide to us in one go. The more records we can get
-in one go the more opportunity we have to parallelise the processing. As noted
-above when setting B<max_pipelines> to a value greater than one, B<read_ahead>
-is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to
-read as much data into the read buffer as the network can provide and will fit
-into the buffer. Without this set data is read into the read buffer one record
-at a time. The more data that can be read, the more opportunity there is for
-parallelising the processing at the cost of increased memory overhead per
-connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
-function (see L<SSL_pending(3)>).
-
-The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
-functions control the size of the read buffer that will be used. The B<len>
-parameter sets the size of the buffer. The value will only be used if it is
-greater than the default that would have been used anyway. The normal default
-value depends on a number of factors but it will be at least
-SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes.
-
-=head1 RETURN VALUES
-
-All non-void functions return 1 on success and 0 on failure.
-
-=head1 NOTES
-
-With the exception of SSL_CTX_set_default_read_buffer_len() and
-SSL_set_default_read_buffer_len() all these functions are implemented using
-macros.
-
-=head1 HISTORY
-
-The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(),
-SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(),
-SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
-functions were added in OpenSSL 1.1.0.
-
-=head1 SEE ALSO
-
-L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method
-- choose a new TLS/SSL method
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *method);
- int SSL_set_ssl_method(SSL *s, const SSL_METHOD *method);
- const SSL_METHOD *SSL_get_ssl_method(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects
-newly created from this B<ctx>. SSL objects already created with
-L<SSL_new(3)> are not affected, except when
-L<SSL_clear(3)> is being called.
-
-SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl>
-object. It may be reset, when SSL_clear() is called.
-
-SSL_get_ssl_method() returns a function pointer to the TLS/SSL method
-set in B<ssl>.
-
-=head1 NOTES
-
-The available B<method> choices are described in
-L<SSL_CTX_new(3)>.
-
-When L<SSL_clear(3)> is called and no session is connected to
-an SSL object, the method of the SSL object is reset to the method currently
-set in the corresponding SSL_CTX object.
-
-=head1 RETURN VALUES
-
-The following return values can occur for SSL_CTX_set_ssl_version()
-and SSL_set_ssl_method():
-
-=over 4
-
-=item Z<>0
-
-The new choice failed, check the error stack to find out the reason.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_CTX_new(3)>, L<SSL_new(3)>,
-L<SSL_clear(3)>, L<ssl(3)>,
-L<SSL_set_connect_state(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_CTX_set_timeout(SSL_CTX *ctx, long t);
- long SSL_CTX_get_timeout(SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_timeout() sets the timeout for newly created sessions for
-B<ctx> to B<t>. The timeout value B<t> must be given in seconds.
-
-SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>.
-
-=head1 NOTES
-
-Whenever a new session is created, it is assigned a maximum lifetime. This
-lifetime is specified by storing the creation time of the session and the
-timeout value valid at this time. If the actual time is later than creation
-time plus timeout, the session is not reused.
-
-Due to this realization, all sessions behave according to the timeout value
-valid at the time of the session negotiation. Changes of the timeout value
-do not affect already established sessions.
-
-The expiration time of a single session can be modified using the
-L<SSL_SESSION_get_time(3)> family of functions.
-
-Expired sessions are removed from the internal session cache, whenever
-L<SSL_CTX_flush_sessions(3)> is called, either
-directly by the application or automatically (see
-L<SSL_CTX_set_session_cache_mode(3)>)
-
-The default value for session timeout is decided on a per protocol
-basis, see L<SSL_get_default_timeout(3)>.
-All currently supported protocols have the same default timeout value
-of 300 seconds.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_timeout() returns the previously set timeout value.
-
-SSL_CTX_get_timeout() returns the currently set timeout value.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_SESSION_get_time(3)>,
-L<SSL_CTX_flush_sessions(3)>,
-L<SSL_get_default_timeout(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_tlsext_status_cb,
-SSL_CTX_get_tlsext_status_cb,
-SSL_CTX_set_tlsext_status_arg,
-SSL_CTX_get_tlsext_status_arg,
-SSL_CTX_set_tlsext_status_type,
-SSL_CTX_get_tlsext_status_type,
-SSL_set_tlsext_status_type,
-SSL_get_tlsext_status_type,
-SSL_get_tlsext_status_ocsp_resp,
-SSL_set_tlsext_status_ocsp_resp
-- OCSP Certificate Status Request functions
-
-=head1 SYNOPSIS
-
- #include <openssl/tls1.h>
-
- long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx,
- int (*callback)(SSL *, void *));
- long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx,
- int (**callback)(SSL *, void *));
-
- long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
- long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg);
-
- long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type);
- long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx);
-
- long SSL_set_tlsext_status_type(SSL *s, int type);
- long SSL_get_tlsext_status_type(SSL *s);
-
- long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
- long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
-
-=head1 DESCRIPTION
-
-A client application may request that a server send back an OCSP status response
-(also known as OCSP stapling). To do so the client should call the
-SSL_CTX_set_tlsext_status_type() function prior to the creation of any SSL
-objects. Alternatively an application can call the SSL_set_tlsext_status_type()
-function on an individual SSL object prior to the start of the handshake.
-Currently the only supported type is B<TLSEXT_STATUSTYPE_ocsp>. This value
-should be passed in the B<type> argument. Calling
-SSL_CTX_get_tlsext_status_type() will return the type B<TLSEXT_STATUSTYPE_ocsp>
-previously set via SSL_CTX_set_tlsext_status_type() or -1 if not set.
-
-The client should additionally provide a callback function to decide what to do
-with the returned OCSP response by calling SSL_CTX_set_tlsext_status_cb(). The
-callback function should determine whether the returned OCSP response is
-acceptable or not. The callback will be passed as an argument the value
-previously set via a call to SSL_CTX_set_tlsext_status_arg(). Note that the
-callback will not be called in the event of a handshake where session resumption
-occurs (because there are no Certificates exchanged in such a handshake).
-The callback previously set via SSL_CTX_set_tlsext_status_cb() can be retrieved
-by calling SSL_CTX_get_tlsext_status_cb(), and the argument by calling
-SSL_CTX_get_tlsext_status_arg().
-
-On the client side SSL_get_tlsext_status_type() can be used to determine whether
-the client has previously called SSL_set_tlsext_status_type(). It will return
-B<TLSEXT_STATUSTYPE_ocsp> if it has been called or -1 otherwise. On the server
-side SSL_get_tlsext_status_type() can be used to determine whether the client
-requested OCSP stapling. If the client requested it then this function will
-return B<TLSEXT_STATUSTYPE_ocsp>, or -1 otherwise.
-
-The response returned by the server can be obtained via a call to
-SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to point
-to the OCSP response data and the return value will be the length of that data.
-Typically a callback would obtain an OCSP_RESPONSE object from this data via a
-call to the d2i_OCSP_RESPONSE() function. If the server has not provided any
-response data then B<*resp> will be NULL and the return value from
-SSL_get_tlsext_status_ocsp_resp() will be -1.
-
-A server application must also call the SSL_CTX_set_tlsext_status_cb() function
-if it wants to be able to provide clients with OCSP Certificate Status
-responses. Typically the server callback would obtain the server certificate
-that is being sent back to the client via a call to SSL_get_certificate();
-obtain the OCSP response to be sent back; and then set that response data by
-calling SSL_set_tlsext_status_ocsp_resp(). A pointer to the response data should
-be provided in the B<resp> argument, and the length of that data should be in
-the B<len> argument.
-
-=head1 RETURN VALUES
-
-The callback when used on the client side should return a negative value on
-error; 0 if the response is not acceptable (in which case the handshake will
-fail) or a positive value if it is acceptable.
-
-The callback when used on the server side should return with either
-SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be
-returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be
-returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has
-occurred).
-
-SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(),
-SSL_CTX_set_tlsext_status_type(), SSL_set_tlsext_status_type() and
-SSL_set_tlsext_status_ocsp_resp() return 0 on error or 1 on success.
-
-SSL_CTX_get_tlsext_status_type() returns the value previously set by
-SSL_CTX_set_tlsext_status_type(), or -1 if not set.
-
-SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data
-or -1 if there is no OCSP response data.
-
-SSL_get_tlsext_status_type() returns B<TLSEXT_STATUSTYPE_ocsp> on the client
-side if SSL_set_tlsext_status_type() was previously called, or on the server
-side if the client requested OCSP stapling. Otherwise -1 is returned.
-
-=head1 HISTORY
-
-SSL_get_tlsext_status_type(), SSL_CTX_get_tlsext_status_type() and
-SSL_CTX_set_tlsext_status_type() were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing
-
-=head1 SYNOPSIS
-
- #include <openssl/tls1.h>
-
- long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
- int (*cb)(SSL *s, unsigned char key_name[16],
- unsigned char iv[EVP_MAX_IV_LENGTH],
- EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_tlsext_ticket_key_cb() sets a callback function I<cb> for handling
-session tickets for the ssl context I<sslctx>. Session tickets, defined in
-RFC5077 provide an enhanced session resumption capability where the server
-implementation is not required to maintain per session state. It only applies
-to TLS and there is no SSLv3 implementation.
-
-The callback function I<cb> will be called for every client instigated TLS
-session when session ticket extension is presented in the TLS hello
-message. It is the responsibility of this function to create or retrieve the
-cryptographic parameters and to maintain their state.
-
-The OpenSSL library uses your callback function to help implement a common TLS
-ticket construction state according to RFC5077 Section 4 such that per session
-state is unnecessary and a small set of cryptographic variables needs to be
-maintained by the callback function implementation.
-
-In order to reuse a session, a TLS client must send the a session ticket
-extension to the server. The client can only send exactly one session ticket.
-The server, through the callback function, either agrees to reuse the session
-ticket information or it starts a full TLS handshake to create a new session
-ticket.
-
-Before the callback function is started I<ctx> and I<hctx> have been
-initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively.
-
-For new sessions tickets, when the client doesn't present a session ticket, or
-an attempted retrieval of the ticket failed, or a renew option was indicated,
-the callback function will be called with I<enc> equal to 1. The OpenSSL
-library expects that the function will set an arbitrary I<name>, initialize
-I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>.
-
-The I<name> is 16 characters long and is used as a key identifier.
-
-The I<iv> length is the length of the IV of the corresponding cipher. The
-maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
-
-The initialization vector I<iv> should be a random value. The cipher context
-I<ctx> should use the initialisation vector I<iv>. The cipher context can be
-set using L<EVP_EncryptInit_ex(3)>. The hmac context can be set using
-L<HMAC_Init_ex(3)>.
-
-When the client presents a session ticket, the callback function with be called
-with I<enc> set to 0 indicating that the I<cb> function should retrieve a set
-of parameters. In this case I<name> and I<iv> have already been parsed out of
-the session ticket. The OpenSSL library expects that the I<name> will be used
-to retrieve a cryptographic parameters and that the cryptographic context
-I<ctx> will be set with the retrieved parameters and the initialization vector
-I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The I<hctx> needs to be
-set using L<HMAC_Init_ex(3)>.
-
-If the I<name> is still valid but a renewal of the ticket is required the
-callback function should return 2. The library will call the callback again
-with an argument of enc equal to 1 to set the new ticket.
-
-The return value of the I<cb> function is used by OpenSSL to determine what
-further processing will occur. The following return values have meaning:
-
-=over 4
-
-=item Z<>2
-
-This indicates that the I<ctx> and I<hctx> have been set and the session can
-continue on those parameters. Additionally it indicates that the session
-ticket is in a renewal period and should be replaced. The OpenSSL library will
-call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077
-3.3 paragraph 2).
-
-=item Z<>1
-
-This indicates that the I<ctx> and I<hctx> have been set and the session can
-continue on those parameters.
-
-=item Z<>0
-
-This indicates that it was not possible to set/retrieve a session ticket and
-the SSL/TLS session will continue by negotiating a set of cryptographic
-parameters or using the alternate SSL/TLS resumption mechanism, session ids.
-
-If called with enc equal to 0 the library will call the I<cb> again to get
-a new set of parameters.
-
-=item less than 0
-
-This indicates an error.
-
-=back
-
-=head1 NOTES
-
-Session resumption shortcuts the TLS so that the client certificate
-negotiation don't occur. It makes up for this by storing client certificate
-an all other negotiated state information encrypted within the ticket. In a
-resumed session the applications will have all this state information available
-exactly as if a full negotiation had occurred.
-
-If an attacker can obtain the key used to encrypt a session ticket, they can
-obtain the master secret for any ticket using that key and decrypt any traffic
-using that session: even if the ciphersuite supports forward secrecy. As
-a result applications may wish to use multiple keys and avoid using long term
-keys stored in files.
-
-Applications can use longer keys to maintain a consistent level of security.
-For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key
-the overall security is only 128 bits because breaking the ticket key will
-enable an attacker to obtain the session keys.
-
-=head1 EXAMPLES
-
-Reference Implementation:
- SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
- ....
-
- static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
- {
- if (enc) { /* create new session */
- if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) {
- return -1; /* insufficient random */
- }
-
- key = currentkey(); /* something that you need to implement */
- if ( !key ) {
- /* current key doesn't exist or isn't valid */
- key = createkey(); /* something that you need to implement.
- * createkey needs to initialise, a name,
- * an aes_key, a hmac_key and optionally
- * an expire time. */
- if ( !key ) { /* key couldn't be created */
- return 0;
- }
- }
- memcpy(key_name, key->name, 16);
-
- EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
- HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
-
- return 1;
-
- } else { /* retrieve session */
- key = findkey(name);
-
- if (!key || key->expire < now() ) {
- return 0;
- }
-
- HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
- EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv );
-
- if (key->expire < ( now() - RENEW_TIME ) ) {
- /* return 2 - this session will get a new ticket even though the current is still valid */
- return 2;
- }
- return 1;
-
- }
- }
-
-
-
-=head1 RETURN VALUES
-
-returns 0 to indicate the callback function was set.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_set_session(3)>,
-L<SSL_session_reused(3)>,
-L<SSL_CTX_add_session(3)>,
-L<SSL_CTX_sess_number(3)>,
-L<SSL_CTX_sess_set_get_cb(3)>,
-L<SSL_CTX_set_session_id_context(3)>,
-
-=head1 COPYRIGHT
-
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
- DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
- long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
-
- void SSL_set_tmp_dh_callback(SSL *ctx,
- DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
- long SSL_set_tmp_dh(SSL *ssl, DH *dh)
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be
-used when a DH parameters are required to B<tmp_dh_callback>.
-The callback is inherited by all B<ssl> objects created from B<ctx>.
-
-SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>.
-The key is inherited by all B<ssl> objects created from B<ctx>.
-
-SSL_set_tmp_dh_callback() sets the callback only for B<ssl>.
-
-SSL_set_tmp_dh() sets the parameters only for B<ssl>.
-
-These functions apply to SSL/TLS servers only.
-
-=head1 NOTES
-
-When using a cipher with RSA authentication, an ephemeral DH key exchange
-can take place. Ciphers with DSA keys always use ephemeral DH keys as well.
-In these cases, the session data are negotiated using the
-ephemeral/temporary DH key and the key supplied and certified
-by the certificate chain is only used for signing.
-Anonymous ciphers (without a permanent server key) also use ephemeral DH keys.
-
-Using ephemeral DH key exchange yields forward secrecy, as the connection
-can only be decrypted, when the DH key is known. By generating a temporary
-DH key inside the server application that is lost when the application
-is left, it becomes impossible for an attacker to decrypt past sessions,
-even if he gets hold of the normal (certified) key, as this key was
-only used for signing.
-
-In order to perform a DH key exchange the server must use a DH group
-(DH parameters) and generate a DH key. The server will always generate
-a new DH key during the negotiation.
-
-As generating DH parameters is extremely time consuming, an application
-should not generate the parameters on the fly but supply the parameters.
-DH parameters can be reused, as the actual key is newly generated during
-the negotiation. The risk in reusing DH parameters is that an attacker
-may specialize on a very often used DH group. Applications should therefore
-generate their own DH parameters during the installation process using the
-openssl L<dhparam(1)> application. This application
-guarantees that "strong" primes are used.
-
-Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current
-version of the OpenSSL distribution contain the 'SKIP' DH parameters,
-which use safe primes and were generated verifiably pseudo-randomly.
-These files can be converted into C code using the B<-C> option of the
-L<dhparam(1)> application. Generation of custom DH
-parameters during installation should still be preferred to stop an
-attacker from specializing on a commonly used group. File dh1024.pem
-contains old parameters that must not be used by applications.
-
-An application may either directly specify the DH parameters or
-can supply the DH parameters via a callback function.
-
-Previous versions of the callback used B<is_export> and B<keylength>
-parameters to control parameter generation for export and non-export
-cipher suites. Modern servers that do not support export ciphersuites
-are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use
-the callback but ignore B<keylength> and B<is_export> and simply
-supply at least 2048-bit parameters in the callback.
-
-=head1 EXAMPLES
-
-Setup DH parameters with a key length of 2048 bits. (Error handling
-partly left out.)
-
- Command-line parameter generation:
- $ openssl dhparam -out dh_param_2048.pem 2048
-
- Code for setting up parameters during server initialization:
-
- ...
- SSL_CTX ctx = SSL_CTX_new();
- ...
-
- /* Set up ephemeral DH parameters. */
- DH *dh_2048 = NULL;
- FILE *paramfile;
- paramfile = fopen("dh_param_2048.pem", "r");
- if (paramfile) {
- dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
- fclose(paramfile);
- } else {
- /* Error. */
- }
- if (dh_2048 == NULL) {
- /* Error. */
- }
- if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
- /* Error. */
- }
- ...
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
-diagnostic output.
-
-SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
-on failure. Check the error queue to find out the reason of failure.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>,
-L<SSL_CTX_set_options(3)>,
-L<ciphers(1)>, L<dhparam(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
- int (*verify_callback)(int, X509_STORE_CTX *));
- void SSL_set_verify(SSL *s, int mode,
- int (*verify_callback)(int, X509_STORE_CTX *));
- void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth);
- void SSL_set_verify_depth(SSL *s, int depth);
-
- int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
-specifies the B<verify_callback> function to be used. If no callback function
-shall be specified, the NULL pointer can be used for B<verify_callback>.
-
-SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
-specifies the B<verify_callback> function to be used. If no callback function
-shall be specified, the NULL pointer can be used for B<verify_callback>. In
-this case last B<verify_callback> set specifically for this B<ssl> remains. If
-no special B<callback> was set before, the default callback for the underlying
-B<ctx> is used, that was valid at the time B<ssl> was created with
-L<SSL_new(3)>.
-
-SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
-verification that shall be allowed for B<ctx>. (See the BUGS section.)
-
-SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
-verification that shall be allowed for B<ssl>. (See the BUGS section.)
-
-=head1 NOTES
-
-The verification of certificates can be controlled by a set of logically
-or'ed B<mode> flags:
-
-=over 4
-
-=item SSL_VERIFY_NONE
-
-B<Server mode:> the server will not send a client certificate request to the
-client, so the client will not send a certificate.
-
-B<Client mode:> if not using an anonymous cipher (by default disabled), the
-server will send a certificate which will be checked. The result of the
-certificate verification process can be checked after the TLS/SSL handshake
-using the L<SSL_get_verify_result(3)> function.
-The handshake will be continued regardless of the verification result.
-
-=item SSL_VERIFY_PEER
-
-B<Server mode:> the server sends a client certificate request to the client.
-The certificate returned (if any) is checked. If the verification process
-fails, the TLS/SSL handshake is
-immediately terminated with an alert message containing the reason for
-the verification failure.
-The behaviour can be controlled by the additional
-SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags.
-
-B<Client mode:> the server certificate is verified. If the verification process
-fails, the TLS/SSL handshake is
-immediately terminated with an alert message containing the reason for
-the verification failure. If no server certificate is sent, because an
-anonymous cipher is used, SSL_VERIFY_PEER is ignored.
-
-=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT
-
-B<Server mode:> if the client did not return a certificate, the TLS/SSL
-handshake is immediately terminated with a "handshake failure" alert.
-This flag must be used together with SSL_VERIFY_PEER.
-
-B<Client mode:> ignored
-
-=item SSL_VERIFY_CLIENT_ONCE
-
-B<Server mode:> only request a client certificate on the initial TLS/SSL
-handshake. Do not ask for a client certificate again in case of a
-renegotiation. This flag must be used together with SSL_VERIFY_PEER.
-
-B<Client mode:> ignored
-
-=back
-
-If the B<mode> is SSL_VERIFY_NONE none of the other flags may be set.
-
-The actual verification procedure is performed either using the built-in
-verification procedure or using another application provided verification
-function set with
-L<SSL_CTX_set_cert_verify_callback(3)>.
-The following descriptions apply in the case of the built-in procedure. An
-application provided procedure also has access to the verify depth information
-and the verify_callback() function, but the way this information is used
-may be different.
-
-SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up
-to which depth certificates in a chain are used during the verification
-procedure. If the certificate chain is longer than allowed, the certificates
-above the limit are ignored. Error messages are generated as if these
-certificates would not be present, most likely a
-X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
-The depth count is "level 0:peer certificate", "level 1: CA certificate",
-"level 2: higher level CA certificate", and so on. Setting the maximum
-depth to 2 allows the levels 0, 1, and 2. The default depth limit is 100,
-allowing for the peer certificate and additional 100 CA certificates.
-
-The B<verify_callback> function is used to control the behaviour when the
-SSL_VERIFY_PEER flag is set. It must be supplied by the application and
-receives two arguments: B<preverify_ok> indicates, whether the verification of
-the certificate in question was passed (preverify_ok=1) or not
-(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used
-for the certificate chain verification.
-
-The certificate chain is checked starting with the deepest nesting level
-(the root CA certificate) and worked upward to the peer's certificate.
-At each level signatures and issuer attributes are checked. Whenever
-a verification error is found, the error number is stored in B<x509_ctx>
-and B<verify_callback> is called with B<preverify_ok>=0. By applying
-X509_CTX_store_* functions B<verify_callback> can locate the certificate
-in question and perform additional steps (see EXAMPLES). If no error is
-found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
-before advancing to the next level.
-
-The return value of B<verify_callback> controls the strategy of the further
-verification process. If B<verify_callback> returns 0, the verification
-process is immediately stopped with "verification failed" state. If
-SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
-the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
-the verification process is continued. If B<verify_callback> always returns
-1, the TLS/SSL handshake will not be terminated with respect to verification
-failures and the connection will be established. The calling process can
-however retrieve the error code of the last verification error using
-L<SSL_get_verify_result(3)> or by maintaining its
-own error storage managed by B<verify_callback>.
-
-If no B<verify_callback> is specified, the default callback will be used.
-Its return value is identical to B<preverify_ok>, so that any verification
-failure will lead to a termination of the TLS/SSL handshake with an
-alert message, if SSL_VERIFY_PEER is set.
-
-=head1 RETURN VALUES
-
-The SSL*_set_verify*() functions do not provide diagnostic information.
-
-=head1 EXAMPLES
-
-The following code sequence realizes an example B<verify_callback> function
-that will always continue the TLS/SSL handshake regardless of verification
-failure, if wished. The callback realizes a verification depth limit with
-more informational output.
-
-All verification errors are printed; information about the certificate chain
-is printed on request.
-The example is realized for a server that does allow but not require client
-certificates.
-
-The example makes use of the ex_data technique to store application data
-into/retrieve application data from the SSL structure
-(see L<SSL_get_ex_new_index(3)>,
-L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
-
- ...
- typedef struct {
- int verbose_mode;
- int verify_depth;
- int always_continue;
- } mydata_t;
- int mydata_index;
- ...
- static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
- {
- char buf[256];
- X509 *err_cert;
- int err, depth;
- SSL *ssl;
- mydata_t *mydata;
-
- err_cert = X509_STORE_CTX_get_current_cert(ctx);
- err = X509_STORE_CTX_get_error(ctx);
- depth = X509_STORE_CTX_get_error_depth(ctx);
-
- /*
- * Retrieve the pointer to the SSL of the connection currently treated
- * and the application specific data stored into the SSL object.
- */
- ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
- mydata = SSL_get_ex_data(ssl, mydata_index);
-
- X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
-
- /*
- * Catch a too long certificate chain. The depth limit set using
- * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
- * that whenever the "depth>verify_depth" condition is met, we
- * have violated the limit and want to log this error condition.
- * We must do it here, because the CHAIN_TOO_LONG error would not
- * be found explicitly; only errors introduced by cutting off the
- * additional certificates would be logged.
- */
- if (depth > mydata->verify_depth) {
- preverify_ok = 0;
- err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
- X509_STORE_CTX_set_error(ctx, err);
- }
- if (!preverify_ok) {
- printf("verify error:num=%d:%s:depth=%d:%s\n", err,
- X509_verify_cert_error_string(err), depth, buf);
- }
- else if (mydata->verbose_mode)
- {
- printf("depth=%d:%s\n", depth, buf);
- }
-
- /*
- * At this point, err contains the last verification error. We can use
- * it for something special
- */
- if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT))
- {
- X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256);
- printf("issuer= %s\n", buf);
- }
-
- if (mydata->always_continue)
- return 1;
- else
- return preverify_ok;
- }
- ...
-
- mydata_t mydata;
-
- ...
- mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
-
- ...
- SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
- verify_callback);
-
- /*
- * Let the verify_callback catch the verify_depth error so that we get
- * an appropriate error in the logfile.
- */
- SSL_CTX_set_verify_depth(verify_depth + 1);
-
- /*
- * Set up the SSL specific data into "mydata" and store it into th SSL
- * structure.
- */
- mydata.verify_depth = verify_depth; ...
- SSL_set_ex_data(ssl, mydata_index, &mydata);
-
- ...
- SSL_accept(ssl); /* check of success left out for clarity */
- if (peer = SSL_get_peer_certificate(ssl))
- {
- if (SSL_get_verify_result(ssl) == X509_V_OK)
- {
- /* The client sent a certificate which verified OK */
- }
- }
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_new(3)>,
-L<SSL_CTX_get_verify_mode(3)>,
-L<SSL_get_verify_result(3)>,
-L<SSL_CTX_load_verify_locations(3)>,
-L<SSL_get_peer_certificate(3)>,
-L<SSL_CTX_set_cert_verify_callback(3)>,
-L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
-L<SSL_get_ex_new_index(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1,
-SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1,
-SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file,
-SSL_use_certificate_chain_file,
-SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1,
-SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey,
-SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file,
-SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey,
-SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1,
-SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key
-- load certificate and key data
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
- int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
- int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
- int SSL_use_certificate(SSL *ssl, X509 *x);
- int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
- int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
-
- int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
- int SSL_use_certificate_chain_file(SSL *ssl, const char *file);
-
- int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
- int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
- long len);
- int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
- int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
- int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
- int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
- int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
- int SSL_use_PrivateKey_ASN1(int pk, SSL *ssl, unsigned char *d, long len);
- int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
- int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
- int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
- int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
-
- int SSL_CTX_check_private_key(const SSL_CTX *ctx);
- int SSL_check_private_key(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-These functions load the certificates and private keys into the SSL_CTX
-or SSL object, respectively.
-
-The SSL_CTX_* class of functions loads the certificates and keys into the
-SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl>
-created from B<ctx> with L<SSL_new(3)> by copying, so that
-changes applied to B<ctx> do not propagate to already existing SSL objects.
-
-The SSL_* class of functions only loads certificates and keys into a
-specific SSL object. The specific information is kept, when
-L<SSL_clear(3)> is called for this SSL object.
-
-SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>,
-SSL_use_certificate() loads B<x> into B<ssl>. The rest of the
-certificates needed to form the complete certificate chain can be
-specified using the
-L<SSL_CTX_add_extra_chain_cert(3)>
-function.
-
-SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from
-the memory location B<d> (with length B<len>) into B<ctx>,
-SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>.
-
-SSL_CTX_use_certificate_file() loads the first certificate stored in B<file>
-into B<ctx>. The formatting B<type> of the certificate must be specified
-from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
-SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>.
-See the NOTES section on why SSL_CTX_use_certificate_chain_file()
-should be preferred.
-
-SSL_CTX_use_certificate_chain_file() loads a certificate chain from
-B<file> into B<ctx>. The certificates must be in PEM format and must
-be sorted starting with the subject's certificate (actual client or server
-certificate), followed by intermediate CA certificates if applicable, and
-ending at the highest level (root) CA. SSL_use_certificate_chain_file() is
-similar except it loads the certificate chain into B<ssl>.
-
-SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.
-SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA
-to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;
-SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.
-If a certificate has already been set and the private does not belong
-to the certificate an error is returned. To change a certificate, private
-key pair the new certificate needs to be set with SSL_use_certificate()
-or SSL_CTX_use_certificate() before setting the private key with
-SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey().
-
-
-SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>
-stored at memory location B<d> (length B<len>) to B<ctx>.
-SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA
-stored at memory location B<d> (length B<len>) to B<ctx>.
-SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private
-key to B<ssl>.
-
-SSL_CTX_use_PrivateKey_file() adds the first private key found in
-B<file> to B<ctx>. The formatting B<type> of the certificate must be specified
-from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
-SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in
-B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found
-in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private
-RSA key found to B<ssl>.
-
-SSL_CTX_check_private_key() checks the consistency of a private key with
-the corresponding certificate loaded into B<ctx>. If more than one
-key/certificate pair (RSA/DSA) is installed, the last item installed will
-be checked. If e.g. the last item was a RSA certificate or key, the RSA
-key/certificate pair will be checked. SSL_check_private_key() performs
-the same check for B<ssl>. If no key/certificate was explicitly added for
-this B<ssl>, the last item added into B<ctx> will be checked.
-
-=head1 NOTES
-
-The internal certificate store of OpenSSL can hold several private
-key/certificate pairs at a time. The certificate used depends on the
-cipher selected, see also L<SSL_CTX_set_cipher_list(3)>.
-
-When reading certificates and private keys from file, files of type
-SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain
-one certificate or private key, consequently
-SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting.
-Files of type SSL_FILETYPE_PEM can contain more than one item.
-
-SSL_CTX_use_certificate_chain_file() adds the first certificate found
-in the file to the certificate store. The other certificates are added
-to the store of chain certificates using L<SSL_CTX_add1_chain_cert(3)>. Note: versions of OpenSSL before 1.0.2 only had a single
-certificate chain store for all certificate types, OpenSSL 1.0.2 and later
-have a separate chain store for each type. SSL_CTX_use_certificate_chain_file()
-should be used instead of the SSL_CTX_use_certificate_file() function in order
-to allow the use of complete certificate chains even when no trusted CA
-storage is used or when the CA issuing the certificate shall not be added to
-the trusted CA storage.
-
-If additional certificates are needed to complete the chain during the
-TLS negotiation, CA certificates are additionally looked up in the
-locations of trusted CA certificates, see
-L<SSL_CTX_load_verify_locations(3)>.
-
-The private keys loaded from file can be encrypted. In order to successfully
-load encrypted keys, a function returning the passphrase must have been
-supplied, see
-L<SSL_CTX_set_default_passwd_cb(3)>.
-(Certificate files might be encrypted as well from the technical point
-of view, it however does not make sense as the data in the certificate
-is considered public anyway.)
-
-=head1 RETURN VALUES
-
-On success, the functions return 1.
-Otherwise check out the error stack to find out the reason.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>,
-L<SSL_CTX_load_verify_locations(3)>,
-L<SSL_CTX_set_default_passwd_cb(3)>,
-L<SSL_CTX_set_cipher_list(3)>,
-L<SSL_CTX_set_client_CA_list(3)>,
-L<SSL_CTX_set_client_cert_cb(3)>,
-L<SSL_CTX_add_extra_chain_cert(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint,
-SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK
-identity hint to use
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
- int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
-
- void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx,
- unsigned int (*callback)(SSL *ssl, const char *identity,
- unsigned char *psk, int max_psk_len));
- void SSL_set_psk_server_callback(SSL *ssl,
- unsigned int (*callback)(SSL *ssl, const char *identity,
- unsigned char *psk, int max_psk_len));
-
-
-=head1 DESCRIPTION
-
-SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK
-identity hint B<hint> to SSL context object
-B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated
-PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint>
-is B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
-
-In the case where PSK identity hint is B<NULL>, the server
-does not send the ServerKeyExchange message to the client.
-
-A server application must provide a callback function which is called
-when the server receives the ClientKeyExchange message from the
-client. The purpose of the callback function is to validate the
-received PSK identity and to fetch the pre-shared key used during the
-connection setup phase. The callback is set using functions
-SSL_CTX_set_psk_server_callback() or
-SSL_set_psk_server_callback(). The callback function is given the
-connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent
-by the client in parameter B<identity>, and a buffer B<psk> of length
-B<max_psk_len> bytes where the pre-shared key is to be stored.
-
-
-=head1 RETURN VALUES
-
-SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return
-1 on success, 0 otherwise.
-
-Return values from the server callback are interpreted as follows:
-
-=over 4
-
-=item Z<>0
-
-PSK identity was not found. An "unknown_psk_identity" alert message
-will be sent and the connection setup fails.
-
-=item E<gt>0
-
-PSK identity was found and the server callback has provided the PSK
-successfully in parameter B<psk>. Return value is the length of
-B<psk> in bytes. It is an error to return a value greater than
-B<max_psk_len>.
-
-If the PSK identity was not found but the callback instructs the
-protocol to continue anyway, the callback must provide some random
-data to B<psk> and return the length of the random data, so the
-connection will fail with decryption_error before it will be finished
-completely.
-
-=back
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-Copyright 2005 Nokia.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo,
- size_t serverinfo_length);
-
- int SSL_CTX_use_serverinfo_file(SSL_CTX *ctx, const char *file);
-
-=head1 DESCRIPTION
-
-These functions load "serverinfo" TLS ServerHello Extensions into the SSL_CTX.
-A "serverinfo" extension is returned in response to an empty ClientHello
-Extension.
-
-SSL_CTX_use_serverinfo() loads one or more serverinfo extensions from
-a byte array into B<ctx>. The extensions must be concatenated into a
-sequence of bytes. Each extension must consist of a 2-byte Extension Type,
-a 2-byte length, and then length bytes of extension_data.
-
-SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from
-B<file> into B<ctx>. The extensions must be in PEM format. Each extension
-must consist of a 2-byte Extension Type, a 2-byte length, and then length
-bytes of extension_data. Each PEM extension name must begin with the phrase
-"BEGIN SERVERINFO FOR ".
-
-If more than one certificate (RSA/DSA) is installed using
-SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the
-last certificate installed. If e.g. the last item was a RSA certificate, the
-loaded serverinfo extension data will be loaded for that certificate. To
-use the serverinfo extension for multiple certificates,
-SSL_CTX_use_serverinfo() needs to be called multiple times, once B<after>
-each time a certificate is loaded.
-
-=head1 RETURN VALUES
-
-On success, the functions return 1.
-On failure, the functions return 0. Check out the error stack to find out
-the reason.
-
-=head1 COPYRIGHT
-
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_free - free an allocated SSL_SESSION structure
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_SESSION_free(SSL_SESSION *session);
-
-=head1 DESCRIPTION
-
-SSL_SESSION_free() decrements the reference count of B<session> and removes
-the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated
-memory, if the reference count has reached 0.
-If B<session> is NULL nothing is done.
-
-=head1 NOTES
-
-SSL_SESSION objects are allocated, when a TLS/SSL handshake operation
-is successfully completed. Depending on the settings, see
-L<SSL_CTX_set_session_cache_mode(3)>,
-the SSL_SESSION objects are internally referenced by the SSL_CTX and
-linked into its session cache. SSL objects may be using the SSL_SESSION object;
-as a session may be reused, several SSL objects may be using one SSL_SESSION
-object at the same time. It is therefore crucial to keep the reference
-count (usage information) correct and not delete a SSL_SESSION object
-that is still used, as this may lead to program failures due to
-dangling pointers. These failures may also appear delayed, e.g.
-when an SSL_SESSION object was completely freed as the reference count
-incorrectly became 0, but it is still referenced in the internal
-session cache and the cache list is processed during a
-L<SSL_CTX_flush_sessions(3)> operation.
-
-SSL_SESSION_free() must only be called for SSL_SESSION objects, for
-which the reference count was explicitly incremented (e.g.
-by calling SSL_get1_session(), see L<SSL_get_session(3)>)
-or when the SSL_SESSION object was generated outside a TLS handshake
-operation, e.g. by using L<d2i_SSL_SESSION(3)>.
-It must not be called on other SSL_SESSION objects, as this would cause
-incorrect reference counts and therefore program failures.
-
-=head1 RETURN VALUES
-
-SSL_SESSION_free() does not provide diagnostic information.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_session(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_CTX_flush_sessions(3)>,
-L<d2i_SSL_SESSION(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_get0_cipher - retrieve the SSL cipher associated with a session
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSSION *s);
-
-=head1 DESCRIPTION
-
-SSL_SESSION_get0_cipher() retrieves the cipher that was used by the
-connection when the session was created, or NULL if it cannot be determined.
-
-The value returned is a pointer to an object maintained within B<s> and
-should not be released.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<d2i_SSL_SESSION(3)>,
-L<SSL_SESSION_get_time(3)>,
-L<SSL_SESSION_get0_hostname(3)>,
-L<SSL_SESSION_free(3)>
-
-=head1 HISTORY
-
-SSL_SESSION_get0_cipher() was first added to OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_get0_hostname - retrieve the SNI hostname associated with a session
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const char *SSL_SESSION_get0_hostname(const SSL_SESSSION *s);
-
-=head1 DESCRIPTION
-
-SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the
-client when the session was created, or NULL if no value was sent.
-
-The value returned is a pointer to memory maintained within B<s> and
-should not be free'd.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<d2i_SSL_SESSION(3)>,
-L<SSL_SESSION_get_time(3)>,
-L<SSL_SESSION_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_get0_id_context - get the SSL ID context associated with a session
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s,
- unsigned int *len)
-
-=head1 DESCRIPTION
-
-SSL_SESSION_get0_id_context() returns the ID context associated with
-the SSL/TLS session B<s>. The length of the ID context is written to
-B<*len> if B<len> is not NULL.
-
-The value returned is a pointer to an object maintained within B<s> and
-should not be released.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_set_session_id_context(3)>
-
-=head1 HISTORY
-
-SSL_SESSION_get0_id_context() was first added to OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_get_protocol_version - retrieve session protocol version
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_SESSION_get_protocol_version(const SSL_SESSION *s);
-
-=head1 DESCRIPTION
-
-SSL_SESSION_get_protocol_version() returns the protocol version number used
-by session B<s>.
-
-=head1 RETURN VALUES
-
-SSL_SESSION_get_protocol_version() returns a number indicating the protocol
-version used for the session; this number matches the constants I<e.g.>
-B<TLS1_VERSION> or B<TLS1_2_VERSION>.
-
-Note that the SSL_SESSION_get_protocol_version() function
-does B<not> perform a null check on the provided session B<s> pointer.
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 HISTORY
-
-SSL_SESSION_get_protocol_version() was first added to OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout,
-SSL_SESSION_set_timeout
-SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout,
-- retrieve and manipulate session time and timeout settings
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_SESSION_get_time(const SSL_SESSION *s);
- long SSL_SESSION_set_time(SSL_SESSION *s, long tm);
- long SSL_SESSION_get_timeout(const SSL_SESSION *s);
- long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm);
-
- long SSL_get_time(const SSL_SESSION *s);
- long SSL_set_time(SSL_SESSION *s, long tm);
- long SSL_get_timeout(const SSL_SESSION *s);
- long SSL_set_timeout(SSL_SESSION *s, long tm);
-
-=head1 DESCRIPTION
-
-SSL_SESSION_get_time() returns the time at which the session B<s> was
-established. The time is given in seconds since the Epoch and therefore
-compatible to the time delivered by the time() call.
-
-SSL_SESSION_set_time() replaces the creation time of the session B<s> with
-the chosen value B<tm>.
-
-SSL_SESSION_get_timeout() returns the timeout value set for session B<s>
-in seconds.
-
-SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds
-to B<tm>.
-
-The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout()
-functions are synonyms for the SSL_SESSION_*() counterparts.
-
-=head1 NOTES
-
-Sessions are expired by examining the creation time and the timeout value.
-Both are set at creation time of the session to the actual time and the
-default timeout value at creation, respectively, as set by
-L<SSL_CTX_set_timeout(3)>.
-Using these functions it is possible to extend or shorten the lifetime
-of the session.
-
-=head1 RETURN VALUES
-
-SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently
-valid values.
-
-SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success.
-
-If any of the function is passed the NULL pointer for the session B<s>,
-0 is returned.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_timeout(3)>,
-L<SSL_get_default_timeout(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_get0_ticket,
-SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint,
-- get details about the ticket associated with a session
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_SESSION_has_ticket(const SSL_SESSION *s);
- unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s);
- void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick,
- size_t *len);
-
-=head1 DESCRIPTION
-
-SSL_SESSION_has_ticket() returns 1 if there is a Session Ticket associated with
-this session, and 0 otherwise.
-
-SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds
-associated with the session ticket.
-
-SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a
-session. The length of the ticket is written to B<*len>. If B<tick> is non
-NULL then a pointer to the ticket is written to B<*tick>. The pointer is only
-valid while the connection is in use. The session (and hence the ticket pointer)
-may also become invalid as a result of a call to SSL_CTX_flush_sessions().
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<d2i_SSL_SESSION(3)>,
-L<SSL_SESSION_get_time(3)>,
-L<SSL_SESSION_free(3)>
-
-=head1 HISTORY
-
-SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint and
-SSL_SESSION_get0_ticket were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_SESSION_set1_id - set the SSL session ID
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid,
- unsigned int sid_len);
-
-=head1 DESCRIPTION
-
-SSL_SESSION_set1_id() sets the the session ID for the B<ssl> SSL/TLS session
-to B<sid> of length B<sid_len>.
-
-=head1 RETURN VALUES
-
-SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example
-if the supplied session ID length exceeds B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 HISTORY
-
-SSL_SESSION_set1_id() was first added to OpenSSL 1.1.0
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_accept(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL handshake.
-The communication channel must already have been set and assigned to the
-B<ssl> by setting an underlying B<BIO>.
-
-=head1 NOTES
-
-The behaviour of SSL_accept() depends on the underlying BIO.
-
-If the underlying BIO is B<blocking>, SSL_accept() will only return once the
-handshake has been finished or an error occurred.
-
-If the underlying BIO is B<non-blocking>, SSL_accept() will also return
-when the underlying BIO could not satisfy the needs of SSL_accept()
-to continue the handshake, indicating the problem by the return value -1.
-In this case a call to SSL_get_error() with the
-return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
-taking appropriate action to satisfy the needs of SSL_accept().
-The action depends on the underlying BIO. When using a non-blocking socket,
-nothing is to be done, but select() can be used to check for the required
-condition. When using a buffering BIO, like a BIO pair, data must be written
-into or retrieved out of the BIO before being able to continue.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The TLS/SSL handshake was not successful but was shut down controlled and
-by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
-return value B<ret> to find out the reason.
-
-=item Z<>1
-
-The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
-established.
-
-=item E<lt>0
-
-The TLS/SSL handshake was not successful because a fatal error occurred either
-at the protocol level or a connection failure occurred. The shutdown was
-not clean. It can also occur of action is need to continue the operation
-for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
-to find out the reason.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_connect(3)>,
-L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>,
-L<SSL_set_connect_state(3)>,
-L<SSL_do_handshake(3)>,
-L<SSL_CTX_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const char *SSL_alert_type_string(int value);
- const char *SSL_alert_type_string_long(int value);
-
- const char *SSL_alert_desc_string(int value);
- const char *SSL_alert_desc_string_long(int value);
-
-=head1 DESCRIPTION
-
-SSL_alert_type_string() returns a one letter string indicating the
-type of the alert specified by B<value>.
-
-SSL_alert_type_string_long() returns a string indicating the type of the alert
-specified by B<value>.
-
-SSL_alert_desc_string() returns a two letter string as a short form
-describing the reason of the alert specified by B<value>.
-
-SSL_alert_desc_string_long() returns a string describing the reason
-of the alert specified by B<value>.
-
-=head1 NOTES
-
-When one side of an SSL/TLS communication wants to inform the peer about
-a special situation, it sends an alert. The alert is sent as a special message
-and does not influence the normal data stream (unless its contents results
-in the communication being canceled).
-
-A warning alert is sent, when a non-fatal error condition occurs. The
-"close notify" alert is sent as a warning alert. Other examples for
-non-fatal errors are certificate errors ("certificate expired",
-"unsupported certificate"), for which a warning alert may be sent.
-(The sending party may however decide to send a fatal error.) The
-receiving side may cancel the connection on reception of a warning
-alert on it discretion.
-
-Several alert messages must be sent as fatal alert messages as specified
-by the TLS RFC. A fatal alert always leads to a connection abort.
-
-=head1 RETURN VALUES
-
-The following strings can occur for SSL_alert_type_string() or
-SSL_alert_type_string_long():
-
-=over 4
-
-=item "W"/"warning"
-
-=item "F"/"fatal"
-
-=item "U"/"unknown"
-
-This indicates that no support is available for this alert type.
-Probably B<value> does not contain a correct alert message.
-
-=back
-
-The following strings can occur for SSL_alert_desc_string() or
-SSL_alert_desc_string_long():
-
-=over 4
-
-=item "CN"/"close notify"
-
-The connection shall be closed. This is a warning alert.
-
-=item "UM"/"unexpected message"
-
-An inappropriate message was received. This alert is always fatal
-and should never be observed in communication between proper
-implementations.
-
-=item "BM"/"bad record mac"
-
-This alert is returned if a record is received with an incorrect
-MAC. This message is always fatal.
-
-=item "DF"/"decompression failure"
-
-The decompression function received improper input (e.g. data
-that would expand to excessive length). This message is always
-fatal.
-
-=item "HF"/"handshake failure"
-
-Reception of a handshake_failure alert message indicates that the
-sender was unable to negotiate an acceptable set of security
-parameters given the options available. This is a fatal error.
-
-=item "NC"/"no certificate"
-
-A client, that was asked to send a certificate, does not send a certificate
-(SSLv3 only).
-
-=item "BC"/"bad certificate"
-
-A certificate was corrupt, contained signatures that did not
-verify correctly, etc
-
-=item "UC"/"unsupported certificate"
-
-A certificate was of an unsupported type.
-
-=item "CR"/"certificate revoked"
-
-A certificate was revoked by its signer.
-
-=item "CE"/"certificate expired"
-
-A certificate has expired or is not currently valid.
-
-=item "CU"/"certificate unknown"
-
-Some other (unspecified) issue arose in processing the
-certificate, rendering it unacceptable.
-
-=item "IP"/"illegal parameter"
-
-A field in the handshake was out of range or inconsistent with
-other fields. This is always fatal.
-
-=item "DC"/"decryption failed"
-
-A TLSCiphertext decrypted in an invalid way: either it wasn't an
-even multiple of the block length or its padding values, when
-checked, weren't correct. This message is always fatal.
-
-=item "RO"/"record overflow"
-
-A TLSCiphertext record was received which had a length more than
-2^14+2048 bytes, or a record decrypted to a TLSCompressed record
-with more than 2^14+1024 bytes. This message is always fatal.
-
-=item "CA"/"unknown CA"
-
-A valid certificate chain or partial chain was received, but the
-certificate was not accepted because the CA certificate could not
-be located or couldn't be matched with a known, trusted CA. This
-message is always fatal.
-
-=item "AD"/"access denied"
-
-A valid certificate was received, but when access control was
-applied, the sender decided not to proceed with negotiation.
-This message is always fatal.
-
-=item "DE"/"decode error"
-
-A message could not be decoded because some field was out of the
-specified range or the length of the message was incorrect. This
-message is always fatal.
-
-=item "CY"/"decrypt error"
-
-A handshake cryptographic operation failed, including being
-unable to correctly verify a signature, decrypt a key exchange,
-or validate a finished message.
-
-=item "ER"/"export restriction"
-
-A negotiation not in compliance with export restrictions was
-detected; for example, attempting to transfer a 1024 bit
-ephemeral RSA key for the RSA_EXPORT handshake method. This
-message is always fatal.
-
-=item "PV"/"protocol version"
-
-The protocol version the client has attempted to negotiate is
-recognized, but not supported. (For example, old protocol
-versions might be avoided for security reasons). This message is
-always fatal.
-
-=item "IS"/"insufficient security"
-
-Returned instead of handshake_failure when a negotiation has
-failed specifically because the server requires ciphers more
-secure than those supported by the client. This message is always
-fatal.
-
-=item "IE"/"internal error"
-
-An internal error unrelated to the peer or the correctness of the
-protocol makes it impossible to continue (such as a memory
-allocation failure). This message is always fatal.
-
-=item "US"/"user canceled"
-
-This handshake is being canceled for some reason unrelated to a
-protocol failure. If the user cancels an operation after the
-handshake is complete, just closing the connection by sending a
-close_notify is more appropriate. This alert should be followed
-by a close_notify. This message is generally a warning.
-
-=item "NR"/"no renegotiation"
-
-Sent by the client in response to a hello request or by the
-server in response to a client hello after initial handshaking.
-Either of these would normally lead to renegotiation; when that
-is not appropriate, the recipient should respond with this alert;
-at that point, the original requester can decide whether to
-proceed with the connection. One case where this would be
-appropriate would be where a server has spawned a process to
-satisfy a request; the process might receive security parameters
-(key length, authentication, etc.) at startup and it might be
-difficult to communicate changes to these parameters after that
-point. This message is always a warning.
-
-=item "UP"/"unknown PSK identity"
-
-Sent by the server to indicate that it does not recognize a PSK
-identity or an SRP identity.
-
-=item "UK"/"unknown"
-
-This indicates that no description is available for this alert type.
-Probably B<value> does not contain a correct alert message.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_set_info_callback(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_check_chain - check certificate chain suitability
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain);
-
-=head1 DESCRIPTION
-
-SSL_check_chain() checks whether certificate B<x>, private key B<pk> and
-certificate chain B<chain> is suitable for use with the current session
-B<s>.
-
-=head1 RETURN VALUES
-
-SSL_check_chain() returns a bitmap of flags indicating the validity of the
-chain.
-
-B<CERT_PKEY_VALID>: the chain can be used with the current session.
-If this flag is B<not> set then the certificate will never be used even
-if the application tries to set it because it is inconsistent with the
-peer preferences.
-
-B<CERT_PKEY_SIGN>: the EE key can be used for signing.
-
-B<CERT_PKEY_EE_SIGNATURE>: the signature algorithm of the EE certificate is
-acceptable.
-
-B<CERT_PKEY_CA_SIGNATURE>: the signature algorithms of all CA certificates
-are acceptable.
-
-B<CERT_PKEY_EE_PARAM>: the parameters of the end entity certificate are
-acceptable (e.g. it is a supported curve).
-
-B<CERT_PKEY_CA_PARAM>: the parameters of all CA certificates are acceptable.
-
-B<CERT_PKEY_EXPLICIT_SIGN>: the end entity certificate algorithm
-can be used explicitly for signing (i.e. it is mentioned in the signature
-algorithms extension).
-
-B<CERT_PKEY_ISSUER_NAME>: the issuer name is acceptable. This is only
-meaningful for client authentication.
-
-B<CERT_PKEY_CERT_TYPE>: the certificate type is acceptable. Only meaningful
-for client authentication.
-
-B<CERT_PKEY_SUITEB>: chain is suitable for Suite B use.
-
-=head1 NOTES
-
-SSL_check_chain() must be called in servers after a client hello message or in
-clients after a certificate request message. It will typically be called
-in the certificate callback.
-
-An application wishing to support multiple certificate chains may call this
-function on each chain in turn: starting with the one it considers the
-most secure. It could then use the chain of the first set which returns
-suitable flags.
-
-As a minimum the flag B<CERT_PKEY_VALID> must be set for a chain to be
-usable. An application supporting multiple chains with different CA signature
-algorithms may also wish to check B<CERT_PKEY_CA_SIGNATURE> too. If no
-chain is suitable a server should fall back to the most secure chain which
-sets B<CERT_PKEY_VALID>.
-
-The validity of a chain is determined by checking if it matches a supported
-signature algorithm, supported curves and in the case of client authentication
-certificate types and issuer names.
-
-Since the supported signature algorithms extension is only used in TLS 1.2
-and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be
-very useful. Applications may wish to specify a different "legacy" chain
-for earlier versions of TLS or DTLS.
-
-=head1 SEE ALSO
-
-L<SSL_CTX_set_cert_cb(3)>,
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_clear - reset SSL object to allow another connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_clear(SSL *ssl);
-
-=head1 DESCRIPTION
-
-Reset B<ssl> to allow another connection. All settings (method, ciphers,
-BIOs) are kept.
-
-=head1 NOTES
-
-SSL_clear is used to prepare an SSL object for a new connection. While all
-settings are kept, a side effect is the handling of the current SSL session.
-If a session is still B<open>, it is considered bad and will be removed
-from the session cache, as required by RFC2246. A session is considered open,
-if L<SSL_shutdown(3)> was not called for the connection
-or at least L<SSL_set_shutdown(3)> was used to
-set the SSL_SENT_SHUTDOWN state.
-
-If a session was closed cleanly, the session object will be kept and all
-settings corresponding. This explicitly means, that e.g. the special method
-used during the session will be kept for the next handshake. So if the
-session was a TLSv1 session, a SSL client object will use a TLSv1 client
-method for the next handshake and a SSL server object will use a TLSv1
-server method, even if TLS_*_methods were chosen on startup. This
-will might lead to connection failures (see L<SSL_new(3)>)
-for a description of the method's properties.
-
-=head1 WARNINGS
-
-SSL_clear() resets the SSL object to allow for another connection. The
-reset operation however keeps several settings of the last sessions
-(some of these settings were made automatically during the last
-handshake). It only makes sense for a new connection with the exact
-same peer that shares these settings, and may fail if that peer
-changes its settings between connections. Use the sequence
-L<SSL_get_session(3)>;
-L<SSL_new(3)>;
-L<SSL_set_session(3)>;
-L<SSL_free(3)>
-instead to avoid such failures
-(or simply L<SSL_free(3)>; L<SSL_new(3)>
-if session reuse is not desired).
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The SSL_clear() operation could not be performed. Check the error stack to
-find out the reason.
-
-=item Z<>1
-
-The SSL_clear() operation was successful.
-
-=back
-
-L<SSL_new(3)>, L<SSL_free(3)>,
-L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
-L<SSL_CTX_set_options(3)>, L<ssl(3)>,
-L<SSL_CTX_set_client_cert_cb(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_connect(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_connect() initiates the TLS/SSL handshake with a server. The communication
-channel must already have been set and assigned to the B<ssl> by setting an
-underlying B<BIO>.
-
-=head1 NOTES
-
-The behaviour of SSL_connect() depends on the underlying BIO.
-
-If the underlying BIO is B<blocking>, SSL_connect() will only return once the
-handshake has been finished or an error occurred.
-
-If the underlying BIO is B<non-blocking>, SSL_connect() will also return
-when the underlying BIO could not satisfy the needs of SSL_connect()
-to continue the handshake, indicating the problem by the return value -1.
-In this case a call to SSL_get_error() with the
-return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
-taking appropriate action to satisfy the needs of SSL_connect().
-The action depends on the underlying BIO. When using a non-blocking socket,
-nothing is to be done, but select() can be used to check for the required
-condition. When using a buffering BIO, like a BIO pair, data must be written
-into or retrieved out of the BIO before being able to continue.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The TLS/SSL handshake was not successful but was shut down controlled and
-by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
-return value B<ret> to find out the reason.
-
-=item Z<>1
-
-The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
-established.
-
-=item E<lt>0
-
-The TLS/SSL handshake was not successful, because a fatal error occurred either
-at the protocol level or a connection failure occurred. The shutdown was
-not clean. It can also occur of action is need to continue the operation
-for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
-to find out the reason.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_accept(3)>,
-L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>,
-L<SSL_set_connect_state(3)>,
-L<SSL_do_handshake(3)>,
-L<SSL_CTX_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_do_handshake - perform a TLS/SSL handshake
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_do_handshake(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the
-connection is in client mode, the handshake will be started. The handshake
-routines may have to be explicitly set in advance using either
-L<SSL_set_connect_state(3)> or
-L<SSL_set_accept_state(3)>.
-
-=head1 NOTES
-
-The behaviour of SSL_do_handshake() depends on the underlying BIO.
-
-If the underlying BIO is B<blocking>, SSL_do_handshake() will only return
-once the handshake has been finished or an error occurred.
-
-If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return
-when the underlying BIO could not satisfy the needs of SSL_do_handshake()
-to continue the handshake. In this case a call to SSL_get_error() with the
-return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
-taking appropriate action to satisfy the needs of SSL_do_handshake().
-The action depends on the underlying BIO. When using a non-blocking socket,
-nothing is to be done, but select() can be used to check for the required
-condition. When using a buffering BIO, like a BIO pair, data must be written
-into or retrieved out of the BIO before being able to continue.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The TLS/SSL handshake was not successful but was shut down controlled and
-by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
-return value B<ret> to find out the reason.
-
-=item Z<>1
-
-The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
-established.
-
-=item E<lt>0
-
-The TLS/SSL handshake was not successful because a fatal error occurred either
-at the protocol level or a connection failure occurred. The shutdown was
-not clean. It can also occur of action is need to continue the operation
-for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
-to find out the reason.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_connect(3)>,
-L<SSL_accept(3)>, L<ssl(3)>, L<bio(3)>,
-L<SSL_set_connect_state(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_extension_supported,
-SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext
-- custom TLS extension handling
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
- custom_ext_add_cb add_cb,
- custom_ext_free_cb free_cb, void *add_arg,
- custom_ext_parse_cb parse_cb,
- void *parse_arg);
-
- int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
- custom_ext_add_cb add_cb,
- custom_ext_free_cb free_cb, void *add_arg,
- custom_ext_parse_cb parse_cb,
- void *parse_arg);
-
- int SSL_extension_supported(unsigned int ext_type);
-
- typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type,
- const unsigned char **out,
- size_t *outlen, int *al,
- void *add_arg);
-
- typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type,
- const unsigned char *out,
- void *add_arg);
-
- typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type,
- const unsigned char *in,
- size_t inlen, int *al,
- void *parse_arg);
-
-
-=head1 DESCRIPTION
-
-SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client
-with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
-B<parse_cb>.
-
-SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server
-with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and
-B<parse_cb>.
-
-In both cases the extension type must not be handled by OpenSSL internally
-or an error occurs.
-
-SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
-internally by OpenSSL and 0 otherwise.
-
-=head1 EXTENSION CALLBACKS
-
-The callback B<add_cb> is called to send custom extension data to be
-included in ClientHello for TLS clients or ServerHello for servers. The
-B<ext_type> parameter is set to the extension type which will be added and
-B<add_arg> to the value set when the extension handler was added.
-
-If the application wishes to include the extension B<ext_type> it should
-set B<*out> to the extension data, set B<*outlen> to the length of the
-extension data and return 1.
-
-If the B<add_cb> does not wish to include the extension it must return 0.
-
-If B<add_cb> returns -1 a fatal handshake error occurs using the TLS
-alert value specified in B<*al>.
-
-For clients (but not servers) if B<add_cb> is set to NULL a zero length
-extension is added for B<ext_type>.
-
-For clients every registered B<add_cb> is always called to see if the
-application wishes to add an extension to ClientHello.
-
-For servers every registered B<add_cb> is called once if and only if the
-corresponding extension was received in ClientHello to see if the application
-wishes to add the extension to ServerHello. That is, if no corresponding extension
-was received in ClientHello then B<add_cb> will not be called.
-
-If an extension is added (that is B<add_cb> returns 1) B<free_cb> is called
-(if it is set) with the value of B<out> set by the add callback. It can be
-used to free up any dynamic extension data set by B<add_cb>. Since B<out> is
-constant (to permit use of constant data in B<add_cb>) applications may need to
-cast away const to free the data.
-
-The callback B<parse_cb> receives data for TLS extensions. For TLS clients
-the extension data will come from ServerHello and for TLS servers it will
-come from ClientHello.
-
-The extension data consists of B<inlen> bytes in the buffer B<in> for the
-extension B<extension_type>.
-
-If the B<parse_cb> considers the extension data acceptable it must return
-1. If it returns 0 or a negative value a fatal handshake error occurs
-using the TLS alert value specified in B<*al>.
-
-The buffer B<in> is a temporary internal buffer which will not be valid after
-the callback returns.
-
-=head1 NOTES
-
-The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values
-which will be passed to the corresponding callbacks. They can, for example,
-be used to store the extension data received in a convenient structure or
-pass the extension data to be added or freed when adding extensions.
-
-The B<ext_type> parameter corresponds to the B<extension_type> field of
-RFC5246 et al. It is B<not> a NID.
-
-If the same custom extension type is received multiple times a fatal
-B<decode_error> alert is sent and the handshake aborts. If a custom extension
-is received in ServerHello which was not sent in ClientHello a fatal
-B<unsupported_extension> alert is sent and the handshake is aborted. The
-ServerHello B<add_cb> callback is only called if the corresponding extension
-was received in ClientHello. This is compliant with the TLS specifications.
-This behaviour ensures that each callback is called at most once and that
-an application can never send unsolicited extensions.
-
-=head1 RETURN VALUES
-
-SSL_CTX_add_client_custom_ext() and SSL_CTX_add_server_custom_ext() return 1 for
-success and 0 for failure. A failure can occur if an attempt is made to
-add the same B<ext_type> more than once, if an attempt is made to use an
-extension type handled internally by OpenSSL or if an internal error occurs
-(for example a memory allocation failure).
-
-SSL_extension_supported() returns 1 if the extension B<ext_type> is handled
-internally by OpenSSL and 0 otherwise.
-
-=head1 COPYRIGHT
-
-Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_free - free an allocated SSL structure
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_free(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_free() decrements the reference count of B<ssl>, and removes the SSL
-structure pointed to by B<ssl> and frees up the allocated memory if the
-reference count has reached 0.
-If B<ssl> is NULL nothing is done.
-
-=head1 NOTES
-
-SSL_free() also calls the free()ing procedures for indirectly affected items, if
-applicable: the buffering BIO, the read and write BIOs,
-cipher lists specially created for this B<ssl>, the B<SSL_SESSION>.
-Do not explicitly free these indirectly freed up items before or after
-calling SSL_free(), as trying to free things twice may lead to program
-failure.
-
-The ssl session has reference counts from two users: the SSL object, for
-which the reference count is removed by SSL_free() and the internal
-session cache. If the session is considered bad, because
-L<SSL_shutdown(3)> was not called for the connection
-and L<SSL_set_shutdown(3)> was not used to set the
-SSL_SENT_SHUTDOWN state, the session will also be removed
-from the session cache as required by RFC2246.
-
-=head1 RETURN VALUES
-
-SSL_free() does not provide diagnostic information.
-
-L<SSL_new(3)>, L<SSL_clear(3)>,
-L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get0_peer_scts - get SCTs received
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s);
-
-=head1 DESCRIPTION
-
-SSL_get0_peer_scts() returns the signed certificate timestamps (SCTs) that have
-been received. If this is the first time that this function has been called for
-a given B<SSL> instance, it will examine the TLS extensions, OCSP response and
-the peer's certificate for SCTs. Future calls will return the same SCTs.
-
-=head1 RESTRICTIONS
-
-If no Certificate Transparency validation callback has been set (using
-B<SSL_CTX_set_ct_validation_callback> or B<SSL_set_ct_validation_callback>),
-this function is not guaranteed to return all of the SCTs that the peer is
-capable of sending.
-
-=head1 RETURN VALUES
-
-SSL_get0_peer_scts() returns a list of SCTs found, or NULL if an error occurs.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_ct_validation_callback(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_SSL_CTX() returns a pointer to the SSL_CTX object, from which
-B<ssl> was created with L<SSL_new(3)>.
-
-=head1 RETURN VALUES
-
-The pointer to the SSL_CTX object is returned.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_new(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_waiting_for_async,
-SSL_get_all_async_fds,
-SSL_get_changed_async_fds
-- manage asynchronous operations
-
-=for comment multiple includes
-
-=head1 SYNOPSIS
-
- #include <openssl/async.h>
- #include <openssl/ssl.h>
-
- int SSL_waiting_for_async(SSL *s);
- int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds);
- int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds,
- OSSL_ASYNC_FD *delfd, size_t *numdelfds);
-
-=head1 DESCRIPTION
-
-SSL_waiting_for_async() determines whether an SSL connection is currently
-waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in
-L<SSL_CTX_set_mode(3)>).
-
-SSL_get_all_async_fds() returns a list of file descriptor which can be used in a
-call to select() or poll() to determine whether the current asynchronous
-operation has completed or not. A completed operation will result in data
-appearing as "read ready" on the file descriptor (no actual data should be read
-from the file descriptor). This function should only be called if the SSL object
-is currently waiting for asynchronous work to complete (i.e.
-SSL_ERROR_WANT_ASYNC has been received - see L<SSL_get_error(3)>). Typically the
-list will only contain one file descriptor. However if multiple asynchronous
-capable engines are in use then more than one is possible. The number of file
-descriptors returned is stored in B<*numfds> and the file descriptors themselves
-are in B<*fds>. The B<fds> parameter may be NULL in which case no file
-descriptors are returned but B<*numfds> is still populated. It is the callers
-responsibility to ensure sufficient memory is allocated at B<*fds> so typically
-this function is called twice (once with a NULL B<fds> parameter and once
-without).
-
-SSL_get_changed_async_fds() returns a list of the asynchronous file descriptors
-that have been added and a list that have been deleted since the last
-SSL_ERROR_WANT_ASYNC was received (or since the SSL object was created if no
-SSL_ERROR_WANT_ASYNC has been received). Similar to SSL_get_all_async_fds() it
-is the callers responsibility to ensure that B<*addfd> and B<*delfd> have
-sufficient memory allocated, although they may be NULL. The number of added fds
-and the number of deleted fds are stored in B<*numaddfds> and B<*numdelfds>
-respectively.
-
-=head1 RETURN VALUES
-
-SSL_waiting_for_async() will return 1 if the current SSL operation is waiting
-for an async operation to complete and 0 otherwise.
-
-SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or
-0 on error.
-
-=head1 NOTES
-
-On Windows platforms the openssl/async.h header is dependent on some
-of the types customarily made available by including windows.h. The
-application developer is likely to require control over when the latter
-is included, commonly as one of the first included headers. Therefore
-it is defined as an application developer's responsibility to include
-windows.h prior to async.h.
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)>
-
-=head1 HISTORY
-
-SSL_waiting_for_async(), SSL_get_all_async_fds() and SSL_get_changed_async_fds()
-were first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get1_supported_ciphers, SSL_get_client_ciphers,
-SSL_get_ciphers, SSL_CTX_get_ciphers, SSL_get_cipher_list
-- get list of available SSL_CIPHERs
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl);
- STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx);
- STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s);
- STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl);
- const char *SSL_get_cipher_list(const SSL *ssl, int priority);
-
-=head1 DESCRIPTION
-
-SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>,
-sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL
-is returned.
-
-SSL_CTX_get_ciphers() returns the stack of available SSL_CIPHERs for B<ctx>.
-
-SSL_get1_supported_ciphers() returns the stack of enabled SSL_CIPHERs for
-B<ssl>, sorted by preference.
-The list depends on settings like the cipher list, the supported protocol
-versions, the security level, and the enabled signature algorithms.
-SRP and PSK ciphers are only enabled if the appropriate callbacks or settings
-have been applied.
-This is the list that will be sent by the client to the server.
-The list supported by the server might include more ciphers in case there is a
-hole in the list of supported protocols.
-The server will also not use ciphers from this list depending on the
-configured certificates and DH parameters.
-If B<ssl> is NULL or no ciphers are available, NULL is returned.
-
-SSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the
-list received from the client on B<ssl>. If B<ssl> is NULL, no ciphers are
-available, or B<ssl> is not operating in server mode, NULL is returned.
-
-SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER
-listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are
-available, or there are less ciphers than B<priority> available, NULL
-is returned.
-
-=head1 NOTES
-
-The details of the ciphers obtained by SSL_get_ciphers(), SSL_CTX_get_ciphers()
-SSL_get1_supported_ciphers() and SSL_get_client_ciphers() can be obtained using
-the L<SSL_CIPHER_get_name(3)> family of functions.
-
-Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the
-sorted list of available ciphers, until NULL is returned.
-
-Note: SSL_get_ciphers(), SSL_CTX_get_ciphers() and SSL_get_client_ciphers()
-return a pointer to an internal cipher stack, which will be freed later on when
-the SSL or SSL_SESSION object is freed. Therefore, the calling code B<MUST NOT>
-free the return value itself.
-
-The stack returned by SSL_get1_supported_ciphers() should be freed using
-sk_SSL_CIPHER_free().
-
-=head1 RETURN VALUES
-
-See DESCRIPTION
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>,
-L<SSL_CIPHER_get_name(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
- STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
-B<ctx> using L<SSL_CTX_set_client_CA_list(3)>.
-
-SSL_get_client_CA_list() returns the list of client CAs explicitly
-set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
-L<SSL_CTX_set_client_CA_list(3)>, when in
-server mode. In client mode, SSL_get_client_CA_list returns the list of
-client CAs sent from the server, if any.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
-diagnostic information.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
-values:
-
-=over 4
-
-=item STACK_OF(X509_NAMES)
-
-List of CA names explicitly set (for B<ctx> or in server mode) or send
-by the server (client mode).
-
-=item NULL
-
-No client CA list was explicitly set (for B<ctx> or in server mode) or
-the server did not send a list of CAs (client mode).
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_client_CA_list(3)>,
-L<SSL_CTX_set_client_cert_cb(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen);
- size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen);
- size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, size_t outlen);
-
-=head1 DESCRIPTION
-
-SSL_get_client_random() extracts the random value sent from the client
-to the server during the initial SSL/TLS handshake. It copies as many
-bytes as it can of this value into the buffer provided in B<out>,
-which must have at least B<outlen> bytes available. It returns the
-total number of bytes that were actually copied. If B<outlen> is
-zero, SSL_get_client_random() copies nothing, and returns the
-total size of the client_random value.
-
-SSL_get_server_random() behaves the same, but extracts the random value
-sent from the server to the client during the initial SSL/TLS handshake.
-
-SSL_SESSION_get_master_key() behaves the same, but extracts the master
-secret used to guarantee the security of the SSL/TLS session. This one
-can be dangerous if misused; see NOTES below.
-
-
-=head1 NOTES
-
-You probably shouldn't use these functions.
-
-These functions expose internal values from the TLS handshake, for
-use in low-level protocols. You probably should not use them, unless
-you are implementing something that needs access to the internal protocol
-details.
-
-Despite the names of SSL_get_client_random() and SSL_get_server_random(), they
-ARE NOT random number generators. Instead, they return the mostly-random values that
-were already generated and used in the TLS protocol. Using them
-in place of RAND_bytes() would be grossly foolish.
-
-The security of your TLS session depends on keeping the master key secret:
-do not expose it, or any information about it, to anybody.
-If you need to calculate another secret value that depends on the master
-secret, you should probably use SSL_export_keying_material() instead, and
-forget that you ever saw these functions.
-
-In current versions of the TLS protocols, the length of client_random
-(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for
-other outlen arguments to the SSL_get_*_random() functions is provided
-in case of the unlikely event that a future version or variant of TLS
-uses some other length there.
-
-Finally, though the "client_random" and "server_random" values are called
-"random", many TLS implementations will generate four bytes of those
-values based on their view of the current time.
-
-
-=head1 RETURN VALUES
-
-If B<outlen> is greater than 0, these functions return the number of bytes
-actually copied, which will be less than or equal to B<outlen>.
-
-If B<outlen> is 0, these functions return the maximum number
-of bytes they would copy--that is, the length of the underlying field.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<RAND_bytes(3)>,
-L<SSL_export_keying_material(3)>
-
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_current_cipher, SSL_get_cipher_name, SSL_get_cipher,
-SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl);
-
- const char *SSL_get_cipher_name(const SSL *s);
- const char *SSL_get_cipher(const SSL *s);
- int SSL_get_cipher_bits(const SSL *s, int *np) \
- const char *SSL_get_cipher_version(const SSL *s);
-
-=head1 DESCRIPTION
-
-SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing
-the description of the actually used cipher of a connection established with
-the B<ssl> object.
-See L<SSL_CIPHER_get_name(3)> for more details.
-
-SSL_get_cipher_name() obtains the
-name of the currently used cipher.
-SSL_get_cipher() is identical to SSL_get_cipher_name().
-SSL_get_cipher_bits() is a
-macro to obtain the number of secret/algorithm bits used and
-SSL_get_cipher_version() returns the protocol name.
-
-=head1 RETURN VALUES
-
-SSL_get_current_cipher() returns the cipher actually used, or NULL if
-no session has been established.
-
-=head1 NOTES
-
-These are implemented as macros.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CIPHER_get_name(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_default_timeout - get default session timeout value
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_get_default_timeout(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_default_timeout() returns the default timeout value assigned to
-SSL_SESSION objects negotiated for the protocol valid for B<ssl>.
-
-=head1 NOTES
-
-Whenever a new session is negotiated, it is assigned a timeout value,
-after which it will not be accepted for session reuse. If the timeout
-value was not explicitly set using
-L<SSL_CTX_set_timeout(3)>, the hardcoded default
-timeout for the protocol will be used.
-
-SSL_get_default_timeout() return this hardcoded value, which is 300 seconds
-for all currently supported protocols.
-
-=head1 RETURN VALUES
-
-See description.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_SESSION_get_time(3)>,
-L<SSL_CTX_flush_sessions(3)>,
-L<SSL_get_default_timeout(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_error - obtain result code for TLS/SSL I/O operation
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_get_error(const SSL *ssl, int ret);
-
-=head1 DESCRIPTION
-
-SSL_get_error() returns a result code (suitable for the C "switch"
-statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(),
-SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by
-that TLS/SSL I/O function must be passed to SSL_get_error() in parameter
-B<ret>.
-
-In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
-current thread's OpenSSL error queue. Thus, SSL_get_error() must be
-used in the same thread that performed the TLS/SSL I/O operation, and no
-other OpenSSL function calls should appear in between. The current
-thread's error queue must be empty before the TLS/SSL I/O operation is
-attempted, or SSL_get_error() will not work reliably.
-
-=head1 RETURN VALUES
-
-The following return values can currently occur:
-
-=over 4
-
-=item SSL_ERROR_NONE
-
-The TLS/SSL I/O operation completed. This result code is returned
-if and only if B<ret E<gt> 0>.
-
-=item SSL_ERROR_ZERO_RETURN
-
-The TLS/SSL connection has been closed. If the protocol version is SSL 3.0
-or TLS 1.0, this result code is returned only if a closure
-alert has occurred in the protocol, i.e. if the connection has been
-closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN>
-does not necessarily indicate that the underlying transport
-has been closed.
-
-=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
-
-The operation did not complete; the same TLS/SSL I/O function should be
-called again later. If, by then, the underlying B<BIO> has data
-available for reading (if the result code is B<SSL_ERROR_WANT_READ>)
-or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL
-protocol progress will take place, i.e. at least part of an TLS/SSL
-record will be read or written. Note that the retry may again lead to
-a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition.
-There is no fixed upper limit for the number of iterations that
-may be necessary until progress becomes visible at application
-protocol level.
-
-For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or
-poll() on the underlying socket can be used to find out when the
-TLS/SSL I/O function should be retried.
-
-Caveat: Any TLS/SSL I/O function can lead to either of
-B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular,
-SSL_read() or SSL_peek() may want to write data and SSL_write() may want
-to read data. This is mainly because TLS/SSL handshakes may occur at any
-time during the protocol (initiated by either the client or the server);
-SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes.
-
-=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT
-
-The operation did not complete; the same TLS/SSL I/O function should be
-called again later. The underlying BIO was not connected yet to the peer
-and the call would block in connect()/accept(). The SSL function should be
-called again when the connection is established. These messages can only
-appear with a BIO_s_connect() or BIO_s_accept() BIO, respectively.
-In order to find out, when the connection has been successfully established,
-on many platforms select() or poll() for writing on the socket file descriptor
-can be used.
-
-=item SSL_ERROR_WANT_X509_LOOKUP
-
-The operation did not complete because an application callback set by
-SSL_CTX_set_client_cert_cb() has asked to be called again.
-The TLS/SSL I/O function should be called again later.
-Details depend on the application.
-
-=item SSL_ERROR_WANT_ASYNC
-
-The operation did not complete because an asynchronous engine is still
-processing data. This will only occur if the mode has been set to SSL_MODE_ASYNC
-using L<SSL_CTX_set_mode(3)> or L<SSL_set_mode(3)> and an asynchronous capable
-engine is being used. An application can determine whether the engine has
-completed its processing using select() or poll() on the asynchronous wait file
-descriptor. This file descriptor is available by calling
-L<SSL_get_all_async_fds(3)> or L<SSL_get_changed_async_fds(3)>. The TLS/SSL I/O
-function should be called again later. The function B<must> be called from the
-same thread that the original call was made from.
-
-=item SSL_ERROR_WANT_ASYNC_JOB
-
-The asynchronous job could not be started because there were no async jobs
-available in the pool (see ASYNC_init_thread(3)). This will only occur if the
-mode has been set to SSL_MODE_ASYNC using L<SSL_CTX_set_mode(3)> or
-L<SSL_set_mode(3)> and a maximum limit has been set on the async job pool
-through a call to L<ASYNC_init_thread(3)>. The application should retry the
-operation after a currently executing asynchronous operation for the current
-thread has completed.
-
-=item SSL_ERROR_SYSCALL
-
-Some I/O error occurred. The OpenSSL error queue may contain more
-information on the error. If the error queue is empty
-(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
-about the error: If B<ret == 0>, an EOF was observed that violates
-the protocol. If B<ret == -1>, the underlying B<BIO> reported an
-I/O error (for socket I/O on Unix systems, consult B<errno> for details).
-
-=item SSL_ERROR_SSL
-
-A failure in the SSL library occurred, usually a protocol error. The
-OpenSSL error queue contains more information on the error.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<err(3)>
-
-=head1 HISTORY
-
-SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_extms_support - extended master secret support
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_get_extms_support(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_extms_support() indicates whether the current session used extended
-master secret.
-
-This function is implemented as a macro.
-
-=head1 RETURN VALUES
-
-SSL_get_extms_support() returns 1 if the current session used extended
-master secret, 0 if it did not and -1 if a handshake is currently in
-progress i.e. it is not possible to determine if extended master secret
-was used.
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_fd, SSL_get_rfd, SSL_get_wfd - get file descriptor linked to an SSL object
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_get_fd(const SSL *ssl);
- int SSL_get_rfd(const SSL *ssl);
- int SSL_get_wfd(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_fd() returns the file descriptor which is linked to B<ssl>.
-SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the
-read or the write channel, which can be different. If the read and the
-write channel are different, SSL_get_fd() will return the file descriptor
-of the read channel.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item -1
-
-The operation failed, because the underlying BIO is not of the correct type
-(suitable for file descriptors).
-
-=item E<gt>=0
-
-The file descriptor linked to B<ssl>.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_set_fd(3)>, L<ssl(3)> , L<bio(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_peer_cert_chain, SSL_get0_verified_chain - get the X509 certificate
-chain of the peer
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl);
- STACK_OF(X509) *SSL_get0_verified_chain(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) certificates
-forming the certificate chain sent by the peer. If called on the client side,
-the stack also contains the peer's certificate; if called on the server
-side, the peer's certificate must be obtained separately using
-L<SSL_get_peer_certificate(3)>.
-If the peer did not present a certificate, NULL is returned.
-
-NB: SSL_get_peer_chain() returns the peer chain as sent by the peer: it
-only consists of certificates the peer has sent (in the order the peer
-has sent them) it is B<not> a verified chain.
-
-SSL_get0_verified_chain() returns the B<verified> certificate chain
-of the peer including the peer's end entity certificate. It must be called
-after a session has been successfully established. If peer verification was
-not successful (as indicated by SSL_get_verify_result() not returning
-X509_V_OK) the chain may be incomplete or invalid.
-
-=head1 NOTES
-
-If the session is resumed peers do not send certificates so a NULL pointer
-is returned by these functions. Applications can call SSL_session_reused()
-to determine whether a session is resumed.
-
-The reference count of each certificate in the returned STACK_OF(X509) object
-is not incremented and the returned stack may be invalidated by renegotiation.
-If applications wish to use any certificates in the returned chain
-indefinitely they must increase the reference counts using X509_up_ref() or
-obtain a copy of the whole chain with X509_chain_up_ref().
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item NULL
-
-No certificate was presented by the peer or no connection was established
-or the certificate chain is no longer available when a session is reused.
-
-=item Pointer to a STACK_OF(X509)
-
-The return value points to the certificate chain presented by the peer.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_peer_certificate(3)>, L<X509_up_ref(3)>,
-L<X509_chain_up_ref(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_peer_certificate - get the X509 certificate of the peer
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- X509 *SSL_get_peer_certificate(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_peer_certificate() returns a pointer to the X509 certificate the
-peer presented. If the peer did not present a certificate, NULL is returned.
-
-=head1 NOTES
-
-Due to the protocol definition, a TLS/SSL server will always send a
-certificate, if present. A client will only send a certificate when
-explicitly requested to do so by the server (see
-L<SSL_CTX_set_verify(3)>). If an anonymous cipher
-is used, no certificates are sent.
-
-That a certificate is returned does not indicate information about the
-verification state, use L<SSL_get_verify_result(3)>
-to check the verification state.
-
-The reference count of the X509 object is incremented by one, so that it
-will not be destroyed when the session containing the peer certificate is
-freed. The X509 object must be explicitly freed using X509_free().
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item NULL
-
-No certificate was presented by the peer or no connection was established.
-
-=item Pointer to an X509 certificate
-
-The return value points to the certificate presented by the peer.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_verify_result(3)>,
-L<SSL_CTX_set_verify(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and hint
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const char *SSL_get_psk_identity_hint(const SSL *ssl);
- const char *SSL_get_psk_identity(const SSL *ssl);
-
-
-=head1 DESCRIPTION
-
-SSL_get_psk_identity_hint() is used to retrieve the PSK identity hint
-used during the connection setup related to SSL object
-B<ssl>. Similarly, SSL_get_psk_identity() is used to retrieve the PSK
-identity used during the connection setup.
-
-
-=head1 RETURN VALUES
-
-If non-B<NULL>, SSL_get_psk_identity_hint() returns the PSK identity
-hint and SSL_get_psk_identity() returns the PSK identity. Both are
-B<NULL>-terminated. SSL_get_psk_identity_hint() may return B<NULL> if
-no PSK identity hint was used during the connection setup.
-
-Note that the return value is valid only during the lifetime of the
-SSL object B<ssl>.
-
-=head1 COPYRIGHT
-
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-Copyright 2005 Nokia.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_rbio, SSL_get_wbio - get BIO linked to an SSL object
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- BIO *SSL_get_rbio(SSL *ssl);
- BIO *SSL_get_wbio(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the
-read or the write channel, which can be different. The reference count
-of the BIO is not incremented.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item NULL
-
-No BIO was connected to the SSL object
-
-=item Any other pointer
-
-The BIO linked to B<ssl>.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_set_bio(3)>, L<ssl(3)> , L<bio(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_session, SSL_get0_session, SSL_get1_session - retrieve TLS/SSL session data
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- SSL_SESSION *SSL_get_session(const SSL *ssl);
- SSL_SESSION *SSL_get0_session(const SSL *ssl);
- SSL_SESSION *SSL_get1_session(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in
-B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so
-that the pointer can become invalid by other operations.
-
-SSL_get0_session() is the same as SSL_get_session().
-
-SSL_get1_session() is the same as SSL_get_session(), but the reference
-count of the B<SSL_SESSION> is incremented by one.
-
-=head1 NOTES
-
-The ssl session contains all information required to re-establish the
-connection without a new handshake.
-
-SSL_get0_session() returns a pointer to the actual session. As the
-reference counter is not incremented, the pointer is only valid while
-the connection is in use. If L<SSL_clear(3)> or
-L<SSL_free(3)> is called, the session may be removed completely
-(if considered bad), and the pointer obtained will become invalid. Even
-if the session is valid, it can be removed at any time due to timeout
-during L<SSL_CTX_flush_sessions(3)>.
-
-If the data is to be kept, SSL_get1_session() will increment the reference
-count, so that the session will not be implicitly removed by other operations
-but stays in memory. In order to remove the session
-L<SSL_SESSION_free(3)> must be explicitly called once
-to decrement the reference count again.
-
-SSL_SESSION objects keep internal link information about the session cache
-list, when being inserted into one SSL_CTX object's session cache.
-One SSL_SESSION object, regardless of its reference count, must therefore
-only be used with one SSL_CTX object (and the SSL objects created
-from this SSL_CTX object).
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item NULL
-
-There is no session available in B<ssl>.
-
-=item Pointer to an SSL_SESSION
-
-The return value points to the data of an SSL session.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_free(3)>,
-L<SSL_clear(3)>,
-L<SSL_SESSION_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_shared_sigalgs, SSL_get_sigalgs - get supported signature algorithms
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_get_shared_sigalgs(SSL *s, int idx,
- int *psign, int *phash, int *psignhash,
- unsigned char *rsig, unsigned char *rhash);
-
- int SSL_get_sigalgs(SSL *s, int idx,
- int *psign, int *phash, int *psignhash,
- unsigned char *rsig, unsigned char *rhash);
-
-=head1 DESCRIPTION
-
-SSL_get_shared_sigalgs() returns information about the shared signature
-algorithms supported by peer B<s>. The parameter B<idx> indicates the index
-of the shared signature algorithm to return starting from zero. The signature
-algorithm NID is written to B<*psign>, the hash NID to B<*phash> and the
-sign and hash NID to B<*psignhash>. The raw signature and hash values
-are written to B<*rsig> and B<*rhash>.
-
-SSL_get_sigalgs() is similar to SSL_get_shared_sigalgs() except it returns
-information about all signature algorithms supported by B<s> in the order
-they were sent by the peer.
-
-=head1 RETURN VALUES
-
-SSL_get_shared_sigalgs() and SSL_get_sigalgs() return the number of
-signature algorithms or B<0> if the B<idx> parameter is out of range.
-
-=head1 NOTES
-
-These functions are typically called for debugging purposes (to report
-the peer's preferences) or where an application wants finer control over
-certificate selection. Most applications will rely on internal handling
-and will not need to call them.
-
-If an application is only interested in the highest preference shared
-signature algorithm it can just set B<idx> to zero.
-
-Any or all of the parameters B<psign>, B<phash>, B<psignhash>, B<rsig> or
-B<rhash> can be set to B<NULL> if the value is not required. By setting
-them all to B<NULL> and setting B<idx> to zero the total number of
-signature algorithms can be determined: which can be zero.
-
-These functions must be called after the peer has sent a list of supported
-signature algorithms: after a client hello (for servers) or a certificate
-request (for clients). They can (for example) be called in the certificate
-callback.
-
-Only TLS 1.2 and DTLS 1.2 currently support signature algorithms. If these
-functions are called on an earlier version of TLS or DTLS zero is returned.
-
-The shared signature algorithms returned by SSL_get_shared_sigalgs() are
-ordered according to configuration and peer preferences.
-
-The raw values correspond to the on the wire form as defined by RFC5246 et al.
-The NIDs are OpenSSL equivalents. For example if the peer sent sha256(4) and
-rsa(1) then B<*rhash> would be 4, B<*rsign> 1, B<*phash> NID_sha256, B<*psig>
-NID_rsaEncryption and B<*psighash> NID_sha256WithRSAEncryption.
-
-If a signature algorithm is not recognised the corresponding NIDs
-will be set to B<NID_undef>. This may be because the value is not supported
-or is not an appropriate combination (for example MD5 and DSA).
-
-=head1 SEE ALSO
-
-L<SSL_CTX_set_cert_cb(3)>,
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_verify_result - get result of peer certificate verification
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_get_verify_result(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_verify_result() returns the result of the verification of the
-X509 certificate presented by the peer, if any.
-
-=head1 NOTES
-
-SSL_get_verify_result() can only return one error code while the verification
-of a certificate can fail because of many reasons at the same time. Only
-the last verification error that occurred during the processing is available
-from SSL_get_verify_result().
-
-The verification result is part of the established session and is restored
-when a session is reused.
-
-=head1 BUGS
-
-If no peer certificate was presented, the returned result code is
-X509_V_OK. This is because no verification error occurred, it does however
-not indicate success. SSL_get_verify_result() is only useful in connection
-with L<SSL_get_peer_certificate(3)>.
-
-=head1 RETURN VALUES
-
-The following return values can currently occur:
-
-=over 4
-
-=item X509_V_OK
-
-The verification succeeded or no peer certificate was presented.
-
-=item Any other value
-
-Documented in L<verify(1)>.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_set_verify_result(3)>,
-L<SSL_get_peer_certificate(3)>,
-L<verify(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_get_version, SSL_is_dtls - get the protocol information of a connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const char *SSL_get_version(const SSL *ssl);
-
- int SSL_is_dtls(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_get_version() returns the name of the protocol used for the
-connection B<ssl>.
-
-SSL_is_dtls() returns one if the connection is using DTLS, zero if not.
-
-=head1 RETURN VALUES
-
-SSL_get_version() returns one of the following strings:
-
-=over 4
-
-=item SSLv3
-
-The connection uses the SSLv3 protocol.
-
-=item TLSv1
-
-The connection uses the TLSv1.0 protocol.
-
-=item TLSv1.1
-
-The connection uses the TLSv1.1 protocol.
-
-=item TLSv1.2
-
-The connection uses the TLSv1.2 protocol.
-
-=item unknown
-
-This indicates that no version has been set (no connection established).
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 HISTORY
-
-SSL_is_dtls() was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_library_init, OpenSSL_add_ssl_algorithms,
-- initialize SSL library by registering algorithms
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_library_init(void);
-
- int OpenSSL_add_ssl_algorithms(void);
-
-=head1 DESCRIPTION
-
-SSL_library_init() registers the available SSL/TLS ciphers and digests.
-
-OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init() and is
-implemented as a macro.
-
-=head1 NOTES
-
-SSL_library_init() must be called before any other action takes place.
-SSL_library_init() is not reentrant.
-
-=head1 WARNING
-
-SSL_library_init() adds ciphers and digests used directly and indirectly by
-SSL/TLS.
-
-=head1 RETURN VALUES
-
-SSL_library_init() always returns "1", so it is safe to discard the return
-value.
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<RAND_add(3)>
-
-=head1 HISTORY
-
-The SSL_library_init() and OpenSSL_add_ssl_algorithms() functions were
-deprecated in OpenSSL 1.1.0 by OPENSSL_init_ssl().
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_load_client_CA_file - load certificate names from file
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
-
-=head1 DESCRIPTION
-
-SSL_load_client_CA_file() reads certificates from B<file> and returns
-a STACK_OF(X509_NAME) with the subject names found.
-
-=head1 NOTES
-
-SSL_load_client_CA_file() reads a file of PEM formatted certificates and
-extracts the X509_NAMES of the certificates found. While the name suggests
-the specific usage as support function for
-L<SSL_CTX_set_client_CA_list(3)>,
-it is not limited to CA certificates.
-
-=head1 EXAMPLES
-
-Load names of CAs from file and use it as a client CA list:
-
- SSL_CTX *ctx;
- STACK_OF(X509_NAME) *cert_names;
-
- ...
- cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
- if (cert_names != NULL)
- SSL_CTX_set_client_CA_list(ctx, cert_names);
- else
- error_handling();
- ...
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item NULL
-
-The operation failed, check out the error stack for the reason.
-
-=item Pointer to STACK_OF(X509_NAME)
-
-Pointer to the subject names of the successfully read certificates.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>,
-L<SSL_CTX_set_client_CA_list(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_new, SSL_up_ref - create a new SSL structure for a connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- SSL *SSL_new(SSL_CTX *ctx);
- int SSL_up_ref(SSL *s);
-
-=head1 DESCRIPTION
-
-SSL_new() creates a new B<SSL> structure which is needed to hold the
-data for a TLS/SSL connection. The new structure inherits the settings
-of the underlying context B<ctx>: connection method,
-options, verification settings, timeout settings. An B<SSL> structure is
-reference counted. Creating an B<SSL> structure for the first time increments
-the reference count. Freeing it (using SSL_free) decrements it. When the
-reference count drops to zero, any memory or resources allocated to the B<SSL>
-structure are freed. SSL_up_ref() increments the reference count for an
-existing B<SSL> structure.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item NULL
-
-The creation of a new SSL structure failed. Check the error stack to
-find out the reason.
-
-=item Pointer to an SSL structure
-
-The return value points to an allocated SSL structure.
-
-SSL_up_ref() returns 1 for success and 0 for failure.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_free(3)>, L<SSL_clear(3)>,
-L<SSL_CTX_set_options(3)>,
-L<SSL_get_SSL_CTX(3)>,
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_pending, SSL_has_pending - check for readable bytes buffered in an
-SSL object
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_pending(const SSL *ssl);
- int SSL_has_pending(const SSL *s);
-
-=head1 DESCRIPTION
-
-Data is received in whole blocks known as records from the peer. A whole record
-is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
-read by the application via a call to L<SSL_read(3)>.
-
-SSL_pending() returns the number of bytes which have been processed, buffered
-and are available inside B<ssl> for immediate read.
-
-If the B<SSL> object's I<read_ahead> flag is set (see
-L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
-record) may have been read containing more TLS/SSL records. This also applies to
-DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
-additional bytes will be buffered by OpenSSL but will remain unprocessed until
-they are needed. As these bytes are still in an unprocessed state SSL_pending()
-will ignore them. Therefore it is possible for no more bytes to be readable from
-the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
-to return 0, even though readable application data bytes are available (because
-the data is in unprocessed buffered records).
-
-SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
-unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
-return 1, and then a subsequent call to SSL_read() to return no data because the
-unprocessed buffered data when processed yielded no application data (for
-example this can happen during renegotiation). It is also possible in this
-scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()
-call because the buffered and unprocessed data is not yet processable (e.g.
-because OpenSSL has only received a partial record so far).
-
-=head1 RETURN VALUES
-
-SSL_pending() returns the number of buffered and processed application data
-bytes that are pending and are available for immediate read. SSL_has_pending()
-returns 1 if there is buffered record data in the SSL object and 0 otherwise.
-
-=head1 SEE ALSO
-
-L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
-L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>
-
-=head1 HISTORY
-
-The SSL_has_pending() function was added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_read - read bytes from a TLS/SSL connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_read(SSL *ssl, void *buf, int num);
-
-=head1 DESCRIPTION
-
-SSL_read() tries to read B<num> bytes from the specified B<ssl> into the
-buffer B<buf>.
-
-=head1 NOTES
-
-If necessary, SSL_read() will negotiate a TLS/SSL session, if
-not already explicitly performed by L<SSL_connect(3)> or
-L<SSL_accept(3)>. If the
-peer requests a re-negotiation, it will be performed transparently during
-the SSL_read() operation. The behaviour of SSL_read() depends on the
-underlying BIO.
-
-For the transparent negotiation to succeed, the B<ssl> must have been
-initialized to client or server mode. This is being done by calling
-L<SSL_set_connect_state(3)> or SSL_set_accept_state()
-before the first call to an SSL_read() or L<SSL_write(3)>
-function.
-
-SSL_read() works based on the SSL/TLS records. The data are received in
-records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
-record has been completely received, it can be processed (decryption and
-check of integrity). Therefore data that was not retrieved at the last
-call of SSL_read() can still be buffered inside the SSL layer and will be
-retrieved on the next call to SSL_read(). If B<num> is higher than the
-number of bytes buffered, SSL_read() will return with the bytes buffered.
-If no more bytes are in the buffer, SSL_read() will trigger the processing
-of the next record. Only when the record has been received and processed
-completely, SSL_read() will return reporting success. At most the contents
-of the record will be returned. As the size of an SSL/TLS record may exceed
-the maximum packet size of the underlying transport (e.g. TCP), it may
-be necessary to read several packets from the transport layer before the
-record is complete and SSL_read() can succeed.
-
-If the underlying BIO is B<blocking>, SSL_read() will only return, once the
-read operation has been finished or an error occurred, except when a
-renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
-This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
-L<SSL_CTX_set_mode(3)> call.
-
-If the underlying BIO is B<non-blocking>, SSL_read() will also return
-when the underlying BIO could not satisfy the needs of SSL_read()
-to continue the operation. In this case a call to
-L<SSL_get_error(3)> with the
-return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
-call to SSL_read() can also cause write operations! The calling process
-then must repeat the call after taking appropriate action to satisfy the
-needs of SSL_read(). The action depends on the underlying BIO. When using a
-non-blocking socket, nothing is to be done, but select() can be used to check
-for the required condition. When using a buffering BIO, like a BIO pair, data
-must be written into or retrieved out of the BIO before being able to continue.
-
-L<SSL_pending(3)> can be used to find out whether there
-are buffered bytes available for immediate retrieval. In this case
-SSL_read() can be called without blocking or actually receiving new
-data from the underlying socket.
-
-=head1 WARNING
-
-When an SSL_read() operation has to be repeated because of
-B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
-with the same arguments.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item E<gt>0
-
-The read operation was successful; the return value is the number of
-bytes actually read from the TLS/SSL connection.
-
-=item Z<>0
-
-The read operation was not successful. The reason may either be a clean
-shutdown due to a "close notify" alert sent by the peer (in which case
-the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set
-(see L<SSL_shutdown(3)>,
-L<SSL_set_shutdown(3)>). It is also possible, that
-the peer simply shut down the underlying transport and the shutdown is
-incomplete. Call SSL_get_error() with the return value B<ret> to find out,
-whether an error occurred or the connection was shut down cleanly
-(SSL_ERROR_ZERO_RETURN).
-
-=item E<lt>0
-
-The read operation was not successful, because either an error occurred
-or action must be taken by the calling process. Call SSL_get_error() with the
-return value B<ret> to find out the reason.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_write(3)>,
-L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
-L<SSL_connect(3)>, L<SSL_accept(3)>
-L<SSL_set_connect_state(3)>,
-L<SSL_pending(3)>,
-L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
-L<ssl(3)>, L<bio(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const char *SSL_rstate_string(SSL *ssl);
- const char *SSL_rstate_string_long(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_rstate_string() returns a 2 letter string indicating the current read state
-of the SSL object B<ssl>.
-
-SSL_rstate_string_long() returns a string indicating the current read state of
-the SSL object B<ssl>.
-
-=head1 NOTES
-
-When performing a read operation, the SSL/TLS engine must parse the record,
-consisting of header and body. When working in a blocking environment,
-SSL_rstate_string[_long]() should always return "RD"/"read done".
-
-This function should only seldom be needed in applications.
-
-=head1 RETURN VALUES
-
-SSL_rstate_string() and SSL_rstate_string_long() can return the following
-values:
-
-=over 4
-
-=item "RH"/"read header"
-
-The header of the record is being evaluated.
-
-=item "RB"/"read body"
-
-The body of the record is being evaluated.
-
-=item "RD"/"read done"
-
-The record has been completely processed.
-
-=item "unknown"/"unknown"
-
-The read state is unknown. This should never happen.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_session_reused - query whether a reused session was negotiated during handshake
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_session_reused(SSL *ssl);
-
-=head1 DESCRIPTION
-
-Query, whether a reused session was negotiated during the handshake.
-
-=head1 NOTES
-
-During the negotiation, a client can propose to reuse a session. The server
-then looks up the session in its cache. If both client and server agree
-on the session, it will be reused and a flag is being set that can be
-queried by the application.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-A new session was negotiated.
-
-=item Z<>1
-
-A session was reused.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_set_session(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername -
-SSL server verification parameters
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_set1_host(SSL *s, const char *hostname);
- int SSL_add1_host(SSL *s, const char *hostname);
- void SSL_set_hostflags(SSL *s, unsigned int flags);
- const char *SSL_get0_peername(SSL *s);
-
-=head1 DESCRIPTION
-
-These functions configure server hostname checks in the SSL client.
-
-SSL_set1_host() sets the expected DNS hostname to B<name> clearing
-any previously specified host name or names. If B<name> is NULL,
-or the empty string the list of hostnames is cleared, and name
-checks are not performed on the peer certificate. When a non-empty
-B<name> is specified, certificate verification automatically checks
-the peer hostname via L<X509_check_host(3)> with B<flags> as specified
-via SSL_set_hostflags(). Clients that enable DANE TLSA authentication
-via L<SSL_dane_enable(3)> should leave it to that function to set
-the primary reference identifier of the peer, and should not call
-SSL_set1_host().
-
-SSL_add1_host() adds B<name> as an additional reference identifier
-that can match the peer's certificate. Any previous names set via
-SSL_set1_host() or SSL_add1_host() are retained, no change is made
-if B<name> is NULL or empty. When multiple names are configured,
-the peer is considered verified when any name matches. This function
-is required for DANE TLSA in the presence of service name indirection
-via CNAME, MX or SRV records as specified in RFC7671, RFC7672 or
-RFC7673.
-
-SSL_set_hostflags() sets the B<flags> that will be passed to
-L<X509_check_host(3)> when name checks are applicable, by default
-the B<flags> value is 0. See L<X509_check_host(3)> for the list
-of available flags and their meaning.
-
-SSL_get0_peername() returns the DNS hostname or subject CommonName
-from the peer certificate that matched one of the reference
-identifiers. When wildcard matching is not disabled, the name
-matched in the peer certificate may be a wildcard name. When one
-of the reference identifiers configured via SSL_set1_host() or
-SSL_add1_host() starts with ".", which indicates a parent domain prefix
-rather than a fixed name, the matched peer name may be a sub-domain
-of the reference identifier. The returned string is allocated by
-the library and is no longer valid once the associated B<ssl> handle
-is cleared or freed, or a renegotiation takes place. Applications
-must not free the return value.
-
-SSL clients are advised to use these functions in preference to
-explicitly calling L<X509_check_host(3)>. Hostname checks are out
-of scope with the RFC7671 DANE-EE(3) certificate usage, and the
-internal check will be suppressed as appropriate when DANE is
-enabled.
-
-=head1 RETURN VALUES
-
-SSL_set1_host() and SSL_add1_host() return 1 for success and 0 for
-failure.
-
-SSL_get0_peername() returns NULL if peername verification is not
-applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
-matched. Otherwise, it returns the matched peername. To determine
-whether verification succeeded call L<SSL_get_verify_result(3)>.
-
-=head1 EXAMPLE
-
-Suppose "smtp.example.com" is the MX host of the domain "example.com".
-The calls below will arrange to match either the MX hostname or the
-destination domain name in the SMTP server certificate. Wildcards
-are supported, but must match the entire label. The actual name
-matched in the certificate (which might be a wildcard) is retrieved,
-and must be copied by the application if it is to be retained beyond
-the lifetime of the SSL connection.
-
- SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
- if (!SSL_set1_host(ssl, "smtp.example.com")) {
- /* handle error */
- }
- if (!SSL_add1_host(ssl, "example.com")) {
- /* handle error */
- }
-
- /* XXX: Perform SSL_connect() handshake and handle errors here */
-
- if (SSL_get_verify_result(ssl) == X509_V_OK) {
- const char *peername = SSL_get0_peername(ssl);
-
- if (peername != NULL) {
- /* Name checks were in scope and matched the peername */
- }
- }
-
-=head1 SEE ALSO
-
-L<X509_check_host(3)>,
-L<SSL_get_verify_result(3)>.
-L<SSL_dane_enable(3)>.
-
-=head1 HISTORY
-
-These functions were first added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);
- void SSL_set0_rbio(SSL *s, BIO *rbio);
- void SSL_set0_wbio(SSL *s, BIO *wbio);
-
-=head1 DESCRIPTION
-
-SSL_set0_rbio() connects the BIO B<rbio> for the read operations of the B<ssl>
-object. The SSL engine inherits the behaviour of B<rbio>. If the BIO is
-non-blocking then the B<ssl> object will also have non-blocking behaviour. This
-function transfers ownership of B<rbio> to B<ssl>. It will be automatically
-freed using L<BIO_free_all(3)> when the B<ssl> is freed. On calling this
-function, any existing B<rbio> that was previously set will also be freed via a
-call to L<BIO_free_all(3)> (this includes the case where the B<rbio> is set to
-the same value as previously).
-
-SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects
-the BIO B<wbio> for the write operations of the B<ssl> object. Note that if the
-rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take
-ownership of one reference. Therefore it may be necessary to increment the
-number of references available using L<BIO_up_ref(3)> before calling the set0
-functions.
-
-SSL_set_bio() does a similar job as SSL_set0_rbio() and SSL_set0_wbio() except
-that it connects both the B<rbio> and the B<wbio> at the same time. This
-function transfers the ownership of B<rbio> and B<wbio> to B<ssl> except that
-the rules for this are much more complex. For this reason this function is
-considered a legacy function and SSL_set0_rbio() and SSL_set0_wbio() should be
-used in preference. The ownership rules are as follows:
-
-=over 4
-
-=item
-
-If neither the rbio or wbio have changed from their previous values then nothing
-is done.
-
-=item
-
-If the rbio and wbio parameters are different and both are different to their
-previously set values then one reference is consumed for the rbio and one
-reference is consumed for the wbio.
-
-=item
-
-If the rbio and wbio parameters are the same and the rbio is not the same as the
-previously set value then one reference is consumed.
-
-=item
-
-If the rbio and wbio parameters are the same and the rbio is the same as the
-previously set value, then no additional references are consumed.
-
-=item
-
-If the rbio and wbio parameters are different and the rbio is the same as the
-previously set value then one reference is consumbed for the wbio and no
-references are consumed for the rbio.
-
-=item
-
-If the rbio and wbio parameters are different and the wbio is the same as the
-previously set value and the old rbio and wbio values were the same as each
-other then one reference is consumed for the rbio and no references are consumed
-for the wbio.
-
-=item
-
-If the rbio and wbio parameters are different and the wbio is the same as the
-previously set value and the old rbio and wbio values were different to each
-other then one reference is consumed for the rbio and one reference is consumed
-for the wbio.
-
-=back
-
-=head1 RETURN VALUES
-
-SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail.
-
-=head1 SEE ALSO
-
-L<SSL_get_rbio(3)>,
-L<SSL_connect(3)>, L<SSL_accept(3)>,
-L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>
-
-=head1 HISTORY
-
-SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set_connect_state, SSL_set_accept_state - prepare SSL object to work in client or server mode
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_set_connect_state(SSL *ssl);
-
- void SSL_set_accept_state(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_set_connect_state() sets B<ssl> to work in client mode.
-
-SSL_set_accept_state() sets B<ssl> to work in server mode.
-
-=head1 NOTES
-
-When the SSL_CTX object was created with L<SSL_CTX_new(3)>,
-it was either assigned a dedicated client method, a dedicated server
-method, or a generic method, that can be used for both client and
-server connections. (The method might have been changed with
-L<SSL_CTX_set_ssl_version(3)> or
-SSL_set_ssl_method().)
-
-When beginning a new handshake, the SSL engine must know whether it must
-call the connect (client) or accept (server) routines. Even though it may
-be clear from the method chosen, whether client or server mode was
-requested, the handshake routines must be explicitly set.
-
-When using the L<SSL_connect(3)> or
-L<SSL_accept(3)> routines, the correct handshake
-routines are automatically set. When performing a transparent negotiation
-using L<SSL_write(3)> or L<SSL_read(3)>, the
-handshake routines must be explicitly set in advance using either
-SSL_set_connect_state() or SSL_set_accept_state().
-
-=head1 RETURN VALUES
-
-SSL_set_connect_state() and SSL_set_accept_state() do not return diagnostic
-information.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_new(3)>, L<SSL_CTX_new(3)>,
-LL<SSL_connect(3)>, L<SSL_accept(3)>,
-L<SSL_write(3)>, L<SSL_read(3)>,
-L<SSL_do_handshake(3)>,
-L<SSL_CTX_set_ssl_version(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_set_fd(SSL *ssl, int fd);
- int SSL_set_rfd(SSL *ssl, int fd);
- int SSL_set_wfd(SSL *ssl, int fd);
-
-=head1 DESCRIPTION
-
-SSL_set_fd() sets the file descriptor B<fd> as the input/output facility
-for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the
-socket file descriptor of a network connection.
-
-When performing the operation, a B<socket BIO> is automatically created to
-interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine
-inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will
-also have non-blocking behaviour.
-
-If there was already a BIO connected to B<ssl>, BIO_free() will be called
-(for both the reading and writing side, if different).
-
-SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only
-for the read channel or the write channel, which can be set independently.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The operation failed. Check the error stack to find out why.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_get_fd(3)>, L<SSL_set_bio(3)>,
-L<SSL_connect(3)>, L<SSL_accept(3)>,
-L<SSL_shutdown(3)>, L<ssl(3)> , L<bio(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_set_session(SSL *ssl, SSL_SESSION *session);
-
-=head1 DESCRIPTION
-
-SSL_set_session() sets B<session> to be used when the TLS/SSL connection
-is to be established. SSL_set_session() is only useful for TLS/SSL clients.
-When the session is set, the reference count of B<session> is incremented
-by 1. If the session is not reused, the reference count is decremented
-again during SSL_connect(). Whether the session was reused can be queried
-with the L<SSL_session_reused(3)> call.
-
-If there is already a session set inside B<ssl> (because it was set with
-SSL_set_session() before or because the same B<ssl> was already used for
-a connection), SSL_SESSION_free() will be called for that session. If that old
-session is still B<open>, it is considered bad and will be removed from the
-session cache (if used). A session is considered open, if L<SSL_shutdown(3)> was
-not called for the connection (or at least L<SSL_set_shutdown(3)> was used to
-set the SSL_SENT_SHUTDOWN state).
-
-=head1 NOTES
-
-SSL_SESSION objects keep internal link information about the session cache
-list, when being inserted into one SSL_CTX object's session cache.
-One SSL_SESSION object, regardless of its reference count, must therefore
-only be used with one SSL_CTX object (and the SSL objects created
-from this SSL_CTX object).
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The operation failed; check the error stack to find out the reason.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_SESSION_free(3)>,
-L<SSL_get_session(3)>,
-L<SSL_session_reused(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_set_shutdown(SSL *ssl, int mode);
-
- int SSL_get_shutdown(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_set_shutdown() sets the shutdown state of B<ssl> to B<mode>.
-
-SSL_get_shutdown() returns the shutdown mode of B<ssl>.
-
-=head1 NOTES
-
-The shutdown state of an ssl connection is a bitmask of:
-
-=over 4
-
-=item Z<>0
-
-No shutdown setting, yet.
-
-=item SSL_SENT_SHUTDOWN
-
-A "close notify" shutdown alert was sent to the peer, the connection is being
-considered closed and the session is closed and correct.
-
-=item SSL_RECEIVED_SHUTDOWN
-
-A shutdown alert was received form the peer, either a normal "close notify"
-or a fatal error.
-
-=back
-
-SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time.
-
-The shutdown state of the connection is used to determine the state of
-the ssl session. If the session is still open, when
-L<SSL_clear(3)> or L<SSL_free(3)> is called,
-it is considered bad and removed according to RFC2246.
-The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN
-(according to the TLS RFC, it is acceptable to only send the "close notify"
-alert but to not wait for the peer's answer, when the underlying connection
-is closed).
-SSL_set_shutdown() can be used to set this state without sending a
-close alert to the peer (see L<SSL_shutdown(3)>).
-
-If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set,
-for setting SSL_SENT_SHUTDOWN the application must however still call
-L<SSL_shutdown(3)> or SSL_set_shutdown() itself.
-
-=head1 RETURN VALUES
-
-SSL_set_shutdown() does not return diagnostic information.
-
-SSL_get_shutdown() returns the current setting.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_shutdown(3)>,
-L<SSL_CTX_set_quiet_shutdown(3)>,
-L<SSL_clear(3)>, L<SSL_free(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_set_verify_result - override result of peer certificate verification
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_set_verify_result(SSL *ssl, long verify_result);
-
-=head1 DESCRIPTION
-
-SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the
-result of the verification of the X509 certificate presented by the peer,
-if any.
-
-=head1 NOTES
-
-SSL_set_verify_result() overrides the verification result. It only changes
-the verification result of the B<ssl> object. It does not become part of the
-established session, so if the session is to be reused later, the original
-value will reappear.
-
-The valid codes for B<verify_result> are documented in L<verify(1)>.
-
-=head1 RETURN VALUES
-
-SSL_set_verify_result() does not provide a return value.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_get_verify_result(3)>,
-L<SSL_get_peer_certificate(3)>,
-L<verify(1)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_shutdown - shut down a TLS/SSL connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_shutdown(SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
-"close notify" shutdown alert to the peer.
-
-=head1 NOTES
-
-SSL_shutdown() tries to send the "close notify" shutdown alert to the peer.
-Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
-a currently open session is considered closed and good and will be kept in the
-session cache for further reuse.
-
-The shutdown procedure consists of 2 steps: the sending of the "close notify"
-shutdown alert and the reception of the peer's "close notify" shutdown
-alert. According to the TLS standard, it is acceptable for an application
-to only send its shutdown alert and then close the underlying connection
-without waiting for the peer's response (this way resources can be saved,
-as the process can already terminate or serve another connection).
-When the underlying connection shall be used for more communications, the
-complete shutdown procedure (bidirectional "close notify" alerts) must be
-performed, so that the peers stay synchronized.
-
-SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step
-behaviour.
-
-=over 4
-
-=item When the application is the first party to send the "close notify"
-alert, SSL_shutdown() will only send the alert and then set the
-SSL_SENT_SHUTDOWN flag (so that the session is considered good and will
-be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional
-shutdown is enough (the underlying connection shall be closed anyway), this
-first call to SSL_shutdown() is sufficient. In order to complete the
-bidirectional shutdown handshake, SSL_shutdown() must be called again.
-The second call will make SSL_shutdown() wait for the peer's "close notify"
-shutdown alert. On success, the second call to SSL_shutdown() will return
-with 1.
-
-=item If the peer already sent the "close notify" alert B<and> it was
-already processed implicitly inside another function
-(L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
-SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN
-flag and will immediately return with 1.
-Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
-SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
-
-=back
-
-It is therefore recommended, to check the return value of SSL_shutdown()
-and call SSL_shutdown() again, if the bidirectional shutdown is not yet
-complete (return value of the first call is 0).
-
-The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
-
-If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
-handshake step has been finished or an error occurred.
-
-If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
-when the underlying BIO could not satisfy the needs of SSL_shutdown()
-to continue the handshake. In this case a call to SSL_get_error() with the
-return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
-taking appropriate action to satisfy the needs of SSL_shutdown().
-The action depends on the underlying BIO. When using a non-blocking socket,
-nothing is to be done, but select() can be used to check for the required
-condition. When using a buffering BIO, like a BIO pair, data must be written
-into or retrieved out of the BIO before being able to continue.
-
-SSL_shutdown() can be modified to only set the connection to "shutdown"
-state but not actually send the "close notify" alert messages,
-see L<SSL_CTX_set_quiet_shutdown(3)>.
-When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
-and return 1.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item Z<>0
-
-The shutdown is not yet finished. Call SSL_shutdown() for a second time,
-if a bidirectional shutdown shall be performed.
-The output of L<SSL_get_error(3)> may be misleading, as an
-erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
-
-=item Z<>1
-
-The shutdown was successfully completed. The "close notify" alert was sent
-and the peer's "close notify" alert was received.
-
-=item E<lt>0
-
-The shutdown was not successful because a fatal error occurred either
-at the protocol level or a connection failure occurred. It can also occur if
-action is need to continue the operation for non-blocking BIOs.
-Call L<SSL_get_error(3)> with the return value B<ret>
-to find out the reason.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_connect(3)>,
-L<SSL_accept(3)>, L<SSL_set_shutdown(3)>,
-L<SSL_CTX_set_quiet_shutdown(3)>,
-L<SSL_clear(3)>, L<SSL_free(3)>,
-L<ssl(3)>, L<bio(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- const char *SSL_state_string(const SSL *ssl);
- const char *SSL_state_string_long(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_state_string() returns a 6 letter string indicating the current state
-of the SSL object B<ssl>.
-
-SSL_state_string_long() returns a string indicating the current state of
-the SSL object B<ssl>.
-
-=head1 NOTES
-
-During its use, an SSL objects passes several states. The state is internally
-maintained. Querying the state information is not very informative before
-or when a connection has been established. It however can be of significant
-interest during the handshake.
-
-When using non-blocking sockets, the function call performing the handshake
-may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition,
-so that SSL_state_string[_long]() may be called.
-
-For both blocking or non-blocking sockets, the details state information
-can be used within the info_callback function set with the
-SSL_set_info_callback() call.
-
-=head1 RETURN VALUES
-
-Detailed description of possible states to be included later.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_CTX_set_info_callback(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup,
-SSL_want_async, SSL_want_async_job - obtain state information TLS/SSL I/O
-operation
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_want(const SSL *ssl);
- int SSL_want_nothing(const SSL *ssl);
- int SSL_want_read(const SSL *ssl);
- int SSL_want_write(const SSL *ssl);
- int SSL_want_x509_lookup(const SSL *ssl);
- int SSL_want_async(const SSL *ssl);
- int SSL_want_async_job(const SSL *ssl);
-
-=head1 DESCRIPTION
-
-SSL_want() returns state information for the SSL object B<ssl>.
-
-The other SSL_want_*() calls are shortcuts for the possible states returned
-by SSL_want().
-
-=head1 NOTES
-
-SSL_want() examines the internal state information of the SSL object. Its
-return values are similar to that of L<SSL_get_error(3)>.
-Unlike L<SSL_get_error(3)>, which also evaluates the
-error queue, the results are obtained by examining an internal state flag
-only. The information must therefore only be used for normal operation under
-non-blocking I/O. Error conditions are not handled and must be treated
-using L<SSL_get_error(3)>.
-
-The result returned by SSL_want() should always be consistent with
-the result of L<SSL_get_error(3)>.
-
-=head1 RETURN VALUES
-
-The following return values can currently occur for SSL_want():
-
-=over 4
-
-=item SSL_NOTHING
-
-There is no data to be written or to be read.
-
-=item SSL_WRITING
-
-There are data in the SSL buffer that must be written to the underlying
-B<BIO> layer in order to complete the actual SSL_*() operation.
-A call to L<SSL_get_error(3)> should return
-SSL_ERROR_WANT_WRITE.
-
-=item SSL_READING
-
-More data must be read from the underlying B<BIO> layer in order to
-complete the actual SSL_*() operation.
-A call to L<SSL_get_error(3)> should return
-SSL_ERROR_WANT_READ.
-
-=item SSL_X509_LOOKUP
-
-The operation did not complete because an application callback set by
-SSL_CTX_set_client_cert_cb() has asked to be called again.
-A call to L<SSL_get_error(3)> should return
-SSL_ERROR_WANT_X509_LOOKUP.
-
-=item SSL_ASYNC_PAUSED
-
-An asynchronous operation partially completed and was then paused. See
-L<SSL_get_all_async_fds(3)>. A call to L<SSL_get_error(3)> should return
-SSL_ERROR_WANT_ASYNC.
-
-=item SSL_ASYNC_NO_JOBS
-
-The asynchronous job could not be started because there were no async jobs
-available in the pool (see ASYNC_init_thread(3)). A call to L<SSL_get_error(3)>
-should return SSL_ERROR_WANT_ASYNC_JOB.
-
-=back
-
-SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup(),
-SSL_want_async() and SSL_want_async_job() return 1, when the corresponding
-condition is true or 0 otherwise.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<err(3)>, L<SSL_get_error(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-SSL_write - write bytes to a TLS/SSL connection
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- int SSL_write(SSL *ssl, const void *buf, int num);
-
-=head1 DESCRIPTION
-
-SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
-B<ssl> connection.
-
-=head1 NOTES
-
-If necessary, SSL_write() will negotiate a TLS/SSL session, if
-not already explicitly performed by L<SSL_connect(3)> or
-L<SSL_accept(3)>. If the
-peer requests a re-negotiation, it will be performed transparently during
-the SSL_write() operation. The behaviour of SSL_write() depends on the
-underlying BIO.
-
-For the transparent negotiation to succeed, the B<ssl> must have been
-initialized to client or server mode. This is being done by calling
-L<SSL_set_connect_state(3)> or SSL_set_accept_state()
-before the first call to an L<SSL_read(3)> or SSL_write() function.
-
-If the underlying BIO is B<blocking>, SSL_write() will only return, once the
-write operation has been finished or an error occurred, except when a
-renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
-This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
-L<SSL_CTX_set_mode(3)> call.
-
-If the underlying BIO is B<non-blocking>, SSL_write() will also return,
-when the underlying BIO could not satisfy the needs of SSL_write()
-to continue the operation. In this case a call to
-L<SSL_get_error(3)> with the
-return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
-call to SSL_write() can also cause read operations! The calling process
-then must repeat the call after taking appropriate action to satisfy the
-needs of SSL_write(). The action depends on the underlying BIO. When using a
-non-blocking socket, nothing is to be done, but select() can be used to check
-for the required condition. When using a buffering BIO, like a BIO pair, data
-must be written into or retrieved out of the BIO before being able to continue.
-
-SSL_write() will only return with success, when the complete contents
-of B<buf> of length B<num> has been written. This default behaviour
-can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
-L<SSL_CTX_set_mode(3)>. When this flag is set,
-SSL_write() will also return with success, when a partial write has been
-successfully completed. In this case the SSL_write() operation is considered
-completed. The bytes are sent and a new SSL_write() operation with a new
-buffer (with the already sent bytes removed) must be started.
-A partial write is performed with the size of a message block, which is
-16kB for SSLv3/TLSv1.
-
-=head1 WARNING
-
-When an SSL_write() operation has to be repeated because of
-B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
-with the same arguments.
-
-When calling SSL_write() with num=0 bytes to be sent the behaviour is
-undefined.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item E<gt>0
-
-The write operation was successful, the return value is the number of
-bytes actually written to the TLS/SSL connection.
-
-=item Z<>0
-
-The write operation was not successful. Probably the underlying connection
-was closed. Call SSL_get_error() with the return value B<ret> to find out,
-whether an error occurred or the connection was shut down cleanly
-(SSL_ERROR_ZERO_RETURN).
-
-=item E<lt>0
-
-The write operation was not successful, because either an error occurred
-or action must be taken by the calling process. Call SSL_get_error() with the
-return value B<ret> to find out the reason.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_get_error(3)>, L<SSL_read(3)>,
-L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
-L<SSL_connect(3)>, L<SSL_accept(3)>
-L<SSL_set_connect_state(3)>,
-L<ssl(3)>, L<bio(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=head1 NAME
-
-d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length);
- int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);
-
-=head1 DESCRIPTION
-
-These functions decode and encode an SSL_SESSION object.
-For encoding details see L<d2i_X509(3)>.
-
-SSL_SESSION objects keep internal link information about the session cache
-list, when being inserted into one SSL_CTX object's session cache.
-One SSL_SESSION object, regardless of its reference count, must therefore
-only be used with one SSL_CTX object (and the SSL objects created
-from this SSL_CTX object).
-
-=head1 RETURN VALUES
-
-d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION
-object. In case of failure the NULL-pointer is returned and the error message
-can be retrieved from the error stack.
-
-i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes.
-When the session is not valid, B<0> is returned and no operation is performed.
-
-=head1 SEE ALSO
-
-L<ssl(3)>, L<SSL_SESSION_free(3)>,
-L<SSL_CTX_sess_set_get_cb(3)>,
-L<d2i_X509(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
+++ /dev/null
-=pod
-
-=for comment openssl_manual_section:7
-
-=head1 NAME
-
-SSL - OpenSSL SSL/TLS library
-
-=head1 SYNOPSIS
-
-See the individual manual pages for details.
-
-=head1 DESCRIPTION
-
-The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
-Transport Layer Security (TLS v1) protocols. It provides a rich API which is
-documented here.
-
-Then an B<SSL_CTX> object is created as a framework to establish
-TLS/SSL enabled connections (see L<SSL_CTX_new(3)>).
-Various options regarding certificates, algorithms etc. can be set
-in this object.
-
-When a network connection has been created, it can be assigned to an
-B<SSL> object. After the B<SSL> object has been created using
-L<SSL_new(3)>, L<SSL_set_fd(3)> or
-L<SSL_set_bio(3)> can be used to associate the network
-connection with the object.
-
-Then the TLS/SSL handshake is performed using
-L<SSL_accept(3)> or L<SSL_connect(3)>
-respectively.
-L<SSL_read(3)> and L<SSL_write(3)> are used
-to read and write data on the TLS/SSL connection.
-L<SSL_shutdown(3)> can be used to shut down the
-TLS/SSL connection.
-
-=head1 DATA STRUCTURES
-
-Currently the OpenSSL B<ssl> library functions deals with the following data
-structures:
-
-=over 4
-
-=item B<SSL_METHOD> (SSL Method)
-
-That's a dispatch structure describing the internal B<ssl> library
-methods/functions which implement the various protocol versions (SSLv3
-TLSv1, ...). It's needed to create an B<SSL_CTX>.
-
-=item B<SSL_CIPHER> (SSL Cipher)
-
-This structure holds the algorithm information for a particular cipher which
-are a core part of the SSL/TLS protocol. The available ciphers are configured
-on a B<SSL_CTX> basis and the actually used ones are then part of the
-B<SSL_SESSION>.
-
-=item B<SSL_CTX> (SSL Context)
-
-That's the global context structure which is created by a server or client
-once per program life-time and which holds mainly default values for the
-B<SSL> structures which are later created for the connections.
-
-=item B<SSL_SESSION> (SSL Session)
-
-This is a structure containing the current TLS/SSL session details for a
-connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
-
-=item B<SSL> (SSL Connection)
-
-That's the main SSL/TLS structure which is created by a server or client per
-established connection. This actually is the core structure in the SSL API.
-Under run-time the application usually deals with this structure which has
-links to mostly all other structures.
-
-=back
-
-
-=head1 HEADER FILES
-
-Currently the OpenSSL B<ssl> library provides the following C header files
-containing the prototypes for the data structures and functions:
-
-=over 4
-
-=item B<ssl.h>
-
-That's the common header file for the SSL/TLS API. Include it into your
-program to make the API of the B<ssl> library available. It internally
-includes both more private SSL headers and headers from the B<crypto> library.
-Whenever you need hard-core details on the internals of the SSL API, look
-inside this header file.
-
-=item B<ssl2.h>
-
-Unused. Present for backwards compatibility only.
-
-=item B<ssl3.h>
-
-That's the sub header file dealing with the SSLv3 protocol only.
-I<Usually you don't have to include it explicitly because
-it's already included by ssl.h>.
-
-=item B<tls1.h>
-
-That's the sub header file dealing with the TLSv1 protocol only.
-I<Usually you don't have to include it explicitly because
-it's already included by ssl.h>.
-
-=back
-
-=head1 API FUNCTIONS
-
-Currently the OpenSSL B<ssl> library exports 214 API functions.
-They are documented in the following:
-
-=head2 Dealing with Protocol Methods
-
-Here we document the various API functions which deal with the SSL/TLS
-protocol methods defined in B<SSL_METHOD> structures.
-
-=over 4
-
-=item const SSL_METHOD *B<TLS_method>(void);
-
-Constructor for the I<version-flexible> SSL_METHOD structure for clients,
-servers or both.
-See L<SSL_CTX_new(3)> for details.
-
-=item const SSL_METHOD *B<TLS_client_method>(void);
-
-Constructor for the I<version-flexible> SSL_METHOD structure for clients.
-
-=item const SSL_METHOD *B<TLS_server_method>(void);
-
-Constructor for the I<version-flexible> SSL_METHOD structure for servers.
-
-=item const SSL_METHOD *B<TLSv1_2_method>(void);
-
-Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both.
-
-=item const SSL_METHOD *B<TLSv1_2_client_method>(void);
-
-Constructor for the TLSv1.2 SSL_METHOD structure for clients.
-
-=item const SSL_METHOD *B<TLSv1_2_server_method>(void);
-
-Constructor for the TLSv1.2 SSL_METHOD structure for servers.
-
-=item const SSL_METHOD *B<TLSv1_1_method>(void);
-
-Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both.
-
-=item const SSL_METHOD *B<TLSv1_1_client_method>(void);
-
-Constructor for the TLSv1.1 SSL_METHOD structure for clients.
-
-=item const SSL_METHOD *B<TLSv1_1_server_method>(void);
-
-Constructor for the TLSv1.1 SSL_METHOD structure for servers.
-
-=item const SSL_METHOD *B<TLSv1_method>(void);
-
-Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both.
-
-=item const SSL_METHOD *B<TLSv1_client_method>(void);
-
-Constructor for the TLSv1 SSL_METHOD structure for clients.
-
-=item const SSL_METHOD *B<TLSv1_server_method>(void);
-
-Constructor for the TLSv1 SSL_METHOD structure for servers.
-
-=item const SSL_METHOD *B<SSLv3_method>(void);
-
-Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both.
-
-=item const SSL_METHOD *B<SSLv3_client_method>(void);
-
-Constructor for the SSLv3 SSL_METHOD structure for clients.
-
-=item const SSL_METHOD *B<SSLv3_server_method>(void);
-
-Constructor for the SSLv3 SSL_METHOD structure for servers.
-
-=back
-
-=head2 Dealing with Ciphers
-
-Here we document the various API functions which deal with the SSL/TLS
-ciphers defined in B<SSL_CIPHER> structures.
-
-=over 4
-
-=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len);
-
-Write a string to I<buf> (with a maximum size of I<len>) containing a human
-readable description of I<cipher>. Returns I<buf>.
-
-=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits);
-
-Determine the number of bits in I<cipher>. Because of export crippled ciphers
-there are two bits: The bits the algorithm supports in general (stored to
-I<alg_bits>) and the bits which are actually used (the return value).
-
-=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher);
-
-Return the internal name of I<cipher> as a string. These are the various
-strings defined by the I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx>
-definitions in the header files.
-
-=item const char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher);
-
-Returns a string like "C<SSLv3>" or "C<TLSv1.2>" which indicates the
-SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined
-in the specification the first time).
-
-=back
-
-=head2 Dealing with Protocol Contexts
-
-Here we document the various API functions which deal with the SSL/TLS
-protocol context defined in the B<SSL_CTX> structure.
-
-=over 4
-
-=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x);
-
-=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509);
-
-=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c);
-
-=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx);
-
-=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg);
-
-=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t);
-
-=item void B<SSL_CTX_free>(SSL_CTX *a);
-
-=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx);
-
-=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx);
-
-=item STACK *B<SSL_CTX_get_ciphers>(const SSL_CTX *ctx);
-
-=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx);
-
-=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
-
-=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx);
-
-=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx);
-
-=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
-
-=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret);
-
-=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx);
-
-=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx);
-
-=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx);
-
-=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx);
-
-=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, const char *CAfile, const char *CApath);
-
-=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth);
-
-=item int SSL_CTX_up_ref(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c);
-
-=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx);
-
-=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy);
-
-=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess);
-
-=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess);
-
-=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx);
-
-=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx, t);
-
-=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy));
-
-=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess));
-
-=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess));
-
-=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx);
-
-=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx);
-
-=item int B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg);
-
-=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
-
-=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg)
-
-=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str);
-
-=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list);
-
-=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
-
-=item int B<SSL_CTX_set_ct_validation_callback>(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg);
-
-=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void))
-
-=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m);
-
-=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx);
-
-Use the default paths to locate trusted CA certificates. There is one default
-directory path and one default file path. Both are set via this call.
-
-=item int B<SSL_CTX_set_default_verify_dir>(SSL_CTX *ctx)
-
-Use the default directory path to locate trusted CA certificates.
-
-=item int B<SSL_CTX_set_default_verify_file>(SSL_CTX *ctx)
-
-Use the file path to locate trusted CA certificates.
-
-=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg);
-
-=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));
-
-=item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
-
-=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg);
-
-=item unsigned long B<SSL_CTX_clear_options>(SSL_CTX *ctx, unsigned long op);
-
-=item unsigned long B<SSL_CTX_get_options>(SSL_CTX *ctx);
-
-=item unsigned long B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op);
-
-=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode);
-
-=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m);
-
-=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode);
-
-=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth);
-
-=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t);
-
-=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh);
-
-=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void));
-
-=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void))
-
-=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey);
-
-=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len);
-
-=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
-
-=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa);
-
-=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len);
-
-=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, const char *file, int type);
-
-=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x);
-
-=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d);
-
-=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, const char *file, int type);
-
-=item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx);
-
-=item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx);
-
-=item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
-
-=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint);
-
-=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
-
-
-=back
-
-=head2 Dealing with Sessions
-
-Here we document the various API functions which deal with the SSL/TLS
-sessions defined in the B<SSL_SESSION> structures.
-
-=over 4
-
-=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b);
-
-=item void B<SSL_SESSION_free>(SSL_SESSION *ss);
-
-=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s);
-
-=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx);
-
-=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
-
-=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s);
-
-=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s);
-
-=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a);
-
-=item SSL_SESSION *B<SSL_SESSION_new>(void);
-
-=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x);
-
-=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x);
-
-=item int B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a);
-
-=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg);
-
-=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t);
-
-=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t);
-
-=back
-
-=head2 Dealing with Connections
-
-Here we document the various API functions which deal with the SSL/TLS
-connection defined in the B<SSL> structure.
-
-=over 4
-
-=item int B<SSL_accept>(SSL *ssl);
-
-=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir);
-
-=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file);
-
-=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x);
-
-=item char *B<SSL_alert_desc_string>(int value);
-
-=item char *B<SSL_alert_desc_string_long>(int value);
-
-=item char *B<SSL_alert_type_string>(int value);
-
-=item char *B<SSL_alert_type_string_long>(int value);
-
-=item int B<SSL_check_private_key>(const SSL *ssl);
-
-=item void B<SSL_clear>(SSL *ssl);
-
-=item long B<SSL_clear_num_renegotiations>(SSL *ssl);
-
-=item int B<SSL_connect>(SSL *ssl);
-
-=item int B<SSL_copy_session_id>(SSL *t, const SSL *f);
-
-Sets the session details for B<t> to be the same as in B<f>. Returns 1 on
-success or 0 on failure.
-
-=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg);
-
-=item int B<SSL_do_handshake>(SSL *ssl);
-
-=item SSL *B<SSL_dup>(SSL *ssl);
-
-SSL_dup() allows applications to configure an SSL handle for use
-in multiple SSL connections, and then duplicate it prior to initiating
-each connection with the duplicated handle.
-Use of SSL_dup() avoids the need to repeat the configuration of the
-handles for each connection.
-This is used internally by L<BIO_s_accept(3)> to construct
-per-connection SSL handles after L<accept(2)>.
-
-For SSL_dup() to work, the connection MUST be in its initial state
-and MUST NOT have not yet have started the SSL handshake.
-For connections that are not in their initial state SSL_dup() just
-increments an internal reference count and returns the I<same>
-handle.
-It may be possible to use L<SSL_clear(3)> to recycle an SSL handle
-that is not in its initial state for re-use, but this is best
-avoided.
-Instead, save and restore the session, if desired, and construct a
-fresh handle for each connection.
-
-=item STACK *B<SSL_dup_CA_list>(STACK *sk);
-
-=item void B<SSL_free>(SSL *ssl);
-
-=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl);
-
-=item char *B<SSL_get_app_data>(SSL *ssl);
-
-=item X509 *B<SSL_get_certificate>(const SSL *ssl);
-
-=item const char *B<SSL_get_cipher>(const SSL *ssl);
-
-=item int B<SSL_is_dtls>(const SSL *ssl);
-
-=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits);
-
-=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n);
-
-=item char *B<SSL_get_cipher_name>(const SSL *ssl);
-
-=item char *B<SSL_get_cipher_version>(const SSL *ssl);
-
-=item STACK *B<SSL_get_ciphers>(const SSL *ssl);
-
-=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl);
-
-=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl);
-
-=item long B<SSL_get_default_timeout>(const SSL *ssl);
-
-=item int B<SSL_get_error>(const SSL *ssl, int i);
-
-=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx);
-
-=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void);
-
-=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void))
-
-=item int B<SSL_get_fd>(const SSL *ssl);
-
-=item void (*B<SSL_get_info_callback>(const SSL *ssl);)()
-
-=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl);
-
-=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl);
-
-=item const STACK_OF(SCT) *B<SSL_get0_peer_scts>(SSL *s);
-
-=item EVP_PKEY *B<SSL_get_privatekey>(const SSL *ssl);
-
-=item int B<SSL_get_quiet_shutdown>(const SSL *ssl);
-
-=item BIO *B<SSL_get_rbio>(const SSL *ssl);
-
-=item int B<SSL_get_read_ahead>(const SSL *ssl);
-
-=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl);
-
-=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len);
-
-=item int B<SSL_get_shutdown>(const SSL *ssl);
-
-=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl);
-
-=item int B<SSL_get_state>(const SSL *ssl);
-
-=item long B<SSL_get_time>(const SSL *ssl);
-
-=item long B<SSL_get_timeout>(const SSL *ssl);
-
-=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int, X509_STORE_CTX *)
-
-=item int B<SSL_get_verify_mode>(const SSL *ssl);
-
-=item long B<SSL_get_verify_result>(const SSL *ssl);
-
-=item char *B<SSL_get_version>(const SSL *ssl);
-
-=item BIO *B<SSL_get_wbio>(const SSL *ssl);
-
-=item int B<SSL_in_accept_init>(SSL *ssl);
-
-=item int B<SSL_in_before>(SSL *ssl);
-
-=item int B<SSL_in_connect_init>(SSL *ssl);
-
-=item int B<SSL_in_init>(SSL *ssl);
-
-=item int B<SSL_is_init_finished>(SSL *ssl);
-
-=item STACK *B<SSL_load_client_CA_file>(const char *file);
-
-=item SSL *B<SSL_new>(SSL_CTX *ctx);
-
-=item int SSL_up_ref(SSL *s);
-
-=item long B<SSL_num_renegotiations>(SSL *ssl);
-
-=item int B<SSL_peek>(SSL *ssl, void *buf, int num);
-
-=item int B<SSL_pending>(const SSL *ssl);
-
-=item int B<SSL_read>(SSL *ssl, void *buf, int num);
-
-=item int B<SSL_renegotiate>(SSL *ssl);
-
-=item char *B<SSL_rstate_string>(SSL *ssl);
-
-=item char *B<SSL_rstate_string_long>(SSL *ssl);
-
-=item long B<SSL_session_reused>(SSL *ssl);
-
-=item void B<SSL_set_accept_state>(SSL *ssl);
-
-=item void B<SSL_set_app_data>(SSL *ssl, char *arg);
-
-=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio);
-
-=item int B<SSL_set_cipher_list>(SSL *ssl, char *str);
-
-=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list);
-
-=item void B<SSL_set_connect_state>(SSL *ssl);
-
-=item int B<SSL_set_ct_validation_callback>(SSL *ssl, ssl_ct_validation_cb callback, void *arg);
-
-=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg);
-
-=item int B<SSL_set_fd>(SSL *ssl, int fd);
-
-=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void))
-
-=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg));
-
-=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg);
-
-=item unsigned long B<SSL_clear_options>(SSL *ssl, unsigned long op);
-
-=item unsigned long B<SSL_get_options>(SSL *ssl);
-
-=item unsigned long B<SSL_set_options>(SSL *ssl, unsigned long op);
-
-=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode);
-
-=item void B<SSL_set_read_ahead>(SSL *ssl, int yes);
-
-=item int B<SSL_set_rfd>(SSL *ssl, int fd);
-
-=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session);
-
-=item void B<SSL_set_shutdown>(SSL *ssl, int mode);
-
-=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth);
-
-=item void B<SSL_set_time>(SSL *ssl, long t);
-
-=item void B<SSL_set_timeout>(SSL *ssl, long t);
-
-=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void))
-
-=item void B<SSL_set_verify_result>(SSL *ssl, long arg);
-
-=item int B<SSL_set_wfd>(SSL *ssl, int fd);
-
-=item int B<SSL_shutdown>(SSL *ssl);
-
-=item OSSL_HANDSHAKE_STATE B<SSL_get_state>(const SSL *ssl);
-
-Returns the current handshake state.
-
-=item char *B<SSL_state_string>(const SSL *ssl);
-
-=item char *B<SSL_state_string_long>(const SSL *ssl);
-
-=item long B<SSL_total_renegotiations>(SSL *ssl);
-
-=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey);
-
-=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len);
-
-=item int B<SSL_use_PrivateKey_file>(SSL *ssl, const char *file, int type);
-
-=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa);
-
-=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len);
-
-=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, const char *file, int type);
-
-=item int B<SSL_use_certificate>(SSL *ssl, X509 *x);
-
-=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d);
-
-=item int B<SSL_use_certificate_file>(SSL *ssl, const char *file, int type);
-
-=item int B<SSL_version>(const SSL *ssl);
-
-=item int B<SSL_want>(const SSL *ssl);
-
-=item int B<SSL_want_nothing>(const SSL *ssl);
-
-=item int B<SSL_want_read>(const SSL *ssl);
-
-=item int B<SSL_want_write>(const SSL *ssl);
-
-=item int B<SSL_want_x509_lookup>(const SSL *ssl);
-
-=item int B<SSL_write>(SSL *ssl, const void *buf, int num);
-
-=item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len));
-
-=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint);
-
-=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len));
-
-=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl);
-
-=item const char *B<SSL_get_psk_identity>(SSL *ssl);
-
-=back
-
-=head1 RETURN VALUES
-
-See the individual manual pages for details.
-
-=head1 SEE ALSO
-
-L<openssl(1)>, L<crypto(3)>,
-L<CRYPTO_get_ex_new_index(3)>,
-L<SSL_accept(3)>, L<SSL_clear(3)>,
-L<SSL_connect(3)>,
-L<SSL_CIPHER_get_name(3)>,
-L<SSL_COMP_add_compression_method(3)>,
-L<SSL_CTX_add_extra_chain_cert(3)>,
-L<SSL_CTX_add_session(3)>,
-L<SSL_CTX_ctrl(3)>,
-L<SSL_CTX_flush_sessions(3)>,
-L<SSL_CTX_get_verify_mode(3)>,
-L<SSL_CTX_load_verify_locations(3)>
-L<SSL_CTX_new(3)>,
-L<SSL_CTX_sess_number(3)>,
-L<SSL_CTX_sess_set_cache_size(3)>,
-L<SSL_CTX_sess_set_get_cb(3)>,
-L<SSL_CTX_sessions(3)>,
-L<SSL_CTX_set_cert_store(3)>,
-L<SSL_CTX_set_cert_verify_callback(3)>,
-L<SSL_CTX_set_cipher_list(3)>,
-L<SSL_CTX_set_client_CA_list(3)>,
-L<SSL_CTX_set_client_cert_cb(3)>,
-L<SSL_CTX_set_default_passwd_cb(3)>,
-L<SSL_CTX_set_generate_session_id(3)>,
-L<SSL_CTX_set_info_callback(3)>,
-L<SSL_CTX_set_max_cert_list(3)>,
-L<SSL_CTX_set_mode(3)>,
-L<SSL_CTX_set_msg_callback(3)>,
-L<SSL_CTX_set_options(3)>,
-L<SSL_CTX_set_quiet_shutdown(3)>,
-L<SSL_CTX_set_read_ahead(3)>,
-L<SSL_CTX_set_session_cache_mode(3)>,
-L<SSL_CTX_set_session_id_context(3)>,
-L<SSL_CTX_set_ssl_version(3)>,
-L<SSL_CTX_set_timeout(3)>,
-L<SSL_CTX_set_tmp_dh_callback(3)>,
-L<SSL_CTX_set_verify(3)>,
-L<SSL_CTX_use_certificate(3)>,
-L<SSL_alert_type_string(3)>,
-L<SSL_do_handshake(3)>,
-L<SSL_enable_ct(3)>,
-L<SSL_get_SSL_CTX(3)>,
-L<SSL_get_ciphers(3)>,
-L<SSL_get_client_CA_list(3)>,
-L<SSL_get_default_timeout(3)>,
-L<SSL_get_error(3)>,
-L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
-L<SSL_get_fd(3)>,
-L<SSL_get_peer_cert_chain(3)>,
-L<SSL_get_rbio(3)>,
-L<SSL_get_session(3)>,
-L<SSL_get_verify_result(3)>,
-L<SSL_get_version(3)>,
-L<SSL_load_client_CA_file(3)>,
-L<SSL_new(3)>,
-L<SSL_pending(3)>,
-L<SSL_read(3)>,
-L<SSL_rstate_string(3)>,
-L<SSL_session_reused(3)>,
-L<SSL_set_bio(3)>,
-L<SSL_set_connect_state(3)>,
-L<SSL_set_fd(3)>,
-L<SSL_set_session(3)>,
-L<SSL_set_shutdown(3)>,
-L<SSL_shutdown(3)>,
-L<SSL_state_string(3)>,
-L<SSL_want(3)>,
-L<SSL_write(3)>,
-L<SSL_SESSION_free(3)>,
-L<SSL_SESSION_get_time(3)>,
-L<d2i_SSL_SESSION(3)>,
-L<SSL_CTX_set_psk_client_callback(3)>,
-L<SSL_CTX_use_psk_identity_hint(3)>,
-L<SSL_get_psk_identity(3)>,
-L<DTLSv1_listen(3)>
-
-=head1 HISTORY
-
-B<SSLv2_client_method>, B<SSLv2_server_method> and B<SSLv2_method> where removed
-in OpenSSL 1.1.0.
-
-The return type of B<SSL_copy_session_id> was changed from void to int in
-OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (the "License"). You may not use
-this file except in compliance with the License. You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
3 => [ 'SYNOPSIS', 'RETURN\s+VALUES' ],
5 => [ ],
7 => [ ] );
-my %default_sections =
- ( apps => 1,
- crypto => 3,
- ssl => 3 );
# Cross-check functions in the NAME and SYNOPSIS section.
sub name_synopsis()
&name_synopsis($id, $filename, $contents)
unless $contents =~ /=for comment generic/
- or $contents =~ /=for comment openssl_manual_section:7/
- or $filename =~ m@/apps/@;
+ or $filename =~ m@man[157]/@;
print "$id doesn't start with =pod\n"
if $contents !~ /^=pod/;
# Find what section this page is in. If run from "." assume
# section 3.
- my $section = $default_sections{$dirname} || 3;
- if ($contents =~ /^=for\s+comment\s+openssl_manual_section:\s*(\d+)\s*$/m) {
- $section = $1;
- }
+ my $section = 3;
+ $section = $1 if $dirname =~ /man([1-9])/;
foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
print "$id doesn't have a head1 section matching $_\n"
my %return;
foreach my $pod ( glob("$dir/*.pod") ) {
- next if $pod eq 'doc/crypto/crypto.pod';
- next if $pod eq 'doc/ssl/ssl.pod';
my %podinfo = extract_pod_info($pod);
foreach my $n ( @{$podinfo{names}} ) {
$return{$n} = $pod;
print "# Duplicate $n in $pod and $dups{$n}\n"
- if defined $dups{$n};
+ if defined $dups{$n} && $dups{$n} ne $pod;
$dups{$n} = $pod;
}
}
return %return;
}
+my %docced = &getdocced('doc/man3');
+
sub printem()
{
- my $docdir = shift;
my $numfile = shift;
- my %docced = &getdocced($docdir);
my $count = 0;
foreach my $func ( &parsenum($numfile) ) {
print "# Found $count missing from $numfile\n\n";
}
-
-&printem('doc/crypto', 'util/libcrypto.num');
-&printem('doc/ssl', 'util/libssl.num');
+&printem('util/libcrypto.num');
+&printem('util/libssl.num');
=item B<section =E<gt> N>
-The value MUST be a number, and will be the default man section number
-to be used with the given .pod file. This number can be altered if
-the .pod file has a line like this:
-
- =for comment openssl_manual_section: 4
+The value MUST be a number, and will be the man section number
+to be used with the given .pod file.
=item B<debug =E<gt> 0|1>
my %podinfo = ( section => $defaults{section});
while(<$input>) {
s|\R$||;
- if (m|^=for\s+comment\s+openssl_manual_section:\s*([0-9])\s*$|) {
- print STDERR "DEBUG: Found man section number $1\n"
- if $defaults{debug};
- $podinfo{section} = $1;
- }
-
# Stop reading when we have reached past the NAME section.
last if (m|^=head1|
&& defined $podinfo{lastsect}
my %options = ();
GetOptions(\%options,
'sourcedir=s', # Source directory
- 'subdir=s%', # Subdirectories to look through,
+ 'section=i@', # Subdirectories to look through,
# with associated section numbers
'destdir=s', # Destination directory
#'in=s@', # Explicit files to process (ignores sourcedir)
- #'section=i', # Default section used for --in files
'type=s', # The result type, 'man' or 'html'
'remove', # To remove files rather than writing them
'dry-run|n', # Only output file names on STDOUT
'debug|D+',
);
-unless ($options{subdir}) {
- $options{subdir} = { apps => '1',
- crypto => '3',
- ssl => '3' };
+unless ($options{section}) {
+ $options{section} = [ 1, 3, 5, 7 ];
}
unless ($options{sourcedir}) {
$options{sourcedir} = catdir($config{sourcedir}, "doc");
}
-pod2usage(1) unless ( defined $options{subdir}
+pod2usage(1) unless ( defined $options{section}
&& defined $options{sourcedir}
&& defined $options{destdir}
&& defined $options{type}
if defined $options{destdir};
print STDERR "DEBUG: --type = $options{type}\n"
if defined $options{type};
- foreach (keys %{$options{subdir}}) {
- print STDERR "DEBUG: --subdir = $_=$options{subdir}->{$_}\n";
+ foreach (sort @{$options{section}}) {
+ print STDERR "DEBUG: --section = $_\n";
}
print STDERR "DEBUG: --remove = $options{remove}\n"
if defined $options{remove};
my $symlink_exists = eval { symlink("",""); 1 };
-foreach my $subdir (keys %{$options{subdir}}) {
- my $section = $options{subdir}->{$subdir};
+foreach my $section (sort @{$options{section}}) {
+ my $subdir = "man$section";
my $podsourcedir = catfile($options{sourcedir}, $subdir);
my $podglob = catfile($podsourcedir, "*.pod");
projects / oweals / openssl.git / commitdiff