diff options
| author |   Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com> | 2023-10-10 14:33:42 +0000 |
|---|---|---|
| committer | Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com> | 2023-10-10 14:33:42 +0000 |
| commit | af1a266670d040d2f4083ff309d732d648afba2a (patch) | |
| tree | 2fc46203448ddcc6f81546d379abfaeb323575e9 /roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1 | |
| parent | e02cda008591317b1625707ff8e115a4841aa889 (diff) | |
Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec
Diffstat (limited to 'roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1')
50 files changed, 15243 insertions, 0 deletions
diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/CA.pl.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/CA.pl.pod new file mode 100644 index 000000000..6949ec622 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/CA.pl.pod @@ -0,0 +1,214 @@ +=pod + +=head1 NAME + +CA.pl - friendlier interface for OpenSSL certificate programs + +=head1 SYNOPSIS + +B<CA.pl> +B<-?> | +B<-h> | +B<-help> + +B<CA.pl> +B<-newcert> | +B<-newreq> | +B<-newreq-nodes> | +B<-xsign> | +B<-sign> | +B<-signCA> | +B<-signcert> | +B<-crl> | +B<-newca> +[B<-extra-cmd> extra-params] + +B<CA.pl> B<-pkcs12> [B<-extra-pkcs12> extra-params] [B<certname>] + +B<CA.pl> B<-verify> [B<-extra-verify> extra-params] B<certfile>... + +B<CA.pl> B<-revoke> [B<-extra-ca> extra-params] B<certfile> [B<reason>] + +=head1 DESCRIPTION + +The B<CA.pl> script is a perl script that supplies the relevant command line +arguments to the B<openssl> command for some common certificate operations. +It is intended to simplify the process of certificate creation and management +by the use of some simple options. + +=head1 OPTIONS + +=over 4 + +=item B<?>, B<-h>, B<-help> + +Prints a usage message. + +=item B<-newcert> + +Creates a new self signed certificate. The private key is written to the file +"newkey.pem" and the request written to the file "newreq.pem". +This argument invokes B<openssl req> command. + +=item B<-newreq> + +Creates a new certificate request. The private key is written to the file +"newkey.pem" and the request written to the file "newreq.pem". +Executes B<openssl req> command below the hood. + +=item B<-newreq-nodes> + +Is like B<-newreq> except that the private key will not be encrypted. +Uses B<openssl req> command. + +=item B<-newca> + +Creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert> +and B<-xsign> options). The user is prompted to enter the filename of the CA +certificates (which should also contain the private key) or by hitting ENTER +details of the CA will be prompted for. The relevant files and directories +are created in a directory called "demoCA" in the current directory. +B<openssl req> and B<openssl ca> commands are get invoked. + +=item B<-pkcs12> + +Create a PKCS#12 file containing the user certificate, private key and CA +certificate. It expects the user certificate and private key to be in the +file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem, +it creates a file "newcert.p12". This command can thus be called after the +B<-sign> option. The PKCS#12 file can be imported directly into a browser. +If there is an additional argument on the command line it will be used as the +"friendly name" for the certificate (which is typically displayed in the browser +list box), otherwise the name "My Certificate" is used. +Delegates work to B<openssl pkcs12> command. + +=item B<-sign>, B<-signcert>, B<-xsign> + +Calls the B<ca> program to sign a certificate request. It expects the request +to be in the file "newreq.pem". The new certificate is written to the file +"newcert.pem" except in the case of the B<-xsign> option when it is written +to standard output. Leverages B<openssl ca> command. + +=item B<-signCA> + +This option is the same as the B<-signreq> option except it uses the +configuration file section B<v3_ca> and so makes the signed request a +valid CA certificate. This is useful when creating intermediate CA from +a root CA. Extra params are passed on to B<openssl ca> command. + +=item B<-signcert> + +This option is the same as B<-sign> except it expects a self signed certificate +to be present in the file "newreq.pem". +Extra params are passed on to B<openssl x509> and B<openssl ca> commands. + +=item B<-crl> + +Generate a CRL. Executes B<openssl ca> command. + +=item B<-revoke certfile [reason]> + +Revoke the certificate contained in the specified B<certfile>. An optional +reason may be specified, and must be one of: B<unspecified>, +B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>, +B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>. +Leverages B<openssl ca> command. + +=item B<-verify> + +Verifies certificates against the CA certificate for "demoCA". If no +certificates are specified on the command line it tries to verify the file +"newcert.pem". Invokes B<openssl verify> command. + +=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> <extra-params> + +The purpose of these parameters is to allow optional parameters to be supplied +to B<openssl> that this command executes. The B<-extra-cmd> are specific to the +option being used and the B<openssl> command getting invoked. For example +when this command invokes B<openssl req> extra parameters can be passed on +with the B<-extra-req> parameter. The +B<openssl> commands being invoked per option are documented below. +Users should consult B<openssl> command documentation for more information. + +=back + +=head1 EXAMPLES + +Create a CA hierarchy: + + CA.pl -newca + +Complete certificate creation example: create a CA, create a request, sign +the request and finally create a PKCS#12 file containing it. + + CA.pl -newca + CA.pl -newreq + CA.pl -signreq + CA.pl -pkcs12 "My Test Certificate" + +=head1 DSA CERTIFICATES + +Although the B<CA.pl> creates RSA CAs and requests it is still possible to +use it with DSA certificates and requests using the L<req(1)> command +directly. The following example shows the steps that would typically be taken. + +Create some DSA parameters: + + openssl dsaparam -out dsap.pem 1024 + +Create a DSA CA certificate and private key: + + openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem + +Create the CA directories and files: + + CA.pl -newca + +enter cacert.pem when prompted for the CA file name. + +Create a DSA certificate request and private key (a different set of parameters +can optionally be created first): + + openssl req -out newreq.pem -newkey dsa:dsap.pem + +Sign the request: + + CA.pl -signreq + +=head1 NOTES + +Most of the filenames mentioned can be modified by editing the B<CA.pl> script. + +If the demoCA directory already exists then the B<-newca> command will not +overwrite it and will do nothing. This can happen if a previous call using +the B<-newca> option terminated abnormally. To get the correct behaviour +delete the demoCA directory if it already exists. + +Under some environments it may not be possible to run the B<CA.pl> script +directly (for example Win32) and the default configuration file location may +be wrong. In this case the command: + + perl -S CA.pl + +can be used and the B<OPENSSL_CONF> environment variable changed to point to +the correct path of the configuration file. + +The script is intended as a simple front end for the B<openssl> program for use +by a beginner. Its behaviour isn't always what is wanted. For more control over the +behaviour of the certificate commands call the B<openssl> command directly. + +=head1 SEE ALSO + +L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>, +L<config(5)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/asn1parse.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/asn1parse.pod new file mode 100644 index 000000000..0e1fcc686 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/asn1parse.pod @@ -0,0 +1,215 @@ +=pod + +=head1 NAME + +openssl-asn1parse, +asn1parse - ASN.1 parsing tool + +=head1 SYNOPSIS + +B<openssl> B<asn1parse> +[B<-help>] +[B<-inform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-offset number>] +[B<-length number>] +[B<-i>] +[B<-oid filename>] +[B<-dump>] +[B<-dlimit num>] +[B<-strparse offset>] +[B<-genstr string>] +[B<-genconf file>] +[B<-strictpem>] +[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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ca.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ca.pod new file mode 100644 index 000000000..27bb31493 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ca.pod @@ -0,0 +1,769 @@ +=pod + +=head1 NAME + +openssl-ca, +ca - sample minimal CA application + +=head1 SYNOPSIS + +B<openssl> B<ca> +[B<-help>] +[B<-verbose>] +[B<-config filename>] +[B<-name section>] +[B<-gencrl>] +[B<-revoke file>] +[B<-valid file>] +[B<-status serial>] +[B<-updatedb>] +[B<-crl_reason reason>] +[B<-crl_hold instruction>] +[B<-crl_compromise time>] +[B<-crl_CA_compromise time>] +[B<-crldays days>] +[B<-crlhours hours>] +[B<-crlexts section>] +[B<-startdate date>] +[B<-enddate date>] +[B<-days arg>] +[B<-md arg>] +[B<-policy arg>] +[B<-keyfile arg>] +[B<-keyform PEM|DER>] +[B<-key arg>] +[B<-passin arg>] +[B<-cert file>] +[B<-selfsign>] +[B<-in file>] +[B<-out file>] +[B<-notext>] +[B<-outdir dir>] +[B<-infiles>] +[B<-spkac file>] +[B<-ss_cert file>] +[B<-preserveDN>] +[B<-noemailDN>] +[B<-batch>] +[B<-msie_hack>] +[B<-extensions section>] +[B<-extfile section>] +[B<-engine id>] +[B<-subj arg>] +[B<-utf8>] +[B<-sigopt nm:v>] +[B<-create_serial>] +[B<-rand_serial>] +[B<-multivalue-rdn>] +[B<-rand file...>] +[B<-writerand file>] + +=head1 DESCRIPTION + +The B<ca> command is a minimal CA application. It can be used +to sign certificate requests in a variety of forms and generate +CRLs it also maintains a text database of issued certificates +and their status. + +The options descriptions will be divided into each purpose. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-verbose> + +This prints extra details about the operations being performed. + +=item B<-config filename> + +Specifies the configuration file to use. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. + +=item B<-name section> + +Specifies the configuration file section to use (overrides +B<default_ca> in the B<ca> section). + +=item B<-in filename> + +An input filename containing a single certificate request to be +signed by the CA. + +=item B<-ss_cert filename> + +A single self-signed certificate to be signed by the CA. + +=item B<-spkac filename> + +A file containing a single Netscape signed public key and challenge +and additional field values to be signed by the CA. See the B<SPKAC FORMAT> +section for information on the required input and output format. + +=item B<-infiles> + +If present this should be the last option, all subsequent arguments +are taken as the names of files containing certificate requests. + +=item B<-out filename> + +The output file to output certificates to. The default is standard +output. The certificate details will also be printed out to this +file in PEM format (except that B<-spkac> outputs DER format). + +=item B<-outdir directory> + +The directory to output certificates to. The certificate will be +written to a filename consisting of the serial number in hex with +".pem" appended. + +=item B<-cert> + +The CA certificate file. + +=item B<-keyfile filename> + +The private key to sign requests with. + +=item B<-keyform PEM|DER> + +The format of the data in the private key file. +The default is PEM. + +=item B<-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<-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), or +YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In +both formats, seconds SS and timezone Z must be present. + +=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), or +YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In +both formats, seconds SS and timezone Z must be present. + +=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. For signing +algorithms that do not support a digest (i.e. Ed25519 and Ed448) any message +digest that is set is ignored. 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 deprecated 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. + +=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 +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=...>. +Keyword characters may be escaped by \ (backslash), and whitespace is retained. +Empty values are permitted, but the corresponding type will not be included +in the resulting certificate. + +=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. +To get random serial numbers, use the B<-rand_serial> flag instead; this +should only be used for simple error-recovery. + +=item B<-rand_serial> + +Generate a large random number to use as the serial number. +This overrides any option or configuration to use a serial number file. + +=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<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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> + +At startup the specified file is loaded into the random number generator, +and at exit 256 bytes will be written to it. + +=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 except where the signing algorithm does +not require a digest (i.e. Ed25519 and Ed448). + +=item B<database> + +The text database file to use. Mandatory. This file must be present +though initially it will be empty. + +=item B<unique_subject> + +If the value B<yes> is given, the valid certificate entries in the +database must have unique subjects. if the value B<no> is given, +several valid certificate entries may have the exact same subject. +The default value is B<yes>, to be compatible with older (pre 0.9.8) +versions of OpenSSL. However, to make CA certificate roll-over easier, +it's recommended to use the value B<no>, especially if combined with +the B<-selfsign> command line option. + +Note that it is valid in some circumstances for certificates to be created +without any subject. In the case where there are multiple certificates without +subjects this does not count as a duplicate. + +=item B<serial> + +A text file containing the next serial number to use in hex. Mandatory. +This file must be present and contain a valid serial number. + +=item B<crlnumber> + +A text file containing the next CRL number to use in hex. The crl number +will be inserted in the CRLs only if this file exists. If this file is +present, it must contain a valid CRL number. + +=item B<x509_extensions> + +The same as B<-extensions>. + +=item B<crl_extensions> + +The same as B<-crlexts>. + +=item B<preserve> + +The same as B<-preserveDN> + +=item B<email_in_dn> + +The same as B<-noemailDN>. If you want the EMAIL field to be removed +from the DN of the certificate simply set this to 'no'. If not present +the default is to allow for the EMAIL filed in the certificate's DN. + +=item B<msie_hack> + +The same as B<-msie_hack> + +=item B<policy> + +The same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section +for more information. + +=item B<name_opt>, B<cert_opt> + +These options allow the format used to display the certificate details +when asking the user to confirm signing. All the options supported by +the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used +here, except the B<no_signame> and B<no_sigdump> are permanently set +and cannot be disabled (this is because the certificate signature cannot +be displayed because the certificate has not been signed at this point). + +For convenience the values B<ca_default> are accepted by both to produce +a reasonable output. + +If neither option is present the format used in earlier versions of +OpenSSL is used. Use of the old format is B<strongly> discouraged because +it only displays fields mentioned in the B<policy> section, mishandles +multicharacter string types and does not display extensions. + +=item B<copy_extensions> + +Determines how extensions in certificate requests should be handled. +If set to B<none> or this option is not present then extensions are +ignored and not copied to the certificate. If set to B<copy> then any +extensions present in the request that are not already present are copied +to the certificate. If set to B<copyall> then all extensions in the +request are copied to the certificate: if the extension is already present +in the certificate it is deleted first. See the B<WARNINGS> section before +using this option. + +The main use of this option is to allow a certificate request to supply +values for certain extensions such as subjectAltName. + +=back + +=head1 POLICY FORMAT + +The policy section consists of a set of variables corresponding to +certificate DN fields. If the value is "match" then the field value +must match the same field in the CA certificate. If the value is +"supplied" then it must be present. If the value is "optional" then +it may be present. Any fields not mentioned in the policy section +are silently deleted, unless the B<-preserveDN> option is set but +this can be regarded more of a quirk than intended behaviour. + +=head1 SPKAC FORMAT + +The input to the B<-spkac> command line option is a Netscape +signed public key and challenge. This will usually come from +the B<KEYGEN> tag in an HTML form to create a new private key. +It is however possible to create SPKACs using the B<spkac> utility. + +The file should contain the variable SPKAC set to the value of +the SPKAC and also the required DN components as name value pairs. +If you need to include the same component twice then it can be +preceded by a number and a '.'. + +When processing SPKAC format, the output is DER if the B<-out> +flag is used, but PEM format if sending to stdout or the B<-outdir> +flag is used. + +=head1 EXAMPLES + +Note: these examples assume that the B<ca> directory structure is +already set up and the relevant files already exist. This usually +involves creating a CA certificate and private key with B<req>, a +serial number file and an empty index file and placing them in +the relevant directories. + +To use the sample configuration file below the directories demoCA, +demoCA/private and demoCA/newcerts would be created. The CA +certificate would be copied to demoCA/cacert.pem and its private +key to demoCA/private/cakey.pem. A file demoCA/serial would be +created containing for example "01" and the empty index file +demoCA/index.txt. + + +Sign a certificate request: + + openssl ca -in req.pem -out newcert.pem + +Sign a certificate request, using CA extensions: + + openssl ca -in req.pem -extensions v3_ca -out newcert.pem + +Generate a CRL + + openssl ca -gencrl -out crl.pem + +Sign several requests: + + openssl ca -infiles req1.pem req2.pem req3.pem + +Certify a Netscape SPKAC: + + openssl ca -spkac spkac.txt + +A sample SPKAC file (the SPKAC line has been truncated for clarity): + + SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 + CN=Steve Test + emailAddress=steve@openssl.org + 0.OU=OpenSSL Group + 1.OU=Another Group + +A sample configuration file with the relevant sections for B<ca>: + + [ ca ] + default_ca = CA_default # The default ca section + + [ CA_default ] + + dir = ./demoCA # top dir + database = $dir/index.txt # index file. + new_certs_dir = $dir/newcerts # new certs dir + + certificate = $dir/cacert.pem # The CA cert + serial = $dir/serial # serial no file + #rand_serial = yes # for random serial#'s + private_key = $dir/private/cakey.pem# CA private key + RANDFILE = $dir/private/.rand # random number file + + default_days = 365 # how long to certify for + default_crl_days= 30 # how long before next CRL + default_md = md5 # md to use + + policy = policy_any # default policy + email_in_dn = no # Don't add the email into cert DN + + name_opt = ca_default # Subject name display option + cert_opt = ca_default # Certificate display option + copy_extensions = none # Don't copy extensions from request + + [ policy_any ] + countryName = supplied + stateOrProvinceName = optional + organizationName = optional + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + +=head1 FILES + +Note: the location of all files can change either by compile time options, +configuration file entries, environment variables or command line options. +The values below reflect the default values. + + /usr/local/ssl/lib/openssl.cnf - master configuration file + ./demoCA - main CA directory + ./demoCA/cacert.pem - CA certificate + ./demoCA/private/cakey.pem - CA private key + ./demoCA/serial - CA serial number file + ./demoCA/serial.old - CA serial number backup file + ./demoCA/index.txt - CA text database file + ./demoCA/index.txt.old - CA text database backup file + ./demoCA/certs - certificate output file + ./demoCA/.rnd - CA random seed information + +=head1 RESTRICTIONS + +The text database index file is a critical part of the process and +if corrupted it can be difficult to fix. It is theoretically possible +to rebuild the index file from all the issued certificates and a current +CRL: however there is no option to do this. + +V2 CRL features like delta CRLs are not currently supported. + +Although several requests can be input and handled at once it is only +possible to include one SPKAC or self-signed certificate. + +=head1 BUGS + +The use of an in-memory text database can cause problems when large +numbers of certificates are present because, as the name implies +the database has to be kept in memory. + +The B<ca> command really needs rewriting or the required functionality +exposed at either a command or interface level so a more friendly utility +(perl script or GUI) can handle things properly. The script +B<CA.pl> helps a little but not very much. + +Any fields in a request that are not present in a policy are silently +deleted. This does not happen if the B<-preserveDN> option is used. To +enforce the absence of the EMAIL field within the DN, as suggested by +RFCs, regardless the contents of the request' subject the B<-noemailDN> +option can be used. The behaviour should be more friendly and +configurable. + +Canceling some commands by refusing to certify a certificate can +create an empty file. + +=head1 WARNINGS + +The B<ca> command is quirky and at times downright unfriendly. + +The B<ca> utility was originally meant as an example of how to do things +in a CA. It was not supposed to be used as a full blown CA itself: +nevertheless some people are using it for this purpose. + +The B<ca> command is effectively a single user command: no locking is +done on the various files and attempts to run more than one B<ca> command +on the same database can have unpredictable results. + +The B<copy_extensions> option should be used with caution. If care is +not taken then it can be a security risk. For example if a certificate +request contains a basicConstraints extension with CA:TRUE and the +B<copy_extensions> value is set to B<copyall> and the user does not spot +this when the certificate is displayed then this will hand the requester +a valid CA certificate. + +This situation can be avoided by setting B<copy_extensions> to B<copy> +and including basicConstraints with CA:FALSE in the configuration file. +Then if the request contains a basicConstraints extension it will be +ignored. + +It is advisable to also include values for other extensions such +as B<keyUsage> to prevent a request supplying its own values. + +Additional restrictions can be placed on the CA certificate itself. +For example if the CA certificate has: + + basicConstraints = CA:TRUE, pathlen:0 + +then even if a certificate is issued with CA:TRUE it will not be valid. + +=head1 HISTORY + +Since OpenSSL 1.1.1, the program follows RFC5280. Specifically, +certificate validity period (specified by any of B<-startdate>, +B<-enddate> and B<-days>) will be encoded as UTCTime if the dates are +earlier than year 2049 (included), and as GeneralizedTime if the dates +are in year 2050 or later. + +=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-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ciphers.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ciphers.pod new file mode 100644 index 000000000..faf9e5381 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ciphers.pod @@ -0,0 +1,776 @@ +=pod + +=head1 NAME + +openssl-ciphers, +ciphers - SSL cipher display and cipher list tool + +=head1 SYNOPSIS + +B<openssl> B<ciphers> +[B<-help>] +[B<-s>] +[B<-v>] +[B<-V>] +[B<-ssl3>] +[B<-tls1>] +[B<-tls1_1>] +[B<-tls1_2>] +[B<-tls1_3>] +[B<-s>] +[B<-psk>] +[B<-srp>] +[B<-stdname>] +[B<-convert name>] +[B<-ciphersuites val>] +[B<cipherlist>] + +=head1 DESCRIPTION + +The B<ciphers> command converts textual OpenSSL cipher lists into ordered +SSL cipher preference lists. It can be used as a test tool to determine +the appropriate cipherlist. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print a usage message. + +=item B<-s> + +Only list supported ciphers: those consistent with the security level, and +minimum and maximum protocol version. This is closer to the actual cipher list +an application will support. + +PSK and SRP ciphers are not enabled by default: they require B<-psk> or B<-srp> +to enable them. + +It also does not change the default list of supported signature algorithms. + +On a server the list of supported ciphers might also exclude other ciphers +depending on the configured certificates and presence of DH parameters. + +If this option is not used then all ciphers that match the cipherlist will be +listed. + +=item B<-psk> + +When combined with B<-s> includes cipher suites which require PSK. + +=item B<-srp> + +When combined with B<-s> includes cipher suites which require SRP. + +=item B<-v> + +Verbose output: For each cipher suite, 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_3>, B<-tls1_2>, B<-tls1_1>, B<-tls1>, B<-ssl3> + +In combination with the B<-s> option, list the ciphers which could be used if +the specified protocol were negotiated. +Note that not all protocols and flags may be available, depending on how +OpenSSL was built. + +=item B<-stdname> + +Precede each cipher suite by its standard name. + +=item B<-convert name> + +Convert a standard cipher B<name> to its OpenSSL name. + +=item B<-ciphersuites val> + +Sets the list of TLSv1.3 ciphersuites. This list will be combined with any +TLSv1.2 and below ciphersuites that have been configured. The format for this +list is a simple colon (":") separated list of TLSv1.3 ciphersuite names. By +default this value is: + + TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 + +=item B<cipherlist> + +A cipher list of TLSv1.2 and below ciphersuites to convert to a cipher +preference list. This list will be combined with any TLSv1.3 ciphersuites that +have been configured. 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>, which should be a number between zero and five, inclusive. +See L<SSL_CTX_set_security_level> for a description of what each level means. + +The cipher list can be prefixed with the B<DEFAULT> keyword, which enables +the default cipher list as defined below. Unlike cipher strings, +this prefix may not be combined with other strings using B<+> character. +For example, B<DEFAULT+DES> is not valid. + +The content of the default list is determined at compile time and normally +corresponds to B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>. + +=head1 CIPHER STRINGS + +The following is a list of all permitted cipher strings and their meanings. + +=over 4 + +=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 cipher suites 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 +cipher suites have been removed as of OpenSSL 1.1.0. + +=item B<eNULL>, B<NULL> + +The "NULL" ciphers that is those offering no encryption. Because these offer no +encryption at all and are a security risk they are not enabled via either the +B<DEFAULT> or B<ALL> cipher strings. +Be careful when building cipherlists out of lower-level primitives such as +B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers. When in +doubt, include B<!eNULL> in your cipherlist. + +=item B<aNULL> + +The cipher suites offering no authentication. This is currently the anonymous +DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable +to "man in the middle" attacks and so their use is discouraged. +These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL> +ciphers. +Be careful when building cipherlists out of lower-level primitives such as +B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers. +When in doubt, include B<!aNULL> in your cipherlist. + +=item B<kRSA>, B<aRSA>, B<RSA> + +Cipher suites using RSA key exchange or authentication. B<RSA> is an alias for +B<kRSA>. + +=item B<kDHr>, B<kDHd>, B<kDH> + +Cipher suites using static DH key agreement and DH certificates signed by CAs +with RSA and DSS keys or either respectively. +All these cipher suites have been removed in OpenSSL 1.1.0. + +=item B<kDHE>, B<kEDH>, B<DH> + +Cipher suites using ephemeral DH key agreement, including anonymous cipher +suites. + +=item B<DHE>, B<EDH> + +Cipher suites using authenticated ephemeral DH key agreement. + +=item B<ADH> + +Anonymous DH cipher suites, note that this does not include anonymous Elliptic +Curve DH (ECDH) cipher suites. + +=item B<kEECDH>, B<kECDHE>, B<ECDH> + +Cipher suites using ephemeral ECDH key agreement, including anonymous +cipher suites. + +=item B<ECDHE>, B<EECDH> + +Cipher suites using authenticated ephemeral ECDH key agreement. + +=item B<AECDH> + +Anonymous Elliptic Curve Diffie-Hellman cipher suites. + +=item B<aDSS>, B<DSS> + +Cipher suites using DSS authentication, i.e. the certificates carry DSS keys. + +=item B<aDH> + +Cipher suites effectively using DH authentication, i.e. the certificates carry +DH keys. +All these cipher suites have been removed in OpenSSL 1.1.0. + +=item B<aECDSA>, B<ECDSA> + +Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA +keys. + +=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3> + +Lists cipher suites which are only supported in at least TLS v1.2, TLS v1.0 or +SSL v3.0 respectively. +Note: there are no cipher suites 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 cipher suites 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 cipher suites are only supported +in TLS v1.2. + +=item B<AESCCM>, B<AESCCM8> + +AES in Cipher Block Chaining - Message Authentication Mode (CCM): these +cipher suites 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<ARIA128>, B<ARIA256>, B<ARIA> + +Cipher suites using 128 bit ARIA, 256 bit ARIA or either 128 or 256 bit +ARIA. + +=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> + +Cipher suites 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 cipher suites +(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 cipher suites 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 cipher suites 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 cipher suites 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 cipher suites 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 ARIA cipher suites from RFC6209, extending TLS v1.2 + +Note: the CBC modes mentioned in this RFC are not supported. + + TLS_RSA_WITH_ARIA_128_GCM_SHA256 ARIA128-GCM-SHA256 + TLS_RSA_WITH_ARIA_256_GCM_SHA384 ARIA256-GCM-SHA384 + TLS_DHE_RSA_WITH_ARIA_128_GCM_SHA256 DHE-RSA-ARIA128-GCM-SHA256 + TLS_DHE_RSA_WITH_ARIA_256_GCM_SHA384 DHE-RSA-ARIA256-GCM-SHA384 + TLS_DHE_DSS_WITH_ARIA_128_GCM_SHA256 DHE-DSS-ARIA128-GCM-SHA256 + TLS_DHE_DSS_WITH_ARIA_256_GCM_SHA384 DHE-DSS-ARIA256-GCM-SHA384 + TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256 ECDHE-ECDSA-ARIA128-GCM-SHA256 + TLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384 ECDHE-ECDSA-ARIA256-GCM-SHA384 + TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256 ECDHE-ARIA128-GCM-SHA256 + TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384 ECDHE-ARIA256-GCM-SHA384 + TLS_PSK_WITH_ARIA_128_GCM_SHA256 PSK-ARIA128-GCM-SHA256 + TLS_PSK_WITH_ARIA_256_GCM_SHA384 PSK-ARIA256-GCM-SHA384 + TLS_DHE_PSK_WITH_ARIA_128_GCM_SHA256 DHE-PSK-ARIA128-GCM-SHA256 + TLS_DHE_PSK_WITH_ARIA_256_GCM_SHA384 DHE-PSK-ARIA256-GCM-SHA384 + TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 RSA-PSK-ARIA128-GCM-SHA256 + TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 RSA-PSK-ARIA256-GCM-SHA384 + +=head2 Camellia HMAC-Based cipher suites 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) cipher suites + + 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 TLS v1.3 cipher suites + + TLS_AES_128_GCM_SHA256 TLS_AES_128_GCM_SHA256 + TLS_AES_256_GCM_SHA384 TLS_AES_256_GCM_SHA384 + TLS_CHACHA20_POLY1305_SHA256 TLS_CHACHA20_POLY1305_SHA256 + TLS_AES_128_CCM_SHA256 TLS_AES_128_CCM_SHA256 + TLS_AES_128_CCM_8_SHA256 TLS_AES_128_CCM_8_SHA256 + +=head2 Older names used by OpenSSL + +The following names are accepted by older releases: + + SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA) + SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA) + +=head1 NOTES + +Some compiled versions of OpenSSL may not include all the ciphers +listed here because some ciphers were excluded at compile time. + +=head1 EXAMPLES + +Verbose listing of all OpenSSL ciphers including NULL ciphers: + + openssl ciphers -v 'ALL:eNULL' + +Include all ciphers except NULL and anonymous DH then sort by +strength: + + openssl ciphers -v 'ALL:!ADH:@STRENGTH' + +Include all ciphers except ones with no encryption (eNULL) or no +authentication (aNULL): + + openssl ciphers -v 'ALL:!aNULL' + +Include only 3DES ciphers and then place RSA ciphers last: + + openssl ciphers -v '3DES:+RSA' + +Include all RC4 ciphers but leave out those without authentication: + + openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT' + +Include all ciphers with RSA authentication but leave out ciphers without +encryption. + + openssl ciphers -v 'RSA:!COMPLEMENTOFALL' + +Set security level to 2 and display all ciphers consistent with level 2: + + openssl ciphers -s -v 'ALL:@SECLEVEL=2' + +=head1 SEE ALSO + +L<s_client(1)>, L<s_server(1)>, L<ssl(7)> + +=head1 HISTORY + +The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0. + +The B<-stdname> is only available if OpenSSL is built with tracing enabled +(B<enable-ssl-trace> argument to Configure) before OpenSSL 1.1.1. + +The B<-convert> option was added in OpenSSL 1.1.1. + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/cms.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/cms.pod new file mode 100644 index 000000000..72cd9b5d4 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/cms.pod @@ -0,0 +1,745 @@ +=pod + +=head1 NAME + +openssl-cms, +cms - CMS utility + +=head1 SYNOPSIS + +B<openssl> B<cms> +[B<-help>] +[B<-encrypt>] +[B<-decrypt>] +[B<-sign>] +[B<-verify>] +[B<-cmsout>] +[B<-resign>] +[B<-data_create>] +[B<-data_out>] +[B<-digest_create>] +[B<-digest_verify>] +[B<-compress>] +[B<-uncompress>] +[B<-EncryptedData_encrypt>] +[B<-sign_receipt>] +[B<-verify_receipt receipt>] +[B<-in filename>] +[B<-inform SMIME|PEM|DER>] +[B<-rctform SMIME|PEM|DER>] +[B<-out filename>] +[B<-outform SMIME|PEM|DER>] +[B<-stream -indef -noindef>] +[B<-noindef>] +[B<-content filename>] +[B<-text>] +[B<-noout>] +[B<-print>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-md digest>] +[B<-I<cipher>>] +[B<-nointern>] +[B<-noverify>] +[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>] +[B<-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...>] +[B<-writerand file>] +[B<cert.pem...>] +[B<-to addr>] +[B<-from addr>] +[B<-subject subj>] +[cert.pem]... + +=head1 DESCRIPTION + +The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and +verify, compress and uncompress S/MIME messages. + +=head1 OPTIONS + +There are fourteen operation options that set the type of operation to be +performed. The meaning of the other options varies according to the operation +type. + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-encrypt> + +Encrypt mail for the given recipient certificates. Input file is the message +to be encrypted. The output file is the encrypted mail in MIME format. The +actual CMS type is <B>EnvelopedData<B>. + +Note that no revocation check is done for the recipient cert, so if that +key has been compromised, others may be able to decrypt the text. + +=item B<-decrypt> + +Decrypt mail using the supplied certificate and private key. Expects an +encrypted mail message in MIME format for the input file. The decrypted mail +is written to the output file. + +=item B<-debug_decrypt> + +This option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used +with caution: see the notes section below. + +=item B<-sign> + +Sign mail using the supplied certificate and private key. Input file is +the message to be signed. The signed message in MIME format is written +to the output file. + +=item B<-verify> + +Verify signed mail. Expects a signed mail message on input and outputs +the signed data. Both clear text and opaque signing is supported. + +=item B<-cmsout> + +Takes an input message and writes out a PEM encoded CMS structure. + +=item B<-resign> + +Resign a message: take an existing message and one or more new signers. + +=item B<-data_create> + +Create a CMS B<Data> type. + +=item B<-data_out> + +B<Data> type and output the content. + +=item B<-digest_create> + +Create a CMS B<DigestedData> type. + +=item B<-digest_verify> + +Verify a CMS B<DigestedData> type and output the content. + +=item B<-compress> + +Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> +support for this option to work, otherwise it will output an error. + +=item B<-uncompress> + +Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be +compiled with B<zlib> support for this option to work, otherwise it will +output an error. + +=item B<-EncryptedData_encrypt> + +Encrypt content using supplied symmetric key and algorithm using a CMS +B<EncryptedData> type and output the content. + +=item B<-sign_receipt> + +Generate and output a signed receipt for the supplied message. The input +message B<must> contain a signed receipt request. Functionality is otherwise +similar to the B<-sign> operation. + +=item B<-verify_receipt receipt> + +Verify a signed receipt in filename B<receipt>. The input message B<must> +contain the original receipt request. Functionality is otherwise similar +to the B<-verify> operation. + +=item B<-in filename> + +The input message to be encrypted or signed or the message to be decrypted +or verified. + +=item B<-inform SMIME|PEM|DER> + +This specifies the input format for the CMS structure. The default +is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> +format change this to expect PEM and DER format CMS structures +instead. This currently only affects the input format of the CMS +structure, if no CMS structure is being input (for example with +B<-encrypt> or B<-sign>) this option has no effect. + +=item B<-rctform SMIME|PEM|DER> + +Specify the format for a signed receipt for use with the B<-receipt_verify> +operation. + +=item B<-out filename> + +The message text that has been decrypted or verified or the output MIME +format message that has been signed or verified. + +=item B<-outform SMIME|PEM|DER> + +This specifies the output format for the CMS structure. The default +is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER> +format change this to write PEM and DER format CMS structures +instead. This currently only affects the output format of the CMS +structure, if no CMS structure is being output (for example with +B<-verify> or B<-decrypt>) this option has no effect. + +=item B<-stream -indef -noindef> + +The B<-stream> and B<-indef> options are equivalent and enable streaming I/O +for encoding operations. This permits single pass processing of data without +the need to hold the entire contents in memory, potentially supporting very +large files. Streaming is automatically set for S/MIME signing with detached +data if the output format is B<SMIME> it is currently off by default for all +other operations. + +=item B<-noindef> + +Disable streaming I/O where it would produce and indefinite length constructed +encoding. This option currently has no effect. In future streaming will be +enabled by default on all relevant operations and this option will disable it. + +=item B<-content filename> + +This specifies a file containing the detached content, this is only +useful with the B<-verify> command. This is only usable if the CMS +structure is using the detached signature form where the content is +not included. This option will override any content if the input format +is S/MIME and it uses the multipart/signed MIME content type. + +=item B<-text> + +This option adds plain text (text/plain) MIME headers to the supplied +message if encrypting or signing. If decrypting or verifying it strips +off text headers: if the decrypted or verified message is not of MIME +type text/plain then an error occurs. + +=item B<-noout> + +For the B<-cmsout> operation do not output the parsed CMS structure. This +is useful when combined with the B<-print> option or if the syntax of the CMS +structure is being checked. + +=item B<-print> + +For the B<-cmsout> operation print out all fields of the CMS structure. This +is mainly useful for testing purposes. + +=item B<-CAfile file> + +A file containing trusted CA certificates, only used with B<-verify>. + +=item B<-CApath dir> + +A directory containing trusted CA certificates, only used with +B<-verify>. This directory must be a standard certificate directory: that +is a hash of each subject name (using B<x509 -hash>) should be linked +to each certificate. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-md digest> + +Digest algorithm to use when signing or resigning. If not present then the +default digest algorithm for the signing key will be used (usually SHA1). + +=item B<-I<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<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<-noverify> + +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). + +Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this +option. + +=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>, B<-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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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 added in OpenSSL 1.0.2. + +Support for RSA-OAEP and RSA-PSS was added in OpenSSL 1.0.2. + +The use of non-RSA keys with B<-encrypt> and B<-decrypt> +was added in OpenSSL 1.0.2. + +The -no_alt_chains option was added in OpenSSL 1.0.2b. + +=head1 COPYRIGHT + +Copyright 2008-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/crl.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/crl.pod new file mode 100644 index 000000000..58f2bf62d --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/crl.pod @@ -0,0 +1,143 @@ +=pod + +=head1 NAME + +openssl-crl, +crl - CRL utility + +=head1 SYNOPSIS + +B<openssl> B<crl> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-text>] +[B<-in filename>] +[B<-out filename>] +[B<-nameopt option>] +[B<-noout>] +[B<-hash>] +[B<-issuer>] +[B<-lastupdate>] +[B<-nextupdate>] +[B<-CAfile file>] +[B<-CApath dir>] + +=head1 DESCRIPTION + +The B<crl> command processes CRL files in DER or PEM format. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. B<DER> format is DER encoded CRL +structure. B<PEM> (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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 before version 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 -inform 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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/crl2pkcs7.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/crl2pkcs7.pod new file mode 100644 index 000000000..f58a442b5 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/crl2pkcs7.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + +openssl-crl2pkcs7, +crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates + +=head1 SYNOPSIS + +B<openssl> B<crl2pkcs7> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-certfile filename>] +[B<-nocrl>] + +=head1 DESCRIPTION + +The B<crl2pkcs7> command takes an optional CRL and one or more +certificates and converts them into a PKCS#7 degenerate "certificates +only" structure. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the CRL input format. B<DER> format is DER encoded CRL +structure.B<PEM> (the default) is a base64 encoded version of +the DER form with header and footer lines. The default format is PEM. + +=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. The default format is PEM. + +=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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dgst.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dgst.pod new file mode 100644 index 000000000..ea2c4e3e1 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dgst.pod @@ -0,0 +1,252 @@ +=pod + +=head1 NAME + +openssl-dgst, +dgst - perform digest operations + +=head1 SYNOPSIS + +B<openssl dgst> +[B<-I<digest>>] +[B<-help>] +[B<-c>] +[B<-d>] +[B<-list>] +[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<-sigopt nm:v>] +[B<-hmac key>] +[B<-fips-fingerprint>] +[B<-rand file...>] +[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<-list> + +Prints out a list of supported message digests. + +=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, including newlines. +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". Note this option +does not support Ed25519 or Ed448 private keys. Use the B<pkeyutl> command +instead for this. + +=item B<-keyform arg> + +Specifies the key format to sign digest with. The DER, PEM, P12, +and ENGINE formats are supported. + +=item B<-sigopt nm:v> + +Pass options to the signature algorithm during sign or verify operations. +Names and values of these options are algorithm-specific. + +=item B<-passin arg> + +The private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-verify filename> + +Verify the signature using the public key in "filename". +The output is either "Verification OK" or "Verification Failure". + +=item B<-prverify filename> + +Verify the signature using the private key in "filename". + +=item B<-signature filename> + +The actual signature to verify. + +=item B<-hmac key> + +Create a hashed MAC using "key". + +=item B<-mac alg> + +Create MAC (keyed Message Authentication Code). The most popular MAC +algorithm is HMAC (hash-based MAC), but there are other MAC algorithms +which are not based on hash, for instance B<gost-mac> algorithm, +supported by B<ccgost> engine. MAC keys and other options should be set +via B<-macopt> parameter. + +=item B<-macopt nm:v> + +Passes options to MAC algorithm, specified by B<-mac> key. +Following options are supported by both by B<HMAC> and B<gost-mac>: + +=over 4 + +=item B<key:string> + +Specifies MAC key as alphanumeric string (use if key contain printable +characters only). String length must conform to any restrictions of +the MAC algorithm for example exactly 32 chars for gost-mac. + +=item B<hexkey:string> + +Specifies MAC key in hexadecimal form (two hex digits per byte). +Key length must conform to any restrictions of the MAC algorithm +for example exactly 32 chars for gost-mac. + +=back + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dhparam.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dhparam.pod new file mode 100644 index 000000000..1b43b3231 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dhparam.pod @@ -0,0 +1,166 @@ +=pod + +=head1 NAME + +openssl-dhparam, +dhparam - DH parameter manipulation and generation + +=head1 SYNOPSIS + +B<openssl dhparam> +[B<-help>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in> I<filename>] +[B<-out> I<filename>] +[B<-dsaparam>] +[B<-check>] +[B<-noout>] +[B<-text>] +[B<-C>] +[B<-2>] +[B<-5>] +[B<-rand file...>] +[B<-writerand file>] +[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 and default +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 file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dsa.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dsa.pod new file mode 100644 index 000000000..fb6cbf122 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dsa.pod @@ -0,0 +1,182 @@ +=pod + +=head1 NAME + +openssl-dsa, +dsa - DSA key processing + +=head1 SYNOPSIS + +B<openssl> B<dsa> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-aria128>] +[B<-aria192>] +[B<-aria256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-text>] +[B<-noout>] +[B<-modulus>] +[B<-pubin>] +[B<-pubout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<dsa> command processes DSA keys. They can be converted between various +forms and their components printed out. B<Note> This command uses the +traditional SSLeay compatible format for private key encryption: newer +applications should use the more secure PKCS#8 format using the B<pkcs8> + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option with a private key uses +an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of +version (currently zero), p, q, g, the public and private key components +respectively as ASN.1 INTEGERs. When used with a public key it uses a +SubjectPublicKeyInfo structure: it is an error if the key is not DSA. + +The B<PEM> form is the default format: it consists of the B<DER> format base64 +encoded with additional header and footer lines. In the case of a private key +PKCS#8 format is also accepted. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dsaparam.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dsaparam.pod new file mode 100644 index 000000000..94ea435cc --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/dsaparam.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +openssl-dsaparam, +dsaparam - DSA parameter manipulation and generation + +=head1 SYNOPSIS + +B<openssl dsaparam> +[B<-help>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-text>] +[B<-C>] +[B<-rand file...>] +[B<-writerand file>] +[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 and default +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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ec.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ec.pod new file mode 100644 index 000000000..4d368e20a --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ec.pod @@ -0,0 +1,203 @@ +=pod + +=head1 NAME + +openssl-ec, +ec - EC key processing + +=head1 SYNOPSIS + +B<openssl> B<ec> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-text>] +[B<-noout>] +[B<-param_out>] +[B<-pubin>] +[B<-pubout>] +[B<-conv_form arg>] +[B<-param_enc arg>] +[B<-no_public>] +[B<-check>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<ec> command processes EC keys. They can be converted between various +forms and their components printed out. B<Note> OpenSSL uses the +private key format specified in 'SEC 1: Elliptic Curve Cryptography' +(http://www.secg.org/). To convert an OpenSSL EC private key into the +PKCS#8 private key format use the B<pkcs8> command. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option with a private key uses +an ASN.1 DER encoded SEC1 private key. When used with a public key it +uses the SubjectPublicKeyInfo structure as specified in RFC 3280. +The B<PEM> form is the default format: it consists of the B<DER> format base64 +encoded with additional header and footer lines. In the case of a private key +PKCS#8 format is also accepted. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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<-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-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ecparam.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ecparam.pod new file mode 100644 index 000000000..0633f8cda --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ecparam.pod @@ -0,0 +1,192 @@ +=pod + +=head1 NAME + +openssl-ecparam, +ecparam - EC parameter manipulation and generation + +=head1 SYNOPSIS + +B<openssl ecparam> +[B<-help>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-text>] +[B<-C>] +[B<-check>] +[B<-name arg>] +[B<-list_curves>] +[B<-conv_form arg>] +[B<-param_enc arg>] +[B<-no_seed>] +[B<-rand file...>] +[B<-writerand file>] +[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 and default +as the B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. + +=item B<-out filename> + +This specifies the output filename parameters to. Standard output is used +if this option is not present. The output filename should B<not> be the same +as the input filename. + +=item B<-noout> + +This option inhibits the output of the encoded version of the parameters. + +=item B<-text> + +This option prints out the EC parameters in human readable form. + +=item B<-C> + +This option converts the EC parameters into C code. The parameters can then +be loaded by calling the get_ec_group_XXX() function. + +=item B<-check> + +Validate the elliptic curve parameters. + +=item B<-name arg> + +Use the EC parameters with the specified 'short' name. Use B<-list_curves> +to get a list of all currently implemented EC parameters. + +=item B<-list_curves> + +If this options is specified B<ecparam> will print out a list of all +currently implemented EC parameters names and exit. + +=item B<-conv_form> + +This specifies how the points on the elliptic curve are converted +into octet strings. Possible values are: B<compressed>, B<uncompressed> (the +default value) and B<hybrid>. For more information regarding +the point conversion forms please read the X9.62 standard. +B<Note> Due to patent issues the B<compressed> option is disabled +by default for binary curves and can be enabled by defining +the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time. + +=item B<-param_enc arg> + +This specifies how the elliptic curve parameters are encoded. +Possible value are: B<named_curve>, i.e. the ec parameters are +specified by an OID, or B<explicit> where the ec parameters are +explicitly given (see RFC 3279 for the definition of the +EC parameters structures). The default value is B<named_curve>. +B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279, +is currently not implemented in OpenSSL. + +=item B<-no_seed> + +This option inhibits that the 'seed' for the parameter generation +is included in the ECParameters structure (see RFC 3279). + +=item B<-genkey> + +This option will generate an EC private key using the specified parameters. + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=item B<-engine id> + +Specifying an engine (by its unique B<id> string) will cause B<ecparam> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 NOTES + +PEM format EC parameters use the header and footer lines: + + -----BEGIN EC PARAMETERS----- + -----END EC PARAMETERS----- + +OpenSSL is currently not able to generate new groups and therefore +B<ecparam> can only create EC parameters from known (named) curves. + +=head1 EXAMPLES + +To create EC parameters with the group 'prime192v1': + + openssl ecparam -out ec_param.pem -name prime192v1 + +To create EC parameters with explicit parameters: + + openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit + +To validate given EC parameters: + + openssl ecparam -in ec_param.pem -check + +To create EC parameters and a private key: + + openssl ecparam -out ec_key.pem -name prime192v1 -genkey + +To change the point encoding to 'compressed': + + openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed + +To print out the EC parameters to standard output: + + openssl ecparam -in ec_param.pem -noout -text + +=head1 SEE ALSO + +L<ec(1)>, L<dsaparam(1)> + +=head1 COPYRIGHT + +Copyright 2003-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/enc.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/enc.pod new file mode 100644 index 000000000..6f20ac1fc --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/enc.pod @@ -0,0 +1,438 @@ +=pod + +=head1 NAME + +openssl-enc, +enc - symmetric cipher routines + +=head1 SYNOPSIS + +B<openssl enc -I<cipher>> +[B<-help>] +[B<-list>] +[B<-ciphers>] +[B<-in filename>] +[B<-out filename>] +[B<-pass arg>] +[B<-e>] +[B<-d>] +[B<-a>] +[B<-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<-iter count>] +[B<-pbkdf2>] +[B<-p>] +[B<-P>] +[B<-bufsize number>] +[B<-nopad>] +[B<-debug>] +[B<-none>] +[B<-rand file...>] +[B<-writerand file>] +[B<-engine id>] + +B<openssl> I<[cipher]> [B<...>] + +=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<-list> + +List all supported ciphers. + +=item B<-ciphers> + +Alias of -list to display 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<-iter count> + +Use a given number of iterations on the password in deriving the encryption key. +High values increase the time required to brute-force the resulting file. +This option enables the use of PBKDF2 algorithm to derive the key. + +=item B<-pbkdf2> + +Use PBKDF2 algorithm with default iteration count unless otherwise specified. + +=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 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). + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=back + +=head1 NOTES + +The program can be called either as B<openssl cipher> or +B<openssl enc -cipher>. 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. +Use the B<list> command to get a list of supported ciphers. + +Engines which provide entirely new encryption algorithms (such as the ccgost +engine which provides gost89 algorithm) should be configured in the +configuration file. Engines specified on the command line using -engine +options can only be used for hardware-assisted implementations of +ciphers which are supported by the OpenSSL core or another engine specified +in the configuration file. + +When the 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, such as AES, in CBC mode. + +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 +the B<-ciphers> option (that is B<openssl enc -ciphers>) produces 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, and will not support such modes in the future. +The B<enc> interface by necessity must begin streaming output (e.g., +to standard output when B<-out> is not used) before the authentication +tag could be validated, leading to the usage of B<enc> in pipelines +that begin processing untrusted data and are not capable of rolling +back upon authentication failure. The AEAD modes currently in common +use also suffer from catastrophic failure of confidentiality and/or +integrity upon reuse of key/iv/nonce, and since B<enc> places the +entire burden of key/iv/nonce management upon the user, the risk of +exposing AEAD modes is too great to allow. These key/iv/nonce +management issues also affect other modes currently exposed in B<enc>, +but the failure modes are less extreme in these cases, and the +functionality cannot be removed with a stable release branch. +For bulk encryption of data, whether using authenticated encryption +modes or other modes, L<cms(1)> is recommended, as it provides a +standard data format and performs the needed key/iv/nonce management. + + + base64 Base 64 + + bf-cbc Blowfish in CBC mode + bf Alias for bf-cbc + blowfish 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 + + chacha20 ChaCha20 algorithm + + des-cbc DES in CBC mode + des Alias for des-cbc + des-cfb DES in CFB 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 + + seed-cbc SEED cipher in CBC mode + seed Alias for seed-cbc + seed-cfb SEED cipher in CFB mode + seed-ecb SEED cipher in ECB mode + seed-ofb SEED cipher in OFB mode + + sm4-cbc SM4 cipher in CBC mode + sm4 Alias for sm4-cbc + sm4-cfb SM4 cipher in CFB mode + sm4-ctr SM4 cipher in CTR mode + sm4-ecb SM4 cipher in ECB mode + sm4-ofb SM4 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]-ctr 128/192/256 bit AES in CTR 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 + + aria-[128|192|256]-cbc 128/192/256 bit ARIA in CBC mode + aria[128|192|256] Alias for aria-[128|192|256]-cbc + aria-[128|192|256]-cfb 128/192/256 bit ARIA in 128 bit CFB mode + aria-[128|192|256]-cfb1 128/192/256 bit ARIA in 1 bit CFB mode + aria-[128|192|256]-cfb8 128/192/256 bit ARIA in 8 bit CFB mode + aria-[128|192|256]-ctr 128/192/256 bit ARIA in CTR mode + aria-[128|192|256]-ecb 128/192/256 bit ARIA in ECB mode + aria-[128|192|256]-ofb 128/192/256 bit ARIA in OFB mode + + camellia-[128|192|256]-cbc 128/192/256 bit Camellia in CBC mode + camellia[128|192|256] Alias for camellia-[128|192|256]-cbc + camellia-[128|192|256]-cfb 128/192/256 bit Camellia in 128 bit CFB mode + camellia-[128|192|256]-cfb1 128/192/256 bit Camellia in 1 bit CFB mode + camellia-[128|192|256]-cfb8 128/192/256 bit Camellia in 8 bit CFB mode + camellia-[128|192|256]-ctr 128/192/256 bit Camellia in CTR mode + camellia-[128|192|256]-ecb 128/192/256 bit Camellia in ECB mode + camellia-[128|192|256]-ofb 128/192/256 bit Camellia 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 AES-128 using a prompted password +and PBKDF2 key derivation: + + openssl enc -aes128 -pbkdf2 -in file.txt -out file.aes128 + +Decrypt a file using a supplied password: + + openssl enc -aes128 -pbkdf2 -d -in file.aes128 -out file.txt \ + -pass pass:<password> + +Encrypt a file then base64 encode it (so it can be sent via mail for example) +using AES-256 in CTR mode and PBKDF2 key derivation: + + openssl enc -aes-256-ctr -pbkdf2 -a -in file.txt -out file.aes256 + +Base64 decode a file then decrypt it using a password supplied in a file: + + openssl enc -aes-256-ctr -pbkdf2 -d -a -in file.aes256 -out file.txt \ + -pass file:<passfile> + +=head1 BUGS + +The B<-A> option when used with large files doesn't work properly. + +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.0. + +The B<-list> option was added in OpenSSL 1.1.1e. + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/engine.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/engine.pod new file mode 100644 index 000000000..d49f04292 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/engine.pod @@ -0,0 +1,119 @@ +=pod + +=head1 NAME + +openssl-engine, +engine - load and query engines + +=head1 SYNOPSIS + +B<openssl engine> +[ I<engine...> ] +[B<-v>] +[B<-vv>] +[B<-vvv>] +[B<-vvv>] +[B<-vvv>] +[B<-c>] +[B<-t>] +[B<-tt>] +[B<-pre> I<command>] +[B<-post> I<command>] +[ I<engine...> ] + +=head1 DESCRIPTION + +The B<engine> command is used to query the status and capabilities +of the specified B<engine>'s. +Engines may be specified before and after all other command-line flags. +Only those specified are queried. + +=head1 OPTIONS + +=over 4 + +=item B<-v> B<-vv> B<-vvv> B<-vvvv> + +Provides information about each specified engine. The first flag lists +all the possible run-time control commands; the second adds a +description of each command; the third adds the input flags, and the +final option adds the internal input flags. + +=item B<-c> + +Lists the capabilities of each engine. + +=item B<-t> + +Tests if each specified engine is available, and displays the answer. + +=item B<-tt> + +Displays an error trace for any unavailable engine. + +=item B<-pre> I<command> + +=item B<-post> I<command> + +Command-line configuration of engines. +The B<-pre> command is given to the engine before it is loaded and +the B<-post> command is given after the engine is loaded. +The I<command> is of the form I<cmd:val> where I<cmd> is the command, +and I<val> is the value for the command. +See the example below. + +=back + +=head1 EXAMPLES + +To list all the commands available to a dynamic engine: + + $ openssl engine -t -tt -vvvv dynamic + (dynamic) Dynamic engine loading support + [ unavailable ] + SO_PATH: Specifies the path to the new ENGINE shared library + (input flags): STRING + NO_VCHECK: Specifies to continue even if version checking fails (boolean) + (input flags): NUMERIC + ID: Specifies an ENGINE id name for loading + (input flags): STRING + LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory) + (input flags): NUMERIC + DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory) + (input flags): NUMERIC + DIR_ADD: Adds a directory from which ENGINEs can be loaded + (input flags): STRING + LOAD: Load up the ENGINE specified by other settings + (input flags): NO_INPUT + +To list the capabilities of the I<rsax> engine: + + $ openssl engine -c + (rsax) RSAX engine support + [RSA] + (dynamic) Dynamic engine loading support + +=head1 ENVIRONMENT + +=over 4 + +=item B<OPENSSL_ENGINES> + +The path to the engines directory. + +=back + +=head1 SEE ALSO + +L<config(5)> + +=head1 COPYRIGHT + +Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/errstr.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/errstr.pod new file mode 100644 index 000000000..94198c123 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/errstr.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +openssl-errstr, +errstr - lookup error codes + +=head1 SYNOPSIS + +B<openssl errstr error_code> + +=head1 DESCRIPTION + +Sometimes an application will not load error message and only +numerical forms will be available. The B<errstr> utility can be used to +display the meaning of the hex code. The hex code is the hex digits after the +second colon. + +=head1 OPTIONS + +None. + +=head1 EXAMPLES + +The error code: + + 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107: + +can be displayed with: + + openssl errstr 2006D080 + +to produce the error message: + + error:2006D080:BIO routines:BIO_new_file:no such file + +=head1 COPYRIGHT + +Copyright 2004-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/gendsa.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/gendsa.pod new file mode 100644 index 000000000..b2580b4f0 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/gendsa.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + +openssl-gendsa, +gendsa - generate a DSA private key from a set of parameters + +=head1 SYNOPSIS + +B<openssl> B<gendsa> +[B<-help>] +[B<-out filename>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-aria128>] +[B<-aria192>] +[B<-aria256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-rand file...>] +[B<-writerand file>] +[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>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/genpkey.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/genpkey.pod new file mode 100644 index 000000000..1ba54d486 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/genpkey.pod @@ -0,0 +1,335 @@ +=pod + +=head1 NAME + +openssl-genpkey, +genpkey - generate a private key + +=head1 SYNOPSIS + +B<openssl> B<genpkey> +[B<-help>] +[B<-out filename>] +[B<-outform PEM|DER>] +[B<-pass arg>] +[B<-I<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. The default format is 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<-I<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. Engines may add algorithms in addition to the standard +built-in ones. + +Valid built-in algorithm names for private key generation are RSA, RSA-PSS, EC, +X25519, X448, ED25519 and ED448. + +Valid built-in algorithm names for parameter generation (see the B<-genparam> +option) are DH, DSA and EC. + +Note that the algorithm name X9.42 DH may be used as a synonym for the DH +algorithm. These are identical and do not indicate the type of parameters that +will be generated. Use the B<dh_paramgen_type> option to indicate whether PKCS#3 +or X9.42 DH parameters are required. See L<DH Parameter Generation Options> +below for more details. + +=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 L<KEY GENERATION OPTIONS> and +L<PARAMETER 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. There are no key generation options defined for the X25519, X448, ED25519 +or ED448 algorithms. + +=head2 RSA Key Generation Options + +=over 4 + +=item B<rsa_keygen_bits:numbits> + +The number of bits in the generated key. If not specified 2048 is used. + +=item B<rsa_keygen_primes:numprimes> + +The number of primes in the generated key. If not specified 2 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 + +=head2 RSA-PSS Key Generation Options + +Note: by default an B<RSA-PSS> key has no parameter restrictions. + +=over 4 + +=item B<rsa_keygen_bits:numbits>, B<rsa_keygen_primes:numprimes>, B<rsa_keygen_pubexp:value> + +These options have the same meaning as the B<RSA> algorithm. + +=item B<rsa_pss_keygen_md:digest> + +If set the key is restricted and can only use B<digest> for signing. + +=item B<rsa_pss_keygen_mgf1_md:digest> + +If set the key is restricted and can only use B<digest> as it's MGF1 +parameter. + +=item B<rsa_pss_keygen_saltlen:len> + +If set the key is restricted and B<len> specifies the minimum salt length. + +=back + +=head2 EC Key Generation Options + +The EC key generation options can also be used for parameter generation. + +=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". The default value is "named_curve". + +=back + +=head1 PARAMETER 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. + +=head2 DSA Parameter Generation Options + +=over 4 + +=item B<dsa_paramgen_bits:numbits> + +The number of bits in the generated prime. If not specified 2048 is used. + +=item B<dsa_paramgen_q_bits:numbits> + +The number of bits in the q parameter. Must be one of 160, 224 or 256. If not +specified 224 is used. + +=item B<dsa_paramgen_md:digest> + +The digest to use during parameter generation. Must be one of B<sha1>, B<sha224> +or B<sha256>. If set, then the number of bits in B<q> will match the output size +of the specified digest and the B<dsa_paramgen_q_bits> parameter will be +ignored. If not set, then a digest will be used that gives an output matching +the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224 +or B<sha256> if it is 256. + +=back + +=head2 DH Parameter Generation Options + +=over 4 + +=item B<dh_paramgen_prime_len:numbits> + +The number of bits in the prime parameter B<p>. The default is 2048. + +=item B<dh_paramgen_subprime_len:numbits> + +The number of bits in the sub prime parameter B<q>. The default is 256 if the +prime is at least 2048 bits long or 160 otherwise. Only relevant if used in +conjunction with the B<dh_paramgen_type> option to generate X9.42 DH parameters. + +=item B<dh_paramgen_generator:value> + +The value to use for the generator B<g>. The default is 2. + +=item B<dh_paramgen_type:value> + +The type of DH parameters to generate. Use 0 for PKCS#3 DH and 1 for X9.42 DH. +The default is 0. + +=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. If present this overrides all other DH parameter +options. + +=back + +=head2 EC Parameter Generation Options + +The EC parameter generation options are the same as for key generation. See +L<EC Key Generation Options> above. + +=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 2048 bit DSA parameters: + + openssl genpkey -genparam -algorithm DSA -out dsap.pem \ + -pkeyopt dsa_paramgen_bits:2048 + +Generate DSA key from parameters: + + openssl genpkey -paramfile dsap.pem -out dsakey.pem + +Generate 2048 bit DH parameters: + + openssl genpkey -genparam -algorithm DH -out dhp.pem \ + -pkeyopt dh_paramgen_prime_len:2048 + +Generate 2048 bit X9.42 DH parameters: + + openssl genpkey -genparam -algorithm DH -out dhpx.pem \ + -pkeyopt dh_paramgen_prime_len:2048 \ + -pkeyopt dh_paramgen_type:1 + +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 + +Generate an ED448 private key: + + openssl genpkey -algorithm ED448 -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. +The ability to generate X25519 keys was added in OpenSSL 1.1.0. +The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1. + +=head1 COPYRIGHT + +Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/genrsa.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/genrsa.pod new file mode 100644 index 000000000..a9c994ffb --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/genrsa.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +openssl-genrsa, +genrsa - generate an RSA private key + +=head1 SYNOPSIS + +B<openssl> B<genrsa> +[B<-help>] +[B<-out filename>] +[B<-passout arg>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-aria128>] +[B<-aria192>] +[B<-aria256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-f4>] +[B<-3>] +[B<-rand file...>] +[B<-writerand file>] +[B<-engine id>] +[B<-primes num>] +[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>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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<-primes num> + +Specify the number of primes to use while generating the RSA key. The B<num> +parameter must be a positive integer that is greater than 1 and less than 16. +If B<num> is greater than 2, then the generated key is called a 'multi-prime' +RSA key, which is defined in RFC 8017. + +=item B<numbits> + +The size of the private key to generate in bits. This must be the last option +specified. The default is 2048 and values less than 512 are not allowed. + +=back + +=head1 NOTES + +RSA private key generation essentially involves the generation of two or more +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, B<*> means the current prime starts +a regenerating progress due to some failed tests. 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. But in general, more primes lead to less generation time +of a key. + +=head1 SEE ALSO + +L<gendsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/list.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/list.pod new file mode 100644 index 000000000..bed39b0c7 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/list.pod @@ -0,0 +1,94 @@ +=pod + +=head1 NAME + +openssl-list, +list - list algorithms and features + +=head1 SYNOPSIS + +B<openssl list> +[B<-help>] +[B<-1>] +[B<-commands>] +[B<-digest-commands>] +[B<-digest-algorithms>] +[B<-cipher-commands>] +[B<-cipher-algorithms>] +[B<-public-key-algorithms>] +[B<-public-key-methods>] +[B<-disabled>] + +=head1 DESCRIPTION + +This command is used to generate list of algorithms or disabled +features. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Display a usage message. + +=item B<-1> + +List the commands, digest-commands, or cipher-commands in a single column. +If used, this option must be given first. + +=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<-public-key-methods> + +Display a list of public key method OIDs: this also includes public key methods +without an associated ASN.1 method, for example, KDF algorithms. + +=item B<-disabled> + +Display a list of disabled features, those that were compiled out +of the installation. + +=back + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/nseq.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/nseq.pod new file mode 100644 index 000000000..7d5f009aa --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/nseq.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +openssl-nseq, +nseq - create or examine a Netscape certificate sequence + +=head1 SYNOPSIS + +B<openssl> B<nseq> +[B<-help>] +[B<-in filename>] +[B<-out filename>] +[B<-toseq>] + +=head1 DESCRIPTION + +The B<nseq> command takes a file containing a Netscape certificate +sequence and prints out the certificates contained in it or takes a +file of certificates and converts it into a Netscape certificate +sequence. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read or standard input if this +option is not specified. + +=item B<-out filename> + +Specifies the output filename or standard output by default. + +=item B<-toseq> + +Normally a Netscape certificate sequence will be input and the output +is the certificates contained in it. With the B<-toseq> option the +situation is reversed: a Netscape certificate sequence is created from +a file of certificates. + +=back + +=head1 EXAMPLES + +Output the certificates in a Netscape certificate sequence + + openssl nseq -in nseq.pem -out certs.pem + +Create a Netscape certificate sequence + + openssl nseq -in certs.pem -toseq -out nseq.pem + +=head1 NOTES + +The B<PEM> encoded form uses the same headers and footers as a certificate: + + -----BEGIN CERTIFICATE----- + -----END CERTIFICATE----- + +A Netscape certificate sequence is a Netscape specific format 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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ocsp.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ocsp.pod new file mode 100644 index 000000000..736055b1b --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ocsp.pod @@ -0,0 +1,500 @@ +=pod + +=head1 NAME + +openssl-ocsp, +ocsp - Online Certificate Status Protocol utility + +=head1 SYNOPSIS + +B<openssl> B<ocsp> +[B<-help>] +[B<-out file>] +[B<-issuer file>] +[B<-cert file>] +[B<-serial n>] +[B<-signer file>] +[B<-signkey file>] +[B<-sign_other file>] +[B<-no_certs>] +[B<-req_text>] +[B<-resp_text>] +[B<-text>] +[B<-reqout file>] +[B<-respout file>] +[B<-reqin file>] +[B<-respin file>] +[B<-nonce>] +[B<-no_nonce>] +[B<-url URL>] +[B<-host host:port>] +[B<-multi process-count>] +[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<-ignore_err>] +[B<-index file>] +[B<-CA file>] +[B<-rsigner file>] +[B<-rkey file>] +[B<-rother file>] +[B<-rsigopt nm:v>] +[B<-resp_no_certs>] +[B<-nmin n>] +[B<-ndays n>] +[B<-resp_key_id>] +[B<-nrequest n>] +[B<-I<digest>>] + +=head1 DESCRIPTION + +The Online Certificate Status Protocol (OCSP) enables applications to +determine the (revocation) state of an identified certificate (RFC 2560). + +The B<ocsp> command performs many common OCSP tasks. It can be used +to print out requests and responses, create requests and send queries +to an OCSP responder and behave like a mini OCSP server itself. + +=head1 OPTIONS + +This command operates as either a client or a server. +The options are described below, divided into those two modes. + +=head2 OCSP Client Options + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out filename> + +specify output filename, default is standard output. + +=item B<-issuer filename> + +This specifies the current issuer certificate. This option can be used +multiple times. The certificate specified in B<filename> must be in +PEM format. This option B<MUST> come before any B<-cert> options. + +=item B<-cert filename> + +Add the certificate B<filename> to the request. The issuer certificate +is taken from the previous B<issuer> option, or an error occurs if no +issuer certificate is specified. + +=item B<-serial num> + +Same as the B<cert> option except the certificate with serial number +B<num> is added to the request. The serial number is interpreted as a +decimal integer unless preceded by B<0x>. Negative integers can also +be specified by preceding the value by a B<-> sign. + +=item B<-signer filename>, B<-signkey filename> + +Sign the OCSP request using the certificate specified in the B<signer> +option and the private key specified by the B<signkey> option. If +the B<signkey> option is not present then the private key is read +from the same file as the certificate. If neither option is specified then +the OCSP request is not signed. + +=item B<-sign_other filename> + +Additional certificates to include in the signed request. + +=item B<-nonce>, B<-no_nonce> + +Add an OCSP nonce extension to a request or disable OCSP nonce addition. +Normally if an OCSP request is input using the B<reqin> option no +nonce is added: using the B<nonce> option will force addition of a nonce. +If an OCSP request is being created (using B<cert> and B<serial> options) +a nonce is automatically added specifying B<no_nonce> overrides this. + +=item B<-req_text>, B<-resp_text>, B<-text> + +Print out the text form of the OCSP request, response or both respectively. + +=item B<-reqout file>, B<-respout file> + +Write out the DER encoded certificate request or response to B<file>. + +=item B<-reqin file>, B<-respin file> + +Read OCSP request or response file from B<file>. These option are ignored +if OCSP request or response creation is implied by other options (for example +with B<serial>, B<cert> and B<host> options). + +=item B<-url responder_url> + +Specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. + +=item B<-host hostname:port>, B<-path pathname> + +If the B<host> option is present then the OCSP request is sent to the host +B<hostname> on port B<port>. B<path> specifies the HTTP path name to use +or "/" by default. This is equivalent to specifying B<-url> with scheme +http:// and the given hostname, port, and pathname. + +=item B<-header name=value> + +Adds the header B<name> with the specified B<value> to the OCSP request +that is sent to the responder. +This may be repeated. + +=item B<-timeout seconds> + +Connection timeout to the OCSP responder in seconds. +On POSIX systems, when running as an OCSP responder, this option also limits +the time that the responder is willing to wait for the client request. +This time is measured from the time the responder accepts the connection until +the complete request is received. + +=item B<-multi process-count> + +Run the specified number of OCSP responder child processes, with the parent +process respawning child processes as needed. +Child processes will detect changes in the CA index file and automatically +reload it. +When running as a responder B<-timeout> option is recommended to limit the time +each child is willing to wait for the client's OCSP response. +This option is available on POSIX systems (that support the fork() and other +required unix system-calls). + +=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<-I<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> + +The B<indexfile> parameter is the name of 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<-rsigopt nm:v> + +Pass options to the signature algorithm when signing OCSP responses. +Names and values of these options are algorithm-specific. + +=item B<-port portnum> + +Port to listen for OCSP requests on. The port may also be specified +using the B<url> option. + +=item B<-ignore_err> + +Ignore malformed requests or responses: When acting as an OCSP client, retry if +a malformed response is received. When acting as an OCSP responder, continue +running instead of terminating upon receiving a malformed request. + +=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 option was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/openssl.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/openssl.pod new file mode 100644 index 000000000..a39cf963d --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/openssl.pod @@ -0,0 +1,568 @@ +=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). + +Detailed documentation and use cases for most standard subcommands are available +(e.g., L<x509(1)> or L<openssl-x509(1)>). + +Many commands use an external configuration file for some or all of their +arguments and have a B<-config> option to specify that file. +The environment variable B<OPENSSL_CONF> can be used to specify +the location of the file. +If the environment variable is not specified, then the file is named +B<openssl.cnf> in the default certificate storage area, whose value +depends on the configuration flags specified when the OpenSSL +was built. + +The list parameters B<standard-commands>, B<digest-commands>, +and B<cipher-commands> output a list (one entry per line) of the names +of all standard commands, message digest commands, or cipher commands, +respectively, that are available in the present B<openssl> utility. + +The list parameters B<cipher-algorithms> and +B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as: + + from => to + +The list parameter B<public-key-algorithms> lists all supported public +key algorithms. + +The command B<no->I<XXX> tests whether a command of the +specified name is available. If no command named I<XXX> exists, it +returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1 +and prints I<XXX>. In both cases, the output goes to B<stdout> and +nothing is printed to B<stderr>. Additional command line arguments +are always ignored. Since for each cipher there is a command of the +same name, this provides an easy way for shell scripts to test for the +availability of ciphers in the B<openssl> program. (B<no->I<XXX> is +not able to detect pseudo-commands such as B<quit>, +B<list>, or B<no->I<XXX> itself.) + +=head2 Standard Commands + +=over 4 + +=item B<asn1parse> + +Parse an ASN.1 sequence. + +=item B<ca> + +Certificate Authority (CA) Management. + +=item B<ciphers> + +Cipher Suite Description Determination. + +=item B<cms> + +CMS (Cryptographic Message Syntax) utility. + +=item B<crl> + +Certificate Revocation List (CRL) Management. + +=item B<crl2pkcs7> + +CRL to PKCS#7 Conversion. + +=item B<dgst> + +Message Digest Calculation. + +=item B<dh> + +Diffie-Hellman Parameter Management. +Obsoleted by L<dhparam(1)>. + +=item B<dhparam> + +Generation and Management of Diffie-Hellman Parameters. Superseded by +L<genpkey(1)> and L<pkeyparam(1)>. + +=item B<dsa> + +DSA Data Management. + +=item B<dsaparam> + +DSA Parameter Generation and Management. Superseded by +L<genpkey(1)> and L<pkeyparam(1)>. + +=item B<ec> + +EC (Elliptic curve) key processing. + +=item B<ecparam> + +EC parameter manipulation and generation. + +=item B<enc> + +Encoding with Ciphers. + +=item B<engine> + +Engine (loadable module) information and manipulation. + +=item B<errstr> + +Error Number to Error String Conversion. + +=item B<gendh> + +Generation of Diffie-Hellman Parameters. +Obsoleted by L<dhparam(1)>. + +=item B<gendsa> + +Generation of DSA Private Key from Parameters. Superseded by +L<genpkey(1)> and L<pkey(1)>. + +=item B<genpkey> + +Generation of Private Key or Parameters. + +=item B<genrsa> + +Generation of RSA Private Key. Superseded by L<genpkey(1)>. + +=item B<nseq> + +Create or examine a Netscape certificate sequence. + +=item B<ocsp> + +Online Certificate Status Protocol utility. + +=item B<passwd> + +Generation of hashed passwords. + +=item B<pkcs12> + +PKCS#12 Data Management. + +=item B<pkcs7> + +PKCS#7 Data Management. + +=item B<pkcs8> + +PKCS#8 format private key conversion tool. + +=item B<pkey> + +Public and private key management. + +=item B<pkeyparam> + +Public key algorithm parameter management. + +=item B<pkeyutl> + +Public key algorithm cryptographic operation utility. + +=item B<prime> + +Compute prime numbers. + +=item B<rand> + +Generate pseudo-random bytes. + +=item B<rehash> + +Create symbolic links to certificate and CRL files named by the hash values. + +=item B<req> + +PKCS#10 X.509 Certificate Signing Request (CSR) Management. + +=item B<rsa> + +RSA key management. + +=item B<rsautl> + +RSA utility for signing, verification, encryption, and decryption. Superseded +by L<pkeyutl(1)>. + +=item B<s_client> + +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 B<s_server> + +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 B<s_time> + +SSL Connection Timer. + +=item B<sess_id> + +SSL Session Data Management. + +=item B<smime> + +S/MIME mail processing. + +=item B<speed> + +Algorithm Speed Measurement. + +=item B<spkac> + +SPKAC printing and generating utility. + +=item B<srp> + +Maintain SRP password file. + +=item B<storeutl> + +Utility to list and display certificates, keys, CRLs, etc. + +=item B<ts> + +Time Stamping Authority tool (client/server). + +=item B<verify> + +X.509 Certificate Verification. + +=item B<version> + +OpenSSL Version Information. + +=item B<x509> + +X.509 Certificate Data Management. + +=back + +=head2 Message Digest Commands + +=over 4 + +=item B<blake2b512> + +BLAKE2b-512 Digest + +=item B<blake2s256> + +BLAKE2s-256 Digest + +=item B<md2> + +MD2 Digest + +=item B<md4> + +MD4 Digest + +=item B<md5> + +MD5 Digest + +=item B<mdc2> + +MDC2 Digest + +=item B<rmd160> + +RMD-160 Digest + +=item B<sha1> + +SHA-1 Digest + +=item B<sha224> + +SHA-2 224 Digest + +=item B<sha256> + +SHA-2 256 Digest + +=item B<sha384> + +SHA-2 384 Digest + +=item B<sha512> + +SHA-2 512 Digest + +=item B<sha3-224> + +SHA-3 224 Digest + +=item B<sha3-256> + +SHA-3 256 Digest + +=item B<sha3-384> + +SHA-3 384 Digest + +=item B<sha3-512> + +SHA-3 512 Digest + +=item B<shake128> + +SHA-3 SHAKE128 Digest + +=item B<shake256> + +SHA-3 SHAKE256 Digest + +=item B<sm3> + +SM3 Digest + +=back + +=head2 Encoding and Cipher Commands + +The following aliases provide convenient access to the most used encodings +and ciphers. + +Depending on how OpenSSL was configured and built, not all ciphers listed +here may be present. See L<enc(1)> for more information and command usage. + +=over 4 + +=item B<aes128>, B<aes-128-cbc>, B<aes-128-cfb>, B<aes-128-ctr>, B<aes-128-ecb>, B<aes-128-ofb> + +AES-128 Cipher + +=item B<aes192>, B<aes-192-cbc>, B<aes-192-cfb>, B<aes-192-ctr>, B<aes-192-ecb>, B<aes-192-ofb> + +AES-192 Cipher + +=item B<aes256>, B<aes-256-cbc>, B<aes-256-cfb>, B<aes-256-ctr>, B<aes-256-ecb>, B<aes-256-ofb> + +AES-256 Cipher + +=item B<aria128>, B<aria-128-cbc>, B<aria-128-cfb>, B<aria-128-ctr>, B<aria-128-ecb>, B<aria-128-ofb> + +Aria-128 Cipher + +=item B<aria192>, B<aria-192-cbc>, B<aria-192-cfb>, B<aria-192-ctr>, B<aria-192-ecb>, B<aria-192-ofb> + +Aria-192 Cipher + +=item B<aria256>, B<aria-256-cbc>, B<aria-256-cfb>, B<aria-256-ctr>, B<aria-256-ecb>, B<aria-256-ofb> + +Aria-256 Cipher + +=item B<base64> + +Base64 Encoding + +=item B<bf>, B<bf-cbc>, B<bf-cfb>, B<bf-ecb>, B<bf-ofb> + +Blowfish Cipher + +=item B<camellia128>, B<camellia-128-cbc>, B<camellia-128-cfb>, B<camellia-128-ctr>, B<camellia-128-ecb>, B<camellia-128-ofb> + +Camellia-128 Cipher + +=item B<camellia192>, B<camellia-192-cbc>, B<camellia-192-cfb>, B<camellia-192-ctr>, B<camellia-192-ecb>, B<camellia-192-ofb> + +Camellia-192 Cipher + +=item B<camellia256>, B<camellia-256-cbc>, B<camellia-256-cfb>, B<camellia-256-ctr>, B<camellia-256-ecb>, B<camellia-256-ofb> + +Camellia-256 Cipher + +=item B<cast>, B<cast-cbc> + +CAST Cipher + +=item B<cast5-cbc>, B<cast5-cfb>, B<cast5-ecb>, B<cast5-ofb> + +CAST5 Cipher + +=item B<chacha20> + +Chacha20 Cipher + +=item B<des>, B<des-cbc>, B<des-cfb>, B<des-ecb>, B<des-ede>, B<des-ede-cbc>, B<des-ede-cfb>, B<des-ede-ofb>, B<des-ofb> + +DES Cipher + +=item B<des3>, B<desx>, B<des-ede3>, B<des-ede3-cbc>, B<des-ede3-cfb>, B<des-ede3-ofb> + +Triple-DES Cipher + +=item B<idea>, B<idea-cbc>, B<idea-cfb>, B<idea-ecb>, B<idea-ofb> + +IDEA Cipher + +=item B<rc2>, B<rc2-cbc>, B<rc2-cfb>, B<rc2-ecb>, B<rc2-ofb> + +RC2 Cipher + +=item B<rc4> + +RC4 Cipher + +=item B<rc5>, B<rc5-cbc>, B<rc5-cfb>, B<rc5-ecb>, B<rc5-ofb> + +RC5 Cipher + +=item B<seed>, B<seed-cbc>, B<seed-cfb>, B<seed-ecb>, B<seed-ofb> + +SEED Cipher + +=item B<sm4>, B<sm4-cbc>, B<sm4-cfb>, B<sm4-ctr>, B<sm4-ecb>, B<sm4-ofb> + +SM4 Cipher + +=back + +=head1 OPTIONS + +Details of which options are available depend on the specific command. +This section describes some common options with common behavior. + +=head2 Common Options + +=over 4 + +=item B<-help> + +Provides a terse summary of all options. + +=back + +=head2 Pass Phrase Options + +Several commands accept password arguments, typically using B<-passin> +and B<-passout> for input and output passwords respectively. These allow +the password to be obtained from a variety of sources. Both of these +options take a single argument whose format is described below. If no +password argument is given and a password is required then the user is +prompted to enter one: this will typically be read from the current +terminal with echoing turned off. + +Note that character encoding may be relevant, please see +L<passphrase-encoding(7)>. + +=over 4 + +=item B<pass:password> + +The actual password is B<password>. Since the password is visible +to utilities (like 'ps' under Unix) this form should only be used +where security is not important. + +=item B<env:var> + +Obtain the password from the environment variable B<var>. Since +the environment of other processes is visible on certain platforms +(e.g. ps under certain Unix OSes) this option should be used with caution. + +=item B<file:pathname> + +The first line of B<pathname> is the password. If the same B<pathname> +argument is supplied to B<-passin> and B<-passout> arguments then the first +line will be used for the input password and the next line for the output +password. B<pathname> need not refer to a regular file: it could for example +refer to a device or named pipe. + +=item B<fd:number> + +Read the password from the file descriptor B<number>. This can be used to +send the data via a pipe for example. + +=item B<stdin> + +Read the password from standard input. + +=back + +=head1 SEE ALSO + +L<asn1parse(1)>, L<ca(1)>, L<ciphers(1)>, L<cms(1)>, L<config(5)>, +L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>, +L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>, +L<ec(1)>, L<ecparam(1)>, +L<enc(1)>, L<engine(1)>, L<errstr(1)>, L<gendsa(1)>, L<genpkey(1)>, +L<genrsa(1)>, L<nseq(1)>, L<ocsp(1)>, +L<passwd(1)>, +L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>, +L<pkey(1)>, L<pkeyparam(1)>, L<pkeyutl(1)>, L<prime(1)>, +L<rand(1)>, L<rehash(1)>, L<req(1)>, L<rsa(1)>, +L<rsautl(1)>, L<s_client(1)>, +L<s_server(1)>, L<s_time(1)>, L<sess_id(1)>, +L<smime(1)>, L<speed(1)>, L<spkac(1)>, L<srp(1)>, L<storeutl(1)>, +L<ts(1)>, +L<verify(1)>, L<version(1)>, L<x509(1)>, +L<crypto(7)>, L<ssl(7)>, L<x509v3_config(5)> + +=head1 HISTORY + +The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0; +For notes on the availability of other commands, see their individual +manual pages. + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/passwd.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/passwd.pod new file mode 100644 index 000000000..c5760fe76 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/passwd.pod @@ -0,0 +1,132 @@ +=pod + +=head1 NAME + +openssl-passwd, +passwd - compute password hashes + +=head1 SYNOPSIS + +B<openssl passwd> +[B<-help>] +[B<-crypt>] +[B<-1>] +[B<-apr1>] +[B<-aixmd5>] +[B<-5>] +[B<-6>] +[B<-salt> I<string>] +[B<-in> I<file>] +[B<-stdin>] +[B<-noverify>] +[B<-quiet>] +[B<-table>] +[B<-rand file...>] +[B<-writerand file>] +{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>, its Apache variant B<apr1>, and its AIX variant 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<-aixmd5> + +Use the B<AIX MD5> algorithm (AIX 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. + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=back + +=head1 EXAMPLES + + % openssl passwd -crypt -salt xx password + xxj31ZMTZzkVA + + % openssl passwd -1 -salt xxxxxxxx password + $1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a. + + % openssl passwd -apr1 -salt xxxxxxxx password + $apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0 + + % openssl passwd -aixmd5 -salt xxxxxxxx password + xxxxxxxx$8Oaipk/GPKhC64w/YVeFD/ + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs12.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs12.pod new file mode 100644 index 000000000..da887a469 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs12.pod @@ -0,0 +1,393 @@ +=pod + +=head1 NAME + +openssl-pkcs12, +pkcs12 - PKCS#12 file utility + +=head1 SYNOPSIS + +B<openssl> B<pkcs12> +[B<-help>] +[B<-export>] +[B<-chain>] +[B<-inkey file_or_id>] +[B<-certfile filename>] +[B<-name name>] +[B<-caname name>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-nomacver>] +[B<-nocerts>] +[B<-clcerts>] +[B<-cacerts>] +[B<-nokeys>] +[B<-info>] +[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -aria128 | -aria192 | -aria256 | -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...>] +[B<-writerand file>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-CSP name>] + +=head1 DESCRIPTION + +The B<pkcs12> command allows PKCS#12 files (sometimes referred to as +PFX files) to be created and parsed. PKCS#12 files are used by several +programs including Netscape, MSIE and MS Outlook. + +=head1 OPTIONS + +There are a lot of options the meaning of some depends of whether a PKCS#12 file +is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 +file can be created by using the B<-export> option (see below). + +=head1 PARSING OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies filename of the PKCS#12 file to be parsed. Standard input is used +by default. + +=item B<-out filename> + +The filename to write certificates and private keys to, standard output by +default. They are all written in PEM format. + +=item B<-passin arg> + +The PKCS#12 file (i.e. input file) password source. For more information about +the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in +L<openssl(1)>. + +=item B<-passout arg> + +Pass phrase source to encrypt any outputted private keys with. For more +information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section +in L<openssl(1)>. + +=item B<-password arg> + +With -export, -password is equivalent to -passout. +Otherwise, -password is equivalent to -passin. + +=item B<-noout> + +This option inhibits output of the keys and certificates to the output file +version of the PKCS#12 file. + +=item B<-clcerts> + +Only output client certificates (not CA certificates). + +=item B<-cacerts> + +Only output CA certificates (not client certificates). + +=item B<-nocerts> + +No certificates at all will be output. + +=item B<-nokeys> + +No private keys will be output. + +=item B<-info> + +Output additional information about the PKCS#12 file structure, algorithms +used and iteration counts. + +=item B<-des> + +Use DES to encrypt private keys before outputting. + +=item B<-des3> + +Use triple DES to encrypt private keys before outputting, this is the default. + +=item B<-idea> + +Use IDEA to encrypt private keys before outputting. + +=item B<-aes128>, B<-aes192>, B<-aes256> + +Use AES to encrypt private keys before outputting. + +=item B<-aria128>, B<-aria192>, B<-aria256> + +Use ARIA 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. Cannot be used in combination with the options +-password, -passin (if importing) or -passout (if exporting). + +=back + +=head1 FILE CREATION OPTIONS + +=over 4 + +=item B<-export> + +This option specifies that a PKCS#12 file will be created rather than +parsed. + +=item B<-out filename> + +This specifies filename to write the PKCS#12 file to. Standard output is used +by default. + +=item B<-in filename> + +The filename to read certificates and private keys from, standard input by +default. They must all be in PEM format. The order doesn't matter but one +private key and its corresponding certificate should be present. If additional +certificates are present they will also be included in the PKCS#12 file. + +=item B<-inkey file_or_id> + +File to read private key from. If not present then a private key must be present +in the input file. +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. + +=item B<-name friendlyname> + +This specifies the "friendly name" for the certificate and private key. This +name is typically displayed in list boxes by software importing the file. + +=item B<-certfile filename> + +A filename to read additional certificates from. + +=item B<-caname friendlyname> + +This specifies the "friendly name" for other certificates. This option may be +used multiple times to specify names for all certificates in the order they +appear. Netscape ignores friendly names on other certificates whereas MSIE +displays them. + +=item B<-pass arg>, B<-passout arg> + +The PKCS#12 file (i.e. output file) password source. For more information about +the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in +L<openssl(1)>. + +=item B<-passin password> + +Pass phrase source to decrypt any input private keys with. For more information +about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in +L<openssl(1)>. + +=item B<-chain> + +If this option is present then an attempt is made to include the entire +certificate chain of the user certificate. The standard CA store is used +for this search. If the search fails it is considered a fatal error. + +=item B<-descert> + +Encrypt the certificate using triple DES, this may render the PKCS#12 +file unreadable by some "export grade" software. By default the private +key is encrypted using triple DES and the certificate using 40 bit RC2 +unless RC2 is disabled in which case triple DES is used. + +=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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs7.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs7.pod new file mode 100644 index 000000000..cf445b3dc --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs7.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +openssl-pkcs7, +pkcs7 - PKCS#7 utility + +=head1 SYNOPSIS + +B<openssl> B<pkcs7> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-print_certs>] +[B<-text>] +[B<-noout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<pkcs7> command processes PKCS#7 files in DER or PEM format. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. B<DER> format is DER encoded PKCS#7 +v1.5 structure.B<PEM> (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs8.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs8.pod new file mode 100644 index 000000000..b079885d2 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkcs8.pod @@ -0,0 +1,319 @@ +=pod + +=head1 NAME + +openssl-pkcs8, +pkcs8 - PKCS#8 format private key conversion tool + +=head1 SYNOPSIS + +B<openssl> B<pkcs8> +[B<-help>] +[B<-topk8>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-iter count>] +[B<-noiter>] +[B<-rand file...>] +[B<-writerand file>] +[B<-nocrypt>] +[B<-traditional>] +[B<-v2 alg>] +[B<-v2prf alg>] +[B<-v1 alg>] +[B<-engine id>] +[B<-scrypt>] +[B<-scrypt_N N>] +[B<-scrypt_r r>] +[B<-scrypt_p p>] + +=head1 DESCRIPTION + +The B<pkcs8> command processes private keys in PKCS#8 format. It can handle +both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo +format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-topk8> + +Normally a PKCS#8 private key is expected on input and a private key will be +written to the output file. With the B<-topk8> option the situation is +reversed: it reads a private key and writes a PKCS#8 format key. + +=item B<-inform DER|PEM> + +This specifies the input format: see L<KEY FORMATS> for more details. The default +format is PEM. + +=item B<-outform DER|PEM> + +This specifies the output format: see L<KEY FORMATS> for more details. The default +format is PEM. + +=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<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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. + +=item 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>, B<PBE-MD2-RC2-64>, B<PBE-MD5-RC2-64>, B<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>, B<PBE-SHA1-RC4-40>, B<PBE-SHA1-3DES>, B<PBE-SHA1-2DES>, B<PBE-SHA1-RC2-128>, B<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 in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkey.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkey.pod new file mode 100644 index 000000000..9569fe0e4 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkey.pod @@ -0,0 +1,168 @@ +=pod + +=head1 NAME + +openssl-pkey, +pkey - public or private key processing tool + +=head1 SYNOPSIS + +B<openssl> B<pkey> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-traditional>] +[B<-I<cipher>>] +[B<-text>] +[B<-text_pub>] +[B<-noout>] +[B<-pubin>] +[B<-pubout>] +[B<-engine id>] +[B<-check>] +[B<-pubcheck>] + +=head1 DESCRIPTION + +The B<pkey> command processes public or private keys. They can be converted +between various forms and their components printed out. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format DER or PEM. The default format is PEM. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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<-I<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. + +=item B<-check> + +This option checks the consistency of a key pair for both public and private +components. + +=item B<-pubcheck> + +This option checks the correctness of either a public key or the public component +of a key pair. + +=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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkeyparam.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkeyparam.pod new file mode 100644 index 000000000..bddabc270 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkeyparam.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +openssl-pkeyparam, +pkeyparam - public key algorithm parameter processing tool + +=head1 SYNOPSIS + +B<openssl> B<pkeyparam> +[B<-help>] +[B<-in filename>] +[B<-out filename>] +[B<-text>] +[B<-noout>] +[B<-engine id>] +[B<-check>] + +=head1 DESCRIPTION + +The B<pkeyparam> command processes public key algorithm parameters. +They can be checked for correctness and their components printed out. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. + +=item B<-out filename> + +This specifies the output filename to write parameters to or standard output if +this option is not specified. + +=item B<-text> + +Prints out the parameters in plain text in addition to the encoded version. + +=item B<-noout> + +Do not output the encoded version of the parameters. + +=item B<-engine id> + +Specifying an engine (by its unique B<id> string) will cause B<pkeyparam> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-check> + +This option checks the correctness of parameters. + +=back + +=head1 EXAMPLES + +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-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkeyutl.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkeyutl.pod new file mode 100644 index 000000000..dffc449a4 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/pkeyutl.pod @@ -0,0 +1,337 @@ +=pod + +=head1 NAME + +openssl-pkeyutl, +pkeyutl - public key algorithm utility + +=head1 SYNOPSIS + +B<openssl> B<pkeyutl> +[B<-help>] +[B<-in file>] +[B<-out file>] +[B<-sigfile file>] +[B<-inkey file>] +[B<-keyform PEM|DER|ENGINE>] +[B<-passin arg>] +[B<-peerkey file>] +[B<-peerform PEM|DER|ENGINE>] +[B<-pubin>] +[B<-certin>] +[B<-rev>] +[B<-sign>] +[B<-verify>] +[B<-verifyrecover>] +[B<-encrypt>] +[B<-decrypt>] +[B<-derive>] +[B<-kdf algorithm>] +[B<-kdflen length>] +[B<-pkeyopt opt:value>] +[B<-hexdump>] +[B<-asn1parse>] +[B<-rand file...>] +[B<-writerand file>] +[B<-engine id>] +[B<-engine_impl>] + +=head1 DESCRIPTION + +The B<pkeyutl> command can be used to perform low level public key operations +using any supported algorithm. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read data from or standard input +if this option is not specified. + +=item B<-out filename> + +Specifies the output filename to write to or standard output by +default. + +=item B<-sigfile file> + +Signature file, required for B<verify> operations only + +=item B<-inkey file> + +The input key file, by default it should be a private key. + +=item B<-keyform PEM|DER|ENGINE> + +The key format PEM, DER or ENGINE. Default is PEM. + +=item B<-passin arg> + +The input key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-peerkey file> + +The peer key file, used by key derivation (agreement) operations. + +=item B<-peerform PEM|DER|ENGINE> + +The peer key format PEM, DER or ENGINE. Default is PEM. + +=item B<-pubin> + +The input file is a public key. + +=item B<-certin> + +The input is a certificate containing a public key. + +=item B<-rev> + +Reverse the order of the input buffer. This is useful for some libraries +(such as CryptoAPI) which represent the buffer in little endian format. + +=item B<-sign> + +Sign the input data (which must be a hash) and output the signed result. This +requires a private key. + +=item B<-verify> + +Verify the input data (which must be a hash) against the signature file and +indicate if the verification succeeded or failed. + +=item B<-verifyrecover> + +Verify the input data (which must be a hash) and output the recovered data. + +=item B<-encrypt> + +Encrypt the input data using a public key. + +=item B<-decrypt> + +Decrypt the input data using a private key. + +=item B<-derive> + +Derive a shared secret using the peer key. + +=item B<-kdf algorithm> + +Use key derivation function B<algorithm>. The supported algorithms are +at present B<TLS1-PRF> and B<HKDF>. +Note: additional parameters and the KDF output length will normally have to be +set for this to work. +See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)> +for the supported string parameters of each algorithm. + +=item B<-kdflen length> + +Set the output length for KDF. + +=item B<-pkeyopt opt:value> + +Public key options specified as opt:value. See NOTES below for more details. + +=item B<-hexdump> + +hex dump the output data. + +=item B<-asn1parse> + +Parse the ASN.1 output data, this is useful when combined with the +B<-verifyrecover> option when an ASN1 structure is signed. + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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 not used to +hash the input data. It is used (by some algorithms) 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). + +This utility does not hash the input data but rather it will use the data +directly as input to the signature algorithm. Depending on the key type, +signature type, and mode of padding, the maximum acceptable lengths of input +data differ. The signed data can't be longer than the key modulus with RSA. In +case of ECDSA and DSA the data shouldn't be longer than the field +size, otherwise it will be silently truncated to the field size. In any event +the input size must not be larger than the largest supported digest size. + +In other words, if the value of digest is B<sha1> the input should be the 20 +bytes long binary encoding of the SHA-1 hash function output. + +The Ed25519 and Ed448 signature algorithms are not supported by this utility. +They accept non-hashed input, but this utility can only be used to sign hashed +input. + +=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. Three special +values are supported: "digest" sets the salt length to the digest length, +"max" sets the salt length to the maximum permissible value. When verifying +"auto" causes the salt length to be automatically determined based on the +B<PSS> block structure. + +=item B<rsa_mgf1_md:digest> + +For PSS and OAEP padding sets the MGF1 digest. If the MGF1 digest is not +explicitly set in PSS mode then the signing digest is used. + +=back + +=head1 RSA-PSS ALGORITHM + +The RSA-PSS algorithm is a restricted version of the RSA algorithm which only +supports the sign and verify operations with PSS padding. The following +additional B<pkeyopt> values are supported: + +=over 4 + +=item B<rsa_padding_mode:mode>, B<rsa_pss_saltlen:len>, B<rsa_mgf1_md:digest> + +These have the same meaning as the B<RSA> algorithm with some additional +restrictions. The padding mode can only be set to B<pss> which is the +default value. + +If the key has parameter restrictions than the digest, MGF1 +digest and salt length are set to the values specified in the parameters. +The digest and MG cannot be changed and the salt length cannot be set to a +value less than the minimum restriction. + +=back + +=head1 DSA ALGORITHM + +The DSA algorithm supports signing and verification operations only. Currently +there are no additional B<-pkeyopt> options other than B<digest>. The SHA1 +digest is assumed by default. + +=head1 DH ALGORITHM + +The DH algorithm only supports the derivation operation and no additional +B<-pkeyopt> options. + +=head1 EC ALGORITHM + +The EC algorithm supports sign, verify and derive operations. The sign and +verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for +the B<-pkeyopt> B<digest> option. + +=head1 X25519 and X448 ALGORITHMS + +The X25519 and X448 algorithms support key derivation only. Currently there are +no additional options. + +=head1 EXAMPLES + +Sign some data using a private key: + + openssl pkeyutl -sign -in file -inkey key.pem -out sig + +Recover the signed data (e.g. if an RSA key is used): + + openssl pkeyutl -verifyrecover -in sig -inkey key.pem + +Verify the signature (e.g. a DSA key): + + openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem + +Sign data using a message digest value (this is currently only valid for RSA): + + openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 + +Derive a shared secret value: + + openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret + +Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and +seed consisting of the single byte 0xFF: + + openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \ + -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump + +=head1 SEE ALSO + +L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)> +L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>, +L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)> + +=head1 COPYRIGHT + +Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/prime.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/prime.pod new file mode 100644 index 000000000..1d25954af --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/prime.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +openssl-prime, +prime - compute prime numbers + +=head1 SYNOPSIS + +B<openssl prime> +[B<-help>] +[B<-hex>] +[B<-generate>] +[B<-bits>] +[B<-safe>] +[B<-checks>] +[I<number...>] + +=head1 DESCRIPTION + +The B<prime> command checks if the specified numbers are prime. + +If no numbers are given on the command line, the B<-generate> flag should +be used to generate primes according to the requirements specified by the +rest of the flags. + +=head1 OPTIONS + +=over 4 + +=item [B<-help>] + +Display an option summary. + +=item [B<-hex>] + +Generate hex output. + +=item [B<-generate>] + +Generate a prime number. + +=item [B<-bits num>] + +Generate a prime with B<num> bits. + +=item [B<-safe>] + +When used with B<-generate>, generates a "safe" prime. If the number +generated is B<n>, then check that B<(n-1)/2> is also prime. + +=item [B<-checks num>] + +Perform the checks B<num> times to see that the generated number +is prime. The default is 20. + +=back + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rand.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rand.pod new file mode 100644 index 000000000..b5d45ab51 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rand.pod @@ -0,0 +1,95 @@ +=pod + +=head1 NAME + +openssl-rand, +rand - generate pseudo-random bytes + +=head1 SYNOPSIS + +B<openssl rand> +[B<-help>] +[B<-out> I<file>] +[B<-rand file...>] +[B<-writerand file>] +[B<-base64>] +[B<-hex>] +I<num> + +=head1 DESCRIPTION + +This command generates I<num> random bytes using a cryptographically +secure pseudo random number generator (CSPRNG). + +The random bytes are generated using the L<RAND_bytes(3)> function, +which provides a security level of 256 bits, provided it managed to +seed itself successfully from a trusted operating system entropy source. +Otherwise, the command will fail with a nonzero error code. +For more details, see L<RAND_bytes(3)>, L<RAND(7)>, and L<RAND_DRBG(7)>. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out file> + +Write to I<file> instead of standard output. + +=item B<-rand file...> + +A file or files containing random data used to seed 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. +Explicitly specifying a seed file is in general not necessary, see the +L</NOTES> section for more information. + +=item [B<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=item B<-base64> + +Perform base64 encoding on the output. + +=item B<-hex> + +Show the output as a hex string. + +=back + +=head1 NOTES + +Prior to OpenSSL 1.1.1, it was common for applications to store information +about the state of the random-number generator in a file that was loaded +at startup and rewritten upon exit. On modern operating systems, this is +generally no longer necessary as OpenSSL will seed itself from a trusted +entropy source provided by the operating system. The B<-rand> and +B<-writerand> flags are still supported for special platforms or +circumstances that might require them. + +It is generally an error to use the same seed file more than once and +every use of B<-rand> should be paired with B<-writerand>. + +=head1 SEE ALSO + +L<RAND_bytes(3)>, +L<RAND(7)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rehash.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rehash.pod new file mode 100644 index 000000000..22f3b7a40 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rehash.pod @@ -0,0 +1,146 @@ +=pod + +=for comment +Original text by James Westby, contributed under the OpenSSL license. + +=head1 NAME + +openssl-c_rehash, openssl-rehash, +c_rehash, rehash - Create symbolic links to files named by the hash values + +=head1 SYNOPSIS + +B<openssl> +B<rehash> +B<[-h]> +B<[-help]> +B<[-old]> +B<[-n]> +B<[-v]> +[ I<directory>...] + +B<c_rehash> +I<flags...> + +=head1 DESCRIPTION + +On some platforms, the OpenSSL B<rehash> command is available as +an external script called B<c_rehash>. They are functionally equivalent, +except for minor differences noted below. + +B<rehash> scans directories and calculates a hash value of each +C<.pem>, C<.crt>, C<.cer>, or C<.crl> +file in the specified directory list and creates symbolic links +for each file, where the name of the link is the hash value. +(If the platform does not support symbolic links, a copy is made.) +This utility is useful as many programs that use OpenSSL require +directories to be set up like this in order to find certificates. + +If any directories are named on the command line, then those are +processed in turn. If not, then the B<SSL_CERT_DIR> environment variable +is consulted; this should be a colon-separated list of directories, +like the Unix B<PATH> variable. +If that is not set then the default directory (installation-specific +but often B</usr/local/ssl/certs>) is processed. + +In order for a directory to be processed, the user must have write +permissions on that directory, otherwise an error will be generated. + +The links created are of the form C<HHHHHHHH.D>, where each B<H> +is a hexadecimal character and B<D> is a single decimal digit. +When processing a directory, B<rehash> will first remove all links +that have a name in that syntax, even if they are being used for some +other purpose. +To skip the removal step, use the B<-n> flag. +Hashes for CRL's look similar except the letter B<r> appears after +the period, like this: C<HHHHHHHH.rD>. + +Multiple objects may have the same hash; they will be indicated by +incrementing the B<D> value. Duplicates are found by comparing the +full SHA-1 fingerprint. A warning will be displayed if a duplicate +is found. + +A warning will also be displayed if there are files that +cannot be parsed as either a certificate or a CRL or if +more than one such object appears in the file. + +=head2 Script Configuration + +The B<c_rehash> script +uses the B<openssl> program to compute the hashes and +fingerprints. If not found in the user's B<PATH>, then set the +B<OPENSSL> environment variable to the full pathname. +Any program can be used, it will be invoked as follows for either +a certificate or CRL: + + $OPENSSL x509 -hash -fingerprint -noout -in FILENAME + $OPENSSL crl -hash -fingerprint -noout -in FILENAME + +where B<FILENAME> is the filename. It must output the hash of the +file on the first line, and the fingerprint on the second, +optionally prefixed with some text and an equals sign. + +=head1 OPTIONS + +=over 4 + +=item B<-help> B<-h> + +Display a brief usage message. + +=item B<-old> + +Use old-style hashing (MD5, as opposed to SHA-1) for generating +links to be used for releases before 1.0.0. +Note that current versions will not use the old style. + +=item B<-n> + +Do not remove existing links. +This is needed when keeping new and old-style links in the same directory. + +=item B<-compat> + +Generate links for both old-style (MD5) and new-style (SHA1) hashing. +This allows releases before 1.0.0 to use these links along-side newer +releases. + +=item B<-v> + +Print messages about old links removed and new links created. +By default, B<rehash> only lists each directory as it is processed. + +=back + +=head1 ENVIRONMENT + +=over 4 + +=item B<OPENSSL> + +The path to an executable to use to generate hashes and +fingerprints (see above). + +=item B<SSL_CERT_DIR> + +Colon separated list of directories to operate on. +Ignored if directories are listed on the command line. + +=back + +=head1 SEE ALSO + +L<openssl(1)>, +L<crl(1)>. +L<x509(1)>. + +=head1 COPYRIGHT + +Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/req.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/req.pod new file mode 100644 index 000000000..730c59079 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/req.pod @@ -0,0 +1,705 @@ +=pod + +=head1 NAME + +openssl-req, +req - PKCS#10 certificate request and certificate generating utility + +=head1 SYNOPSIS + +B<openssl> B<req> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-text>] +[B<-pubkey>] +[B<-noout>] +[B<-verify>] +[B<-modulus>] +[B<-new>] +[B<-rand file...>] +[B<-writerand file>] +[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<-I<digest>>] +[B<-config filename>] +[B<-multivalue-rdn>] +[B<-x509>] +[B<-days n>] +[B<-set_serial n>] +[B<-newhdr>] +[B<-addext ext>] +[B<-extensions section>] +[B<-reqexts section>] +[B<-precert>] +[B<-utf8>] +[B<-nameopt>] +[B<-reqopt>] +[B<-subject>] +[B<-subj arg>] +[B<-sigopt nm:v>] +[B<-batch>] +[B<-verbose>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<req> command primarily creates and processes certificate requests +in PKCS#10 format. It can additionally create self signed certificates +for use as root CAs for example. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option uses an ASN1 DER encoded +form compatible with the PKCS#10. The B<PEM> form is the default format: it +consists of the B<DER> format base64 encoded with additional header and +footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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<-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 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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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<-I<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>), Ed25519 and Ed448 never use any digest. + +=item B<-config filename> + +This allows an alternative configuration file to be specified. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. + +=item B<-subj arg> + +Sets subject name for new request or supersedes the subject name +when processing a request. +The arg must be formatted as I</type0=value0/type1=value1/type2=...>. +Keyword characters may be escaped by \ (backslash), and whitespace is retained. +Empty values are permitted, but the corresponding type will not be included +in the request. + +=item B<-multivalue-rdn> + +This option causes the -subj argument to be interpreted with full +support for multivalued RDNs. Example: + +I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> + +If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. + +=item B<-x509> + +This option outputs a self signed certificate instead of a certificate +request. This is typically used to generate a test certificate or +a self signed root CA. The extensions added to the certificate +(if any) are specified in the configuration file. Unless specified +using the B<set_serial> option, a large random number will be used for +the serial number. + +If existing request is specified with the B<-in> option, it is converted +to the self signed certificate otherwise new request is created. + +=item B<-days n> + +When the B<-x509> option is being used this specifies the number of +days to certify the certificate for, otherwise it is ignored. B<n> should +be a positive integer. The default is 30 days. + +=item B<-set_serial n> + +Serial number to use when outputting a self signed certificate. This +may be specified as a decimal value or a hex value if preceded by B<0x>. + +=item B<-addext ext> + +Add a specific extension to the certificate (if the B<-x509> option is +present) or certificate request. The argument must have the form of +a key=value pair as it would appear in a config file. + +This option can be given multiple times. + +=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<-precert> + +A poison extension will be added to the certificate, making it a +"pre-certificate" (see RFC6962). This can be submitted to Certificate +Transparency logs in order to obtain signed certificate timestamps (SCTs). +These SCTs can then be embedded into the pre-certificate as an extension, before +removing the poison and signing the certificate. + +This implies the B<-new> flag. + +=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> + +At startup the specified file is loaded into the random number generator, +and at exit 256 bytes will be written to it. +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. This option can be overridden on the +command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore +any digest that has been set. + +=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 included 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 + +Example of giving the most common attributes (subject and extensions) +on the command line: + + openssl req -new -subj "/C=GB/CN=foo" \ + -addext "subjectAltName = DNS:foo.co.uk" \ + -addext "certificatePolicies = 1.2.3.4" \ + -newkey rsa:2048 -keyout key.pem -out req.pem + + +=head1 NOTES + +The header and footer lines in the B<PEM> format are normally: + + -----BEGIN CERTIFICATE REQUEST----- + -----END CERTIFICATE REQUEST----- + +some software (some versions of Netscape certificate server) instead needs: + + -----BEGIN NEW CERTIFICATE REQUEST----- + -----END NEW CERTIFICATE REQUEST----- + +which is produced with the B<-newhdr> option but is otherwise compatible. +Either form is accepted transparently on input. + +The certificate requests generated by B<Xenroll> with MSIE have extensions +added. It includes the B<keyUsage> extension which determines the type of +key (signature only or general purpose) and any additional OIDs entered +by the script in an extendedKeyUsage extension. + +=head1 DIAGNOSTICS + +The following messages are frequently asked about: + + Using configuration from /some/path/openssl.cnf + Unable to load config info + +This is followed some time later by... + + unable to find 'distinguished_name' in config + problems making Certificate Request + +The first error message is the clue: it can't find the configuration +file! Certain operations (like examining a certificate request) don't +need a configuration file so its use isn't enforced. Generation of +certificates or requests however does need a configuration file. This +could be regarded as a bug. + +Another puzzling message is this: + + Attributes: + a0:00 + +this is displayed when no attributes are present and the request includes +the correct empty B<SET OF> structure (the DER encoding of which is 0xa0 +0x00). If you just see: + + Attributes: + +then the B<SET OF> is missing and the encoding is technically invalid (but +it is tolerated). See the description of the command line option B<-asn1-kludge> +for more information. + +=head1 BUGS + +OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively +treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. +This can cause problems if you need characters that aren't available in +PrintableStrings and you don't want to or can't use BMPStrings. + +As a consequence of the T61String handling the only correct way to represent +accented characters in OpenSSL is to use a BMPString: unfortunately Netscape +currently chokes on these. If you have to use accented characters with Netscape +and MSIE then you currently need to use the invalid T61String form. + +The current prompting is not very friendly. It doesn't allow you to confirm what +you've just entered. Other things like extensions in certificate requests are +statically defined in the configuration file. Some of these: like an email +address in subjectAltName should be input by the user. + +=head1 SEE ALSO + +L<x509(1)>, L<ca(1)>, L<genrsa(1)>, +L<gendsa(1)>, L<config(5)>, +L<x509v3_config(5)> + +=head1 COPYRIGHT + +Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rsa.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rsa.pod new file mode 100644 index 000000000..37f64616c --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rsa.pod @@ -0,0 +1,205 @@ +=pod + +=head1 NAME + +openssl-rsa, +rsa - RSA key processing tool + +=head1 SYNOPSIS + +B<openssl> B<rsa> +[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<-aria128>] +[B<-aria192>] +[B<-aria256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-text>] +[B<-noout>] +[B<-modulus>] +[B<-check>] +[B<-pubin>] +[B<-pubout>] +[B<-RSAPublicKey_in>] +[B<-RSAPublicKey_out>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<rsa> command processes RSA keys. They can be converted between various +forms and their components printed out. B<Note> this command uses the +traditional SSLeay compatible format for private key encryption: newer +applications should use the more secure PKCS#8 format using the B<pkcs8> +utility. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|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. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-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----- + +=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 + +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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rsautl.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rsautl.pod new file mode 100644 index 000000000..fdc67432f --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/rsautl.pod @@ -0,0 +1,220 @@ +=pod + +=head1 NAME + +openssl-rsautl, +rsautl - RSA utility + +=head1 SYNOPSIS + +B<openssl> B<rsautl> +[B<-help>] +[B<-in file>] +[B<-out file>] +[B<-inkey file>] +[B<-keyform PEM|DER|ENGINE>] +[B<-pubin>] +[B<-certin>] +[B<-sign>] +[B<-verify>] +[B<-encrypt>] +[B<-decrypt>] +[B<-rand file...>] +[B<-writerand file>] +[B<-pkcs>] +[B<-ssl>] +[B<-raw>] +[B<-hexdump>] +[B<-asn1parse>] + +=head1 DESCRIPTION + +The B<rsautl> command can be used to sign, verify, encrypt and decrypt +data using the RSA algorithm. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read data from or standard input +if this option is not specified. + +=item B<-out filename> + +Specifies the output filename to write to or standard output by +default. + +=item B<-inkey file> + +The input key file, by default it should be an RSA private key. + +=item B<-keyform PEM|DER|ENGINE> + +The key format PEM, DER or ENGINE. + +=item B<-pubin> + +The input file is an RSA public key. + +=item B<-certin> + +The input is a certificate containing an RSA public key. + +=item B<-sign> + +Sign the input data and output the signed result. This requires +an RSA private key. + +=item B<-verify> + +Verify the input data and output the recovered data. + +=item B<-encrypt> + +Encrypt the input data using an RSA public key. + +=item B<-decrypt> + +Decrypt the input data using an RSA private key. + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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> + +Parse the ASN.1 output data, this is useful when combined with the +B<-verify> option. + +=back + +=head1 NOTES + +B<rsautl> because it uses the RSA algorithm directly can only be +used to sign or verify small pieces of data. + +=head1 EXAMPLES + +Sign some data using a private key: + + openssl rsautl -sign -in file -inkey key.pem -out sig + +Recover the signed data + + openssl rsautl -verify -in sig -inkey key.pem + +Examine the raw signed data: + + openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump + + 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world + +The PKCS#1 block formatting is evident from this. If this was done using +encrypt and decrypt the block would have been of type 2 (the second byte) +and random padding data visible instead of the 0xff bytes. + +It is possible to analyse the signature of certificates using this +utility in conjunction with B<asn1parse>. Consider the self signed +example in certs/pca-cert.pem . Running B<asn1parse> as follows yields: + + openssl asn1parse -in pca-cert.pem + + 0:d=0 hl=4 l= 742 cons: SEQUENCE + 4:d=1 hl=4 l= 591 cons: SEQUENCE + 8:d=2 hl=2 l= 3 cons: cont [ 0 ] + 10:d=3 hl=2 l= 1 prim: INTEGER :02 + 13:d=2 hl=2 l= 1 prim: INTEGER :00 + 16:d=2 hl=2 l= 13 cons: SEQUENCE + 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption + 29:d=3 hl=2 l= 0 prim: NULL + 31:d=2 hl=2 l= 92 cons: SEQUENCE + 33:d=3 hl=2 l= 11 cons: SET + 35:d=4 hl=2 l= 9 cons: SEQUENCE + 37:d=5 hl=2 l= 3 prim: OBJECT :countryName + 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU + .... + 599:d=1 hl=2 l= 13 cons: SEQUENCE + 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption + 612:d=2 hl=2 l= 0 prim: NULL + 614:d=1 hl=3 l= 129 prim: BIT STRING + + +The final BIT STRING contains the actual signature. It can be extracted with: + + openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614 + +The certificate public key can be extracted with: + + openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem + +The signature can be analysed with: + + openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin + + 0:d=0 hl=2 l= 32 cons: SEQUENCE + 2:d=1 hl=2 l= 12 cons: SEQUENCE + 4:d=2 hl=2 l= 8 prim: OBJECT :md5 + 14:d=2 hl=2 l= 0 prim: NULL + 16:d=1 hl=2 l= 16 prim: OCTET STRING + 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%.. + +This is the parsed version of an ASN1 DigestInfo structure. It can be seen that +the digest used was md5. The actual part of the certificate that was signed can +be extracted with: + + openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4 + +and its digest computed with: + + openssl md5 -c tbs + MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5 + +which it can be seen agrees with the recovered value above. + +=head1 SEE ALSO + +L<dgst(1)>, L<rsa(1)>, L<genrsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_client.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_client.pod new file mode 100644 index 000000000..68a152a27 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_client.pod @@ -0,0 +1,838 @@ +=pod + +=head1 NAME + +openssl-s_client, +s_client - SSL/TLS client program + +=head1 SYNOPSIS + +B<openssl> B<s_client> +[B<-help>] +[B<-connect host:port>] +[B<-bind host:port>] +[B<-proxy host:port>] +[B<-unix path>] +[B<-4>] +[B<-6>] +[B<-servername name>] +[B<-noservername>] +[B<-verify depth>] +[B<-verify_return_error>] +[B<-cert filename>] +[B<-certform DER|PEM>] +[B<-key filename>] +[B<-keyform DER|PEM>] +[B<-cert_chain filename>] +[B<-build_chain>] +[B<-xkey>] +[B<-xcert>] +[B<-xchain>] +[B<-xchain_build>] +[B<-xcertform PEM|DER>] +[B<-xkeyform PEM|DER>] +[B<-pass arg>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-chainCApath directory>] +[B<-chainCAfile filename>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-requestCAfile filename>] +[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<-nameopt option>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-build_chain>] +[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<-psk_identity identity>] +[B<-psk key>] +[B<-psk_session file>] +[B<-quiet>] +[B<-ssl3>] +[B<-tls1>] +[B<-tls1_1>] +[B<-tls1_2>] +[B<-tls1_3>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-no_tls1_1>] +[B<-no_tls1_2>] +[B<-no_tls1_3>] +[B<-dtls>] +[B<-dtls1>] +[B<-dtls1_2>] +[B<-sctp>] +[B<-sctp_label_bug>] +[B<-fallback_scsv>] +[B<-async>] +[B<-max_send_frag>] +[B<-split_send_frag>] +[B<-max_pipelines>] +[B<-read_buf>] +[B<-bugs>] +[B<-comp>] +[B<-no_comp>] +[B<-allow_no_dhe_kex>] +[B<-sigalgs sigalglist>] +[B<-curves curvelist>] +[B<-cipher cipherlist>] +[B<-ciphersuites val>] +[B<-serverpref>] +[B<-starttls protocol>] +[B<-xmpphost hostname>] +[B<-name hostname>] +[B<-engine id>] +[B<-tlsextdebug>] +[B<-no_ticket>] +[B<-sess_out filename>] +[B<-sess_in filename>] +[B<-rand file...>] +[B<-writerand file>] +[B<-serverinfo types>] +[B<-status>] +[B<-alpn protocols>] +[B<-nextprotoneg protocols>] +[B<-ct>] +[B<-noct>] +[B<-ctlogfile>] +[B<-keylogfile file>] +[B<-early_data file>] +[B<-enable_pha>] +[B<target>] + +=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 "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. It is possible to +select the host and port using the optional target positional argument instead. +If neither this nor the target positional argument are specified then an attempt +is made to connect to the local host on port 4433. + +=item B<-bind host:port>] + +This specifies the host address and or port to bind as the source for the +connection. For Unix-domain sockets the port is ignored and the host is +used as the source socket address. + +=item B<-proxy host:port> + +When used with the B<-connect> flag, the program uses the host and port +specified with this flag and issues an HTTP CONNECT command to connect +to the desired server. + +=item B<-unix path> + +Connect over the specified Unix-domain socket. + +=item B<-4> + +Use IPv4 only. + +=item B<-6> + +Use IPv6 only. + +=item B<-servername name> + +Set the TLS SNI (Server Name Indication) extension in the ClientHello message to +the given value. +If B<-servername> is not provided, the TLS SNI extension will be populated with +the name given to B<-connect> if it follows a DNS name format. If B<-connect> is +not provided either, the SNI is set to "localhost". +This is the default since OpenSSL 1.1.1. + +Even though SNI should normally be a DNS name and not an IP address, if +B<-servername> is provided then that name will be sent, regardless of whether +it is a DNS name or not. + +This option cannot be used in conjunction with B<-noservername>. + +=item B<-noservername> + +Suppresses sending of the SNI (Server Name Indication) extension in the +ClientHello message. Cannot be used in conjunction with the B<-servername> or +<-dane_tlsa_domain> options. + +=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<-cert_chain> + +A file containing trusted certificates to use when attempting to build the +client/server certificate chain related to the certificate specified via the +B<-cert> option. + +=item B<-build_chain> + +Specify whether the application should build the certificate chain to be +provided to the server. + +=item B<-xkey infile>, B<-xcert infile>, B<-xchain> + +Specify an extra certificate, private key and certificate chain. These behave +in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When +specified, the callback returning the first valid chain will be in use by the +client. + +=item B<-xchain_build> + +Specify whether the application should build the certificate chain to be +provided to the server for the extra certificates provided via B<-xkey infile>, +B<-xcert infile>, B<-xchain> options. + +=item B<-xcertform PEM|DER>, B<-xkeyform PEM|DER> + +Extra certificate and private key format respectively. + +=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<-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<-CApath directory> + +The directory to use for server certificate verification. This directory +must be in "hash format", see L<verify(1)> 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<-chainCApath directory> + +The directory to use for building the chain provided to the server. This +directory must be in "hash format", see L<verify(1)> for more information. + +=item B<-chainCAfile file> + +A file containing trusted certificates 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<-requestCAfile file> + +A file containing a list of certificates whose subject names will be sent +to the server in the B<certificate_authorities> extension. Only supported +for TLS 1.3 + +=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 +specified 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> + +Displays the server certificate list as sent by the server: it only consists of +certificates the server has sent (in the order the server has sent them). It is +B<not> a verified chain. + +=item B<-prexit> + +Print session information when the program exits. This will always attempt +to print out information even if the connection fails. Normally information +will only be printed out once if the connection succeeds. This option is useful +because the cipher in use may be renegotiated or the connection may fail +because a client certificate is required or is requested only after an +attempt is made to access a certain URL. Note: the output produced by this +option is not always accurate because a connection might never have been +established. + +=item B<-state> + +Prints out the SSL session states. + +=item B<-debug> + +Print extensive debugging information including a hex dump of all traffic. + +=item B<-msg> + +Show all protocol messages with hex dump. + +=item B<-trace> + +Show verbose trace output of protocol messages. OpenSSL needs to be compiled +with B<enable-ssl-trace> for this option to work. + +=item B<-msgfile> + +File to send output of B<-msg> or B<-trace> to, default standard output. + +=item B<-nbio_test> + +Tests non-blocking I/O + +=item B<-nbio> + +Turns on non-blocking I/O + +=item B<-crlf> + +This option translated a line feed from the terminal into CR+LF as required +by some servers. + +=item B<-ign_eof> + +Inhibit shutting down the connection when end of file is reached in the +input. + +=item B<-quiet> + +Inhibit printing of session and certificate information. This implicitly +turns on B<-ign_eof> as well. + +=item B<-no_ign_eof> + +Shut down the connection when end of file is reached in the input. +Can be used to override the implicit B<-ign_eof> after B<-quiet>. + +=item B<-psk_identity identity> + +Use the PSK identity B<identity> when using a PSK cipher suite. +The default value is "Client_identity" (without the quotes). + +=item B<-psk key> + +Use the PSK key B<key> when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. +This option must be provided in order to use a PSK cipher. + +=item B<-psk_session file> + +Use the pem encoded SSL_SESSION data stored in B<file> as the basis of a PSK. +Note that this will only work if TLSv1.3 is negotiated. + +=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3> + +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. +Note that not all protocols and flags may be available, depending on how +OpenSSL was built. + +=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<-sctp> + +Use SCTP for the transport protocol instead of UDP in DTLS. Must be used in +conjunction with B<-dtls>, B<-dtls1> or B<-dtls1_2>. This option is only +available where OpenSSL has support for SCTP enabled. + +=item B<-sctp_label_bug> + +Use the incorrect behaviour of older OpenSSL implementations when computing +endpoint-pair shared secrets for DTLS/SCTP. This allows communication with +older broken implementations but breaks interoperability with correct +implementations. Must be used in conjunction with B<-sctp>. This option is only +available where OpenSSL has support for SCTP enabled. + +=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<-max_send_frag int> + +The maximum size of data fragment to send. +See L<SSL_CTX_set_max_send_fragment(3)> for further information. + +=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 cipher suite 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 cipher suite 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 bugs in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-comp> + +Enables support for SSL/TLS compression. +This option was introduced in OpenSSL 1.1.0. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-no_comp> + +Disables support for SSL/TLS compression. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-brief> + +Only provide a brief summary of connection parameters instead of the +normal verbose output. + +=item B<-sigalgs sigalglist> + +Specifies the list of signature algorithms that are sent by the client. +The server selects one entry in the list based on its preferences. +For example strings, see L<SSL_CTX_set1_sigalgs(3)> + +=item B<-curves curvelist> + +Specifies the list of supported curves to be sent by the client. The curve is +ultimately selected by the server. For a list of all curves, use: + + $ openssl ecparam -list_curves + +=item B<-cipher cipherlist> + +This allows the TLSv1.2 and below cipher list sent by the client to be modified. +This list will be combined with any TLSv1.3 ciphersuites that have been +configured. Although the server determines which ciphersuite 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<-ciphersuites val> + +This allows the TLSv1.3 ciphersuites sent by the client to be modified. This +list will be combined with any TLSv1.2 and below ciphersuites that have been +configured. 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. The format for this list is a simple +colon (":") separated list of TLSv1.3 ciphersuite names. + +=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", "postgres", "mysql", "lmtp", "nntp", "sieve" and "ldap". + +=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. + +This option is an alias of the B<-name> option for "xmpp" and "xmpp-server". + +=item B<-name hostname> + +This option is used to specify hostname information for various protocols +used with B<-starttls> option. Currently only "xmpp", "xmpp-server", +"smtp" and "lmtp" can utilize this B<-name> option. + +If this option is used with "-starttls xmpp" or "-starttls xmpp-server", +if 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. + +If this option is used with "-starttls lmtp" or "-starttls smtp", it specifies +the name to use in the "LMTP LHLO" or "SMTP EHLO" message, respectively. If +this option is not specified, then "mail.example.com" 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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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 (NPN) extension, respectively. ALPN is the +IETF standard and replaces NPN. +The B<protocols> list is a comma-separated list of protocol names that +the client should advertise support for. The list should contain the most +desirable protocols first. Protocol names are printable ASCII strings, +for example "http/1.1" or "spdy/3". +An 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. +The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used. + +=item B<-ct>, B<-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. + +=item B<-keylogfile file> + +Appends TLS secrets to the specified keylog file such that external programs +(like Wireshark) can decrypt TLS connections. + +=item B<-early_data file> + +Reads the contents of the specified file and attempts to send it as early data +to the server. This will only work with resumed sessions that support early +data and when the server accepts the early data. + +=item B<-enable_pha> + +For TLSv1.3 only, send the Post-Handshake Authentication extension. This will +happen whether or not a certificate has been provided via B<-cert>. + +=item B<[target]> + +Rather than providing B<-connect>, the target hostname and optional port may +be provided as a single positional argument after all options. If neither this +nor B<-connect> are provided, falls back to attempting to connect to localhost +on port 4433. + +=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. If end of file is reached then the connection will be closed down. When +used interactively (which means neither B<-quiet> nor B<-ign_eof> have been +given), then certain commands are also recognized which perform special +operations. These commands are a letter which must appear at the start of a +line. They are listed below. + +=over 4 + +=item B<Q> + +End the current SSL connection and exit. + +=item B<R> + +Renegotiate the SSL session (TLSv1.2 and below only). + +=item B<B> + +Send a heartbeat message to the server (DTLS only) + +=item B<k> + +Send a key update message to the server (TLSv1.3 only) + +=item B<K> + +Send a key update message to the server and request one back (TLSv1.3 only) + +=back + +=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 all the certificates sent by the +server. + +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. + +The B<-bind> option may be useful if the server or a firewall requires +connections to come from some particular address and or port. + +=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)>, +L<SSL_CTX_set_max_send_fragment(3)>, L<SSL_CTX_set_split_send_fragment(3)>, +L<SSL_CTX_set_max_pipelines(3)> + +=head1 HISTORY + +The B<-no_alt_chains> option was added in OpenSSL 1.1.0. +The B<-name> option was added in OpenSSL 1.1.1. + +=head1 COPYRIGHT + +Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_server.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_server.pod new file mode 100644 index 000000000..7fa382a8a --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_server.pod @@ -0,0 +1,855 @@ +=pod + +=head1 NAME + +openssl-s_server, +s_server - SSL/TLS server program + +=head1 SYNOPSIS + +B<openssl> B<s_server> +[B<-help>] +[B<-port +int>] +[B<-accept val>] +[B<-unix val>] +[B<-4>] +[B<-6>] +[B<-unlink>] +[B<-context val>] +[B<-verify int>] +[B<-Verify int>] +[B<-cert infile>] +[B<-nameopt val>] +[B<-naccept +int>] +[B<-serverinfo val>] +[B<-certform PEM|DER>] +[B<-key infile>] +[B<-keyform format>] +[B<-pass val>] +[B<-dcert infile>] +[B<-dcertform PEM|DER>] +[B<-dkey infile>] +[B<-dkeyform PEM|DER>] +[B<-dpass val>] +[B<-nbio_test>] +[B<-crlf>] +[B<-debug>] +[B<-msg>] +[B<-msgfile outfile>] +[B<-state>] +[B<-CAfile infile>] +[B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-nocert>] +[B<-quiet>] +[B<-no_resume_ephemeral>] +[B<-www>] +[B<-WWW>] +[B<-servername>] +[B<-servername_fatal>] +[B<-cert2 infile>] +[B<-key2 infile>] +[B<-tlsextdebug>] +[B<-HTTP>] +[B<-id_prefix val>] +[B<-rand file...>] +[B<-writerand file>] +[B<-keymatexport val>] +[B<-keymatexportlen +int>] +[B<-CRL infile>] +[B<-crl_download>] +[B<-cert_chain infile>] +[B<-dcert_chain infile>] +[B<-chainCApath dir>] +[B<-verifyCApath dir>] +[B<-no_cache>] +[B<-ext_cache>] +[B<-CRLform PEM|DER>] +[B<-verify_return_error>] +[B<-verify_quiet>] +[B<-build_chain>] +[B<-chainCAfile infile>] +[B<-verifyCAfile infile>] +[B<-ign_eof>] +[B<-no_ign_eof>] +[B<-status>] +[B<-status_verbose>] +[B<-status_timeout int>] +[B<-status_url val>] +[B<-status_file infile>] +[B<-trace>] +[B<-security_debug>] +[B<-security_debug_verbose>] +[B<-brief>] +[B<-rev>] +[B<-async>] +[B<-ssl_config val>] +[B<-max_send_frag +int>] +[B<-split_send_frag +int>] +[B<-max_pipelines +int>] +[B<-read_buf +int>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-no_tls1_1>] +[B<-no_tls1_2>] +[B<-no_tls1_3>] +[B<-bugs>] +[B<-no_comp>] +[B<-comp>] +[B<-no_ticket>] +[B<-num_tickets>] +[B<-serverpref>] +[B<-legacy_renegotiation>] +[B<-no_renegotiation>] +[B<-legacy_server_connect>] +[B<-no_resumption_on_reneg>] +[B<-no_legacy_server_connect>] +[B<-allow_no_dhe_kex>] +[B<-prioritize_chacha>] +[B<-strict>] +[B<-sigalgs val>] +[B<-client_sigalgs val>] +[B<-groups val>] +[B<-curves val>] +[B<-named_curve val>] +[B<-cipher val>] +[B<-ciphersuites val>] +[B<-dhparam infile>] +[B<-record_padding val>] +[B<-debug_broken_protocol>] +[B<-policy val>] +[B<-purpose val>] +[B<-verify_name val>] +[B<-verify_depth int>] +[B<-auth_level int>] +[B<-attime intmax>] +[B<-verify_hostname val>] +[B<-verify_email val>] +[B<-verify_ip>] +[B<-ignore_critical>] +[B<-issuer_checks>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-policy_check>] +[B<-explicit_policy>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-x509_strict>] +[B<-extended_crl>] +[B<-use_deltas>] +[B<-policy_print>] +[B<-check_ss_sig>] +[B<-trusted_first>] +[B<-suiteB_128_only>] +[B<-suiteB_128>] +[B<-suiteB_192>] +[B<-partial_chain>] +[B<-no_alt_chains>] +[B<-no_check_time>] +[B<-allow_proxy_certs>] +[B<-xkey>] +[B<-xcert>] +[B<-xchain>] +[B<-xchain_build>] +[B<-xcertform PEM|DER>] +[B<-xkeyform PEM|DER>] +[B<-nbio>] +[B<-psk_identity val>] +[B<-psk_hint val>] +[B<-psk val>] +[B<-psk_session file>] +[B<-srpvfile infile>] +[B<-srpuserseed val>] +[B<-ssl3>] +[B<-tls1>] +[B<-tls1_1>] +[B<-tls1_2>] +[B<-tls1_3>] +[B<-dtls>] +[B<-timeout>] +[B<-mtu +int>] +[B<-listen>] +[B<-dtls1>] +[B<-dtls1_2>] +[B<-sctp>] +[B<-sctp_label_bug>] +[B<-no_dhe>] +[B<-nextprotoneg val>] +[B<-use_srtp val>] +[B<-alpn val>] +[B<-engine val>] +[B<-keylogfile outfile>] +[B<-max_early_data int>] +[B<-early_data>] +[B<-anti_replay>] +[B<-no_anti_replay>] + +=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 "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)> +manual page. + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-port +int> + +The TCP port to listen on for connections. If not specified 4433 is used. + +=item B<-accept val> + +The optional TCP host and port to listen on for connections. If not specified, *:4433 is used. + +=item B<-unix val> + +Unix domain socket to accept on. + +=item B<-4> + +Use IPv4 only. + +=item B<-6> + +Use IPv6 only. + +=item B<-unlink> + +For -unix, unlink any existing socket first. + +=item B<-context val> + +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<-verify int>, B<-Verify int> + +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 cipher suite cannot request a client certificate (for example an +anonymous cipher suite or PSK) this option has no effect. + +=item B<-cert infile> + +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<-cert_chain> + +A file containing trusted certificates to use when attempting to build the +client/server certificate chain related to the certificate specified via the +B<-cert> option. + +=item B<-build_chain> + +Specify whether the application should build the certificate chain to be +provided to the client. + +=item B<-nameopt val> + +Option which determines how the subject or issuer names are displayed. The +B<val> 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<-naccept +int> + +The server will exit after receiving the specified number of connections, +default unlimited. + +=item B<-serverinfo val> + +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<-certform PEM|DER> + +The certificate format to use: DER or PEM. PEM is the default. + +=item B<-key infile> + +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 val> + +The private key password source. For more information about the format of B<val> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-dcert infile>, B<-dkey infile> + +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<-dcert_chain> + +A file containing trusted certificates to use when attempting to build the +server certificate chain when a certificate specified via the B<-dcert> option +is in use. + +=item B<-dcertform PEM|DER>, B<-dkeyform PEM|DER>, B<-dpass val> + +Additional certificate and private key format and passphrase respectively. + +=item B<-xkey infile>, B<-xcert infile>, B<-xchain> + +Specify an extra certificate, private key and certificate chain. These behave +in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When +specified, the callback returning the first valid chain will be in use by +the server. + +=item B<-xchain_build> + +Specify whether the application should build the certificate chain to be +provided to the client for the extra certificates provided via B<-xkey infile>, +B<-xcert infile>, B<-xchain> options. + +=item B<-xcertform PEM|DER>, B<-xkeyform PEM|DER> + +Extra certificate and private key format respectively. + +=item B<-nbio_test> + +Tests non blocking I/O. + +=item B<-crlf> + +This option translated a line feed from the terminal into CR+LF. + +=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<-msgfile outfile> + +File to send output of B<-msg> or B<-trace> to, default standard output. + +=item B<-state> + +Prints the SSL session states. + +=item B<-CAfile infile> + +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<-CApath dir> + +The directory to use for client certificate verification. This directory +must be in "hash format", see L<verify(1)> for more information. These are +also used when building the server certificate chain. + +=item B<-chainCApath dir> + +The directory to use for building the chain provided to the client. This +directory must be in "hash format", see L<verify(1)> for more information. + +=item B<-chainCAfile file> + +A file containing trusted certificates to use when attempting to build the +server 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<-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<-quiet> + +Inhibit printing of session and certificate information. + +=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. Cannot be used in conjunction with B<-early_data>. + +=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. Cannot be used in conjunction +with B<-early_data>. + +=item B<-tlsextdebug> + +Print a hex dump of any TLS extensions received from the server. + +=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). Cannot be +used in conjunction with B<-early_data>. + +=item B<-id_prefix val> + +Generate SSL/TLS session IDs prefixed by B<val>. 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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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<-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 int> + +Sets the timeout for OCSP response to B<int> seconds. + +=item B<-status_url val> + +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<-status_file infile> + +Overrides any OCSP responder URLs from the certificate and always provides the +OCSP Response stored in the file. The file must be in DER format. + +=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<-brief> + +Provide a brief summary of connection parameters instead of the normal verbose +output. + +=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>. Cannot be used in +conjunction with B<-early_data>. + +=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<-max_send_frag +int> + +The maximum size of data fragment to send. +See L<SSL_CTX_set_max_send_fragment(3)> for further information. + +=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 cipher suite 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 cipher suite 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<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3> + +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. +Note that not all protocols and flags may be available, depending on how +OpenSSL was built. + +=item B<-bugs> + +There are several known bugs in SSL and TLS implementations. Adding this +option enables various workarounds. + +=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<-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_ticket> + +Disable RFC4507bis session ticket support. This option has no effect if TLSv1.3 +is negotiated. See B<-num_tickets>. + +=item B<-num_tickets> + +Control the number of tickets that will be sent to the client after a full +handshake in TLSv1.3. The default number of tickets is 2. This option does not +affect the number of tickets sent after a resumption handshake. + +=item B<-serverpref> + +Use the server's cipher preferences, rather than the client's preferences. + +=item B<-prioritize_chacha> + +Prioritize ChaCha ciphers when preferred by clients. Requires B<-serverpref>. + +=item B<-no_resumption_on_reneg> + +Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option. + +=item B<-client_sigalgs val> + +Signature algorithms to support for client certificate authentication +(colon-separated list). + +=item B<-named_curve val> + +Specifies the elliptic curve to use. NOTE: this is single curve, not a list. +For a list of all possible curves, use: + + $ openssl ecparam -list_curves + +=item B<-cipher val> + +This allows the list of TLSv1.2 and below ciphersuites used by the server to be +modified. This list is combined with any TLSv1.3 ciphersuites that have been +configured. 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 is irrelevant. See +the B<ciphers> command for more information. + +=item B<-ciphersuites val> + +This allows the list of TLSv1.3 ciphersuites used by the server to be modified. +This list is combined with any TLSv1.2 and below ciphersuites that have been +configured. 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 is irrelevant. See +the B<ciphers> command for more information. The format for this list is a +simple colon (":") separated list of TLSv1.3 ciphersuite names. + +=item B<-dhparam infile> + +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<-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<-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<-nbio> + +Turns on non blocking I/O. + +=item B<-psk_identity val> + +Expect the client to send PSK identity B<val> when using a PSK +cipher suite, and warn if they do not. By default, the expected PSK +identity is the string "Client_identity". + +=item B<-psk_hint val> + +Use the PSK identity hint B<val> when using a PSK cipher suite. + +=item B<-psk val> + +Use the PSK key B<val> when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. +This option must be provided in order to use a PSK cipher. + +=item B<-psk_session file> + +Use the pem encoded SSL_SESSION data stored in B<file> as the basis of a PSK. +Note that this will only work if TLSv1.3 is negotiated. + +=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<-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<-sctp> + +Use SCTP for the transport protocol instead of UDP in DTLS. Must be used in +conjunction with B<-dtls>, B<-dtls1> or B<-dtls1_2>. This option is only +available where OpenSSL has support for SCTP enabled. + +=item B<-sctp_label_bug> + +Use the incorrect behaviour of older OpenSSL implementations when computing +endpoint-pair shared secrets for DTLS/SCTP. This allows communication with +older broken implementations but breaks interoperability with correct +implementations. Must be used in conjunction with B<-sctp>. This option is only +available where OpenSSL has support for SCTP enabled. + +=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<-alpn val>, B<-nextprotoneg val> + +These flags enable the Enable the Application-Layer Protocol Negotiation +or Next Protocol Negotiation (NPN) extension, respectively. ALPN is the +IETF standard and replaces NPN. +The B<val> list is a comma-separated list of supported protocol +names. The list should contain the most desirable protocols first. +Protocol names are printable ASCII strings, for example "http/1.1" or +"spdy/3". +The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used. + +=item B<-engine val> + +Specifying an engine (by its unique id string in B<val>) 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<-keylogfile outfile> + +Appends TLS secrets to the specified keylog file such that external programs +(like Wireshark) can decrypt TLS connections. + +=item B<-max_early_data int> + +Change the default maximum early data bytes that are specified for new sessions +and any incoming early data (when used in conjunction with the B<-early_data> +flag). The default value is approximately 16k. The argument must be an integer +greater than or equal to 0. + +=item B<-early_data> + +Accept early data where possible. Cannot be used in conjunction with B<-www>, +B<-WWW>, B<-HTTP> or B<-rev>. + +=item B<-anti_replay>, B<-no_anti_replay> + +Switches replay protection on or off, respectively. Replay protection is on by +default unless overridden by a configuration file. When it is on, OpenSSL will +automatically detect if a session ticket has been used more than once, TLSv1.3 +has been negotiated, and early data is enabled on the server. A full handshake +is forced if a session ticket is used a second or subsequent time. Any early +data that was sent will be rejected. + +=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 commands are also recognized which perform special operations. These +commands are a letter which must appear at the start of a line. They 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 (TLSv1.2 and below only). + +=item B<R> + +Renegotiate the SSL session and request a client certificate (TLSv1.2 and below +only). + +=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. + +=item B<B> + +Send a heartbeat message to the client (DTLS only) + +=item B<k> + +Send a key update message to the client (TLSv1.3 only) + +=item B<K> + +Send a key update message to the client and request one back (TLSv1.3 only) + +=item B<c> + +Send a certificate request to the client (TLSv1.3 only) + +=back + +=head1 NOTES + +B<s_server> can be used to debug SSL clients. To accept connections from +a web browser the command: + + openssl s_server -accept 443 -www + +can be used for example. + +Although specifying an empty list of CAs when requesting a client certificate +is strictly speaking a protocol violation, some SSL clients interpret this to +mean any CA is acceptable. This is useful for debugging purposes. + +The session parameters can printed out using the B<sess_id> program. + +=head1 BUGS + +Because this program has a lot of options and also because some of the +techniques used are rather old, the C source of B<s_server> is rather hard to +read and not a model of how things should be done. +A typical SSL server program would be much simpler. + +The output of common ciphers is wrong: it just gives the list of ciphers that +OpenSSL recognizes and the client supports. + +There should be a way for the B<s_server> program to print out details of any +unknown cipher suites a client says it supports. + +=head1 SEE ALSO + +L<SSL_CONF_cmd(3)>, L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)> +L<SSL_CTX_set_max_send_fragment(3)>, +L<SSL_CTX_set_split_send_fragment(3)>, +L<SSL_CTX_set_max_pipelines(3)> + +=head1 HISTORY + +The -no_alt_chains option was added in OpenSSL 1.1.0. + +The +-allow-no-dhe-kex and -prioritize_chacha options were added in OpenSSL 1.1.1. + +=head1 COPYRIGHT + +Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_time.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_time.pod new file mode 100644 index 000000000..e1a3bef41 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/s_time.pod @@ -0,0 +1,212 @@ +=pod + +=head1 NAME + +openssl-s_time, +s_time - SSL/TLS performance timing program + +=head1 SYNOPSIS + +B<openssl> B<s_time> +[B<-help>] +[B<-connect host:port>] +[B<-www page>] +[B<-cert filename>] +[B<-key filename>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-reuse>] +[B<-new>] +[B<-verify depth>] +[B<-nameopt option>] +[B<-time seconds>] +[B<-ssl3>] +[B<-bugs>] +[B<-cipher cipherlist>] +[B<-ciphersuites val>] + +=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<-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<-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<-ssl3> + +This option disables the use of SSL version 3. 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. + +Note that this option may not be available, depending on how +OpenSSL was built. + +=item B<-bugs> + +There are several known bugs in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-cipher cipherlist> + +This allows the TLSv1.2 and below cipher list sent by the client to be modified. +This list will be combined with any TLSv1.3 ciphersuites that have been +configured. Although the server determines which cipher suite is used it should +take the first supported cipher in the list sent by the client. See +L<ciphers(1)> for more information. + +=item B<-ciphersuites val> + +This allows the TLSv1.3 ciphersuites sent by the client to be modified. This +list will be combined with any TLSv1.2 and below ciphersuites that have been +configured. Although the server determines which cipher suite is used it should +take the first supported cipher in the list sent by the client. See +L<ciphers(1)> for more information. The format for this list is a simple +colon (":") separated list of TLSv1.3 ciphersuite names. + +=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-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/sess_id.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/sess_id.pod new file mode 100644 index 000000000..6c54ed988 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/sess_id.pod @@ -0,0 +1,166 @@ +=pod + +=head1 NAME + +openssl-sess_id, +sess_id - SSL/TLS session handling utility + +=head1 SYNOPSIS + +B<openssl> B<sess_id> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER|NSS>] +[B<-in filename>] +[B<-out filename>] +[B<-text>] +[B<-noout>] +[B<-context ID>] + +=head1 DESCRIPTION + +The B<sess_id> process the encoded version of the SSL session structure +and optionally prints out SSL session details (for example the SSL session +master key) in human readable format. Since this is a diagnostic tool that +needs some knowledge of the SSL protocol to use properly, most users will +not need to use it. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option uses an ASN1 DER encoded +format containing session details. The precise format can vary from one version +to the next. The B<PEM> form is the default format: it consists of the B<DER> +format base64 encoded with additional header and footer lines. + +=item B<-outform DER|PEM|NSS> + +This specifies the output format. The B<PEM> and B<DER> options have the same meaning +and default 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) + +These are described below in more detail. + +=over 4 + +=item B<Protocol> + +This is the protocol in use TLSv1.3, 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-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/smime.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/smime.pod new file mode 100644 index 000000000..7f224fdc5 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/smime.pod @@ -0,0 +1,524 @@ +=pod + +=head1 NAME + +openssl-smime, +smime - S/MIME utility + +=head1 SYNOPSIS + +B<openssl> B<smime> +[B<-help>] +[B<-encrypt>] +[B<-decrypt>] +[B<-sign>] +[B<-resign>] +[B<-verify>] +[B<-pk7out>] +[B<-binary>] +[B<-crlfeol>] +[B<-I<cipher>>] +[B<-in file>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-certfile file>] +[B<-signer file>] +[B<-recip file>] +[B<-inform SMIME|PEM|DER>] +[B<-passin arg>] +[B<-inkey file_or_id>] +[B<-out file>] +[B<-outform SMIME|PEM|DER>] +[B<-content file>] +[B<-to addr>] +[B<-from ad>] +[B<-subject s>] +[B<-text>] +[B<-indef>] +[B<-noindef>] +[B<-stream>] +[B<-rand file...>] +[B<-writerand file>] +[B<-md digest>] +[cert.pem]... + +=head1 DESCRIPTION + +The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and +verify S/MIME messages. + +=head1 OPTIONS + +There are six operation options that set the type of operation to be performed. +The meaning of the other options varies according to the operation type. + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-encrypt> + +Encrypt mail for the given recipient certificates. Input file is the message +to be encrypted. The output file is the encrypted mail in MIME format. + +Note that no revocation check is done for the recipient cert, so if that +key has been compromised, others may be able to decrypt the text. + +=item B<-decrypt> + +Decrypt mail using the supplied certificate and private key. Expects an +encrypted mail message in MIME format for the input file. The decrypted mail +is written to the output file. + +=item B<-sign> + +Sign mail using the supplied certificate and private key. Input file is +the message to be signed. The signed message in MIME format is written +to the output file. + +=item B<-verify> + +Verify signed mail. Expects a signed mail message on input and outputs +the signed data. Both clear text and opaque signing is supported. + +=item B<-pk7out> + +Takes an input message and writes out a PEM encoded PKCS#7 structure. + +=item B<-resign> + +Resign a message: take an existing message and one or more new signers. + +=item B<-in filename> + +The input message to be encrypted or signed or the MIME message to +be decrypted or verified. + +=item B<-inform SMIME|PEM|DER> + +This specifies the input format for the PKCS#7 structure. The default +is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> +format change this to expect PEM and DER format PKCS#7 structures +instead. This currently only affects the input format of the PKCS#7 +structure, if no PKCS#7 structure is being input (for example with +B<-encrypt> or B<-sign>) this option has no effect. + +=item B<-out filename> + +The message text that has been decrypted or verified or the output MIME +format message that has been signed or verified. + +=item B<-outform SMIME|PEM|DER> + +This specifies the output format for the PKCS#7 structure. The default +is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> +format change this to write PEM and DER format PKCS#7 structures +instead. This currently only affects the output format of the PKCS#7 +structure, if no PKCS#7 structure is being output (for example with +B<-verify> or B<-decrypt>) this option has no effect. + +=item B<-stream -indef -noindef> + +The B<-stream> and B<-indef> options are equivalent and enable streaming I/O +for encoding operations. This permits single pass processing of data without +the need to hold the entire contents in memory, potentially supporting very +large files. Streaming is automatically set for S/MIME signing with detached +data if the output format is B<SMIME> it is currently off by default for all +other operations. + +=item B<-noindef> + +Disable streaming I/O where it would produce and indefinite length constructed +encoding. This option currently has no effect. In future streaming will be +enabled by default on all relevant operations and this option will disable it. + +=item B<-content filename> + +This specifies a file containing the detached content, this is only +useful with the B<-verify> command. This is only usable if the PKCS#7 +structure is using the detached signature form where the content is +not included. This option will override any content if the input format +is S/MIME and it uses the multipart/signed MIME content type. + +=item B<-text> + +This option adds plain text (text/plain) MIME headers to the supplied +message if encrypting or signing. If decrypting or verifying it strips +off text headers: if the decrypted or verified message is not of MIME +type text/plain then an error occurs. + +=item B<-CAfile file> + +A file containing trusted CA certificates, only used with B<-verify>. + +=item B<-CApath dir> + +A directory containing trusted CA certificates, only used with +B<-verify>. This directory must be a standard certificate directory: that +is a hash of each subject name (using B<x509 -hash>) should be linked +to each certificate. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location. + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location. + +=item B<-md digest> + +Digest algorithm to use when signing or resigning. If not present then the +default digest algorithm for the signing key will be used (usually SHA1). + +=item B<-I<cipher>> + +The encryption algorithm to use. For example DES (56 bits) - B<-des>, +triple DES (168 bits) - B<-des3>, +EVP_get_cipherbyname() function) can also be used preceded by a dash, for +example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers +supported by your version of OpenSSL. + +If not specified triple DES is used. Only used with B<-encrypt>. + +=item B<-nointern> + +When verifying a message normally certificates (if any) included in +the message are searched for the signing certificate. With this option +only the certificates specified in the B<-certfile> option are used. +The supplied certificates can still be used as untrusted CAs however. + +=item B<-noverify> + +Do not verify the signers certificate of a signed message. + +=item B<-nochain> + +Do not do chain verification of signers certificates: that is don't +use the certificates in the signed message as untrusted CAs. + +=item B<-nosigs> + +Don't try to verify the signatures on the message. + +=item B<-nocerts> + +When signing a message the signer's certificate is normally included +with this option it is excluded. This will reduce the size of the +signed message but the verifier must have a copy of the signers certificate +available locally (passed using the B<-certfile> option for example). + +=item B<-noattr> + +Normally when a message is signed a set of attributes are included which +include the signing time and supported symmetric algorithms. With this +option they are not included. + +=item B<-binary> + +Normally the input message is converted to "canonical" format which is +effectively using CR and LF as end of line: as required by the S/MIME +specification. When this option is present no translation occurs. This +is useful when handling binary data which may not be in MIME format. + +=item B<-crlfeol> + +Normally the output file uses a single B<LF> as end of line. When this +option is present B<CRLF> is used instead. + +=item B<-nodetach> + +When signing a message use opaque signing: this form is more resistant +to translation by mail relays but it cannot be read by mail agents that +do not support S/MIME. Without this option cleartext signing with +the MIME type multipart/signed is used. + +=item B<-certfile file> + +Allows additional certificates to be specified. When signing these will +be included with the message. When verifying these will be searched for +the signers certificates. The certificates should be in PEM format. + +=item B<-signer file> + +A signing certificate when signing or resigning a message, this option can be +used multiple times if more than one signer is required. If a message is being +verified then the signers certificates will be written to this file if the +verification was successful. + +=item B<-recip file> + +The recipients certificate when decrypting a message. This certificate +must match one of the recipients of the message or an error occurs. + +=item B<-inkey file_or_id> + +The private key to use when signing or decrypting. This must match the +corresponding certificate. If this option is not specified then the +private key must be included in the certificate file specified with +the B<-recip> or B<-signer> file. When signing this option can be used +multiple times to specify successive keys. +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. + +=item B<-passin arg> + +The private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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 option was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/speed.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/speed.pod new file mode 100644 index 000000000..523da0d3b --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/speed.pod @@ -0,0 +1,104 @@ +=pod + +=head1 NAME + +openssl-speed, +speed - test library performance + +=head1 SYNOPSIS + +B<openssl speed> +[B<-help>] +[B<-engine id>] +[B<-elapsed>] +[B<-evp algo>] +[B<-decrypt>] +[B<-rand file...>] +[B<-writerand file>] +[B<-primes num>] +[B<-seconds num>] +[B<-bytes num>] +[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. The global CSPRNG is denoted by +the I<rand> algorithm name. + +=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> + +When calculating operations- or bytes-per-second, use wall-clock time +instead of CPU user time as divisor. 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. +If B<algo> is an AEAD cipher, then you can pass <-aead> to benchmark a +TLS-like sequence. And if B<algo> is a multi-buffer capable cipher, e.g. +aes-128-cbc-hmac-sha1, then B<-mb> will time multi-buffer operation. + +=item B<-decrypt> + +Time the decryption instead of encryption. Affects only the EVP testing. + +=item B<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=item B<-primes num> + +Generate a B<num>-prime RSA key and use it to run the benchmarks. This option +is only effective if RSA algorithm is specified to test. + +=item B<-seconds num> + +Run benchmarks for B<num> seconds. + +=item B<-bytes num> + +Run benchmarks on B<num>-byte buffers. Affects ciphers, digests and the CSPRNG. + +=item B<[zero or more test algorithms]> + +If any options are given, B<speed> tests those algorithms, otherwise a +pre-compiled grand selection is tested. + +=back + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/spkac.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/spkac.pod new file mode 100644 index 000000000..655f13580 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/spkac.pod @@ -0,0 +1,155 @@ +=pod + +=head1 NAME + +openssl-spkac, +spkac - SPKAC printing and generating utility + +=head1 SYNOPSIS + +B<openssl> B<spkac> +[B<-help>] +[B<-in filename>] +[B<-out filename>] +[B<-key keyfile>] +[B<-keyform PEM|DER|ENGINE>] +[B<-passin arg>] +[B<-challenge string>] +[B<-pubkey>] +[B<-spkac spkacname>] +[B<-spksect section>] +[B<-noout>] +[B<-verify>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<spkac> command processes Netscape signed public key and challenge +(SPKAC) files. It can print out their contents, verify the signature and +produce its own SPKACs from a supplied private key. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read from or standard input if this +option is not specified. Ignored if the B<-key> option is used. + +=item B<-out filename> + +Specifies the output filename to write to or standard output by +default. + +=item B<-key keyfile> + +Create an SPKAC file using the private key in B<keyfile>. The +B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if +present. + +=item B<-keyform PEM|DER|ENGINE> + +Whether the key format is PEM, DER, or an engine-backed key. +The default is PEM. + +=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=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA\ + 1cCoq2Wa3Ixs47uI7FPVwHVIPDx5yso105Y6zpozam135a\ + 8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03uPFoQIDAQAB\ + FgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJ\ + h1bEIYuc2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnD\ + dq+NQ3F+X4deMx9AaEglZtULwV4= + +=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-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/srp.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/srp.pod new file mode 100644 index 000000000..e858a2226 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/srp.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +openssl-srp, +srp - maintain SRP password file + +=head1 SYNOPSIS + +B<openssl srp> +[B<-help>] +[B<-verbose>] +[B<-add>] +[B<-modify>] +[B<-delete>] +[B<-list>] +[B<-name section>] +[B<-config file>] +[B<-srpvfile file>] +[B<-gn identifier>] +[B<-userinfo text...>] +[B<-passin arg>] +[B<-passout arg>] +[I<user...>] + +=head1 DESCRIPTION + +The B<srp> command is user to maintain an SRP (secure remote password) +file. +At most one of the B<-add>, B<-modify>, B<-delete>, and B<-list> options +can be specified. +These options take zero or more usernames as parameters and perform the +appropriate operation on the SRP file. +For B<-list>, if no B<user> is given then all users are displayed. + +The configuration file to use, and the section within the file, can be +specified with the B<-config> and B<-name> flags, respectively. +If the config file is not specified, the B<-srpvfile> can be used to +just specify the file to operate on. + +The B<-userinfo> option specifies additional information to add when +adding or modifying a user. + +The B<-gn> flag specifies the B<g> and B<N> values, using one of +the strengths defined in IETF RFC 5054. + +The B<-passin> and B<-passout> arguments are parsed as described in +the L<openssl(1)> command. + +=head1 OPTIONS + +=over 4 + +=item [B<-help>] + +Display an option summary. + +=item [B<-verbose>] + +Generate verbose output while processing. + +=back + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/storeutl.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/storeutl.pod new file mode 100644 index 000000000..a8d82bfb6 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/storeutl.pod @@ -0,0 +1,133 @@ +=pod + +=head1 NAME + +openssl-storeutl, +storeutl - STORE utility + +=head1 SYNOPSIS + +B<openssl> B<storeutl> +[B<-help>] +[B<-out file>] +[B<-noout>] +[B<-passin arg>] +[B<-text arg>] +[B<-engine id>] +[B<-r>] +[B<-certs>] +[B<-keys>] +[B<-crls>] +[B<-subject arg>] +[B<-issuer arg>] +[B<-serial arg>] +[B<-alias arg>] +[B<-fingerprint arg>] +[B<-I<digest>>] +B<uri> ... + +=head1 DESCRIPTION + +The B<storeutl> command can be used to display the contents (after decryption +as the case may be) fetched from the given URIs. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-noout> + +this option prevents output of the PEM data. + +=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<-text> + +Prints out the objects in text form, similarly to the B<-text> output from +B<openssl x509>, B<openssl pkey>, etc. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<storeutl> +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<-r> + +Fetch objects recursively when possible. + +=item B<-certs> + +=item B<-keys> + +=item B<-crls> + +Only select the certificates, keys or CRLs from the given URI. +However, if this URI would return a set of names (URIs), those are always +returned. + +=item B<-subject arg> + +Search for an object having the subject name B<arg>. +The arg must be formatted as I</type0=value0/type1=value1/type2=...>. +Keyword characters may be escaped by \ (backslash), and whitespace is retained. +Empty values are permitted but are ignored for the search. That is, +a search with an empty value will have the same effect as not specifying +the type at all. + +=item B<-issuer arg> + +=item B<-serial arg> + +Search for an object having the given issuer name and serial number. +These two options I<must> be used together. +The issuer arg must be formatted as I</type0=value0/type1=value1/type2=...>, +characters may be escaped by \ (backslash), no spaces are skipped. +The serial arg may be specified as a decimal value or a hex value if preceded +by B<0x>. + +=item B<-alias arg> + +Search for an object having the given alias. + +=item B<-fingerprint arg> + +Search for an object having the given fingerprint. + +=item B<-I<digest>> + +The digest that was used to compute the fingerprint given with B<-fingerprint>. + +=back + +=head1 SEE ALSO + +L<openssl(1)> + +=head1 HISTORY + +The B<openssl> B<storeutl> app was added in OpenSSL 1.1.1. + +=head1 COPYRIGHT + +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ts.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ts.pod new file mode 100644 index 000000000..ec57ec7eb --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/ts.pod @@ -0,0 +1,675 @@ +=pod + +=head1 NAME + +openssl-ts, +ts - Time Stamping Authority tool (client/server) + +=head1 SYNOPSIS + +B<openssl> B<ts> +B<-query> +[B<-rand file...>] +[B<-writerand file>] +[B<-config> configfile] +[B<-data> file_to_hash] +[B<-digest> digest_bytes] +[B<-I<digest>>] +[B<-tspolicy> object_id] +[B<-no_nonce>] +[B<-cert>] +[B<-in> request.tsq] +[B<-out> request.tsq] +[B<-text>] + +B<openssl> B<ts> +B<-reply> +[B<-config> configfile] +[B<-section> tsa_section] +[B<-queryfile> request.tsq] +[B<-passin> password_src] +[B<-signer> tsa_cert.pem] +[B<-inkey> file_or_id] +[B<-I<digest>>] +[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...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=item B<-config> configfile + +The configuration file to use. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. + +=item B<-data> file_to_hash + +The data file for which the time stamp request needs to be +created. stdin is the default if neither the B<-data> nor the B<-digest> +parameter is specified. (Optional) + +=item B<-digest> digest_bytes + +It is possible to specify the message imprint explicitly without the data +file. The imprint must be specified in a hexadecimal format, two characters +per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or +1AF601...). The number of bytes must match the message digest algorithm +in use. (Optional) + +=item B<-I<digest>> + +The message digest to apply to the data file. +Any digest supported by the OpenSSL B<dgst> command can be used. +The default is SHA-1. (Optional) + +=item B<-tspolicy> object_id + +The policy that the client expects the TSA to use for creating the +time stamp token. Either the dotted OID notation or OID names defined +in the config file can be used. If no policy is requested the TSA will +use its own default policy. (Optional) + +=item B<-no_nonce> + +No nonce is specified in the request if this option is +given. Otherwise a 64 bit long pseudo-random none is +included in the request. It is recommended to use nonce to +protect against replay-attacks. (Optional) + +=item B<-cert> + +The TSA is expected to include its signing certificate in the +response. (Optional) + +=item B<-in> request.tsq + +This option specifies a previously created time stamp request in DER +format that will be printed into the output file. Useful when you need +to examine the content of a request in human-readable +format. (Optional) + +=item B<-out> request.tsq + +Name of the output file to which the request will be written. Default +is stdout. (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=back + +=head2 Time Stamp Response generation + +A time stamp response (TimeStampResp) consists of a response status +and the time stamp token itself (ContentInfo), if the token generation was +successful. The B<-reply> command is for creating a time stamp +response or time stamp token based on a request and printing the +response/token in human-readable format. If B<-token_out> is not +specified the output is always a time stamp response (TimeStampResp), +otherwise it is a time stamp token (ContentInfo). + +=over 4 + +=item B<-config> configfile + +The configuration file to use. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. +See B<CONFIGURATION FILE OPTIONS> for configurable variables. + +=item B<-section> tsa_section + +The name of the config file section containing the settings for the +response generation. If not specified the default TSA section is +used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional) + +=item B<-queryfile> request.tsq + +The name of the file containing a DER encoded time stamp request. (Optional) + +=item B<-passin> password_src + +Specifies the password source for the private key of the TSA. See +B<PASS PHRASE ARGUMENTS> in L<openssl(1)>. (Optional) + +=item B<-signer> tsa_cert.pem + +The signer certificate of the TSA in PEM format. The TSA signing +certificate must have exactly one extended key usage assigned to it: +timeStamping. The extended key usage must also be critical, otherwise +the certificate is going to be refused. Overrides the B<signer_cert> +variable of the config file. (Optional) + +=item B<-inkey> file_or_id + +The signer private key of the TSA in PEM format. Overrides the +B<signer_key> config file option. (Optional) +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. + +=item B<-I<digest>> + +Signing digest to use. Overrides the B<signer_digest> config file +option. (Mandatory unless specified in the config file) + +=item B<-chain> certs_file.pem + +The collection of certificates in PEM format that will all +be included in the response in addition to the signer certificate if +the B<-cert> option was used for the request. This file is supposed to +contain the certificate chain for the signer certificate from its +issuer upwards. The B<-reply> command does not build a certificate +chain automatically. (Optional) + +=item B<-tspolicy> object_id + +The default policy to use for the response unless the client +explicitly requires a particular TSA policy. The OID can be specified +either in dotted notation or with its name. Overrides the +B<default_policy> config file option. (Optional) + +=item B<-in> response.tsr + +Specifies a previously created time stamp response or time stamp token +(if B<-token_in> is also specified) in DER format that will be written +to the output file. This option does not require a request, it is +useful e.g. when you need to examine the content of a response or +token or you want to extract the time stamp token from a response. If +the input is a token and the output is a time stamp response a default +'granted' status info is added to the token. (Optional) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-out> response.tsr + +The response is written to this file. The format and content of the +file depends on other options (see B<-text>, B<-token_out>). The default is +stdout. (Optional) + +=item B<-token_out> + +The output is a time stamp token (ContentInfo) instead of time stamp +response (TimeStampResp). (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=item B<-engine> id + +Specifying an engine (by its unique B<id> string) will cause B<ts> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. Default is builtin. (Optional) + +=back + +=head2 Time Stamp Response verification + +The B<-verify> command is for verifying if a time stamp response or time +stamp token is valid and matches a particular time stamp request or +data file. The B<-verify> command does not use the configuration file. + +=over 4 + +=item B<-data> file_to_hash + +The response or token must be verified against file_to_hash. The file +is hashed with the message digest algorithm specified in the token. +The B<-digest> and B<-queryfile> options must not be specified with this one. +(Optional) + +=item B<-digest> digest_bytes + +The response or token must be verified against the message digest specified +with this option. The number of bytes must match the message digest algorithm +specified in the token. The B<-data> and B<-queryfile> options must not be +specified with this one. (Optional) + +=item B<-queryfile> request.tsq + +The original time stamp request in DER format. The B<-data> and B<-digest> +options must not be specified with this one. (Optional) + +=item B<-in> response.tsr + +The time stamp response that needs to be verified in DER format. (Mandatory) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-CApath> trusted_cert_path + +The name of the directory containing the trusted CA certificates of the +client. See the similar option of L<verify(1)> for additional +details. Either this option or B<-CAfile> must be specified. (Optional) + + +=item B<-CAfile> trusted_certs.pem + +The name of the file containing a set of trusted self-signed CA +certificates in PEM format. See the similar option of +L<verify(1)> for additional details. Either this option +or B<-CApath> must be specified. +(Optional) + +=item B<-untrusted> cert_file.pem + +Set of additional untrusted certificates in PEM format which may be +needed when building the certificate chain for the TSA's signing +certificate. This file must contain the TSA signing certificate and +all intermediate CA certificates unless the response includes them. +(Optional) + +=item I<verify options> + +The options B<-attime timestamp>, B<-check_ss_sig>, B<-crl_check>, +B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, +B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>, +B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>, +B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>, +B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>, +B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>, +B<-verify_name>, and B<-x509_strict> can be used to control timestamp +verification. See L<verify(1)>. + +=back + +=head1 CONFIGURATION FILE OPTIONS + +The B<-query> and B<-reply> commands make use of a configuration file. +See L<config(5)> +for a general description of the syntax of the config file. The +B<-query> command uses only the symbolic OID names section +and it can work without it. However, the B<-reply> command needs the +config file for its operation. + +When there is a command line switch equivalent of a variable the +switch always overrides the settings in the config file. + +=over 4 + +=item B<tsa> section, B<default_tsa> + +This is the main section and it specifies the name of another section +that contains all the options for the B<-reply> command. This default +section can be overridden with the B<-section> command line switch. (Optional) + +=item B<oid_file> + +See L<ca(1)> for description. (Optional) + +=item B<oid_section> + +See L<ca(1)> for description. (Optional) + +=item B<RANDFILE> + +See L<ca(1)> for description. (Optional) + +=item B<serial> + +The name of the file containing the hexadecimal serial number of the +last time stamp response created. This number is incremented by 1 for +each response. If the file does not exist at the time of response +generation a new file is created with serial number 1. (Mandatory) + +=item B<crypto_device> + +Specifies the OpenSSL engine that will be set as the default for +all available algorithms. The default value is builtin, you can specify +any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM). +(Optional) + +=item B<signer_cert> + +TSA signing certificate in PEM format. The same as the B<-signer> +command line option. (Optional) + +=item B<certs> + +A file containing a set of PEM encoded certificates that need to be +included in the response. The same as the B<-chain> command line +option. (Optional) + +=item B<signer_key> + +The private key of the TSA in PEM format. The same as the B<-inkey> +command line option. (Optional) + +=item B<signer_digest> + +Signing digest to use. The same as the +B<-I<digest>> command line option. (Mandatory unless specified on the command +line) + +=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) + +=item B<ess_cert_id_alg> + +This option specifies the hash function to be used to calculate the TSA's +public key certificate identifier. Default is sha1. (Optional) + +=back + +=head1 EXAMPLES + +All the examples below presume that B<OPENSSL_CONF> is set to a proper +configuration file, e.g. the example configuration file +openssl/apps/openssl.cnf will do. + +=head2 Time Stamp Request + +To create a time stamp request for design1.txt with SHA-1 +without nonce and policy and no certificate is required in the response: + + openssl ts -query -data design1.txt -no_nonce \ + -out design1.tsq + +To create a similar time stamp request with specifying the message imprint +explicitly: + + openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -no_nonce -out design1.tsq + +To print the content of the previous request in human readable format: + + openssl ts -query -in design1.tsq -text + +To create a time stamp request which includes the MD-5 digest +of design2.txt, requests the signer certificate and nonce, +specifies a policy id (assuming the tsa_policy1 name is defined in the +OID section of the config file): + + openssl ts -query -data design2.txt -md5 \ + -tspolicy tsa_policy1 -cert -out design2.tsq + +=head2 Time Stamp Response + +Before generating a response a signing certificate must be created for +the TSA that contains the B<timeStamping> critical extended key usage extension +without any other key usage extensions. You can add this line to the +user certificate section of the config file to generate a proper certificate; + + extendedKeyUsage = critical,timeStamping + +See L<req(1)>, L<ca(1)>, and L<x509(1)> for instructions. The examples +below assume that cacert.pem contains the certificate of the CA, +tsacert.pem is the signing certificate issued by cacert.pem and +tsakey.pem is the private key of the TSA. + +To create a time stamp response for a request: + + openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \ + -signer tsacert.pem -out design1.tsr + +If you want to use the settings in the config file you could just write: + + openssl ts -reply -queryfile design1.tsq -out design1.tsr + +To print a time stamp reply to stdout in human readable format: + + openssl ts -reply -in design1.tsr -text + +To create a time stamp token instead of time stamp response: + + openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out + +To print a time stamp token to stdout in human readable format: + + openssl ts -reply -in design1_token.der -token_in -text -token_out + +To extract the time stamp token from a response: + + openssl ts -reply -in design1.tsr -out design1_token.der -token_out + +To add 'granted' status info to a time stamp token thereby creating a +valid response: + + openssl ts -reply -in design1_token.der -token_in -out design1.tsr + +=head2 Time Stamp Verification + +To verify a time stamp reply against a request: + + openssl ts -verify -queryfile design1.tsq -in design1.tsr \ + -CAfile cacert.pem -untrusted tsacert.pem + +To verify a time stamp reply that includes the certificate chain: + + openssl ts -verify -queryfile design2.tsq -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against the original data file: + openssl ts -verify -data design2.txt -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against a message imprint: + openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -in design2.tsr -CAfile cacert.pem + +You could also look at the 'test' directory for more examples. + +=head1 BUGS + +=for comment foreign manuals: procmail(1), perl(1) + +=over 2 + +=item * + +No support for time stamps over SMTP, though it is quite easy +to implement an automatic e-mail based TSA with L<procmail(1)> +and L<perl(1)>. HTTP server support is provided in the form of +a separate apache module. HTTP client support is provided by +L<tsget(1)>. Pure TCP/IP protocol is not supported. + +=item * + +The file containing the last serial number of the TSA is not +locked when being read or written. This is a problem if more than one +instance of L<openssl(1)> is trying to create a time stamp +response at the same time. This is not an issue when using the apache +server module, it does proper locking. + +=item * + +Look for the FIXME word in the source files. + +=item * + +The source code should really be reviewed by somebody else, too. + +=item * + +More testing is needed, I have done only some basic tests (see +test/testtsa). + +=back + +=head1 SEE ALSO + +L<tsget(1)>, L<openssl(1)>, L<req(1)>, +L<x509(1)>, L<ca(1)>, L<genrsa(1)>, +L<config(5)> + +=head1 COPYRIGHT + +Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/tsget.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/tsget.pod new file mode 100644 index 000000000..43bf2c7e3 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/tsget.pod @@ -0,0 +1,202 @@ +=pod + +=head1 NAME + +openssl-tsget, +tsget - Time Stamping HTTP/HTTPS client + +=head1 SYNOPSIS + +B<tsget> +B<-h> server_url +[B<-e> extension] +[B<-o> output] +[B<-v>] +[B<-d>] +[B<-k> private_key.pem] +[B<-p> key_password] +[B<-c> client_cert.pem] +[B<-C> CA_certs.pem] +[B<-P> CA_path] +[B<-r> file:file...] +[B<-g> EGD_socket] +[request]... + +=head1 DESCRIPTION + +The B<tsget> command can be used for sending a time stamp request, as +specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing +the time stamp response in a file. This tool cannot be used for creating the +requests and verifying responses, you can use the OpenSSL B<ts(1)> command to +do that. B<tsget> can send several requests to the server without closing +the TCP connection if more than one requests are specified on the command +line. + +The tool sends the following HTTP request for each time stamp request: + + POST url HTTP/1.1 + User-Agent: OpenTSA tsget.pl/<version> + Host: <host>:<port> + Pragma: no-cache + Content-Type: application/timestamp-query + Accept: application/timestamp-reply + Content-Length: length of body + + ...binary request specified by the user... + +B<tsget> expects a response of type application/timestamp-reply, which is +written to a file without any interpretation. + +=head1 OPTIONS + +=over 4 + +=item B<-h> server_url + +The URL of the HTTP/HTTPS server listening for time stamp requests. + +=item B<-e> extension + +If the B<-o> option is not given this argument specifies the extension of the +output files. The base name of the output file will be the same as those of +the input files. Default extension is '.tsr'. (Optional) + +=item B<-o> output + +This option can be specified only when just one request is sent to the +server. The time stamp response will be written to the given output file. '-' +means standard output. In case of multiple time stamp requests or the absence +of this argument the names of the output files will be derived from the names +of the input files and the default or specified extension argument. (Optional) + +=item B<-v> + +The name of the currently processed request is printed on standard +error. (Optional) + +=item B<-d> + +Switches on verbose mode for the underlying B<curl> library. You can see +detailed debug messages for the connection. (Optional) + +=item B<-k> private_key.pem + +(HTTPS) In case of certificate-based client authentication over HTTPS +<private_key.pem> must contain the private key of the user. The private key +file can optionally be protected by a passphrase. The B<-c> option must also +be specified. (Optional) + +=item B<-p> key_password + +(HTTPS) Specifies the passphrase for the private key specified by the B<-k> +argument. If this option is omitted and the key is passphrase protected B<tsget> +will ask for it. (Optional) + +=item B<-c> client_cert.pem + +(HTTPS) In case of certificate-based client authentication over HTTPS +<client_cert.pem> must contain the X.509 certificate of the user. The B<-k> +option must also be specified. If this option is not specified no +certificate-based client authentication will take place. (Optional) + +=item B<-C> CA_certs.pem + +(HTTPS) The trusted CA certificate store. The certificate chain of the peer's +certificate must include one of the CA certificates specified in this file. +Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional) + +=item B<-P> CA_path + +(HTTPS) The path containing the trusted CA certificates to verify the peer's +certificate. The directory must be prepared with the B<c_rehash> +OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of +HTTPS. (Optional) + +=item B<-rand> file:file... + +The files containing random data for seeding the random number +generator. Multiple files can be specified, the separator is B<;> for +MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) + +=item B<-g> EGD_socket + +The name of an EGD socket to get random data from. (Optional) + +=item [request]... + +List of files containing B<RFC 3161> DER-encoded time stamp requests. If no +requests are specified only one request will be sent to the server and it will be +read from the standard input. (Optional) + +=back + +=head1 ENVIRONMENT VARIABLES + +The B<TSGET> environment variable can optionally contain default +arguments. The content of this variable is added to the list of command line +arguments. + +=head1 EXAMPLES + +The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid +time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests +and at port 8443 for HTTPS requests, the TSA service is available at the /tsa +absolute path. + +Get a time stamp response for file1.tsq over HTTP, output is written to +file1.tsr: + + tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq + +Get a time stamp response for file1.tsq and file2.tsq over HTTP showing +progress, output is written to file1.reply and file2.reply respectively: + + tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ + file1.tsq file2.tsq + +Create a time stamp request, write it to file3.tsq, send it to the server and +write the response to file3.tsr: + + openssl ts -query -data file3.txt -cert | tee file3.tsq \ + | tsget -h http://tsa.opentsa.org:8080/tsa \ + -o file3.tsr + +Get a time stamp response for file1.tsq over HTTPS without client +authentication: + + tsget -h https://tsa.opentsa.org:8443/tsa \ + -C cacerts.pem file1.tsq + +Get a time stamp response for file1.tsq over HTTPS with certificate-based +client authentication (it will ask for the passphrase if client_key.pem is +protected): + + tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ + -k client_key.pem -c client_cert.pem file1.tsq + +You can shorten the previous command line if you make use of the B<TSGET> +environment variable. The following commands do the same as the previous +example: + + TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ + -k client_key.pem -c client_cert.pem' + export TSGET + tsget file1.tsq + +=head1 SEE ALSO + +=for comment foreign manuals: curl(1) + +L<openssl(1)>, L<ts(1)>, L<curl(1)>, +B<RFC 3161> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/verify.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/verify.pod new file mode 100644 index 000000000..63ba850b9 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/verify.pod @@ -0,0 +1,779 @@ +=pod + +=head1 NAME + +openssl-verify, +verify - Utility to verify certificates + +=head1 SYNOPSIS + +B<openssl> B<verify> +[B<-help>] +[B<-CAfile file>] +[B<-CApath directory>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-allow_proxy_certs>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-CRLfile file>] +[B<-crl_download>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-engine id>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-nameopt option>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-untrusted file>] +[B<-trusted file>] +[B<-use_deltas>] +[B<-verbose>] +[B<-auth_level level>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-show_chain>] +[B<->] +[certificates] + +=head1 DESCRIPTION + +The B<verify> command verifies certificate chains. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-CAfile file> + +A B<file> of trusted certificates. +The file should contain one or more certificates in PEM format. + +=item B<-CApath directory> + +A directory of trusted certificates. The certificates should have names +of the form: hash.0 or have symbolic links to them of this +form ("hash" is the hashed certificate subject name: see the B<-hash> option +of the B<x509> utility). Under Unix the B<c_rehash> script will automatically +create symbolic links to a directory of certificates. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location. + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location. + +=item B<-allow_proxy_certs> + +Allow the verification of proxy certificates. + +=item B<-attime timestamp> + +Perform validation checks using time specified by B<timestamp> and not +current system time. B<timestamp> is the number of seconds since +01.01.1970 (UNIX time). + +=item B<-check_ss_sig> + +Verify the signature on the self-signed root CA. This is disabled by default +because it doesn't add any security. + +=item B<-CRLfile file> + +The B<file> should contain one or more CRLs in PEM format. +This option can be specified more than once to include CRLs from multiple +B<files>. + +=item B<-crl_download> + +Attempt to download CRL information for this certificate. + +=item B<-crl_check> + +Checks end entity certificate validity by attempting to look up a valid CRL. +If a valid CRL cannot be found an error occurs. + +=item B<-crl_check_all> + +Checks the validity of B<all> certificates in the chain by attempting +to look up valid CRLs. + +=item B<-engine id> + +Specifying an engine B<id> will cause L<verify(1)> to attempt to load the +specified engine. +The engine will then be set as the default for all its supported algorithms. +If you want to load certificates or CRLs that require engine support via any of +the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option +must be specified before those options. + +=item B<-explicit_policy> + +Set policy variable require-explicit-policy (see RFC5280). + +=item B<-extended_crl> + +Enable extended CRL features such as indirect CRLs and alternate CRL +signing keys. + +=item B<-ignore_critical> + +Normally if an unhandled critical extension is present which is not +supported by OpenSSL the certificate is rejected (as required by RFC5280). +If this option is set critical extensions are ignored. + +=item B<-inhibit_any> + +Set policy variable inhibit-any-policy (see RFC5280). + +=item B<-inhibit_map> + +Set policy variable inhibit-policy-mapping (see RFC5280). + +=item B<-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<-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)>. + +=item B<X509_V_ERR_EE_KEY_TOO_SMALL> + +EE certificate key too weak. + +=item B<X509_ERR_CA_KEY_TOO_SMALL> + +CA certificate key too weak. + +=item B<X509_ERR_CA_MD_TOO_WEAK> + +CA signature digest algorithm too weak. + +=item B<X509_V_ERR_INVALID_CALL> + +nvalid certificate verification context. + +=item B<X509_V_ERR_STORE_LOOKUP> + +Issuer certificate lookup error. + +=item B<X509_V_ERR_NO_VALID_SCTS> + +Certificate Transparency required, but no valid SCTs found. + +=item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION> + +Proxy subject name violation. + +=item B<X509_V_ERR_OCSP_VERIFY_NEEDED> + +Returned by the verify callback to indicate an OCSP verification is needed. + +=item B<X509_V_ERR_OCSP_VERIFY_FAILED> + +Returned by the verify callback to indicate OCSP verification failed. + +=item B<X509_V_ERR_OCSP_CERT_UNKNOWN> + +Returned by the verify callback to indicate that the certificate is not recognized +by the OCSP responder. + +=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 added in 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-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/version.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/version.pod new file mode 100644 index 000000000..757b55b55 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/version.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +openssl-version, +version - print OpenSSL version information + +=head1 SYNOPSIS + +B<openssl version> +[B<-help>] +[B<-a>] +[B<-v>] +[B<-b>] +[B<-o>] +[B<-f>] +[B<-p>] +[B<-d>] +[B<-e>] + +=head1 DESCRIPTION + +This command is used to print out version information about OpenSSL. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-a> + +All information, this is the same as setting all the other flags. + +=item B<-v> + +The current OpenSSL version. + +=item B<-b> + +The date the current version of OpenSSL was built. + +=item B<-o> + +Option information: various options set when the library was built. + +=item B<-f> + +Compilation flags. + +=item B<-p> + +Platform setting. + +=item B<-d> + +OPENSSLDIR setting. + +=item B<-e> + +ENGINESDIR setting. + +=back + +=head1 NOTES + +The output of B<openssl version -a> would typically be used when sending +in a bug report. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/x509.pod b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/x509.pod new file mode 100644 index 000000000..65cec9dbd --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/doc/man1/x509.pod @@ -0,0 +1,942 @@ +=pod + +=head1 NAME + +openssl-x509, +x509 - Certificate display and signing utility + +=head1 SYNOPSIS + +B<openssl> B<x509> +[B<-help>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-keyform DER|PEM|ENGINE>] +[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 arg>] +[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<-ext extensions>] +[B<-certopt option>] +[B<-C>] +[B<-I<digest>>] +[B<-clrext>] +[B<-extfile filename>] +[B<-extensions section>] +[B<-sigopt nm:v>] +[B<-rand file...>] +[B<-writerand file>] +[B<-engine id>] +[B<-preserve_dates>] + +=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> + +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 default format is PEM. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning and default +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<-I<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<-rand file...> + +A file or files containing random data used to seed 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<-writerand file>] + +Writes random data to the specified I<file> upon exit. +This can be used with a subsequent B<-rand> flag. + +=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. + +=item B<-preserve_dates> + +When signing a certificate, preserve the "notBefore" and "notAfter" dates instead +of adjusting them to current time and duration. Cannot be used with the B<-days> option. + +=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<-ext extensions> + +Prints out the certificate extensions in text form. Extensions are specified +with a comma separated string, e.g., "subjectAltName,subjectKeyIdentifier". +See the L<x509v3_config(5)> manual page for the extension names. + +=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 certificate. + +=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 before version 1.0.0. + +=item B<-issuer_hash_old> + +Outputs the "hash" of the certificate issuer name using the older algorithm +as used by OpenSSL before version 1.0.0. + +=item B<-subject> + +Outputs the subject name. + +=item B<-issuer> + +Outputs the issuer name. + +=item B<-nameopt option> + +Option which determines how the subject or issuer names are displayed. The +B<option> argument can be a single option or multiple options separated by +commas. Alternatively the B<-nameopt> switch may be used more than once to +set multiple options. See the B<NAME OPTIONS> section for more information. + +=item B<-email> + +Outputs the email address(es) if any. + +=item B<-ocsp_uri> + +Outputs the OCSP responder address(es) if any. + +=item B<-startdate> + +Prints out the start date of the certificate, that is the notBefore date. + +=item B<-enddate> + +Prints out the expiry date of the certificate, that is the notAfter date. + +=item B<-dates> + +Prints out the start and expiry dates of a certificate. + +=item B<-checkend arg> + +Checks if the certificate expires within the next B<arg> seconds and exits +non-zero if yes it will expire or zero if not. + +=item B<-fingerprint> + +Calculates and outputs the digest of the DER encoded version of the entire +certificate (see digest options). +This is commonly called a "fingerprint". Because of the nature of message +digests, the fingerprint of a certificate is unique to that certificate and +two certificates with the same fingerprint can be considered to be the same. + +=item B<-C> + +This outputs the certificate in the form of a C source file. + +=back + +=head2 Trust Settings + +A B<trusted certificate> is an ordinary certificate which has several +additional pieces of information attached to it such as the permitted +and prohibited uses of the certificate and an "alias". + +Normally when a certificate is being verified at least one certificate +must be "trusted". By default a trusted certificate must be stored +locally and must be a root CA: any certificate chain ending in this CA +is then usable for any purpose. + +Trust settings currently are only used with a root CA. They allow a finer +control over the purposes the root CA can be used for. For example a CA +may be trusted for SSL client but not SSL server use. + +See the description of the B<verify> utility for more information on the +meaning of trust settings. + +Future versions of OpenSSL will recognize trust settings on any +certificate: not just root CAs. + + +=over 4 + +=item B<-trustout> + +This causes B<x509> to output a B<trusted> certificate. An ordinary +or trusted certificate can be input but by default an ordinary +certificate is output and any trust settings are discarded. With the +B<-trustout> option a trusted certificate is output. A trusted +certificate is automatically output if any trust settings are modified. + +=item B<-setalias arg> + +Sets the alias of the certificate. This will allow the certificate +to be referred to using a nickname for example "Steve's Certificate". + +=item B<-alias> + +Outputs the certificate alias, if any. + +=item B<-clrtrust> + +Clears all the permitted or trusted uses of the certificate. + +=item B<-clrreject> + +Clears all the prohibited or rejected uses of the certificate. + +=item B<-addtrust arg> + +Adds a trusted certificate use. +Any object name can be used here but currently only B<clientAuth> (SSL client +use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and +B<anyExtendedKeyUsage> are used. +As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or +enables all purposes when trusted. +Other OpenSSL applications may define additional uses. + +=item B<-addreject arg> + +Adds a prohibited use. It accepts the same values as the B<-addtrust> +option. + +=item B<-purpose> + +This option performs tests on the certificate extensions and outputs +the results. For a more complete description see the B<CERTIFICATE +EXTENSIONS> section. + +=back + +=head2 Signing Options + +The B<x509> utility can be used to sign certificates and requests: it +can thus behave like a "mini CA". + +=over 4 + +=item B<-signkey arg> + +This option causes the input file to be self signed using the supplied +private key or engine. The private key's format is specified with the +B<-keyform> option. + +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<-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 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|ENGINE> + +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. Cannot be used with the B<-preserve_dates> option. + +=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 consists 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 "Subject Alternative Name" extension of a certificate: + + openssl x509 -in cert.pem -noout -ext subjectAltName + +Display more extensions of a certificate: + + openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType + +Display the certificate serial number: + + openssl x509 -in cert.pem -noout -serial + +Display the certificate subject name: + + openssl x509 -in cert.pem -noout -subject + +Display the certificate subject name in RFC2253 form: + + openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 + +Display the certificate subject name in oneline form on a terminal +supporting UTF8: + + openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb + +Display the certificate SHA1 fingerprint: + + openssl x509 -sha1 -in cert.pem -noout -fingerprint + +Convert a certificate from PEM to DER format: + + openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER + +Convert a certificate to a certificate request: + + openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem + +Convert a certificate request into a self signed certificate using +extensions for a CA: + + openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \ + -signkey key.pem -out cacert.pem + +Sign a certificate request using the CA certificate above and add user +certificate extensions: + + openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \ + -CA cacert.pem -CAkey key.pem -CAcreateserial + + +Set a certificate to be trusted for SSL client use and change set its alias to +"Steve's Class 1 CA" + + openssl x509 -in cert.pem -addtrust clientAuth \ + -setalias "Steve's Class 1 CA" -out trust.pem + +=head1 NOTES + +The PEM format uses the header and footer lines: + + -----BEGIN CERTIFICATE----- + -----END CERTIFICATE----- + +it will also handle files containing: + + -----BEGIN X509 CERTIFICATE----- + -----END X509 CERTIFICATE----- + +Trusted certificates have the lines + + -----BEGIN TRUSTED CERTIFICATE----- + -----END TRUSTED CERTIFICATE----- + +The conversion to UTF8 format used with the name options assumes that +T61Strings use the ISO8859-1 character set. This is wrong but Netscape +and MSIE do this as do many certificates. So although this is incorrect +it is more likely to display the majority of certificates correctly. + +The B<-email> option searches the subject name and the subject alternative +name extension. Only unique email addresses will be printed out: it will +not print the same address more than once. + +=head1 CERTIFICATE EXTENSIONS + +The B<-purpose> option checks the certificate extensions and determines +what the certificate can be used for. The actual checks done are rather +complex and include various hacks and workarounds to handle broken +certificates and software. + +The same code is used when verifying untrusted certificates in chains +so this section is useful if a chain is rejected by the verify code. + +The basicConstraints extension CA flag is used to determine whether the +certificate can be used as a CA. If the CA flag is true then it is a CA, +if the CA flag is false then it is not a CA. B<All> CAs should have the +CA flag set to true. + +If the basicConstraints extension is absent then the certificate is +considered to be a "possible CA" other extensions are checked according +to the intended use of the certificate. A warning is given in this case +because the certificate should really not be regarded as a CA: however +it is allowed to be a CA to work around some broken software. + +If the certificate is a V1 certificate (and thus has no extensions) and +it is self signed it is also assumed to be a CA but a warning is again +given: this is to work around the problem of Verisign roots which are V1 +self signed certificates. + +If the keyUsage extension is present then additional restraints are +made on the uses of the certificate. A CA certificate B<must> have the +keyCertSign bit set if the keyUsage extension is present. + +The extended key usage extension places additional restrictions on the +certificate uses. If this extension is present (whether critical or not) +the key can only be used for the purposes specified. + +A complete description of each test is given below. The comments about +basicConstraints and keyUsage and V1 certificates above apply to B<all> +CA certificates. + + +=over 4 + +=item B<SSL Client> + +The extended key usage extension must be absent or include the "web client +authentication" OID. keyUsage must be absent or it must have the +digitalSignature bit set. Netscape certificate type must be absent or it must +have the SSL client bit set. + +=item B<SSL Client CA> + +The extended key usage extension must be absent or include the "web client +authentication" OID. Netscape certificate type must be absent or it must have +the SSL CA bit set: this is used as a work around if the basicConstraints +extension is absent. + +=item B<SSL Server> + +The extended key usage extension must be absent or include the "web server +authentication" and/or one of the SGC OIDs. keyUsage must be absent or it +must have the digitalSignature, the keyEncipherment set or both bits set. +Netscape certificate type must be absent or have the SSL server bit set. + +=item B<SSL Server CA> + +The extended key usage extension must be absent or include the "web server +authentication" and/or one of the SGC OIDs. Netscape certificate type must +be absent or the SSL CA bit must be set: this is used as a work around if the +basicConstraints extension is absent. + +=item B<Netscape SSL Server> + +For Netscape SSL clients to connect to an SSL server it must have the +keyEncipherment bit set if the keyUsage extension is present. This isn't +always valid because some cipher suites use the key for digital signing. +Otherwise it is the same as a normal SSL server. + +=item B<Common S/MIME Client Tests> + +The extended key usage extension must be absent or include the "email +protection" OID. Netscape certificate type must be absent or should have the +S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type +then the SSL client bit is tolerated as an alternative but a warning is shown: +this is because some Verisign certificates don't set the S/MIME bit. + +=item B<S/MIME Signing> + +In addition to the common S/MIME client tests the digitalSignature bit or +the nonRepudiation 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-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |