diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2017-05-02 16:40:01 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2017-05-02 16:40:01 (GMT) |
| commit | 0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692 (patch) | |
| tree | 3d0871d05cfd11f60b86829d2d93704034dad24e /openssl/doc/apps | |
| parent | e9abe0dba896d2b0fc22301588336e89ff246ba7 (diff) | |
| download | blt-0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692.zip blt-0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692.tar.gz blt-0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692.tar.bz2 | |
reinstall
Diffstat (limited to 'openssl/doc/apps')
47 files changed, 0 insertions, 12584 deletions
diff --git a/openssl/doc/apps/CA.pl.pod b/openssl/doc/apps/CA.pl.pod deleted file mode 100644 index d326101..0000000 --- a/openssl/doc/apps/CA.pl.pod +++ /dev/null @@ -1,179 +0,0 @@ - -=pod - -=head1 NAME - -CA.pl - friendlier interface for OpenSSL certificate programs - -=head1 SYNOPSIS - -B<CA.pl> -[B<-?>] -[B<-h>] -[B<-help>] -[B<-newcert>] -[B<-newreq>] -[B<-newreq-nodes>] -[B<-newca>] -[B<-xsign>] -[B<-sign>] -[B<-signreq>] -[B<-signcert>] -[B<-verify>] -[B<files>] - -=head1 DESCRIPTION - -The B<CA.pl> script is a perl script that supplies the relevant command line -arguments to the B<openssl> command for some common certificate operations. -It is intended to simplify the process of certificate creation and management -by the use of some simple options. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<?>, B<-h>, B<-help> - -prints a usage message. - -=item B<-newcert> - -creates a new self signed certificate. The private key is written to the file -"newkey.pem" and the request written to the file "newreq.pem". - -=item B<-newreq> - -creates a new certificate request. The private key is written to the file -"newkey.pem" and the request written to the file "newreq.pem". - -=item B<-newreq-nodes> - -is like B<-newreq> except that the private key will not be encrypted. - -=item B<-newca> - -creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert> -and B<-xsign> options). The user is prompted to enter the filename of the CA -certificates (which should also contain the private key) or by hitting ENTER -details of the CA will be prompted for. The relevant files and directories -are created in a directory called "demoCA" in the current directory. - -=item B<-pkcs12> - -create a PKCS#12 file containing the user certificate, private key and CA -certificate. It expects the user certificate and private key to be in the -file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem, -it creates a file "newcert.p12". This command can thus be called after the -B<-sign> option. The PKCS#12 file can be imported directly into a browser. -If there is an additional argument on the command line it will be used as the -"friendly name" for the certificate (which is typically displayed in the browser -list box), otherwise the name "My Certificate" is used. - -=item B<-sign>, B<-signreq>, B<-xsign> - -calls the B<ca> program to sign a certificate request. It expects the request -to be in the file "newreq.pem". The new certificate is written to the file -"newcert.pem" except in the case of the B<-xsign> option when it is written -to standard output. - - -=item B<-signCA> - -this option is the same as the B<-signreq> option except it uses the configuration -file section B<v3_ca> and so makes the signed request a valid CA certificate. This -is useful when creating intermediate CA from a root CA. - -=item B<-signcert> - -this option is the same as B<-sign> except it expects a self signed certificate -to be present in the file "newreq.pem". - -=item B<-verify> - -verifies certificates against the CA certificate for "demoCA". If no certificates -are specified on the command line it tries to verify the file "newcert.pem". - -=item B<files> - -one or more optional certificate file names for use with the B<-verify> command. - -=back - -=head1 EXAMPLES - -Create a CA hierarchy: - - CA.pl -newca - -Complete certificate creation example: create a CA, create a request, sign -the request and finally create a PKCS#12 file containing it. - - CA.pl -newca - CA.pl -newreq - CA.pl -signreq - CA.pl -pkcs12 "My Test Certificate" - -=head1 DSA CERTIFICATES - -Although the B<CA.pl> creates RSA CAs and requests it is still possible to -use it with DSA certificates and requests using the L<req(1)|req(1)> command -directly. The following example shows the steps that would typically be taken. - -Create some DSA parameters: - - openssl dsaparam -out dsap.pem 1024 - -Create a DSA CA certificate and private key: - - openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem - -Create the CA directories and files: - - CA.pl -newca - -enter cacert.pem when prompted for the CA file name. - -Create a DSA certificate request and private key (a different set of parameters -can optionally be created first): - - openssl req -out newreq.pem -newkey dsa:dsap.pem - -Sign the request: - - CA.pl -signreq - -=head1 NOTES - -Most of the filenames mentioned can be modified by editing the B<CA.pl> script. - -If the demoCA directory already exists then the B<-newca> command will not -overwrite it and will do nothing. This can happen if a previous call using -the B<-newca> option terminated abnormally. To get the correct behaviour -delete the demoCA directory if it already exists. - -Under some environments it may not be possible to run the B<CA.pl> script -directly (for example Win32) and the default configuration file location may -be wrong. In this case the command: - - perl -S CA.pl - -can be used and the B<OPENSSL_CONF> environment variable changed to point to -the correct path of the configuration file "openssl.cnf". - -The script is intended as a simple front end for the B<openssl> program for use -by a beginner. Its behaviour isn't always what is wanted. For more control over the -behaviour of the certificate commands call the B<openssl> command directly. - -=head1 ENVIRONMENT VARIABLES - -The variable B<OPENSSL_CONF> if defined allows an alternative configuration -file location to be specified, it should contain the full path to the -configuration file, not just its directory. - -=head1 SEE ALSO - -L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<req(1)|req(1)>, L<pkcs12(1)|pkcs12(1)>, -L<config(5)|config(5)> - -=cut diff --git a/openssl/doc/apps/asn1parse.pod b/openssl/doc/apps/asn1parse.pod deleted file mode 100644 index 76a765d..0000000 --- a/openssl/doc/apps/asn1parse.pod +++ /dev/null @@ -1,185 +0,0 @@ -=pod - -=head1 NAME - -asn1parse - ASN.1 parsing tool - -=head1 SYNOPSIS - -B<openssl> B<asn1parse> -[B<-inform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-offset number>] -[B<-length number>] -[B<-i>] -[B<-oid filename>] -[B<-dump>] -[B<-dlimit num>] -[B<-strparse offset>] -[B<-genstr string>] -[B<-genconf file>] - -=head1 DESCRIPTION - -The B<asn1parse> command is a diagnostic utility that can parse ASN.1 -structures. It can also be used to extract data from ASN.1 formatted data. - -=head1 OPTIONS - -=over 4 - -=item B<-inform> B<DER|PEM> - -the input format. B<DER> is binary format and B<PEM> (the default) is base64 -encoded. - -=item B<-in filename> - -the input file, default is standard input - -=item B<-out filename> - -output file to place the DER encoded data into. If this -option is not present then no data will be output. This is most useful when -combined with the B<-strparse> option. - -=item B<-noout> - -don't output the parsed version of the input file. - -=item B<-offset number> - -starting offset to begin parsing, default is start of file. - -=item B<-length number> - -number of bytes to parse, default is until end of file. - -=item B<-i> - -indents the output according to the "depth" of the structures. - -=item B<-oid filename> - -a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this -file is described in the NOTES section below. - -=item B<-dump> - -dump unknown data in hex format. - -=item B<-dlimit num> - -like B<-dump>, but only the first B<num> bytes are output. - -=item B<-strparse offset> - -parse the contents octets of the ASN.1 object starting at B<offset>. This -option can be used multiple times to "drill down" into a nested structure. - -=item B<-genstr string>, B<-genconf file> - -generate encoded data based on B<string>, B<file> or both using -L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. If B<file> only is -present then the string is obtained from the default section using the name -B<asn1>. The encoded data is passed through the ASN1 parser and printed out as -though it came from a file, the contents can thus be examined and written to a -file using the B<out> option. - -=back - -=head2 OUTPUT - -The output will typically contain lines like this: - - 0:d=0 hl=4 l= 681 cons: SEQUENCE - -..... - - 229:d=3 hl=3 l= 141 prim: BIT STRING - 373:d=2 hl=3 l= 162 cons: cont [ 3 ] - 376:d=3 hl=3 l= 159 cons: SEQUENCE - 379:d=4 hl=2 l= 29 cons: SEQUENCE - 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier - 386:d=5 hl=2 l= 22 prim: OCTET STRING - 410:d=4 hl=2 l= 112 cons: SEQUENCE - 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier - 417:d=5 hl=2 l= 105 prim: OCTET STRING - 524:d=4 hl=2 l= 12 cons: SEQUENCE - -..... - -This example is part of a self signed certificate. Each line starts with the -offset in decimal. B<d=XX> specifies the current depth. The depth is increased -within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length -(tag and length octets) of the current type. B<l=XX> gives the length of -the contents octets. - -The B<-i> option can be used to make the output more readable. - -Some knowledge of the ASN.1 structure is needed to interpret the output. - -In this example the BIT STRING at offset 229 is the certificate public key. -The contents octets of this will contain the public key information. This can -be examined using the option B<-strparse 229> to yield: - - 0:d=0 hl=3 l= 137 cons: SEQUENCE - 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897 - 135:d=1 hl=2 l= 3 prim: INTEGER :010001 - -=head1 NOTES - -If an OID is not part of OpenSSL's internal table it will be represented in -numerical form (for example 1.2.3.4). The file passed to the B<-oid> option -allows additional OIDs to be included. Each line consists of three columns, -the first column is the OID in numerical format and should be followed by white -space. The second column is the "short name" which is a single word followed -by white space. The final column is the rest of the line and is the -"long name". B<asn1parse> displays the long name. Example: - -C<1.2.3.4 shortName A long name> - -=head1 EXAMPLES - -Parse a file: - - openssl asn1parse -in file.pem - -Parse a DER file: - - openssl asn1parse -inform DER -in file.der - -Generate a simple UTF8String: - - openssl asn1parse -genstr 'UTF8:Hello World' - -Generate and write out a UTF8String, don't print parsed output: - - openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der - -Generate using a config file: - - openssl asn1parse -genconf asn1.cnf -noout -out asn1.der - -Example config file: - - asn1=SEQUENCE:seq_sect - - [seq_sect] - - field1=BOOL:TRUE - field2=EXP:0, UTF8:some random string - - -=head1 BUGS - -There should be options to change the format of output lines. The output of some -ASN.1 types is not well handled (if at all). - -=head1 SEE ALSO - -L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> - -=cut diff --git a/openssl/doc/apps/c_rehash.pod b/openssl/doc/apps/c_rehash.pod deleted file mode 100644 index ccce29e..0000000 --- a/openssl/doc/apps/c_rehash.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=for comment -Original text by James Westby, contributed under the OpenSSL license. - -=head1 NAME - -c_rehash - Create symbolic links to files named by the hash values - -=head1 SYNOPSIS - -B<c_rehash> -B<[-old]> -B<[-h]> -B<[-n]> -B<[-v]> -[ I<directory>...] - -=head1 DESCRIPTION - -B<c_rehash> scans directories and calculates a hash value of each -C<.pem>, C<.crt>, C<.cer>, or C<.crl> -file in the specified directory list and creates symbolic links -for each file, where the name of the link is the hash value. -(If the platform does not support symbolic links, a copy is made.) -This utility is useful as many programs that use OpenSSL require -directories to be set up like this in order to find certificates. - -If any directories are named on the command line, then those are -processed in turn. If not, then the B<SSL_CERT_DIR> environment variable -is consulted; this shold be a colon-separated list of directories, -like the Unix B<PATH> variable. -If that is not set then the default directory (installation-specific -but often B</usr/local/ssl/certs>) is processed. - -In order for a directory to be processed, the user must have write -permissions on that directory, otherwise it will be skipped. -The links created are of the form C<HHHHHHHH.D>, where each B<H> -is a hexadecimal character and B<D> is a single decimal digit. -When processing a directory, B<c_rehash> will first remove all links -that have a name in that syntax. If you have links in that format -used for other purposes, they will be removed. -To skip the removal step, use the B<-n> flag. -Hashes for CRL's look similar except the letter B<r> appears after -the period, like this: C<HHHHHHHH.rD>. - -Multiple objects may have the same hash; they will be indicated by -incrementing the B<D> value. Duplicates are found by comparing the -full SHA-1 fingerprint. A warning will be displayed if a duplicate -is found. - -A warning will also be displayed if there are files that -cannot be parsed as either a certificate or a CRL. - -The program uses the B<openssl> program to compute the hashes and -fingerprints. If not found in the user's B<PATH>, then set the -B<OPENSSL> environment variable to the full pathname. -Any program can be used, it will be invoked as follows for either -a certificate or CRL: - - $OPENSSL x509 -hash -fingerprint -noout -in FILENAME - $OPENSSL crl -hash -fingerprint -noout -in FILENAME - -where B<FILENAME> is the filename. It must output the hash of the -file on the first line, and the fingerprint on the second, -optionally prefixed with some text and an equals sign. - -=head1 OPTIONS - -=over 4 - -=item B<-old> - -Use old-style hashing (MD5, as opposed to SHA-1) for generating -links for releases before 1.0.0. Note that current versions will -not use the old style. - -=item B<-h> - -Display a brief usage message. - -=item B<-n> - -Do not remove existing links. -This is needed when keeping new and old-style links in the same directory. - -=item B<-v> - -Print messages about old links removed and new links created. -By default, B<c_rehash> only lists each directory as it is processed. - -=back - -=head1 ENVIRONMENT - -=over - -=item B<OPENSSL> - -The path to an executable to use to generate hashes and -fingerprints (see above). - -=item B<SSL_CERT_DIR> - -Colon separated list of directories to operate on. -Ignored if directories are listed on the command line. - -=back - -=head1 SEE ALSO - -L<openssl(1)|openssl(1)>, -L<crl(1)|crl(1)>. -L<x509(1)|x509(1)>. diff --git a/openssl/doc/apps/ca.pod b/openssl/doc/apps/ca.pod deleted file mode 100644 index c90e648..0000000 --- a/openssl/doc/apps/ca.pod +++ /dev/null @@ -1,696 +0,0 @@ - -=pod - -=head1 NAME - -ca - sample minimal CA application - -=head1 SYNOPSIS - -B<openssl> B<ca> -[B<-verbose>] -[B<-config filename>] -[B<-name section>] -[B<-gencrl>] -[B<-revoke file>] -[B<-status serial>] -[B<-updatedb>] -[B<-crl_reason reason>] -[B<-crl_hold instruction>] -[B<-crl_compromise time>] -[B<-crl_CA_compromise time>] -[B<-crldays days>] -[B<-crlhours hours>] -[B<-crlexts section>] -[B<-startdate date>] -[B<-enddate date>] -[B<-days arg>] -[B<-md arg>] -[B<-policy arg>] -[B<-keyfile arg>] -[B<-keyform PEM|DER>] -[B<-key arg>] -[B<-passin arg>] -[B<-cert file>] -[B<-selfsign>] -[B<-in file>] -[B<-out file>] -[B<-notext>] -[B<-outdir dir>] -[B<-infiles>] -[B<-spkac file>] -[B<-ss_cert file>] -[B<-preserveDN>] -[B<-noemailDN>] -[B<-batch>] -[B<-msie_hack>] -[B<-extensions section>] -[B<-extfile section>] -[B<-engine id>] -[B<-subj arg>] -[B<-utf8>] -[B<-multivalue-rdn>] - -=head1 DESCRIPTION - -The B<ca> command is a minimal CA application. It can be used -to sign certificate requests in a variety of forms and generate -CRLs it also maintains a text database of issued certificates -and their status. - -The options descriptions will be divided into each purpose. - -=head1 CA OPTIONS - -=over 4 - -=item B<-config filename> - -specifies the configuration file to use. - -=item B<-name section> - -specifies the configuration file section to use (overrides -B<default_ca> in the B<ca> section). - -=item B<-in filename> - -an input filename containing a single certificate request to be -signed by the CA. - -=item B<-ss_cert filename> - -a single self signed certificate to be signed by the CA. - -=item B<-spkac filename> - -a file containing a single Netscape signed public key and challenge -and additional field values to be signed by the CA. See the B<SPKAC FORMAT> -section for information on the required input and output format. - -=item B<-infiles> - -if present this should be the last option, all subsequent arguments -are assumed to the the names of files containing certificate requests. - -=item B<-out filename> - -the output file to output certificates to. The default is standard -output. The certificate details will also be printed out to this -file in PEM format (except that B<-spkac> outputs DER format). - -=item B<-outdir directory> - -the directory to output certificates to. The certificate will be -written to a filename consisting of the serial number in hex with -".pem" appended. - -=item B<-cert> - -the CA certificate file. - -=item B<-keyfile filename> - -the private key to sign requests with. - -=item B<-keyform PEM|DER> - -the format of the data in the private key file. -The default is PEM. - -=item B<-key password> - -the password used to encrypt the private key. Since on some -systems the command line arguments are visible (e.g. Unix with -the 'ps' utility) this option should be used with caution. - -=item B<-selfsign> - -indicates the issued certificates are to be signed with the key -the certificate requests were signed with (given with B<-keyfile>). -Cerificate requests signed with a different key are ignored. If -B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is -ignored. - -A consequence of using B<-selfsign> is that the self-signed -certificate appears among the entries in the certificate database -(see the configuration option B<database>), and uses the same -serial number counter as all other certificates sign with the -self-signed certificate. - -=item B<-passin arg> - -the key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-verbose> - -this prints extra details about the operations being performed. - -=item B<-notext> - -don't output the text form of a certificate to the output file. - -=item B<-startdate date> - -this allows the start date to be explicitly set. The format of the -date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). - -=item B<-enddate date> - -this allows the expiry date to be explicitly set. The format of the -date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). - -=item B<-days arg> - -the number of days to certify the certificate for. - -=item B<-md alg> - -the message digest to use. Possible values include md5, sha1 and mdc2. -This option also applies to CRLs. - -=item B<-policy arg> - -this option defines the CA "policy" to use. This is a section in -the configuration file which decides which fields should be mandatory -or match the CA certificate. Check out the B<POLICY FORMAT> section -for more information. - -=item B<-msie_hack> - -this is a legacy option to make B<ca> work with very old versions of -the IE certificate enrollment control "certenr3". It used UniversalStrings -for almost everything. Since the old control has various security bugs -its use is strongly discouraged. The newer control "Xenroll" does not -need this option. - -=item B<-preserveDN> - -Normally the DN order of a certificate is the same as the order of the -fields in the relevant policy section. When this option is set the order -is the same as the request. This is largely for compatibility with the -older IE enrollment control which would only accept certificates if their -DNs match the order of the request. This is not needed for Xenroll. - -=item B<-noemailDN> - -The DN of a certificate can contain the EMAIL field if present in the -request DN, however it is good policy just having the e-mail set into -the altName extension of the certificate. When this option is set the -EMAIL field is removed from the certificate' subject and set only in -the, eventually present, extensions. The B<email_in_dn> keyword can be -used in the configuration file to enable this behaviour. - -=item B<-batch> - -this sets the batch mode. In this mode no questions will be asked -and all certificates will be certified automatically. - -=item B<-extensions section> - -the section of the configuration file containing certificate extensions -to be added when a certificate is issued (defaults to B<x509_extensions> -unless the B<-extfile> option is used). If no extension section is -present then, a V1 certificate is created. If the extension section -is present (even if it is empty), then a V3 certificate is created. See the:w -L<x509v3_config(5)|x509v3_config(5)> manual page for details of the -extension section format. - -=item B<-extfile file> - -an additional configuration file to read certificate extensions from -(using the default section unless the B<-extensions> option is also -used). - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<ca> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=item B<-subj arg> - -supersedes subject name given in the request. -The arg must be formatted as I</type0=value0/type1=value1/type2=...>, -characters may be escaped by \ (backslash), no spaces are skipped. - -=item B<-utf8> - -this option causes field values to be interpreted as UTF8 strings, by -default they are interpreted as ASCII. This means that the field -values, whether prompted from a terminal or obtained from a -configuration file, must be valid UTF8 strings. - -=item B<-multivalue-rdn> - -this option causes the -subj argument to be interpretedt with full -support for multivalued RDNs. Example: - -I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> - -If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. - -=back - -=head1 CRL OPTIONS - -=over 4 - -=item B<-gencrl> - -this option generates a CRL based on information in the index file. - -=item B<-crldays num> - -the number of days before the next CRL is due. That is the days from -now to place in the CRL nextUpdate field. - -=item B<-crlhours num> - -the number of hours before the next CRL is due. - -=item B<-revoke filename> - -a filename containing a certificate to revoke. - -=item B<-status serial> - -displays the revocation status of the certificate with the specified -serial number and exits. - -=item B<-updatedb> - -Updates the database index to purge expired certificates. - -=item B<-crl_reason reason> - -revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>, -B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>, -B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case -insensitive. Setting any revocation reason will make the CRL v2. - -In practive B<removeFromCRL> is not particularly useful because it is only used -in delta CRLs which are not currently implemented. - -=item B<-crl_hold instruction> - -This sets the CRL revocation reason code to B<certificateHold> and the hold -instruction to B<instruction> which must be an OID. Although any OID can be -used only B<holdInstructionNone> (the use of which is discouraged by RFC2459) -B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used. - -=item B<-crl_compromise time> - -This sets the revocation reason to B<keyCompromise> and the compromise time to -B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>. - -=item B<-crl_CA_compromise time> - -This is the same as B<crl_compromise> except the revocation reason is set to -B<CACompromise>. - -=item B<-crlexts section> - -the section of the configuration file containing CRL extensions to -include. If no CRL extension section is present then a V1 CRL is -created, if the CRL extension section is present (even if it is -empty) then a V2 CRL is created. The CRL extensions specified are -CRL extensions and B<not> CRL entry extensions. It should be noted -that some software (for example Netscape) can't handle V2 CRLs. See -L<x509v3_config(5)|x509v3_config(5)> manual page for details of the -extension section format. - -=back - -=head1 CONFIGURATION FILE OPTIONS - -The section of the configuration file containing options for B<ca> -is found as follows: If the B<-name> command line option is used, -then it names the section to be used. Otherwise the section to -be used must be named in the B<default_ca> option of the B<ca> section -of the configuration file (or in the default section of the -configuration file). Besides B<default_ca>, the following options are -read directly from the B<ca> section: - RANDFILE - preserve - msie_hack -With the exception of B<RANDFILE>, this is probably a bug and may -change in future releases. - -Many of the configuration file options are identical to command line -options. Where the option is present in the configuration file -and the command line the command line value is used. Where an -option is described as mandatory then it must be present in -the configuration file or the command line equivalent (if -any) used. - -=over 4 - -=item B<oid_file> - -This specifies a file containing additional B<OBJECT IDENTIFIERS>. -Each line of the file should consist of the numerical form of the -object identifier followed by white space then the short name followed -by white space and finally the long name. - -=item B<oid_section> - -This specifies a section in the configuration file containing extra -object identifiers. Each line should consist of the short name of the -object identifier followed by B<=> and the numerical form. The short -and long names are the same when this option is used. - -=item B<new_certs_dir> - -the same as the B<-outdir> command line option. It specifies -the directory where new certificates will be placed. Mandatory. - -=item B<certificate> - -the same as B<-cert>. It gives the file containing the CA -certificate. Mandatory. - -=item B<private_key> - -same as the B<-keyfile> option. The file containing the -CA private key. Mandatory. - -=item B<RANDFILE> - -a file used to read and write random number seed information, or -an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). - -=item B<default_days> - -the same as the B<-days> option. The number of days to certify -a certificate for. - -=item B<default_startdate> - -the same as the B<-startdate> option. The start date to certify -a certificate for. If not set the current time is used. - -=item B<default_enddate> - -the same as the B<-enddate> option. Either this option or -B<default_days> (or the command line equivalents) must be -present. - -=item B<default_crl_hours default_crl_days> - -the same as the B<-crlhours> and the B<-crldays> options. These -will only be used if neither command line option is present. At -least one of these must be present to generate a CRL. - -=item B<default_md> - -the same as the B<-md> option. The message digest to use. Mandatory. - -=item B<database> - -the text database file to use. Mandatory. This file must be present -though initially it will be empty. - -=item B<unique_subject> - -if the value B<yes> is given, the valid certificate entries in the -database must have unique subjects. if the value B<no> is given, -several valid certificate entries may have the exact same subject. -The default value is B<yes>, to be compatible with older (pre 0.9.8) -versions of OpenSSL. However, to make CA certificate roll-over easier, -it's recommended to use the value B<no>, especially if combined with -the B<-selfsign> command line option. - -=item B<serial> - -a text file containing the next serial number to use in hex. Mandatory. -This file must be present and contain a valid serial number. - -=item B<crlnumber> - -a text file containing the next CRL number to use in hex. The crl number -will be inserted in the CRLs only if this file exists. If this file is -present, it must contain a valid CRL number. - -=item B<x509_extensions> - -the same as B<-extensions>. - -=item B<crl_extensions> - -the same as B<-crlexts>. - -=item B<preserve> - -the same as B<-preserveDN> - -=item B<email_in_dn> - -the same as B<-noemailDN>. If you want the EMAIL field to be removed -from the DN of the certificate simply set this to 'no'. If not present -the default is to allow for the EMAIL filed in the certificate's DN. - -=item B<msie_hack> - -the same as B<-msie_hack> - -=item B<policy> - -the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section -for more information. - -=item B<name_opt>, B<cert_opt> - -these options allow the format used to display the certificate details -when asking the user to confirm signing. All the options supported by -the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used -here, except the B<no_signame> and B<no_sigdump> are permanently set -and cannot be disabled (this is because the certificate signature cannot -be displayed because the certificate has not been signed at this point). - -For convenience the values B<ca_default> are accepted by both to produce -a reasonable output. - -If neither option is present the format used in earlier versions of -OpenSSL is used. Use of the old format is B<strongly> discouraged because -it only displays fields mentioned in the B<policy> section, mishandles -multicharacter string types and does not display extensions. - -=item B<copy_extensions> - -determines how extensions in certificate requests should be handled. -If set to B<none> or this option is not present then extensions are -ignored and not copied to the certificate. If set to B<copy> then any -extensions present in the request that are not already present are copied -to the certificate. If set to B<copyall> then all extensions in the -request are copied to the certificate: if the extension is already present -in the certificate it is deleted first. See the B<WARNINGS> section before -using this option. - -The main use of this option is to allow a certificate request to supply -values for certain extensions such as subjectAltName. - -=back - -=head1 POLICY FORMAT - -The policy section consists of a set of variables corresponding to -certificate DN fields. If the value is "match" then the field value -must match the same field in the CA certificate. If the value is -"supplied" then it must be present. If the value is "optional" then -it may be present. Any fields not mentioned in the policy section -are silently deleted, unless the B<-preserveDN> option is set but -this can be regarded more of a quirk than intended behaviour. - -=head1 SPKAC FORMAT - -The input to the B<-spkac> command line option is a Netscape -signed public key and challenge. This will usually come from -the B<KEYGEN> tag in an HTML form to create a new private key. -It is however possible to create SPKACs using the B<spkac> utility. - -The file should contain the variable SPKAC set to the value of -the SPKAC and also the required DN components as name value pairs. -If you need to include the same component twice then it can be -preceded by a number and a '.'. - -When processing SPKAC format, the output is DER if the B<-out> -flag is used, but PEM format if sending to stdout or the B<-outdir> -flag is used. - -=head1 EXAMPLES - -Note: these examples assume that the B<ca> directory structure is -already set up and the relevant files already exist. This usually -involves creating a CA certificate and private key with B<req>, a -serial number file and an empty index file and placing them in -the relevant directories. - -To use the sample configuration file below the directories demoCA, -demoCA/private and demoCA/newcerts would be created. The CA -certificate would be copied to demoCA/cacert.pem and its private -key to demoCA/private/cakey.pem. A file demoCA/serial would be -created containing for example "01" and the empty index file -demoCA/index.txt. - - -Sign a certificate request: - - openssl ca -in req.pem -out newcert.pem - -Sign a certificate request, using CA extensions: - - openssl ca -in req.pem -extensions v3_ca -out newcert.pem - -Generate a CRL - - openssl ca -gencrl -out crl.pem - -Sign several requests: - - openssl ca -infiles req1.pem req2.pem req3.pem - -Certify a Netscape SPKAC: - - openssl ca -spkac spkac.txt - -A sample SPKAC file (the SPKAC line has been truncated for clarity): - - SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 - CN=Steve Test - emailAddress=steve@openssl.org - 0.OU=OpenSSL Group - 1.OU=Another Group - -A sample configuration file with the relevant sections for B<ca>: - - [ ca ] - default_ca = CA_default # The default ca section - - [ CA_default ] - - dir = ./demoCA # top dir - database = $dir/index.txt # index file. - new_certs_dir = $dir/newcerts # new certs dir - - certificate = $dir/cacert.pem # The CA cert - serial = $dir/serial # serial no file - private_key = $dir/private/cakey.pem# CA private key - RANDFILE = $dir/private/.rand # random number file - - default_days = 365 # how long to certify for - default_crl_days= 30 # how long before next CRL - default_md = md5 # md to use - - policy = policy_any # default policy - email_in_dn = no # Don't add the email into cert DN - - name_opt = ca_default # Subject name display option - cert_opt = ca_default # Certificate display option - copy_extensions = none # Don't copy extensions from request - - [ policy_any ] - countryName = supplied - stateOrProvinceName = optional - organizationName = optional - organizationalUnitName = optional - commonName = supplied - emailAddress = optional - -=head1 FILES - -Note: the location of all files can change either by compile time options, -configuration file entries, environment variables or command line options. -The values below reflect the default values. - - /usr/local/ssl/lib/openssl.cnf - master configuration file - ./demoCA - main CA directory - ./demoCA/cacert.pem - CA certificate - ./demoCA/private/cakey.pem - CA private key - ./demoCA/serial - CA serial number file - ./demoCA/serial.old - CA serial number backup file - ./demoCA/index.txt - CA text database file - ./demoCA/index.txt.old - CA text database backup file - ./demoCA/certs - certificate output file - ./demoCA/.rnd - CA random seed information - -=head1 ENVIRONMENT VARIABLES - -B<OPENSSL_CONF> reflects the location of master configuration file it can -be overridden by the B<-config> command line option. - -=head1 RESTRICTIONS - -The text database index file is a critical part of the process and -if corrupted it can be difficult to fix. It is theoretically possible -to rebuild the index file from all the issued certificates and a current -CRL: however there is no option to do this. - -V2 CRL features like delta CRLs are not currently supported. - -Although several requests can be input and handled at once it is only -possible to include one SPKAC or self signed certificate. - -=head1 BUGS - -The use of an in memory text database can cause problems when large -numbers of certificates are present because, as the name implies -the database has to be kept in memory. - -The B<ca> command really needs rewriting or the required functionality -exposed at either a command or interface level so a more friendly utility -(perl script or GUI) can handle things properly. The scripts B<CA.sh> and -B<CA.pl> help a little but not very much. - -Any fields in a request that are not present in a policy are silently -deleted. This does not happen if the B<-preserveDN> option is used. To -enforce the absence of the EMAIL field within the DN, as suggested by -RFCs, regardless the contents of the request' subject the B<-noemailDN> -option can be used. The behaviour should be more friendly and -configurable. - -Cancelling some commands by refusing to certify a certificate can -create an empty file. - -=head1 WARNINGS - -The B<ca> command is quirky and at times downright unfriendly. - -The B<ca> utility was originally meant as an example of how to do things -in a CA. It was not supposed to be used as a full blown CA itself: -nevertheless some people are using it for this purpose. - -The B<ca> command is effectively a single user command: no locking is -done on the various files and attempts to run more than one B<ca> command -on the same database can have unpredictable results. - -The B<copy_extensions> option should be used with caution. If care is -not taken then it can be a security risk. For example if a certificate -request contains a basicConstraints extension with CA:TRUE and the -B<copy_extensions> value is set to B<copyall> and the user does not spot -this when the certificate is displayed then this will hand the requestor -a valid CA certificate. - -This situation can be avoided by setting B<copy_extensions> to B<copy> -and including basicConstraints with CA:FALSE in the configuration file. -Then if the request contains a basicConstraints extension it will be -ignored. - -It is advisable to also include values for other extensions such -as B<keyUsage> to prevent a request supplying its own values. - -Additional restrictions can be placed on the CA certificate itself. -For example if the CA certificate has: - - basicConstraints = CA:TRUE, pathlen:0 - -then even if a certificate is issued with CA:TRUE it will not be valid. - -=head1 SEE ALSO - -L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, -L<config(5)|config(5)>, L<x509v3_config(5)|x509v3_config(5)> - -=cut diff --git a/openssl/doc/apps/ciphers.pod b/openssl/doc/apps/ciphers.pod deleted file mode 100644 index 9224557..0000000 --- a/openssl/doc/apps/ciphers.pod +++ /dev/null @@ -1,645 +0,0 @@ -=pod - -=head1 NAME - -ciphers - SSL cipher display and cipher list tool. - -=head1 SYNOPSIS - -B<openssl> B<ciphers> -[B<-v>] -[B<-V>] -[B<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[B<cipherlist>] - -=head1 DESCRIPTION - -The B<ciphers> command converts textual OpenSSL cipher lists into ordered -SSL cipher preference lists. It can be used as a test tool to determine -the appropriate cipherlist. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-v> - -Verbose option. List ciphers with a complete description of -protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange, -authentication, encryption and mac algorithms used along with any key size -restrictions and whether the algorithm is classed as an "export" cipher. -Note that without the B<-v> option, ciphers may seem to appear twice -in a cipher list; this is when similar ciphers are available for -SSL v2 and for SSL v3/TLS v1. - -=item B<-V> - -Like B<-v>, but include cipher suite codes in output (hex format). - -=item B<-ssl3>, B<-tls1> - -This lists ciphers compatible with any of SSLv3, TLSv1, TLSv1.1 or TLSv1.2. - -=item B<-ssl2> - -Only include SSLv2 ciphers. - -=item B<-h>, B<-?> - -Print a brief usage message. - -=item B<cipherlist> - -A cipher list to convert to a cipher preference list. If it is not included -then the default cipher list will be used. The format is described below. - -=back - -=head1 CIPHER LIST FORMAT - -The cipher list consists of one or more I<cipher strings> separated by colons. -Commas or spaces are also acceptable separators but colons are normally used. - -The actual cipher string can take several different forms. - -It can consist of a single cipher suite such as B<RC4-SHA>. - -It can represent a list of cipher suites containing a certain algorithm, or -cipher suites of a certain type. For example B<SHA1> represents all ciphers -suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3 -algorithms. - -Lists of cipher suites can be combined in a single cipher string using the -B<+> character. This is used as a logical B<and> operation. For example -B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES -algorithms. - -Each cipher string can be optionally preceded by the characters B<!>, -B<-> or B<+>. - -If B<!> is used then the ciphers are permanently deleted from the list. -The ciphers deleted can never reappear in the list even if they are -explicitly stated. - -If B<-> is used then the ciphers are deleted from the list, but some or -all of the ciphers can be added again by later options. - -If B<+> is used then the ciphers are moved to the end of the list. This -option doesn't add any new ciphers it just moves matching existing ones. - -If none of these characters is present then the string is just interpreted -as a list of ciphers to be appended to the current preference list. If the -list includes any ciphers already present they will be ignored: that is they -will not moved to the end of the list. - -Additionally the cipher string B<@STRENGTH> can be used at any point to sort -the current cipher list in order of encryption algorithm key length. - -=head1 CIPHER STRINGS - -The following is a list of all permitted cipher strings and their meanings. - -=over 4 - -=item B<DEFAULT> - -The default cipher list. -This is determined at compile time and is normally -B<ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2>. -When used, this must be the first cipherstring specified. - -=item B<COMPLEMENTOFDEFAULT> - -the ciphers included in B<ALL>, but not enabled by default. Currently -this is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>, -which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary). - -=item B<ALL> - -all cipher suites except the B<eNULL> ciphers which must be explicitly enabled; -as of OpenSSL, the B<ALL> cipher suites are reasonably ordered by default - -=item B<COMPLEMENTOFALL> - -the cipher suites not enabled by B<ALL>, currently being B<eNULL>. - -=item B<HIGH> - -"high" encryption cipher suites. This currently means those with key lengths larger -than 128 bits, and some cipher suites with 128-bit keys. - -=item B<MEDIUM> - -"medium" encryption cipher suites, currently some of those using 128 bit encryption. - -=item B<LOW> - -Low strength encryption cipher suites, currently those using 64 or 56 bit -encryption algorithms but excluding export cipher suites. -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=item B<EXP>, B<EXPORT> - -Export strength encryption algorithms. Including 40 and 56 bits algorithms. -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=item B<EXPORT40> - -40-bit export encryption algorithms -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=item B<EXPORT56> - -56-bit export encryption algorithms. In OpenSSL 0.9.8c and later the set of -56 bit export ciphers is empty unless OpenSSL has been explicitly configured -with support for experimental ciphers. -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=item B<eNULL>, B<NULL> - -The "NULL" ciphers that is those offering no encryption. Because these offer no -encryption at all and are a security risk they are not enabled via either the -B<DEFAULT> or B<ALL> cipher strings. -Be careful when building cipherlists out of lower-level primitives such as -B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers. -When in doubt, include B<!eNULL> in your cipherlist. - -=item B<aNULL> - -The cipher suites offering no authentication. This is currently the anonymous -DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable -to a "man in the middle" attack and so their use is normally discouraged. -These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL> -ciphers. -Be careful when building cipherlists out of lower-level primitives such as -B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers. -When in doubt, include B<!aNULL> in your cipherlist. - -=item B<kRSA>, B<RSA> - -cipher suites using RSA key exchange. - -=item B<kDHr>, B<kDHd>, B<kDH> - -cipher suites using DH key agreement and DH certificates signed by CAs with RSA -and DSS keys or either respectively. - -=item B<kDHE>, B<kEDH> - -cipher suites using ephemeral DH key agreement, including anonymous cipher -suites. - -=item B<DHE>, B<EDH> - -cipher suites using authenticated ephemeral DH key agreement. - -=item B<ADH> - -anonymous DH cipher suites, note that this does not include anonymous Elliptic -Curve DH (ECDH) cipher suites. - -=item B<DH> - -cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH. - -=item B<kECDHr>, B<kECDHe>, B<kECDH> - -cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA -keys or either respectively. - -=item B<kECDHE>, B<kEECDH> - -cipher suites using ephemeral ECDH key agreement, including anonymous -cipher suites. - -=item B<ECDHE>, B<EECDH> - -cipher suites using authenticated ephemeral ECDH key agreement. - -=item B<AECDH> - -anonymous Elliptic Curve Diffie Hellman cipher suites. - -=item B<ECDH> - -cipher suites using ECDH key exchange, including anonymous, ephemeral and -fixed ECDH. - -=item B<aRSA> - -cipher suites using RSA authentication, i.e. the certificates carry RSA keys. - -=item B<aDSS>, B<DSS> - -cipher suites using DSS authentication, i.e. the certificates carry DSS keys. - -=item B<aDH> - -cipher suites effectively using DH authentication, i.e. the certificates carry -DH keys. - -=item B<aECDH> - -cipher suites effectively using ECDH authentication, i.e. the certificates -carry ECDH keys. - -=item B<aECDSA>, B<ECDSA> - -cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA -keys. - -=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA> - -ciphers suites using FORTEZZA key exchange, authentication, encryption or all -FORTEZZA algorithms. Not implemented. - -=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2> - -TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note: -there are no ciphersuites specific to TLS v1.1. - -=item B<AES128>, B<AES256>, B<AES> - -cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES. - -=item B<AESGCM> - -AES in Galois Counter Mode (GCM): these ciphersuites are only supported -in TLS v1.2. - -=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA> - -cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit -CAMELLIA. - -=item B<3DES> - -cipher suites using triple DES. - -=item B<DES> - -cipher suites using DES (not triple DES). - -=item B<RC4> - -cipher suites using RC4. - -=item B<RC2> - -cipher suites using RC2. - -=item B<IDEA> - -cipher suites using IDEA. - -=item B<SEED> - -cipher suites using SEED. - -=item B<MD5> - -cipher suites using MD5. - -=item B<SHA1>, B<SHA> - -cipher suites using SHA1. - -=item B<SHA256>, B<SHA384> - -ciphersuites using SHA256 or SHA384. - -=item B<aGOST> - -cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction -(needs an engine supporting GOST algorithms). - -=item B<aGOST01> - -cipher suites using GOST R 34.10-2001 authentication. - -=item B<aGOST94> - -cipher suites using GOST R 34.10-94 authentication (note that R 34.10-94 -standard has been expired so use GOST R 34.10-2001) - -=item B<kGOST> - -cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357. - -=item B<GOST94> - -cipher suites, using HMAC based on GOST R 34.11-94. - -=item B<GOST89MAC> - -cipher suites using GOST 28147-89 MAC B<instead of> HMAC. - -=item B<PSK> - -cipher suites using pre-shared keys (PSK). - -=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192> - -enables suite B mode operation using 128 (permitting 192 bit mode by peer) -128 bit (not permitting 192 bit by peer) or 192 bit level of security -respectively. If used these cipherstrings should appear first in the cipher -list and anything after them is ignored. Setting Suite B mode has additional -consequences required to comply with RFC6460. In particular the supported -signature algorithms is reduced to support only ECDSA and SHA256 or SHA384, -only the elliptic curves P-256 and P-384 can be used and only the two suite B -compliant ciphersuites (ECDHE-ECDSA-AES128-GCM-SHA256 and -ECDHE-ECDSA-AES256-GCM-SHA384) are permissible. - -=back - -=head1 CIPHER SUITE NAMES - -The following lists give the SSL or TLS cipher suites names from the -relevant specification and their OpenSSL equivalents. It should be noted, -that several cipher suite names do not include the authentication used, -e.g. DES-CBC3-SHA. In these cases, RSA authentication is used. - -=head2 SSL v3.0 cipher suites. - - SSL_RSA_WITH_NULL_MD5 NULL-MD5 - SSL_RSA_WITH_NULL_SHA NULL-SHA - SSL_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5 - SSL_RSA_WITH_RC4_128_MD5 RC4-MD5 - SSL_RSA_WITH_RC4_128_SHA RC4-SHA - SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5 - SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA - SSL_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA - SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA - SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA - - SSL_DH_DSS_WITH_DES_CBC_SHA DH-DSS-DES-CBC-SHA - SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA - SSL_DH_RSA_WITH_DES_CBC_SHA DH-RSA-DES-CBC-SHA - SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA - SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA - SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA - SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA - SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA - SSL_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA - SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA - - SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5 - SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 - SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA - SSL_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA - SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA - - SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented. - SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented. - SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented. - -=head2 TLS v1.0 cipher suites. - - TLS_RSA_WITH_NULL_MD5 NULL-MD5 - TLS_RSA_WITH_NULL_SHA NULL-SHA - TLS_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5 - TLS_RSA_WITH_RC4_128_MD5 RC4-MD5 - TLS_RSA_WITH_RC4_128_SHA RC4-SHA - TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5 - TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA - TLS_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA - TLS_RSA_WITH_DES_CBC_SHA DES-CBC-SHA - TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA - - TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented. - TLS_DH_DSS_WITH_DES_CBC_SHA Not implemented. - TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented. - TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented. - TLS_DH_RSA_WITH_DES_CBC_SHA Not implemented. - TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented. - TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA - TLS_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA - TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA - TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA - TLS_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA - TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA - - TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5 - TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 - TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA - TLS_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA - TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA - -=head2 AES ciphersuites from RFC3268, extending TLS v1.0 - - TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA - TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA - - TLS_DH_DSS_WITH_AES_128_CBC_SHA DH-DSS-AES128-SHA - TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA - TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA - TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA - - TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA - TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA - TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE-RSA-AES128-SHA - TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA - - TLS_DH_anon_WITH_AES_128_CBC_SHA ADH-AES128-SHA - TLS_DH_anon_WITH_AES_256_CBC_SHA ADH-AES256-SHA - -=head2 Camellia ciphersuites from RFC4132, extending TLS v1.0 - - TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA - TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA - - TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA DH-DSS-CAMELLIA128-SHA - TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA DH-DSS-CAMELLIA256-SHA - TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA DH-RSA-CAMELLIA128-SHA - TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA DH-RSA-CAMELLIA256-SHA - - TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA - TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA - TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA DHE-RSA-CAMELLIA128-SHA - TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA DHE-RSA-CAMELLIA256-SHA - - TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA ADH-CAMELLIA128-SHA - TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA ADH-CAMELLIA256-SHA - -=head2 SEED ciphersuites from RFC4162, extending TLS v1.0 - - TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA - - TLS_DH_DSS_WITH_SEED_CBC_SHA DH-DSS-SEED-SHA - TLS_DH_RSA_WITH_SEED_CBC_SHA DH-RSA-SEED-SHA - - TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA - TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA - - TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA - -=head2 GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0 - -Note: these ciphers require an engine which including GOST cryptographic -algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution. - - TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89 - TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89 - TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94 - TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94 - -=head2 Additional Export 1024 and other cipher suites - -Note: these ciphers can also be used in SSL v3. - - TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DES-CBC-SHA - TLS_RSA_EXPORT1024_WITH_RC4_56_SHA EXP1024-RC4-SHA - TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA - TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA EXP1024-DHE-DSS-RC4-SHA - TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA - -=head2 Elliptic curve cipher suites. - - TLS_ECDH_RSA_WITH_NULL_SHA ECDH-RSA-NULL-SHA - TLS_ECDH_RSA_WITH_RC4_128_SHA ECDH-RSA-RC4-SHA - TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA ECDH-RSA-DES-CBC3-SHA - TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ECDH-RSA-AES128-SHA - TLS_ECDH_RSA_WITH_AES_256_CBC_SHA ECDH-RSA-AES256-SHA - - TLS_ECDH_ECDSA_WITH_NULL_SHA ECDH-ECDSA-NULL-SHA - TLS_ECDH_ECDSA_WITH_RC4_128_SHA ECDH-ECDSA-RC4-SHA - TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA ECDH-ECDSA-DES-CBC3-SHA - TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA ECDH-ECDSA-AES128-SHA - TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA ECDH-ECDSA-AES256-SHA - - TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA - TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA - TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA - - TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA - TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA - TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA - - TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA - TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA - TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA - TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA - TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA - -=head2 TLS v1.2 cipher suites - - TLS_RSA_WITH_NULL_SHA256 NULL-SHA256 - - TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256 - TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256 - TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256 - TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384 - - TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH-RSA-AES128-SHA256 - TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH-RSA-AES256-SHA256 - TLS_DH_RSA_WITH_AES_128_GCM_SHA256 DH-RSA-AES128-GCM-SHA256 - TLS_DH_RSA_WITH_AES_256_GCM_SHA384 DH-RSA-AES256-GCM-SHA384 - - TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH-DSS-AES128-SHA256 - TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH-DSS-AES256-SHA256 - TLS_DH_DSS_WITH_AES_128_GCM_SHA256 DH-DSS-AES128-GCM-SHA256 - TLS_DH_DSS_WITH_AES_256_GCM_SHA384 DH-DSS-AES256-GCM-SHA384 - - TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE-RSA-AES128-SHA256 - TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE-RSA-AES256-SHA256 - TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE-RSA-AES128-GCM-SHA256 - TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE-RSA-AES256-GCM-SHA384 - - TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE-DSS-AES128-SHA256 - TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE-DSS-AES256-SHA256 - TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256 - TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384 - - TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 ECDH-RSA-AES128-SHA256 - TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 ECDH-RSA-AES256-SHA384 - TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 ECDH-RSA-AES128-GCM-SHA256 - TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 ECDH-RSA-AES256-GCM-SHA384 - - TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 ECDH-ECDSA-AES128-SHA256 - TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 ECDH-ECDSA-AES256-SHA384 - TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 ECDH-ECDSA-AES128-GCM-SHA256 - TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 ECDH-ECDSA-AES256-GCM-SHA384 - - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256 - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384 - - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256 - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384 - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256 - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384 - - TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256 - TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256 - TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256 - TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384 - -=head2 Pre shared keying (PSK) cipheruites - - TLS_PSK_WITH_RC4_128_SHA PSK-RC4-SHA - TLS_PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA - TLS_PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA - TLS_PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA - -=head2 Deprecated SSL v2.0 cipher suites. - - SSL_CK_RC4_128_WITH_MD5 RC4-MD5 - SSL_CK_RC4_128_EXPORT40_WITH_MD5 Not implemented. - SSL_CK_RC2_128_CBC_WITH_MD5 RC2-CBC-MD5 - SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 Not implemented. - SSL_CK_IDEA_128_CBC_WITH_MD5 IDEA-CBC-MD5 - SSL_CK_DES_64_CBC_WITH_MD5 Not implemented. - SSL_CK_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5 - -=head1 NOTES - -Some compiled versions of OpenSSL may not include all the ciphers -listed here because some ciphers were excluded at compile time. - -=head1 EXAMPLES - -Verbose listing of all OpenSSL ciphers including NULL ciphers: - - openssl ciphers -v 'ALL:eNULL' - -Include all ciphers except NULL and anonymous DH then sort by -strength: - - openssl ciphers -v 'ALL:!ADH:@STRENGTH' - -Include all ciphers except ones with no encryption (eNULL) or no -authentication (aNULL): - - openssl ciphers -v 'ALL:!aNULL' - -Include only 3DES ciphers and then place RSA ciphers last: - - openssl ciphers -v '3DES:+RSA' - -Include all RC4 ciphers but leave out those without authentication: - - openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT' - -Include all chiphers with RSA authentication but leave out ciphers without -encryption. - - openssl ciphers -v 'RSA:!COMPLEMENTOFALL' - -=head1 SEE ALSO - -L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)> - -=head1 HISTORY - -The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options -for cipherlist strings were added in OpenSSL 0.9.7. -The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/apps/cms.pod b/openssl/doc/apps/cms.pod deleted file mode 100644 index ac69804..0000000 --- a/openssl/doc/apps/cms.pod +++ /dev/null @@ -1,664 +0,0 @@ -=pod - -=head1 NAME - -cms - CMS utility - -=head1 SYNOPSIS - -B<openssl> B<cms> -[B<-encrypt>] -[B<-decrypt>] -[B<-sign>] -[B<-verify>] -[B<-cmsout>] -[B<-resign>] -[B<-data_create>] -[B<-data_out>] -[B<-digest_create>] -[B<-digest_verify>] -[B<-compress>] -[B<-uncompress>] -[B<-EncryptedData_encrypt>] -[B<-sign_receipt>] -[B<-verify_receipt receipt>] -[B<-in filename>] -[B<-inform SMIME|PEM|DER>] -[B<-rctform SMIME|PEM|DER>] -[B<-out filename>] -[B<-outform SMIME|PEM|DER>] -[B<-stream -indef -noindef>] -[B<-noindef>] -[B<-content filename>] -[B<-text>] -[B<-noout>] -[B<-print>] -[B<-CAfile file>] -[B<-CApath dir>] -[B<-no_alt_chains>] -[B<-md digest>] -[B<-[cipher]>] -[B<-nointern>] -[B<-no_signer_cert_verify>] -[B<-nocerts>] -[B<-noattr>] -[B<-nosmimecap>] -[B<-binary>] -[B<-nodetach>] -[B<-certfile file>] -[B<-certsout file>] -[B<-signer file>] -[B<-recip file>] -[B<-keyid>] -[B<-receipt_request_all -receipt_request_first>] -[B<-receipt_request_from emailaddress>] -[B<-receipt_request_to emailaddress>] -[B<-receipt_request_print>] -[B<-secretkey key>] -[B<-secretkeyid id>] -[B<-econtent_type type>] -[B<-inkey file>] -[B<-keyopt name:parameter>] -[B<-passin arg>] -[B<-rand file(s)>] -[B<cert.pem...>] -[B<-to addr>] -[B<-from addr>] -[B<-subject subj>] -[cert.pem]... - -=head1 DESCRIPTION - -The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and -verify, compress and uncompress S/MIME messages. - -=head1 COMMAND OPTIONS - -There are fourteen operation options that set the type of operation to be -performed. The meaning of the other options varies according to the operation -type. - -=over 4 - -=item B<-encrypt> - -encrypt mail for the given recipient certificates. Input file is the message -to be encrypted. The output file is the encrypted mail in MIME format. The -actual CMS type is <B>EnvelopedData<B>. - -Note that no revocation check is done for the recipient cert, so if that -key has been compromised, others may be able to decrypt the text. - -=item B<-decrypt> - -decrypt mail using the supplied certificate and private key. Expects an -encrypted mail message in MIME format for the input file. The decrypted mail -is written to the output file. - -=item B<-debug_decrypt> - -this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used -with caution: see the notes section below. - -=item B<-sign> - -sign mail using the supplied certificate and private key. Input file is -the message to be signed. The signed message in MIME format is written -to the output file. - -=item B<-verify> - -verify signed mail. Expects a signed mail message on input and outputs -the signed data. Both clear text and opaque signing is supported. - -=item B<-cmsout> - -takes an input message and writes out a PEM encoded CMS structure. - -=item B<-resign> - -resign a message: take an existing message and one or more new signers. - -=item B<-data_create> - -Create a CMS B<Data> type. - -=item B<-data_out> - -B<Data> type and output the content. - -=item B<-digest_create> - -Create a CMS B<DigestedData> type. - -=item B<-digest_verify> - -Verify a CMS B<DigestedData> type and output the content. - -=item B<-compress> - -Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> -support for this option to work, otherwise it will output an error. - -=item B<-uncompress> - -Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be -compiled with B<zlib> support for this option to work, otherwise it will -output an error. - -=item B<-EncryptedData_encrypt> - -Encrypt content using supplied symmetric key and algorithm using a CMS -B<EncrytedData> type and output the content. - -=item B<-sign_receipt> - -Generate and output a signed receipt for the supplied message. The input -message B<must> contain a signed receipt request. Functionality is otherwise -similar to the B<-sign> operation. - -=item B<-verify_receipt receipt> - -Verify a signed receipt in filename B<receipt>. The input message B<must> -contain the original receipt request. Functionality is otherwise similar -to the B<-verify> operation. - -=item B<-in filename> - -the input message to be encrypted or signed or the message to be decrypted -or verified. - -=item B<-inform SMIME|PEM|DER> - -this specifies the input format for the CMS structure. The default -is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> -format change this to expect PEM and DER format CMS structures -instead. This currently only affects the input format of the CMS -structure, if no CMS structure is being input (for example with -B<-encrypt> or B<-sign>) this option has no effect. - -=item B<-rctform SMIME|PEM|DER> - -specify the format for a signed receipt for use with the B<-receipt_verify> -operation. - -=item B<-out filename> - -the message text that has been decrypted or verified or the output MIME -format message that has been signed or verified. - -=item B<-outform SMIME|PEM|DER> - -this specifies the output format for the CMS structure. The default -is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER> -format change this to write PEM and DER format CMS structures -instead. This currently only affects the output format of the CMS -structure, if no CMS structure is being output (for example with -B<-verify> or B<-decrypt>) this option has no effect. - -=item B<-stream -indef -noindef> - -the B<-stream> and B<-indef> options are equivalent and enable streaming I/O -for encoding operations. This permits single pass processing of data without -the need to hold the entire contents in memory, potentially supporting very -large files. Streaming is automatically set for S/MIME signing with detached -data if the output format is B<SMIME> it is currently off by default for all -other operations. - -=item B<-noindef> - -disable streaming I/O where it would produce and indefinite length constructed -encoding. This option currently has no effect. In future streaming will be -enabled by default on all relevant operations and this option will disable it. - -=item B<-content filename> - -This specifies a file containing the detached content, this is only -useful with the B<-verify> command. This is only usable if the CMS -structure is using the detached signature form where the content is -not included. This option will override any content if the input format -is S/MIME and it uses the multipart/signed MIME content type. - -=item B<-text> - -this option adds plain text (text/plain) MIME headers to the supplied -message if encrypting or signing. If decrypting or verifying it strips -off text headers: if the decrypted or verified message is not of MIME -type text/plain then an error occurs. - -=item B<-noout> - -for the B<-cmsout> operation do not output the parsed CMS structure. This -is useful when combined with the B<-print> option or if the syntax of the CMS -structure is being checked. - -=item B<-print> - -for the B<-cmsout> operation print out all fields of the CMS structure. This -is mainly useful for testing purposes. - -=item B<-CAfile file> - -a file containing trusted CA certificates, only used with B<-verify>. - -=item B<-CApath dir> - -a directory containing trusted CA certificates, only used with -B<-verify>. This directory must be a standard certificate directory: that -is a hash of each subject name (using B<x509 -hash>) should be linked -to each certificate. - -=item B<-md digest> - -digest algorithm to use when signing or resigning. If not present then the -default digest algorithm for the signing key will be used (usually SHA1). - -=item B<-[cipher]> - -the encryption algorithm to use. For example triple DES (168 bits) - B<-des3> -or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the -EVP_get_cipherbyname() function) can also be used preceded by a dash, for -example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for a list of ciphers -supported by your version of OpenSSL. - -If not specified triple DES is used. Only used with B<-encrypt> and -B<-EncryptedData_create> commands. - -=item B<-nointern> - -when verifying a message normally certificates (if any) included in -the message are searched for the signing certificate. With this option -only the certificates specified in the B<-certfile> option are used. -The supplied certificates can still be used as untrusted CAs however. - -=item B<-no_signer_cert_verify> - -do not verify the signers certificate of a signed message. - -=item B<-nocerts> - -when signing a message the signer's certificate is normally included -with this option it is excluded. This will reduce the size of the -signed message but the verifier must have a copy of the signers certificate -available locally (passed using the B<-certfile> option for example). - -=item B<-noattr> - -normally when a message is signed a set of attributes are included which -include the signing time and supported symmetric algorithms. With this -option they are not included. - -=item B<-nosmimecap> - -exclude the list of supported algorithms from signed attributes, other options -such as signing time and content type are still included. - -=item B<-binary> - -normally the input message is converted to "canonical" format which is -effectively using CR and LF as end of line: as required by the S/MIME -specification. When this option is present no translation occurs. This -is useful when handling binary data which may not be in MIME format. - -=item B<-nodetach> - -when signing a message use opaque signing: this form is more resistant -to translation by mail relays but it cannot be read by mail agents that -do not support S/MIME. Without this option cleartext signing with -the MIME type multipart/signed is used. - -=item B<-certfile file> - -allows additional certificates to be specified. When signing these will -be included with the message. When verifying these will be searched for -the signers certificates. The certificates should be in PEM format. - -=item B<-certsout file> - -any certificates contained in the message are written to B<file>. - -=item B<-signer file> - -a signing certificate when signing or resigning a message, this option can be -used multiple times if more than one signer is required. If a message is being -verified then the signers certificates will be written to this file if the -verification was successful. - -=item B<-recip file> - -when decrypting a message this specifies the recipients certificate. The -certificate must match one of the recipients of the message or an error -occurs. - -When encrypting a message this option may be used multiple times to specify -each recipient. This form B<must> be used if customised parameters are -required (for example to specify RSA-OAEP). - -=item B<-keyid> - -use subject key identifier to identify certificates instead of issuer name and -serial number. The supplied certificate B<must> include a subject key -identifier extension. Supported by B<-sign> and B<-encrypt> options. - -=item B<-receipt_request_all -receipt_request_first> - -for B<-sign> option include a signed receipt request. Indicate requests should -be provided by all receipient or first tier recipients (those mailed directly -and not from a mailing list). Ignored it B<-receipt_request_from> is included. - -=item B<-receipt_request_from emailaddress> - -for B<-sign> option include a signed receipt request. Add an explicit email -address where receipts should be supplied. - -=item B<-receipt_request_to emailaddress> - -Add an explicit email address where signed receipts should be sent to. This -option B<must> but supplied if a signed receipt it requested. - -=item B<-receipt_request_print> - -For the B<-verify> operation print out the contents of any signed receipt -requests. - -=item B<-secretkey key> - -specify symmetric key to use. The key must be supplied in hex format and be -consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt> -B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used -with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the -content encryption key using an AES key in the B<KEKRecipientInfo> type. - -=item B<-secretkeyid id> - -the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type. -This option B<must> be present if the B<-secretkey> option is used with -B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the -relevant key if it is not supplied then an attempt is used to decrypt any -B<KEKRecipientInfo> structures. - -=item B<-econtent_type type> - -set the encapsulated content type to B<type> if not supplied the B<Data> type -is used. The B<type> argument can be any valid OID name in either text or -numerical format. - -=item B<-inkey file> - -the private key to use when signing or decrypting. This must match the -corresponding certificate. If this option is not specified then the -private key must be included in the certificate file specified with -the B<-recip> or B<-signer> file. When signing this option can be used -multiple times to specify successive keys. - -=item B<-keyopt name:opt> - -for signing and encryption this option can be used multiple times to -set customised parameters for the preceding key or certificate. It can -currently be used to set RSA-PSS for signing, RSA-OAEP for encryption -or to modify default parameters for ECDH. - -=item B<-passin arg> - -the private key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<cert.pem...> - -one or more certificates of message recipients: used when encrypting -a message. - -=item B<-to, -from, -subject> - -the relevant mail headers. These are included outside the signed -portion of a message so they may be included manually. If signing -then many S/MIME mail clients check the signers certificate's email -address matches that specified in the From: address. - -=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> - -Set various certificate chain valiadition option. See the -L<B<verify>|verify(1)> manual page for details. - -=back - -=head1 NOTES - -The MIME message must be sent without any blank lines between the -headers and the output. Some mail programs will automatically add -a blank line. Piping the mail directly to sendmail is one way to -achieve the correct format. - -The supplied message to be signed or encrypted must include the -necessary MIME headers or many S/MIME clients wont display it -properly (if at all). You can use the B<-text> option to automatically -add plain text headers. - -A "signed and encrypted" message is one where a signed message is -then encrypted. This can be produced by encrypting an already signed -message: see the examples section. - -This version of the program only allows one signer per message but it -will verify multiple signers on received messages. Some S/MIME clients -choke if a message contains multiple signers. It is possible to sign -messages "in parallel" by signing an already signed message. - -The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME -clients. Strictly speaking these process CMS enveloped data: CMS -encrypted data is used for other purposes. - -The B<-resign> option uses an existing message digest when adding a new -signer. This means that attributes must be present in at least one existing -signer using the same message digest or this operation will fail. - -The B<-stream> and B<-indef> options enable experimental streaming I/O support. -As a result the encoding is BER using indefinite length constructed encoding -and no longer DER. Streaming is supported for the B<-encrypt> operation and the -B<-sign> operation if the content is not detached. - -Streaming is always used for the B<-sign> operation with detached data but -since the content is no longer part of the CMS structure the encoding -remains DER. - -If the B<-decrypt> option is used without a recipient certificate then an -attempt is made to locate the recipient by trying each potential recipient -in turn using the supplied private key. To thwart the MMA attack -(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are -tried whether they succeed or not and if no recipients match the message -is "decrypted" using a random key which will typically output garbage. -The B<-debug_decrypt> option can be used to disable the MMA attack protection -and return an error if no recipient can be found: this option should be used -with caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>). - -=head1 EXIT CODES - -=over 4 - -=item Z<>0 - -the operation was completely successfully. - -=item Z<>1 - -an error occurred parsing the command options. - -=item Z<>2 - -one of the input files could not be read. - -=item Z<>3 - -an error occurred creating the CMS file or when reading the MIME -message. - -=item Z<>4 - -an error occurred decrypting or verifying the message. - -=item Z<>5 - -the message was verified correctly but an error occurred writing out -the signers certificates. - -=back - -=head1 COMPATIBILITY WITH PKCS#7 format. - -The B<smime> utility can only process the older B<PKCS#7> format. The B<cms> -utility supports Cryptographic Message Syntax format. Use of some features -will result in messages which cannot be processed by applications which only -support the older format. These are detailed below. - -The use of the B<-keyid> option with B<-sign> or B<-encrypt>. - -The B<-outform PEM> option uses different headers. - -The B<-compress> option. - -The B<-secretkey> option when used with B<-encrypt>. - -The use of PSS with B<-sign>. - -The use of OAEP or non-RSA keys with B<-encrypt>. - -Additionally the B<-EncryptedData_create> and B<-data_create> type cannot -be processed by the older B<smime> command. - -=head1 EXAMPLES - -Create a cleartext signed message: - - openssl cms -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem - -Create an opaque signed message - - openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ - -signer mycert.pem - -Create a signed message, include some additional certificates and -read the private key from another file: - - openssl cms -sign -in in.txt -text -out mail.msg \ - -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem - -Create a signed message with two signers, use key identifier: - - openssl cms -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem -signer othercert.pem -keyid - -Send a signed message under Unix directly to sendmail, including headers: - - openssl cms -sign -in in.txt -text -signer mycert.pem \ - -from steve@openssl.org -to someone@somewhere \ - -subject "Signed message" | sendmail someone@somewhere - -Verify a message and extract the signer's certificate if successful: - - openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt - -Send encrypted mail using triple DES: - - openssl cms -encrypt -in in.txt -from steve@openssl.org \ - -to someone@somewhere -subject "Encrypted message" \ - -des3 user.pem -out mail.msg - -Sign and encrypt mail: - - openssl cms -sign -in ml.txt -signer my.pem -text \ - | openssl cms -encrypt -out mail.msg \ - -from steve@openssl.org -to someone@somewhere \ - -subject "Signed and Encrypted message" -des3 user.pem - -Note: the encryption command does not include the B<-text> option because the -message being encrypted already has MIME headers. - -Decrypt mail: - - openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem - -The output from Netscape form signing is a PKCS#7 structure with the -detached signature format. You can use this program to verify the -signature by line wrapping the base64 encoded structure and surrounding -it with: - - -----BEGIN PKCS7----- - -----END PKCS7----- - -and using the command, - - openssl cms -verify -inform PEM -in signature.pem -content content.txt - -alternatively you can base64 decode the signature and use - - openssl cms -verify -inform DER -in signature.der -content content.txt - -Create an encrypted message using 128 bit Camellia: - - openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem - -Add a signer to an existing message: - - openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg - -Sign mail using RSA-PSS: - - openssl cms -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem -keyopt rsa_padding_mode:pss - -Create encrypted mail using RSA-OAEP: - - openssl cms -encrypt -in plain.txt -out mail.msg \ - -recip cert.pem -keyopt rsa_padding_mode:oaep - -Use SHA256 KDF with an ECDH certificate: - - openssl cms -encrypt -in plain.txt -out mail.msg \ - -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256 - -=head1 BUGS - -The MIME parser isn't very clever: it seems to handle most messages that I've -thrown at it but it may choke on others. - -The code currently will only write out the signer's certificate to a file: if -the signer has a separate encryption certificate this must be manually -extracted. There should be some heuristic that determines the correct -encryption certificate. - -Ideally a database should be maintained of a certificates for each email -address. - -The code doesn't currently take note of the permitted symmetric encryption -algorithms as supplied in the SMIMECapabilities signed attribute. this means the -user has to manually include the correct encryption algorithm. It should store -the list of permitted ciphers in a database and only use those. - -No revocation checking is done on the signer's certificate. - -=head1 HISTORY - -The use of multiple B<-signer> options and the B<-resign> command were first -added in OpenSSL 1.0.0 - -The B<keyopt> option was first added in OpenSSL 1.1.0 - -The use of B<-recip> to specify the recipient when encrypting mail was first -added to OpenSSL 1.1.0 - -Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0. - -The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added -to OpenSSL 1.1.0. - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/config.pod b/openssl/doc/apps/config.pod deleted file mode 100644 index e125915..0000000 --- a/openssl/doc/apps/config.pod +++ /dev/null @@ -1,350 +0,0 @@ - -=pod - -=for comment openssl_manual_section:5 - -=head1 NAME - -config - OpenSSL CONF library configuration files - -=head1 DESCRIPTION - -The OpenSSL CONF library can be used to read configuration files. -It is used for the OpenSSL master configuration file B<openssl.cnf> -and in a few other places like B<SPKAC> files and certificate extension -files for the B<x509> utility. OpenSSL applications can also use the -CONF library for their own purposes. - -A configuration file is divided into a number of sections. Each section -starts with a line B<[ section_name ]> and ends when a new section is -started or end of file is reached. A section name can consist of -alphanumeric characters and underscores. - -The first section of a configuration file is special and is referred -to as the B<default> section this is usually unnamed and is from the -start of file until the first named section. When a name is being looked up -it is first looked up in a named section (if any) and then the -default section. - -The environment is mapped onto a section called B<ENV>. - -Comments can be included by preceding them with the B<#> character - -Each section in a configuration file consists of a number of name and -value pairs of the form B<name=value> - -The B<name> string can contain any alphanumeric characters as well as -a few punctuation symbols such as B<.> B<,> B<;> and B<_>. - -The B<value> string consists of the string following the B<=> character -until end of line with any leading and trailing white space removed. - -The value string undergoes variable expansion. This can be done by -including the form B<$var> or B<${var}>: this will substitute the value -of the named variable in the current section. It is also possible to -substitute a value from another section using the syntax B<$section::name> -or B<${section::name}>. By using the form B<$ENV::name> environment -variables can be substituted. It is also possible to assign values to -environment variables by using the name B<ENV::name>, this will work -if the program looks up environment variables using the B<CONF> library -instead of calling B<getenv()> directly. - -It is possible to escape certain characters by using any kind of quote -or the B<\> character. By making the last character of a line a B<\> -a B<value> string can be spread across multiple lines. In addition -the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. - -=head1 OPENSSL LIBRARY CONFIGURATION - -In OpenSSL 0.9.7 and later applications can automatically configure certain -aspects of OpenSSL using the master OpenSSL configuration file, or optionally -an alternative configuration file. The B<openssl> utility includes this -functionality: any sub command uses the master OpenSSL configuration file -unless an option is used in the sub command to use an alternative configuration -file. - -To enable library configuration the default section needs to contain an -appropriate line which points to the main configuration section. The default -name is B<openssl_conf> which is used by the B<openssl> utility. Other -applications may use an alternative name such as B<myapplicaton_conf>. - -The configuration section should consist of a set of name value pairs which -contain specific module configuration information. The B<name> represents -the name of the I<configuration module> the meaning of the B<value> is -module specific: it may, for example, represent a further configuration -section containing configuration module specific information. E.g. - - openssl_conf = openssl_init - - [openssl_init] - - oid_section = new_oids - engines = engine_section - - [new_oids] - - ... new oids here ... - - [engine_section] - - ... engine stuff here ... - -The features of each configuration module are described below. - -=head2 ASN1 OBJECT CONFIGURATION MODULE - -This module has the name B<oid_section>. The value of this variable points -to a section containing name value pairs of OIDs: the name is the OID short -and long name, the value is the numerical form of the OID. Although some of -the B<openssl> utility sub commands already have their own ASN1 OBJECT section -functionality not all do. By using the ASN1 OBJECT configuration module -B<all> the B<openssl> utility sub commands can see the new objects as well -as any compliant applications. For example: - - [new_oids] - - some_new_oid = 1.2.3.4 - some_other_oid = 1.2.3.5 - -In OpenSSL 0.9.8 it is also possible to set the value to the long name followed -by a comma and the numerical OID form. For example: - - shortName = some object long name, 1.2.3.4 - -=head2 ENGINE CONFIGURATION MODULE - -This ENGINE configuration module has the name B<engines>. The value of this -variable points to a section containing further ENGINE configuration -information. - -The section pointed to by B<engines> is a table of engine names (though see -B<engine_id> below) and further sections containing configuration information -specific to each ENGINE. - -Each ENGINE specific section is used to set default algorithms, load -dynamic, perform initialization and send ctrls. The actual operation performed -depends on the I<command> name which is the name of the name value pair. The -currently supported commands are listed below. - -For example: - - [engine_section] - - # Configure ENGINE named "foo" - foo = foo_section - # Configure ENGINE named "bar" - bar = bar_section - - [foo_section] - ... foo ENGINE specific commands ... - - [bar_section] - ... "bar" ENGINE specific commands ... - -The command B<engine_id> is used to give the ENGINE name. If used this -command must be first. For example: - - [engine_section] - # This would normally handle an ENGINE named "foo" - foo = foo_section - - [foo_section] - # Override default name and use "myfoo" instead. - engine_id = myfoo - -The command B<dynamic_path> loads and adds an ENGINE from the given path. It -is equivalent to sending the ctrls B<SO_PATH> with the path argument followed -by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is -not the required behaviour then alternative ctrls can be sent directly -to the dynamic ENGINE using ctrl commands. - -The command B<init> determines whether to initialize the ENGINE. If the value -is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to -initialized the ENGINE immediately. If the B<init> command is not present -then an attempt will be made to initialize the ENGINE after all commands in -its section have been processed. - -The command B<default_algorithms> sets the default algorithms an ENGINE will -supply using the functions B<ENGINE_set_default_string()> - -If the name matches none of the above command names it is assumed to be a -ctrl command which is sent to the ENGINE. The value of the command is the -argument to the ctrl command. If the value is the string B<EMPTY> then no -value is sent to the command. - -For example: - - - [engine_section] - - # Configure ENGINE named "foo" - foo = foo_section - - [foo_section] - # Load engine from DSO - dynamic_path = /some/path/fooengine.so - # A foo specific ctrl. - some_ctrl = some_value - # Another ctrl that doesn't take a value. - other_ctrl = EMPTY - # Supply all default algorithms - default_algorithms = ALL - -=head2 EVP CONFIGURATION MODULE - -This modules has the name B<alg_section> which points to a section containing -algorithm commands. - -Currently the only algorithm command supported is B<fips_mode> whose -value should be a boolean string such as B<on> or B<off>. If the value is -B<on> this attempt to enter FIPS mode. If the call fails or the library is -not FIPS capable then an error occurs. - -For example: - - alg_section = evp_settings - - [evp_settings] - - fips_mode = on - - -=head1 NOTES - -If a configuration file attempts to expand a variable that doesn't exist -then an error is flagged and the file will not load. This can happen -if an attempt is made to expand an environment variable that doesn't -exist. For example in a previous version of OpenSSL the default OpenSSL -master configuration file used the value of B<HOME> which may not be -defined on non Unix systems and would cause an error. - -This can be worked around by including a B<default> section to provide -a default value: then if the environment lookup fails the default value -will be used instead. For this to work properly the default value must -be defined earlier in the configuration file than the expansion. See -the B<EXAMPLES> section for an example of how to do this. - -If the same variable exists in the same section then all but the last -value will be silently ignored. In certain circumstances such as with -DNs the same field may occur multiple times. This is usually worked -around by ignoring any characters before an initial B<.> e.g. - - 1.OU="My first OU" - 2.OU="My Second OU" - -=head1 EXAMPLES - -Here is a sample configuration file using some of the features -mentioned above. - - # This is the default section. - - HOME=/temp - RANDFILE= ${ENV::HOME}/.rnd - configdir=$ENV::HOME/config - - [ section_one ] - - # We are now in section one. - - # Quotes permit leading and trailing whitespace - any = " any variable name " - - other = A string that can \ - cover several lines \ - by including \\ characters - - message = Hello World\n - - [ section_two ] - - greeting = $section_one::message - -This next example shows how to expand environment variables safely. - -Suppose you want a variable called B<tmpfile> to refer to a -temporary filename. The directory it is placed in can determined by -the the B<TEMP> or B<TMP> environment variables but they may not be -set to any value at all. If you just include the environment variable -names and the variable doesn't exist then this will cause an error when -an attempt is made to load the configuration file. By making use of the -default section both values can be looked up with B<TEMP> taking -priority and B</tmp> used if neither is defined: - - TMP=/tmp - # The above value is used if TMP isn't in the environment - TEMP=$ENV::TMP - # The above value is used if TEMP isn't in the environment - tmpfile=${ENV::TEMP}/tmp.filename - -Simple OpenSSL library configuration example to enter FIPS mode: - - # Default appname: should match "appname" parameter (if any) - # supplied to CONF_modules_load_file et al. - openssl_conf = openssl_conf_section - - [openssl_conf_section] - # Configuration module list - alg_section = evp_sect - - [evp_sect] - # Set to "yes" to enter FIPS mode if supported - fips_mode = yes - -Note: in the above example you will get an error in non FIPS capable versions -of OpenSSL. - -More complex OpenSSL library configuration. Add OID and don't enter FIPS mode: - - # Default appname: should match "appname" parameter (if any) - # supplied to CONF_modules_load_file et al. - openssl_conf = openssl_conf_section - - [openssl_conf_section] - # Configuration module list - alg_section = evp_sect - oid_section = new_oids - - [evp_sect] - # This will have no effect as FIPS mode is off by default. - # Set to "yes" to enter FIPS mode, if supported - fips_mode = no - - [new_oids] - # New OID, just short name - newoid1 = 1.2.3.4.1 - # New OID shortname and long name - newoid2 = New OID 2 long name, 1.2.3.4.2 - -The above examples can be used with with any application supporting library -configuration if "openssl_conf" is modified to match the appropriate "appname". - -For example if the second sample file above is saved to "example.cnf" then -the command line: - - OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1 - -will output: - - 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 - -showing that the OID "newoid1" has been added as "1.2.3.4.1". - -=head1 BUGS - -Currently there is no way to include characters using the octal B<\nnn> -form. Strings are all null terminated so nulls cannot form part of -the value. - -The escaping isn't quite right: if you want to use sequences like B<\n> -you can't use any quote escaping on the same line. - -Files are loaded in a single pass. This means that an variable expansion -will only work if the variables referenced are defined earlier in the -file. - -=head1 SEE ALSO - -L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> - -=cut diff --git a/openssl/doc/apps/crl.pod b/openssl/doc/apps/crl.pod deleted file mode 100644 index 044a9da..0000000 --- a/openssl/doc/apps/crl.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -crl - CRL utility - -=head1 SYNOPSIS - -B<openssl> B<crl> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-text>] -[B<-in filename>] -[B<-out filename>] -[B<-nameopt option>] -[B<-noout>] -[B<-hash>] -[B<-issuer>] -[B<-lastupdate>] -[B<-nextupdate>] -[B<-CAfile file>] -[B<-CApath dir>] - -=head1 DESCRIPTION - -The B<crl> command processes CRL files in DER or PEM format. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. B<DER> format is DER encoded CRL -structure. B<PEM> (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read from or standard input if this -option is not specified. - -=item B<-out filename> - -specifies the output filename to write to or standard output by -default. - -=item B<-text> - -print out the CRL in text form. - -=item B<-nameopt option> - -option which determines how the subject or issuer names are displayed. See -the description of B<-nameopt> in L<x509(1)|x509(1)>. - -=item B<-noout> - -don't output the encoded version of the CRL. - -=item B<-hash> - -output a hash of the issuer name. This can be use to lookup CRLs in -a directory by issuer name. - -=item B<-hash_old> - -outputs the "hash" of the CRL issuer name using the older algorithm -as used by OpenSSL versions before 1.0.0. - -=item B<-issuer> - -output the issuer name. - -=item B<-lastupdate> - -output the lastUpdate field. - -=item B<-nextupdate> - -output the nextUpdate field. - -=item B<-CAfile file> - -verify the signature on a CRL by looking up the issuing certificate in -B<file> - -=item B<-CApath dir> - -verify the signature on a CRL by looking up the issuing certificate in -B<dir>. This directory must be a standard certificate directory: that -is a hash of each subject name (using B<x509 -hash>) should be linked -to each certificate. - -=back - -=head1 NOTES - -The PEM CRL format uses the header and footer lines: - - -----BEGIN X509 CRL----- - -----END X509 CRL----- - -=head1 EXAMPLES - -Convert a CRL file from PEM to DER: - - openssl crl -in crl.pem -outform DER -out crl.der - -Output the text form of a DER encoded certificate: - - openssl crl -in crl.der -text -noout - -=head1 BUGS - -Ideally it should be possible to create a CRL using appropriate options -and files too. - -=head1 SEE ALSO - -L<crl2pkcs7(1)|crl2pkcs7(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)> - -=cut diff --git a/openssl/doc/apps/crl2pkcs7.pod b/openssl/doc/apps/crl2pkcs7.pod deleted file mode 100644 index 3797bc0..0000000 --- a/openssl/doc/apps/crl2pkcs7.pod +++ /dev/null @@ -1,91 +0,0 @@ -=pod - -=head1 NAME - -crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates. - -=head1 SYNOPSIS - -B<openssl> B<crl2pkcs7> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-certfile filename>] -[B<-nocrl>] - -=head1 DESCRIPTION - -The B<crl2pkcs7> command takes an optional CRL and one or more -certificates and converts them into a PKCS#7 degenerate "certificates -only" structure. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the CRL input format. B<DER> format is DER encoded CRL -structure.B<PEM> (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the PKCS#7 structure output format. B<DER> format is DER -encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=item B<-in filename> - -This specifies the input filename to read a CRL from or standard input if this -option is not specified. - -=item B<-out filename> - -specifies the output filename to write the PKCS#7 structure to or standard -output by default. - -=item B<-certfile filename> - -specifies a filename containing one or more certificates in B<PEM> format. -All certificates in the file will be added to the PKCS#7 structure. This -option can be used more than once to read certificates form multiple -files. - -=item B<-nocrl> - -normally a CRL is included in the output file. With this option no CRL is -included in the output file and a CRL is not read from the input file. - -=back - -=head1 EXAMPLES - -Create a PKCS#7 structure from a certificate and CRL: - - openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem - -Creates a PKCS#7 structure in DER format with no CRL from several -different certificates: - - openssl crl2pkcs7 -nocrl -certfile newcert.pem - -certfile demoCA/cacert.pem -outform DER -out p7.der - -=head1 NOTES - -The output file is a PKCS#7 signed data structure containing no signers and -just certificates and an optional CRL. - -This utility can be used to send certificates and CAs to Netscape as part of -the certificate enrollment process. This involves sending the DER encoded output -as MIME type application/x-x509-user-cert. - -The B<PEM> encoded form with the header and footer lines removed can be used to -install user certificates and CAs in MSIE using the Xenroll control. - -=head1 SEE ALSO - -L<pkcs7(1)|pkcs7(1)> - -=cut diff --git a/openssl/doc/apps/dgst.pod b/openssl/doc/apps/dgst.pod deleted file mode 100644 index b27bb94..0000000 --- a/openssl/doc/apps/dgst.pod +++ /dev/null @@ -1,208 +0,0 @@ -=pod - -=head1 NAME - -dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests - -=head1 SYNOPSIS - -B<openssl> B<dgst> -[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>] -[B<-c>] -[B<-d>] -[B<-hex>] -[B<-binary>] -[B<-r>] -[B<-non-fips-allow>] -[B<-out filename>] -[B<-sign filename>] -[B<-keyform arg>] -[B<-passin arg>] -[B<-verify filename>] -[B<-prverify filename>] -[B<-signature filename>] -[B<-hmac key>] -[B<-non-fips-allow>] -[B<-fips-fingerprint>] -[B<file...>] - -B<openssl> -[I<digest>] -[B<...>] - -=head1 DESCRIPTION - -The digest functions output the message digest of a supplied file or files -in hexadecimal. The digest functions also generate and verify digital -signatures using message digests. - -=head1 OPTIONS - -=over 4 - -=item B<-c> - -print out the digest in two digit groups separated by colons, only relevant if -B<hex> format output is used. - -=item B<-d> - -print out BIO debugging information. - -=item B<-hex> - -digest is to be output as a hex dump. This is the default case for a "normal" -digest as opposed to a digital signature. See NOTES below for digital -signatures using B<-hex>. - -=item B<-binary> - -output the digest or signature in binary form. - -=item B<-r> - -output the digest in the "coreutils" format used by programs like B<sha1sum>. - -=item B<-non-fips-allow> - -Allow use of non FIPS digest when in FIPS mode. This has no effect when not in -FIPS mode. - -=item B<-out filename> - -filename to output to, or standard output by default. - -=item B<-sign filename> - -digitally sign the digest using the private key in "filename". - -=item B<-keyform arg> - -Specifies the key format to sign digest with. The DER, PEM, P12, -and ENGINE formats are supported. - -=item B<-engine id> - -Use engine B<id> for operations (including private key storage). -This engine is not used as source for digest algorithms, unless it is -also specified in the configuration file. - -=item B<-sigopt nm:v> - -Pass options to the signature algorithm during sign or verify operations. -Names and values of these options are algorithm-specific. - - -=item B<-passin arg> - -the private key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-verify filename> - -verify the signature using the the public key in "filename". -The output is either "Verification OK" or "Verification Failure". - -=item B<-prverify filename> - -verify the signature using the the private key in "filename". - -=item B<-signature filename> - -the actual signature to verify. - -=item B<-hmac key> - -create a hashed MAC using "key". - -=item B<-mac alg> - -create MAC (keyed Message Authentication Code). The most popular MAC -algorithm is HMAC (hash-based MAC), but there are other MAC algorithms -which are not based on hash, for instance B<gost-mac> algorithm, -supported by B<ccgost> engine. MAC keys and other options should be set -via B<-macopt> parameter. - -=item B<-macopt nm:v> - -Passes options to MAC algorithm, specified by B<-mac> key. -Following options are supported by both by B<HMAC> and B<gost-mac>: - -=over 8 - -=item B<key:string> - -Specifies MAC key as alphnumeric string (use if key contain printable -characters only). String length must conform to any restrictions of -the MAC algorithm for example exactly 32 chars for gost-mac. - -=item B<hexkey:string> - -Specifies MAC key in hexadecimal form (two hex digits per byte). -Key length must conform to any restrictions of the MAC algorithm -for example exactly 32 chars for gost-mac. - -=back - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-non-fips-allow> - -enable use of non-FIPS algorithms such as MD5 even in FIPS mode. - -=item B<-fips-fingerprint> - -compute HMAC using a specific key -for certain OpenSSL-FIPS operations. - -=item B<file...> - -file or files to digest. If no files are specified then standard input is -used. - -=back - - -=head1 EXAMPLES - -To create a hex-encoded message digest of a file: - openssl dgst -md5 -hex file.txt - -To sign a file using SHA-256 with binary file output: - openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt - -To verify a signature: - openssl dgst -sha256 -verify publickey.pem \ - -signature signature.sign \ - file.txt - - -=head1 NOTES - -The digest of choice for all new applications is SHA1. Other digests are -however still widely used. - -When signing a file, B<dgst> will automatically determine the algorithm -(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. -When verifying signatures, it only handles the RSA, DSA, or ECDSA signature -itself, not the related data to identify the signer and algorithm used in -formats such as x.509, CMS, and S/MIME. - -A source of random numbers is required for certain signing algorithms, in -particular ECDSA and DSA. - -The signing and verify options should only be used if a single file is -being signed or verified. - -Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r" -or similar program to transform the hex signature into a binary signature -prior to verification. - - -=cut diff --git a/openssl/doc/apps/dhparam.pod b/openssl/doc/apps/dhparam.pod deleted file mode 100644 index 1cd4c76..0000000 --- a/openssl/doc/apps/dhparam.pod +++ /dev/null @@ -1,149 +0,0 @@ -=pod - -=head1 NAME - -dhparam - DH parameter manipulation and generation - -=head1 SYNOPSIS - -B<openssl dhparam> -[B<-inform DER|PEM>] -[B<-outform DER|PEM>] -[B<-in> I<filename>] -[B<-out> I<filename>] -[B<-dsaparam>] -[B<-check>] -[B<-noout>] -[B<-text>] -[B<-C>] -[B<-2>] -[B<-5>] -[B<-rand> I<file(s)>] -[B<-engine id>] -[I<numbits>] - -=head1 DESCRIPTION - -This command is used to manipulate DH parameter files. - -=head1 OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B<DER> option uses an ASN1 DER encoded -form compatible with the PKCS#3 DHparameter structure. The PEM form is the -default format: it consists of the B<DER> format base64 encoded with -additional header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in> I<filename> - -This specifies the input filename to read parameters from or standard input if -this option is not specified. - -=item B<-out> I<filename> - -This specifies the output filename parameters to. Standard output is used -if this option is not present. The output filename should B<not> be the same -as the input filename. - -=item B<-dsaparam> - -If this option is used, DSA rather than DH parameters are read or created; -they are converted to DH format. Otherwise, "strong" primes (such -that (p-1)/2 is also prime) will be used for DH parameter generation. - -DH parameter generation with the B<-dsaparam> option is much faster, -and the recommended exponent length is shorter, which makes DH key -exchange more efficient. Beware that with such DSA-style DH -parameters, a fresh DH key should be created for each use to -avoid small-subgroup attacks that may be possible otherwise. - -=item B<-check> - -check if the parameters are valid primes and generator. - -=item B<-2>, B<-5> - -The generator to use, either 2 or 5. If present then the -input file is ignored and parameters are generated instead. If not -present but B<numbits> is present, parameters are generated with the -default generator 2. - -=item B<-rand> I<file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item I<numbits> - -this option specifies that a parameter set should be generated of size -I<numbits>. It must be the last option. If this option is present then -the input file is ignored and parameters are generated instead. If -this option is not present but a generator (B<-2> or B<-5>) is -present, parameters are generated with a default length of 2048 bits. - -=item B<-noout> - -this option inhibits the output of the encoded version of the parameters. - -=item B<-text> - -this option prints out the DH parameters in human readable form. - -=item B<-C> - -this option converts the parameters into C code. The parameters can then -be loaded by calling the B<get_dh>I<numbits>B<()> function. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<dhparam> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 WARNINGS - -The program B<dhparam> combines the functionality of the programs B<dh> and -B<gendh> in previous versions of OpenSSL and SSLeay. The B<dh> and B<gendh> -programs are retained for now but may have different purposes in future -versions of OpenSSL. - -=head1 NOTES - -PEM format DH parameters use the header and footer lines: - - -----BEGIN DH PARAMETERS----- - -----END DH PARAMETERS----- - -OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42 -DH. - -This program manipulates DH parameters not keys. - -=head1 BUGS - -There should be a way to generate and manipulate DH keys. - -=head1 SEE ALSO - -L<dsaparam(1)|dsaparam(1)> - -=head1 HISTORY - -The B<dhparam> command was added in OpenSSL 0.9.5. -The B<-dsaparam> option was added in OpenSSL 0.9.6. - -=cut diff --git a/openssl/doc/apps/dsa.pod b/openssl/doc/apps/dsa.pod deleted file mode 100644 index 8bf6cc9..0000000 --- a/openssl/doc/apps/dsa.pod +++ /dev/null @@ -1,164 +0,0 @@ -=pod - -=head1 NAME - -dsa - DSA key processing - -=head1 SYNOPSIS - -B<openssl> B<dsa> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-aes128>] -[B<-aes192>] -[B<-aes256>] -[B<-camellia128>] -[B<-camellia192>] -[B<-camellia256>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-text>] -[B<-noout>] -[B<-modulus>] -[B<-pubin>] -[B<-pubout>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<dsa> command processes DSA keys. They can be converted between various -forms and their components printed out. B<Note> This command uses the -traditional SSLeay compatible format for private key encryption: newer -applications should use the more secure PKCS#8 format using the B<pkcs8> - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B<DER> option with a private key uses -an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of -version (currently zero), p, q, g, the public and private key components -respectively as ASN.1 INTEGERs. When used with a public key it uses a -SubjectPublicKeyInfo structure: it is an error if the key is not DSA. - -The B<PEM> form is the default format: it consists of the B<DER> format base64 -encoded with additional header and footer lines. In the case of a private key -PKCS#8 format is also accepted. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read a key from or standard input if this -option is not specified. If the key is encrypted a pass phrase will be -prompted for. - -=item B<-passin arg> - -the input file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output by -is not specified. If any encryption options are set then a pass phrase will be -prompted for. The output filename should B<not> be the same as the input -filename. - -=item B<-passout arg> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> - -These options encrypt the private key with the specified -cipher before outputting it. A pass phrase is prompted for. -If none of these options is specified the key is written in plain text. This -means that using the B<dsa> utility to read in an encrypted key with no -encryption option can be used to remove the pass phrase from a key, or by -setting the encryption options it can be use to add or change the pass phrase. -These options can only be used with PEM format output files. - -=item B<-text> - -prints out the public, private key components and parameters. - -=item B<-noout> - -this option prevents output of the encoded version of the key. - -=item B<-modulus> - -this option prints out the value of the public key component of the key. - -=item B<-pubin> - -by default a private key is read from the input file: with this option a -public key is read instead. - -=item B<-pubout> - -by default a private key is output. With this option a public -key will be output instead. This option is automatically set if the input is -a public key. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<dsa> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 NOTES - -The PEM private key format uses the header and footer lines: - - -----BEGIN DSA PRIVATE KEY----- - -----END DSA PRIVATE KEY----- - -The PEM public key format uses the header and footer lines: - - -----BEGIN PUBLIC KEY----- - -----END PUBLIC KEY----- - -=head1 EXAMPLES - -To remove the pass phrase on a DSA private key: - - openssl dsa -in key.pem -out keyout.pem - -To encrypt a private key using triple DES: - - openssl dsa -in key.pem -des3 -out keyout.pem - -To convert a private key from PEM to DER format: - - openssl dsa -in key.pem -outform DER -out keyout.der - -To print out the components of a private key to standard output: - - openssl dsa -in key.pem -text -noout - -To just output the public part of a private key: - - openssl dsa -in key.pem -pubout -out pubkey.pem - -=head1 SEE ALSO - -L<dsaparam(1)|dsaparam(1)>, L<gendsa(1)|gendsa(1)>, L<rsa(1)|rsa(1)>, -L<genrsa(1)|genrsa(1)> - -=cut diff --git a/openssl/doc/apps/dsaparam.pod b/openssl/doc/apps/dsaparam.pod deleted file mode 100644 index ba5ec4d..0000000 --- a/openssl/doc/apps/dsaparam.pod +++ /dev/null @@ -1,110 +0,0 @@ -=pod - -=head1 NAME - -dsaparam - DSA parameter manipulation and generation - -=head1 SYNOPSIS - -B<openssl dsaparam> -[B<-inform DER|PEM>] -[B<-outform DER|PEM>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-text>] -[B<-C>] -[B<-rand file(s)>] -[B<-genkey>] -[B<-engine id>] -[B<numbits>] - -=head1 DESCRIPTION - -This command is used to manipulate or generate DSA parameter files. - -=head1 OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B<DER> option uses an ASN1 DER encoded -form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting -of p, q and g respectively. The PEM form is the default format: it consists -of the B<DER> format base64 encoded with additional header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read parameters from or standard input if -this option is not specified. If the B<numbits> parameter is included then -this option will be ignored. - -=item B<-out filename> - -This specifies the output filename parameters to. Standard output is used -if this option is not present. The output filename should B<not> be the same -as the input filename. - -=item B<-noout> - -this option inhibits the output of the encoded version of the parameters. - -=item B<-text> - -this option prints out the DSA parameters in human readable form. - -=item B<-C> - -this option converts the parameters into C code. The parameters can then -be loaded by calling the B<get_dsaXXX()> function. - -=item B<-genkey> - -this option will generate a DSA either using the specified or generated -parameters. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<numbits> - -this option specifies that a parameter set should be generated of size -B<numbits>. It must be the last option. If this option is included then -the input file (if any) is ignored. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<dsaparam> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 NOTES - -PEM format DSA parameters use the header and footer lines: - - -----BEGIN DSA PARAMETERS----- - -----END DSA PARAMETERS----- - -DSA parameter generation is a slow process and as a result the same set of -DSA parameters is often used to generate several distinct keys. - -=head1 SEE ALSO - -L<gendsa(1)|gendsa(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, -L<rsa(1)|rsa(1)> - -=cut diff --git a/openssl/doc/apps/ec.pod b/openssl/doc/apps/ec.pod deleted file mode 100644 index 5c7b45d..0000000 --- a/openssl/doc/apps/ec.pod +++ /dev/null @@ -1,190 +0,0 @@ -=pod - -=head1 NAME - -ec - EC key processing - -=head1 SYNOPSIS - -B<openssl> B<ec> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-text>] -[B<-noout>] -[B<-param_out>] -[B<-pubin>] -[B<-pubout>] -[B<-conv_form arg>] -[B<-param_enc arg>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<ec> command processes EC keys. They can be converted between various -forms and their components printed out. B<Note> OpenSSL uses the -private key format specified in 'SEC 1: Elliptic Curve Cryptography' -(http://www.secg.org/). To convert a OpenSSL EC private key into the -PKCS#8 private key format use the B<pkcs8> command. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B<DER> option with a private key uses -an ASN.1 DER encoded SEC1 private key. When used with a public key it -uses the SubjectPublicKeyInfo structure as specified in RFC 3280. -The B<PEM> form is the default format: it consists of the B<DER> format base64 -encoded with additional header and footer lines. In the case of a private key -PKCS#8 format is also accepted. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read a key from or standard input if this -option is not specified. If the key is encrypted a pass phrase will be -prompted for. - -=item B<-passin arg> - -the input file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output by -is not specified. If any encryption options are set then a pass phrase will be -prompted for. The output filename should B<not> be the same as the input -filename. - -=item B<-passout arg> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-des|-des3|-idea> - -These options encrypt the private key with the DES, triple DES, IDEA or -any other cipher supported by OpenSSL before outputting it. A pass phrase is -prompted for. -If none of these options is specified the key is written in plain text. This -means that using the B<ec> utility to read in an encrypted key with no -encryption option can be used to remove the pass phrase from a key, or by -setting the encryption options it can be use to add or change the pass phrase. -These options can only be used with PEM format output files. - -=item B<-text> - -prints out the public, private key components and parameters. - -=item B<-noout> - -this option prevents output of the encoded version of the key. - -=item B<-modulus> - -this option prints out the value of the public key component of the key. - -=item B<-pubin> - -by default a private key is read from the input file: with this option a -public key is read instead. - -=item B<-pubout> - -by default a private key is output. With this option a public -key will be output instead. This option is automatically set if the input is -a public key. - -=item B<-conv_form> - -This specifies how the points on the elliptic curve are converted -into octet strings. Possible values are: B<compressed> (the default -value), B<uncompressed> and B<hybrid>. For more information regarding -the point conversion forms please read the X9.62 standard. -B<Note> Due to patent issues the B<compressed> option is disabled -by default for binary curves and can be enabled by defining -the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time. - -=item B<-param_enc arg> - -This specifies how the elliptic curve parameters are encoded. -Possible value are: B<named_curve>, i.e. the ec parameters are -specified by a OID, or B<explicit> where the ec parameters are -explicitly given (see RFC 3279 for the definition of the -EC parameters structures). The default value is B<named_curve>. -B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279, -is currently not implemented in OpenSSL. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<ec> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 NOTES - -The PEM private key format uses the header and footer lines: - - -----BEGIN EC PRIVATE KEY----- - -----END EC PRIVATE KEY----- - -The PEM public key format uses the header and footer lines: - - -----BEGIN PUBLIC KEY----- - -----END PUBLIC KEY----- - -=head1 EXAMPLES - -To encrypt a private key using triple DES: - - openssl ec -in key.pem -des3 -out keyout.pem - -To convert a private key from PEM to DER format: - - openssl ec -in key.pem -outform DER -out keyout.der - -To print out the components of a private key to standard output: - - openssl ec -in key.pem -text -noout - -To just output the public part of a private key: - - openssl ec -in key.pem -pubout -out pubkey.pem - -To change the parameters encoding to B<explicit>: - - openssl ec -in key.pem -param_enc explicit -out keyout.pem - -To change the point conversion form to B<compressed>: - - openssl ec -in key.pem -conv_form compressed -out keyout.pem - -=head1 SEE ALSO - -L<ecparam(1)|ecparam(1)>, L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)> - -=head1 HISTORY - -The ec command was first introduced in OpenSSL 0.9.8. - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/openssl/doc/apps/ecparam.pod b/openssl/doc/apps/ecparam.pod deleted file mode 100644 index 88e9d1e..0000000 --- a/openssl/doc/apps/ecparam.pod +++ /dev/null @@ -1,179 +0,0 @@ -=pod - -=head1 NAME - -ecparam - EC parameter manipulation and generation - -=head1 SYNOPSIS - -B<openssl ecparam> -[B<-inform DER|PEM>] -[B<-outform DER|PEM>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-text>] -[B<-C>] -[B<-check>] -[B<-name arg>] -[B<-list_curves>] -[B<-conv_form arg>] -[B<-param_enc arg>] -[B<-no_seed>] -[B<-rand file(s)>] -[B<-genkey>] -[B<-engine id>] - -=head1 DESCRIPTION - -This command is used to manipulate or generate EC parameter files. - -=head1 OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B<DER> option uses an ASN.1 DER encoded -form compatible with RFC 3279 EcpkParameters. The PEM form is the default -format: it consists of the B<DER> format base64 encoded with additional -header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read parameters from or standard input if -this option is not specified. - -=item B<-out filename> - -This specifies the output filename parameters to. Standard output is used -if this option is not present. The output filename should B<not> be the same -as the input filename. - -=item B<-noout> - -This option inhibits the output of the encoded version of the parameters. - -=item B<-text> - -This option prints out the EC parameters in human readable form. - -=item B<-C> - -This option converts the EC parameters into C code. The parameters can then -be loaded by calling the B<get_ec_group_XXX()> function. - -=item B<-check> - -Validate the elliptic curve parameters. - -=item B<-name arg> - -Use the EC parameters with the specified 'short' name. Use B<-list_curves> -to get a list of all currently implemented EC parameters. - -=item B<-list_curves> - -If this options is specified B<ecparam> will print out a list of all -currently implemented EC parameters names and exit. - -=item B<-conv_form> - -This specifies how the points on the elliptic curve are converted -into octet strings. Possible values are: B<compressed> (the default -value), B<uncompressed> and B<hybrid>. For more information regarding -the point conversion forms please read the X9.62 standard. -B<Note> Due to patent issues the B<compressed> option is disabled -by default for binary curves and can be enabled by defining -the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time. - -=item B<-param_enc arg> - -This specifies how the elliptic curve parameters are encoded. -Possible value are: B<named_curve>, i.e. the ec parameters are -specified by a OID, or B<explicit> where the ec parameters are -explicitly given (see RFC 3279 for the definition of the -EC parameters structures). The default value is B<named_curve>. -B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279, -is currently not implemented in OpenSSL. - -=item B<-no_seed> - -This option inhibits that the 'seed' for the parameter generation -is included in the ECParameters structure (see RFC 3279). - -=item B<-genkey> - -This option will generate a EC private key using the specified parameters. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<ecparam> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 NOTES - -PEM format EC parameters use the header and footer lines: - - -----BEGIN EC PARAMETERS----- - -----END EC PARAMETERS----- - -OpenSSL is currently not able to generate new groups and therefore -B<ecparam> can only create EC parameters from known (named) curves. - -=head1 EXAMPLES - -To create EC parameters with the group 'prime192v1': - - openssl ecparam -out ec_param.pem -name prime192v1 - -To create EC parameters with explicit parameters: - - openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit - -To validate given EC parameters: - - openssl ecparam -in ec_param.pem -check - -To create EC parameters and a private key: - - openssl ecparam -out ec_key.pem -name prime192v1 -genkey - -To change the point encoding to 'compressed': - - openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed - -To print out the EC parameters to standard output: - - openssl ecparam -in ec_param.pem -noout -text - -=head1 SEE ALSO - -L<ec(1)|ec(1)>, L<dsaparam(1)|dsaparam(1)> - -=head1 HISTORY - -The ecparam command was first introduced in OpenSSL 0.9.8. - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org) - -=cut diff --git a/openssl/doc/apps/enc.pod b/openssl/doc/apps/enc.pod deleted file mode 100644 index 41791ad..0000000 --- a/openssl/doc/apps/enc.pod +++ /dev/null @@ -1,333 +0,0 @@ -=pod - -=head1 NAME - -enc - symmetric cipher routines - -=head1 SYNOPSIS - -B<openssl enc -ciphername> -[B<-in filename>] -[B<-out filename>] -[B<-pass arg>] -[B<-e>] -[B<-d>] -[B<-a/-base64>] -[B<-A>] -[B<-k password>] -[B<-kfile filename>] -[B<-K key>] -[B<-iv IV>] -[B<-S salt>] -[B<-salt>] -[B<-nosalt>] -[B<-z>] -[B<-md>] -[B<-p>] -[B<-P>] -[B<-bufsize number>] -[B<-nopad>] -[B<-debug>] -[B<-none>] -[B<-engine id>] - -=head1 DESCRIPTION - -The symmetric cipher commands allow data to be encrypted or decrypted -using various block and stream ciphers using keys based on passwords -or explicitly provided. Base64 encoding or decoding can also be performed -either by itself or in addition to the encryption or decryption. - -=head1 OPTIONS - -=over 4 - -=item B<-in filename> - -the input filename, standard input by default. - -=item B<-out filename> - -the output filename, standard output by default. - -=item B<-pass arg> - -the password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-salt> - -use a salt in the key derivation routines. This is the default. - -=item B<-nosalt> - -don't use a salt in the key derivation routines. This option B<SHOULD NOT> be -used except for test purposes or compatibility with ancient versions of OpenSSL -and SSLeay. - -=item B<-e> - -encrypt the input data: this is the default. - -=item B<-d> - -decrypt the input data. - -=item B<-a> - -base64 process the data. This means that if encryption is taking place -the data is base64 encoded after encryption. If decryption is set then -the input data is base64 decoded before being decrypted. - -=item B<-base64> - -same as B<-a> - -=item B<-A> - -if the B<-a> option is set then base64 process the data on one line. - -=item B<-k password> - -the password to derive the key from. This is for compatibility with previous -versions of OpenSSL. Superseded by the B<-pass> argument. - -=item B<-kfile filename> - -read the password to derive the key from the first line of B<filename>. -This is for compatibility with previous versions of OpenSSL. Superseded by -the B<-pass> argument. - -=item B<-nosalt> - -do not use a salt - -=item B<-salt> - -use salt (randomly generated or provide with B<-S> option) when -encrypting (this is the default). - -=item B<-S salt> - -the actual salt to use: this must be represented as a string of hex digits. - -=item B<-K key> - -the actual key to use: this must be represented as a string comprised only -of hex digits. If only the key is specified, the IV must additionally specified -using the B<-iv> option. When both a key and a password are specified, the -key given with the B<-K> option will be used and the IV generated from the -password will be taken. It probably does not make much sense to specify -both key and password. - -=item B<-iv IV> - -the actual IV to use: this must be represented as a string comprised only -of hex digits. When only the key is specified using the B<-K> option, the -IV must explicitly be defined. When a password is being specified using -one of the other options, the IV is generated from this password. - -=item B<-p> - -print out the key and IV used. - -=item B<-P> - -print out the key and IV used then immediately exit: don't do any encryption -or decryption. - -=item B<-bufsize number> - -set the buffer size for I/O - -=item B<-nopad> - -disable standard block padding - -=item B<-debug> - -debug the BIOs used for I/O. - -=item B<-z> - -Compress or decompress clear text using zlib before encryption or after -decryption. This option exists only if OpenSSL with compiled with zlib -or zlib-dynamic option. - -=item B<-none> - -Use NULL cipher (no encryption or decryption of input). - -=back - -=head1 NOTES - -The program can be called either as B<openssl ciphername> or -B<openssl enc -ciphername>. But the first form doesn't work with -engine-provided ciphers, because this form is processed before the -configuration file is read and any ENGINEs loaded. - -Engines which provide entirely new encryption algorithms (such as ccgost -engine which provides gost89 algorithm) should be configured in the -configuration file. Engines, specified in the command line using -engine -options can only be used for hadrware-assisted implementations of -ciphers, which are supported by OpenSSL core or other engine, specified -in the configuration file. - -When enc command lists supported ciphers, ciphers provided by engines, -specified in the configuration files are listed too. - -A password will be prompted for to derive the key and IV if necessary. - -The B<-salt> option should B<ALWAYS> be used if the key is being derived -from a password unless you want compatibility with previous versions of -OpenSSL and SSLeay. - -Without the B<-salt> option it is possible to perform efficient dictionary -attacks on the password and to attack stream cipher encrypted data. The reason -for this is that without the salt the same password always generates the same -encryption key. When the salt is being used the first eight bytes of the -encrypted data are reserved for the salt: it is generated at random when -encrypting a file and read from the encrypted file when it is decrypted. - -Some of the ciphers do not have large keys and others have security -implications if not used correctly. A beginner is advised to just use -a strong block cipher in CBC mode such as bf or des3. - -All the block ciphers normally use PKCS#5 padding also known as standard block -padding: this allows a rudimentary integrity or password check to be -performed. However since the chance of random data passing the test is -better than 1 in 256 it isn't a very good test. - -If padding is disabled then the input data must be a multiple of the cipher -block length. - -All RC2 ciphers have the same key and effective key length. - -Blowfish and RC5 algorithms use a 128 bit key. - -=head1 SUPPORTED CIPHERS - -Note that some of these ciphers can be disabled at compile time -and some are available only if an appropriate engine is configured -in the configuration file. The output of the B<enc> command run with -unsupported options (for example B<openssl enc -help>) includes a -list of ciphers, supported by your versesion of OpenSSL, including -ones provided by configured engines. - -The B<enc> program does not support authenticated encryption modes -like CCM and GCM. The utility does not store or retrieve the -authentication tag. - - - base64 Base 64 - - bf-cbc Blowfish in CBC mode - bf Alias for bf-cbc - bf-cfb Blowfish in CFB mode - bf-ecb Blowfish in ECB mode - bf-ofb Blowfish in OFB mode - - cast-cbc CAST in CBC mode - cast Alias for cast-cbc - cast5-cbc CAST5 in CBC mode - cast5-cfb CAST5 in CFB mode - cast5-ecb CAST5 in ECB mode - cast5-ofb CAST5 in OFB mode - - des-cbc DES in CBC mode - des Alias for des-cbc - des-cfb DES in CBC mode - des-ofb DES in OFB mode - des-ecb DES in ECB mode - - des-ede-cbc Two key triple DES EDE in CBC mode - des-ede Two key triple DES EDE in ECB mode - des-ede-cfb Two key triple DES EDE in CFB mode - des-ede-ofb Two key triple DES EDE in OFB mode - - des-ede3-cbc Three key triple DES EDE in CBC mode - des-ede3 Three key triple DES EDE in ECB mode - des3 Alias for des-ede3-cbc - des-ede3-cfb Three key triple DES EDE CFB mode - des-ede3-ofb Three key triple DES EDE in OFB mode - - desx DESX algorithm. - - gost89 GOST 28147-89 in CFB mode (provided by ccgost engine) - gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine) - - idea-cbc IDEA algorithm in CBC mode - idea same as idea-cbc - idea-cfb IDEA in CFB mode - idea-ecb IDEA in ECB mode - idea-ofb IDEA in OFB mode - - rc2-cbc 128 bit RC2 in CBC mode - rc2 Alias for rc2-cbc - rc2-cfb 128 bit RC2 in CFB mode - rc2-ecb 128 bit RC2 in ECB mode - rc2-ofb 128 bit RC2 in OFB mode - rc2-64-cbc 64 bit RC2 in CBC mode - rc2-40-cbc 40 bit RC2 in CBC mode - - rc4 128 bit RC4 - rc4-64 64 bit RC4 - rc4-40 40 bit RC4 - - rc5-cbc RC5 cipher in CBC mode - rc5 Alias for rc5-cbc - rc5-cfb RC5 cipher in CFB mode - rc5-ecb RC5 cipher in ECB mode - rc5-ofb RC5 cipher in OFB mode - - aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode - aes-[128|192|256] Alias for aes-[128|192|256]-cbc - aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode - aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode - aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode - aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode - aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode - -=head1 EXAMPLES - -Just base64 encode a binary file: - - openssl base64 -in file.bin -out file.b64 - -Decode the same file - - openssl base64 -d -in file.b64 -out file.bin - -Encrypt a file using triple DES in CBC mode using a prompted password: - - openssl des3 -salt -in file.txt -out file.des3 - -Decrypt a file using a supplied password: - - openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword - -Encrypt a file then base64 encode it (so it can be sent via mail for example) -using Blowfish in CBC mode: - - openssl bf -a -salt -in file.txt -out file.bf - -Base64 decode a file then decrypt it: - - openssl bf -d -salt -a -in file.bf -out file.txt - -Decrypt some data using a supplied 40 bit RC4 key: - - openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 - -=head1 BUGS - -The B<-A> option when used with large files doesn't work properly. - -There should be an option to allow an iteration count to be included. - -The B<enc> program only supports a fixed number of algorithms with -certain parameters. So if, for example, you want to use RC2 with a -76 bit key or RC4 with an 84 bit key you can't use this program. - -=cut diff --git a/openssl/doc/apps/errstr.pod b/openssl/doc/apps/errstr.pod deleted file mode 100644 index b3c6ccf..0000000 --- a/openssl/doc/apps/errstr.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -errstr - lookup error codes - -=head1 SYNOPSIS - -B<openssl errstr error_code> - -=head1 DESCRIPTION - -Sometimes an application will not load error message and only -numerical forms will be available. The B<errstr> utility can be used to -display the meaning of the hex code. The hex code is the hex digits after the -second colon. - -=head1 EXAMPLE - -The error code: - - 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107: - -can be displayed with: - - openssl errstr 2006D080 - -to produce the error message: - - error:2006D080:BIO routines:BIO_new_file:no such file - -=head1 SEE ALSO - -L<err(3)|err(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> - - -=cut diff --git a/openssl/doc/apps/gendsa.pod b/openssl/doc/apps/gendsa.pod deleted file mode 100644 index d9f56be..0000000 --- a/openssl/doc/apps/gendsa.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -gendsa - generate a DSA private key from a set of parameters - -=head1 SYNOPSIS - -B<openssl> B<gendsa> -[B<-out filename>] -[B<-aes128>] -[B<-aes192>] -[B<-aes256>] -[B<-camellia128>] -[B<-camellia192>] -[B<-camellia256>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-rand file(s)>] -[B<-engine id>] -[B<paramfile>] - -=head1 DESCRIPTION - -The B<gendsa> command generates a DSA private key from a DSA parameter file -(which will be typically generated by the B<openssl dsaparam> command). - -=head1 OPTIONS - -=over 4 - -=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> - -These options encrypt the private key with specified -cipher before outputting it. A pass phrase is prompted for. -If none of these options is specified no encryption is used. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<gendsa> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=item B<paramfile> - -This option specifies the DSA parameter file to use. The parameters in this -file determine the size of the private key. DSA parameters can be generated -and examined using the B<openssl dsaparam> command. - -=back - -=head1 NOTES - -DSA key generation is little more than random number generation so it is -much quicker that RSA key generation for example. - -=head1 SEE ALSO - -L<dsaparam(1)|dsaparam(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, -L<rsa(1)|rsa(1)> - -=cut diff --git a/openssl/doc/apps/genpkey.pod b/openssl/doc/apps/genpkey.pod deleted file mode 100644 index 929edcd..0000000 --- a/openssl/doc/apps/genpkey.pod +++ /dev/null @@ -1,228 +0,0 @@ -=pod - -=head1 NAME - -genpkey - generate a private key - -=head1 SYNOPSIS - -B<openssl> B<genpkey> -[B<-out filename>] -[B<-outform PEM|DER>] -[B<-pass arg>] -[B<-cipher>] -[B<-engine id>] -[B<-paramfile file>] -[B<-algorithm alg>] -[B<-pkeyopt opt:value>] -[B<-genparam>] -[B<-text>] - -=head1 DESCRIPTION - -The B<genpkey> command generates a private key. - -=head1 OPTIONS - -=over 4 - -=item B<-out filename> - -the output filename. If this argument is not specified then standard output is -used. - -=item B<-outform DER|PEM> - -This specifies the output format DER or PEM. - -=item B<-pass arg> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-cipher> - -This option encrypts the private key with the supplied cipher. Any algorithm -name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<genpkey> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. If used this option should precede all other -options. - -=item B<-algorithm alg> - -public key algorithm to use such as RSA, DSA or DH. If used this option must -precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> -are mutually exclusive. - -=item B<-pkeyopt opt:value> - -set the public key algorithm option B<opt> to B<value>. The precise set of -options supported depends on the public key algorithm used and its -implementation. See B<KEY GENERATION OPTIONS> below for more details. - -=item B<-genparam> - -generate a set of parameters instead of a private key. If used this option must -precede and B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. - -=item B<-paramfile filename> - -Some public key algorithms generate a private key based on a set of parameters. -They can be supplied using this option. If this option is used the public key -algorithm used is determined by the parameters. If used this option must -precede and B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> -are mutually exclusive. - -=item B<-text> - -Print an (unencrypted) text representation of private and public keys and -parameters along with the PEM or DER structure. - -=back - -=head1 KEY GENERATION OPTIONS - -The options supported by each algorith and indeed each implementation of an -algorithm can vary. The options for the OpenSSL implementations are detailed -below. - -=head1 RSA KEY GENERATION OPTIONS - -=over 4 - -=item B<rsa_keygen_bits:numbits> - -The number of bits in the generated key. If not specified 1024 is used. - -=item B<rsa_keygen_pubexp:value> - -The RSA public exponent value. This can be a large decimal or -hexadecimal value if preceded by B<0x>. Default value is 65537. - -=back - -=head1 DSA PARAMETER GENERATION OPTIONS - -=over 4 - -=item B<dsa_paramgen_bits:numbits> - -The number of bits in the generated parameters. If not specified 1024 is used. - -=back - -=head1 DH PARAMETER GENERATION OPTIONS - -=over 4 - -=item B<dh_paramgen_prime_len:numbits> - -The number of bits in the prime parameter B<p>. - -=item B<dh_paramgen_generator:value> - -The value to use for the generator B<g>. - -=item B<dh_rfc5114:num> - -If this option is set then the appropriate RFC5114 parameters are used -instead of generating new parameters. The value B<num> can take the -values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of -1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup -and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections -2.1, 2.2 and 2.3 respectively. - -=back - -=head1 EC PARAMETER GENERATION OPTIONS - -=over 4 - -=item B<ec_paramgen_curve:curve> - -the EC curve to use. - -=back - -=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS - -Gost 2001 support is not enabled by default. To enable this algorithm, -one should load the ccgost engine in the OpenSSL configuration file. -See README.gost file in the engines/ccgost directiry of the source -distribution for more details. - -Use of a parameter file for the GOST R 34.10 algorithm is optional. -Parameters can be specified during key generation directly as well as -during generation of parameter file. - -=over 4 - -=item B<paramset:name> - -Specifies GOST R 34.10-2001 parameter set according to RFC 4357. -Parameter set can be specified using abbreviated name, object short name or -numeric OID. Following parameter sets are supported: - - paramset OID Usage - A 1.2.643.2.2.35.1 Signature - B 1.2.643.2.2.35.2 Signature - C 1.2.643.2.2.35.3 Signature - XA 1.2.643.2.2.36.0 Key exchange - XB 1.2.643.2.2.36.1 Key exchange - test 1.2.643.2.2.35.0 Test purposes - -=back - - - -=head1 NOTES - -The use of the genpkey program is encouraged over the algorithm specific -utilities because additional algorithm options and ENGINE provided algorithms -can be used. - -=head1 EXAMPLES - -Generate an RSA private key using default parameters: - - openssl genpkey -algorithm RSA -out key.pem - -Encrypt output private key using 128 bit AES and the passphrase "hello": - - openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello - -Generate a 2048 bit RSA key using 3 as the public exponent: - - openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \ - -pkeyopt rsa_keygen_pubexp:3 - -Generate 1024 bit DSA parameters: - - openssl genpkey -genparam -algorithm DSA -out dsap.pem \ - -pkeyopt dsa_paramgen_bits:1024 - -Generate DSA key from parameters: - - openssl genpkey -paramfile dsap.pem -out dsakey.pem - -Generate 1024 bit DH parameters: - - openssl genpkey -genparam -algorithm DH -out dhp.pem \ - -pkeyopt dh_paramgen_prime_len:1024 - -Output RFC5114 2048 bit DH parameters with 224 bit subgroup: - - openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2 - -Generate DH key from parameters: - - openssl genpkey -paramfile dhp.pem -out dhkey.pem - - -=cut - diff --git a/openssl/doc/apps/genrsa.pod b/openssl/doc/apps/genrsa.pod deleted file mode 100644 index 3dc9870..0000000 --- a/openssl/doc/apps/genrsa.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -genrsa - generate an RSA private key - -=head1 SYNOPSIS - -B<openssl> B<genrsa> -[B<-out filename>] -[B<-passout arg>] -[B<-aes128>] -[B<-aes192>] -[B<-aes256>] -[B<-camellia128>] -[B<-camellia192>] -[B<-camellia256>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-f4>] -[B<-3>] -[B<-rand file(s)>] -[B<-engine id>] -[B<numbits>] - -=head1 DESCRIPTION - -The B<genrsa> command generates an RSA private key. - -=head1 OPTIONS - -=over 4 - -=item B<-out filename> - -the output filename. If this argument is not specified then standard output is -used. - -=item B<-passout arg> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> - -These options encrypt the private key with specified -cipher before outputting it. If none of these options is -specified no encryption is used. If encryption is used a pass phrase is prompted -for if it is not supplied via the B<-passout> argument. - -=item B<-F4|-3> - -the public exponent to use, either 65537 or 3. The default is 65537. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<genrsa> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=item B<numbits> - -the size of the private key to generate in bits. This must be the last option -specified. The default is 512. - -=back - -=head1 NOTES - -RSA private key generation essentially involves the generation of two prime -numbers. When generating a private key various symbols will be output to -indicate the progress of the generation. A B<.> represents each number which -has passed an initial sieve test, B<+> means a number has passed a single -round of the Miller-Rabin primality test. A newline means that the number has -passed all the prime tests (the actual number depends on the key size). - -Because key generation is a random process the time taken to generate a key -may vary somewhat. - -=head1 BUGS - -A quirk of the prime generation algorithm is that it cannot generate small -primes. Therefore the number of bits should not be less that 64. For typical -private keys this will not matter because for security reasons they will -be much larger (typically 1024 bits). - -=head1 SEE ALSO - -L<gendsa(1)|gendsa(1)> - -=cut - diff --git a/openssl/doc/apps/nseq.pod b/openssl/doc/apps/nseq.pod deleted file mode 100644 index 989c310..0000000 --- a/openssl/doc/apps/nseq.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -nseq - create or examine a netscape certificate sequence - -=head1 SYNOPSIS - -B<openssl> B<nseq> -[B<-in filename>] -[B<-out filename>] -[B<-toseq>] - -=head1 DESCRIPTION - -The B<nseq> command takes a file containing a Netscape certificate -sequence and prints out the certificates contained in it or takes a -file of certificates and converts it into a Netscape certificate -sequence. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read or standard input if this -option is not specified. - -=item B<-out filename> - -specifies the output filename or standard output by default. - -=item B<-toseq> - -normally a Netscape certificate sequence will be input and the output -is the certificates contained in it. With the B<-toseq> option the -situation is reversed: a Netscape certificate sequence is created from -a file of certificates. - -=back - -=head1 EXAMPLES - -Output the certificates in a Netscape certificate sequence - - openssl nseq -in nseq.pem -out certs.pem - -Create a Netscape certificate sequence - - openssl nseq -in certs.pem -toseq -out nseq.pem - -=head1 NOTES - -The B<PEM> encoded form uses the same headers and footers as a certificate: - - -----BEGIN CERTIFICATE----- - -----END CERTIFICATE----- - -A Netscape certificate sequence is a Netscape specific form that can be sent -to browsers as an alternative to the standard PKCS#7 format when several -certificates are sent to the browser: for example during certificate enrollment. -It is used by Netscape certificate server for example. - -=head1 BUGS - -This program needs a few more options: like allowing DER or PEM input and -output files and allowing multiple certificate files to be used. - -=cut diff --git a/openssl/doc/apps/ocsp.pod b/openssl/doc/apps/ocsp.pod deleted file mode 100644 index 1bb7958..0000000 --- a/openssl/doc/apps/ocsp.pod +++ /dev/null @@ -1,401 +0,0 @@ -=pod - -=head1 NAME - -ocsp - Online Certificate Status Protocol utility - -=head1 SYNOPSIS - -B<openssl> B<ocsp> -[B<-out file>] -[B<-issuer file>] -[B<-cert file>] -[B<-serial n>] -[B<-signer file>] -[B<-signkey file>] -[B<-sign_other file>] -[B<-no_certs>] -[B<-req_text>] -[B<-resp_text>] -[B<-text>] -[B<-reqout file>] -[B<-respout file>] -[B<-reqin file>] -[B<-respin file>] -[B<-nonce>] -[B<-no_nonce>] -[B<-url URL>] -[B<-host host:n>] -[B<-header name value>] -[B<-path>] -[B<-CApath dir>] -[B<-CAfile file>] -[B<-no_alt_chains>] -[B<-VAfile file>] -[B<-validity_period n>] -[B<-status_age n>] -[B<-noverify>] -[B<-verify_other file>] -[B<-trust_other>] -[B<-no_intern>] -[B<-no_signature_verify>] -[B<-no_cert_verify>] -[B<-no_chain>] -[B<-no_cert_checks>] -[B<-no_explicit>] -[B<-port num>] -[B<-index file>] -[B<-CA file>] -[B<-rsigner file>] -[B<-rkey file>] -[B<-rother file>] -[B<-resp_no_certs>] -[B<-nmin n>] -[B<-ndays n>] -[B<-resp_key_id>] -[B<-nrequest n>] -[B<-md5|-sha1|...>] - -=head1 DESCRIPTION - -The Online Certificate Status Protocol (OCSP) enables applications to -determine the (revocation) state of an identified certificate (RFC 2560). - -The B<ocsp> command performs many common OCSP tasks. It can be used -to print out requests and responses, create requests and send queries -to an OCSP responder and behave like a mini OCSP server itself. - -=head1 OCSP CLIENT OPTIONS - -=over 4 - -=item B<-out filename> - -specify output filename, default is standard output. - -=item B<-issuer filename> - -This specifies the current issuer certificate. This option can be used -multiple times. The certificate specified in B<filename> must be in -PEM format. This option B<MUST> come before any B<-cert> options. - -=item B<-cert filename> - -Add the certificate B<filename> to the request. The issuer certificate -is taken from the previous B<issuer> option, or an error occurs if no -issuer certificate is specified. - -=item B<-serial num> - -Same as the B<cert> option except the certificate with serial number -B<num> is added to the request. The serial number is interpreted as a -decimal integer unless preceded by B<0x>. Negative integers can also -be specified by preceding the value by a B<-> sign. - -=item B<-signer filename>, B<-signkey filename> - -Sign the OCSP request using the certificate specified in the B<signer> -option and the private key specified by the B<signkey> option. If -the B<signkey> option is not present then the private key is read -from the same file as the certificate. If neither option is specified then -the OCSP request is not signed. - -=item B<-sign_other filename> - -Additional certificates to include in the signed request. - -=item B<-nonce>, B<-no_nonce> - -Add an OCSP nonce extension to a request or disable OCSP nonce addition. -Normally if an OCSP request is input using the B<respin> option no -nonce is added: using the B<nonce> option will force addition of a nonce. -If an OCSP request is being created (using B<cert> and B<serial> options) -a nonce is automatically added specifying B<no_nonce> overrides this. - -=item B<-req_text>, B<-resp_text>, B<-text> - -print out the text form of the OCSP request, response or both respectively. - -=item B<-reqout file>, B<-respout file> - -write out the DER encoded certificate request or response to B<file>. - -=item B<-reqin file>, B<-respin file> - -read OCSP request or response file from B<file>. These option are ignored -if OCSP request or response creation is implied by other options (for example -with B<serial>, B<cert> and B<host> options). - -=item B<-url responder_url> - -specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. - -=item B<-host hostname:port>, B<-path pathname> - -if the B<host> option is present then the OCSP request is sent to the host -B<hostname> on port B<port>. B<path> specifies the HTTP path name to use -or "/" by default. - -=item B<-header name value> - -If sending a request to an OCSP server, then the specified header name and -value are added to the HTTP request. Note that the B<name> and B<value> must -be specified as two separate parameters, not as a single quoted string, and -that the header name does not have the trailing colon. -Some OCSP responders require a Host header; use this flag to provide it. - -=item B<-timeout seconds> - -connection timeout to the OCSP responder in seconds - -=item B<-CAfile file>, B<-CApath pathname> - -file or pathname containing trusted CA certificates. These are used to verify -the signature on the OCSP response. - -=item B<-no_alt_chains> - -See L<B<verify>|verify(1)> manual page for details. - -=item B<-verify_other file> - -file containing additional certificates to search when attempting to locate -the OCSP response signing certificate. Some responders omit the actual signer's -certificate from the response: this option can be used to supply the necessary -certificate in such cases. - -=item B<-trust_other> - -the certificates specified by the B<-verify_other> option should be explicitly -trusted and no additional checks will be performed on them. This is useful -when the complete responder certificate chain is not available or trusting a -root CA is not appropriate. - -=item B<-VAfile file> - -file containing explicitly trusted responder certificates. Equivalent to the -B<-verify_other> and B<-trust_other> options. - -=item B<-noverify> - -don't attempt to verify the OCSP response signature or the nonce values. This -option will normally only be used for debugging since it disables all verification -of the responders certificate. - -=item B<-no_intern> - -ignore certificates contained in the OCSP response when searching for the -signers certificate. With this option the signers certificate must be specified -with either the B<-verify_other> or B<-VAfile> options. - -=item B<-no_signature_verify> - -don't check the signature on the OCSP response. Since this option tolerates invalid -signatures on OCSP responses it will normally only be used for testing purposes. - -=item B<-no_cert_verify> - -don't verify the OCSP response signers certificate at all. Since this option allows -the OCSP response to be signed by any certificate it should only be used for -testing purposes. - -=item B<-no_chain> - -do not use certificates in the response as additional untrusted CA -certificates. - -=item B<-no_explicit> - -do not explicitly trust the root CA if it is set to be trusted for OCSP signing. - -=item B<-no_cert_checks> - -don't perform any additional checks on the OCSP response signers certificate. -That is do not make any checks to see if the signers certificate is authorised -to provide the necessary status information: as a result this option should -only be used for testing purposes. - -=item B<-validity_period nsec>, B<-status_age age> - -these options specify the range of times, in seconds, which will be tolerated -in an OCSP response. Each certificate status response includes a B<notBefore> time and -an optional B<notAfter> time. The current time should fall between these two values, but -the interval between the two times may be only a few seconds. In practice the OCSP -responder and clients clocks may not be precisely synchronised and so such a check -may fail. To avoid this the B<-validity_period> option can be used to specify an -acceptable error range in seconds, the default value is 5 minutes. - -If the B<notAfter> time is omitted from a response then this means that new status -information is immediately available. In this case the age of the B<notBefore> field -is checked to see it is not older than B<age> seconds old. By default this additional -check is not performed. - -=item B<-md5|-sha1|-sha256|-ripemod160|...> - -this option sets digest algorithm to use for certificate identification -in the OCSP request. By default SHA-1 is used. - -=back - -=head1 OCSP SERVER OPTIONS - -=over 4 - -=item B<-index indexfile> - -B<indexfile> is a text index file in B<ca> format containing certificate revocation -information. - -If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise -it is in client mode. The request(s) the responder processes can be either specified on -the command line (using B<issuer> and B<serial> options), supplied in a file (using the -B<respin> option) or via external OCSP clients (if B<port> or B<url> is specified). - -If the B<index> option is present then the B<CA> and B<rsigner> options must also be -present. - -=item B<-CA file> - -CA certificate corresponding to the revocation information in B<indexfile>. - -=item B<-rsigner file> - -The certificate to sign OCSP responses with. - -=item B<-rother file> - -Additional certificates to include in the OCSP response. - -=item B<-resp_no_certs> - -Don't include any certificates in the OCSP response. - -=item B<-resp_key_id> - -Identify the signer certificate using the key ID, default is to use the subject name. - -=item B<-rkey file> - -The private key to sign OCSP responses with: if not present the file specified in the -B<rsigner> option is used. - -=item B<-port portnum> - -Port to listen for OCSP requests on. The port may also be specified using the B<url> -option. - -=item B<-nrequest number> - -The OCSP server will exit after receiving B<number> requests, default unlimited. - -=item B<-nmin minutes>, B<-ndays days> - -Number of minutes or days when fresh revocation information is available: used in the -B<nextUpdate> field. If neither option is present then the B<nextUpdate> field is -omitted meaning fresh revocation information is immediately available. - -=back - -=head1 OCSP Response verification. - -OCSP Response follows the rules specified in RFC2560. - -Initially the OCSP responder certificate is located and the signature on -the OCSP request checked using the responder certificate's public key. - -Then a normal certificate verify is performed on the OCSP responder certificate -building up a certificate chain in the process. The locations of the trusted -certificates used to build the chain can be specified by the B<CAfile> -and B<CApath> options or they will be looked for in the standard OpenSSL -certificates directory. - -If the initial verify fails then the OCSP verify process halts with an -error. - -Otherwise the issuing CA certificate in the request is compared to the OCSP -responder certificate: if there is a match then the OCSP verify succeeds. - -Otherwise the OCSP responder certificate's CA is checked against the issuing -CA certificate in the request. If there is a match and the OCSPSigning -extended key usage is present in the OCSP responder certificate then the -OCSP verify succeeds. - -Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders -CA is checked to see if it is trusted for OCSP signing. If it is the OCSP -verify succeeds. - -If none of these checks is successful then the OCSP verify fails. - -What this effectively means if that if the OCSP responder certificate is -authorised directly by the CA it is issuing revocation information about -(and it is correctly configured) then verification will succeed. - -If the OCSP responder is a "global responder" which can give details about -multiple CAs and has its own separate certificate chain then its root -CA can be trusted for OCSP signing. For example: - - openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem - -Alternatively the responder certificate itself can be explicitly trusted -with the B<-VAfile> option. - -=head1 NOTES - -As noted, most of the verify options are for testing or debugging purposes. -Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global -VA') B<-VAfile> options need to be used. - -The OCSP server is only useful for test and demonstration purposes: it is -not really usable as a full OCSP responder. It contains only a very -simple HTTP request handling and can only handle the POST form of OCSP -queries. It also handles requests serially meaning it cannot respond to -new requests until it has processed the current one. The text index file -format of revocation is also inefficient for large quantities of revocation -data. - -It is possible to run the B<ocsp> application in responder mode via a CGI -script using the B<respin> and B<respout> options. - -=head1 EXAMPLES - -Create an OCSP request and write it to a file: - - openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der - -Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the -response to a file and print it out in text form - - openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \ - -url http://ocsp.myhost.com/ -resp_text -respout resp.der - -Read in an OCSP response and print out text form: - - openssl ocsp -respin resp.der -text - -OCSP server on port 8888 using a standard B<ca> configuration, and a separate -responder certificate. All requests and responses are printed to a file. - - openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem - -text -out log.txt - -As above but exit after processing one request: - - openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem - -nrequest 1 - -Query status information using internally generated request: - - openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem - -issuer demoCA/cacert.pem -serial 1 - -Query status information using request read from a file, write response to a -second file. - - openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem - -reqin req.der -respout resp.der - -=head1 HISTORY - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/openssl.pod b/openssl/doc/apps/openssl.pod deleted file mode 100644 index 64a160c..0000000 --- a/openssl/doc/apps/openssl.pod +++ /dev/null @@ -1,422 +0,0 @@ - -=pod - -=head1 NAME - -openssl - OpenSSL command line tool - -=head1 SYNOPSIS - -B<openssl> -I<command> -[ I<command_opts> ] -[ I<command_args> ] - -B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> | B<list-cipher-algorithms> | B<list-message-digest-algorithms> | B<list-public-key-algorithms>] - -B<openssl> B<no->I<XXX> [ I<arbitrary options> ] - -=head1 DESCRIPTION - -OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL -v2/v3) and Transport Layer Security (TLS v1) network protocols and related -cryptography standards required by them. - -The B<openssl> program is a command line tool for using the various -cryptography functions of OpenSSL's B<crypto> library from the shell. -It can be used for - - o Creation and management of private keys, public keys and parameters - o Public key cryptographic operations - o Creation of X.509 certificates, CSRs and CRLs - o Calculation of Message Digests - o Encryption and Decryption with Ciphers - o SSL/TLS Client and Server Tests - o Handling of S/MIME signed or encrypted mail - o Time Stamp requests, generation and verification - -=head1 COMMAND SUMMARY - -The B<openssl> program provides a rich variety of commands (I<command> in the -SYNOPSIS above), each of which often has a wealth of options and arguments -(I<command_opts> and I<command_args> in the SYNOPSIS). - -The pseudo-commands B<list-standard-commands>, B<list-message-digest-commands>, -and B<list-cipher-commands> output a list (one entry per line) of the names -of all standard commands, message digest commands, or cipher commands, -respectively, that are available in the present B<openssl> utility. - -The pseudo-commands B<list-cipher-algorithms> and -B<list-message-digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as: - - from => to - -The pseudo-command B<list-public-key-algorithms> lists all supported public -key algorithms. - -The pseudo-command B<no->I<XXX> tests whether a command of the -specified name is available. If no command named I<XXX> exists, it -returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1 -and prints I<XXX>. In both cases, the output goes to B<stdout> and -nothing is printed to B<stderr>. Additional command line arguments -are always ignored. Since for each cipher there is a command of the -same name, this provides an easy way for shell scripts to test for the -availability of ciphers in the B<openssl> program. (B<no->I<XXX> is -not able to detect pseudo-commands such as B<quit>, -B<list->I<...>B<-commands>, or B<no->I<XXX> itself.) - -=head2 STANDARD COMMANDS - -=over 10 - -=item L<B<asn1parse>|asn1parse(1)> - -Parse an ASN.1 sequence. - -=item L<B<ca>|ca(1)> - -Certificate Authority (CA) Management. - -=item L<B<ciphers>|ciphers(1)> - -Cipher Suite Description Determination. - -=item L<B<cms>|cms(1)> - -CMS (Cryptographic Message Syntax) utility - -=item L<B<crl>|crl(1)> - -Certificate Revocation List (CRL) Management. - -=item L<B<crl2pkcs7>|crl2pkcs7(1)> - -CRL to PKCS#7 Conversion. - -=item L<B<dgst>|dgst(1)> - -Message Digest Calculation. - -=item B<dh> - -Diffie-Hellman Parameter Management. -Obsoleted by L<B<dhparam>|dhparam(1)>. - -=item L<B<dhparam>|dhparam(1)> - -Generation and Management of Diffie-Hellman Parameters. Superseded by -L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)> - - -=item L<B<dsa>|dsa(1)> - -DSA Data Management. - -=item L<B<dsaparam>|dsaparam(1)> - -DSA Parameter Generation and Management. Superseded by -L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)> - -=item L<B<ec>|ec(1)> - -EC (Elliptic curve) key processing - -=item L<B<ecparam>|ecparam(1)> - -EC parameter manipulation and generation - -=item L<B<enc>|enc(1)> - -Encoding with Ciphers. - -=item L<B<engine>|engine(1)> - -Engine (loadble module) information and manipulation. - -=item L<B<errstr>|errstr(1)> - -Error Number to Error String Conversion. - -=item B<gendh> - -Generation of Diffie-Hellman Parameters. -Obsoleted by L<B<dhparam>|dhparam(1)>. - -=item L<B<gendsa>|gendsa(1)> - -Generation of DSA Private Key from Parameters. Superseded by -L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)> - -=item L<B<genpkey>|genpkey(1)> - -Generation of Private Key or Parameters. - -=item L<B<genrsa>|genrsa(1)> - -Generation of RSA Private Key. Superceded by L<B<genpkey>|genpkey(1)>. - -=item L<B<nseq>|nseq(1)> - -Create or examine a netscape certificate sequence - -=item L<B<ocsp>|ocsp(1)> - -Online Certificate Status Protocol utility. - -=item L<B<passwd>|passwd(1)> - -Generation of hashed passwords. - -=item L<B<pkcs12>|pkcs12(1)> - -PKCS#12 Data Management. - -=item L<B<pkcs7>|pkcs7(1)> - -PKCS#7 Data Management. - -=item L<B<pkey>|pkey(1)> - -Public and private key management. - -=item L<B<pkeyparam>|pkeyparam(1)> - -Public key algorithm parameter management. - -=item L<B<pkeyutl>|pkeyutl(1)> - -Public key algorithm cryptographic operation utility. - -=item L<B<rand>|rand(1)> - -Generate pseudo-random bytes. - -=item L<B<req>|req(1)> - -PKCS#10 X.509 Certificate Signing Request (CSR) Management. - -=item L<B<rsa>|rsa(1)> - -RSA key management. - - -=item L<B<rsautl>|rsautl(1)> - -RSA utility for signing, verification, encryption, and decryption. Superseded -by L<B<pkeyutl>|pkeyutl(1)> - -=item L<B<s_client>|s_client(1)> - -This implements a generic SSL/TLS client which can establish a transparent -connection to a remote server speaking SSL/TLS. It's intended for testing -purposes only and provides only rudimentary interface functionality but -internally uses mostly all functionality of the OpenSSL B<ssl> library. - -=item L<B<s_server>|s_server(1)> - -This implements a generic SSL/TLS server which accepts connections from remote -clients speaking SSL/TLS. It's intended for testing purposes only and provides -only rudimentary interface functionality but internally uses mostly all -functionality of the OpenSSL B<ssl> library. It provides both an own command -line oriented protocol for testing SSL functions and a simple HTTP response -facility to emulate an SSL/TLS-aware webserver. - -=item L<B<s_time>|s_time(1)> - -SSL Connection Timer. - -=item L<B<sess_id>|sess_id(1)> - -SSL Session Data Management. - -=item L<B<smime>|smime(1)> - -S/MIME mail processing. - -=item L<B<speed>|speed(1)> - -Algorithm Speed Measurement. - -=item L<B<spkac>|spkac(1)> - -SPKAC printing and generating utility - -=item L<B<ts>|ts(1)> - -Time Stamping Authority tool (client/server) - -=item L<B<verify>|verify(1)> - -X.509 Certificate Verification. - -=item L<B<version>|version(1)> - -OpenSSL Version Information. - -=item L<B<x509>|x509(1)> - -X.509 Certificate Data Management. - -=back - -=head2 MESSAGE DIGEST COMMANDS - -=over 10 - -=item B<md2> - -MD2 Digest - -=item B<md5> - -MD5 Digest - -=item B<mdc2> - -MDC2 Digest - -=item B<rmd160> - -RMD-160 Digest - -=item B<sha> - -SHA Digest - -=item B<sha1> - -SHA-1 Digest - -=item B<sha224> - -SHA-224 Digest - -=item B<sha256> - -SHA-256 Digest - -=item B<sha384> - -SHA-384 Digest - -=item B<sha512> - -SHA-512 Digest - -=back - -=head2 ENCODING AND CIPHER COMMANDS - -=over 10 - -=item B<base64> - -Base64 Encoding - -=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb> - -Blowfish Cipher - -=item B<cast cast-cbc> - -CAST Cipher - -=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb> - -CAST5 Cipher - -=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb> - -DES Cipher - -=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb> - -Triple-DES Cipher - -=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb> - -IDEA Cipher - -=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb> - -RC2 Cipher - -=item B<rc4> - -RC4 Cipher - -=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb> - -RC5 Cipher - -=back - -=head1 PASS PHRASE ARGUMENTS - -Several commands accept password arguments, typically using B<-passin> -and B<-passout> for input and output passwords respectively. These allow -the password to be obtained from a variety of sources. Both of these -options take a single argument whose format is described below. If no -password argument is given and a password is required then the user is -prompted to enter one: this will typically be read from the current -terminal with echoing turned off. - -=over 10 - -=item B<pass:password> - -the actual password is B<password>. Since the password is visible -to utilities (like 'ps' under Unix) this form should only be used -where security is not important. - -=item B<env:var> - -obtain the password from the environment variable B<var>. Since -the environment of other processes is visible on certain platforms -(e.g. ps under certain Unix OSes) this option should be used with caution. - -=item B<file:pathname> - -the first line of B<pathname> is the password. If the same B<pathname> -argument is supplied to B<-passin> and B<-passout> arguments then the first -line will be used for the input password and the next line for the output -password. B<pathname> need not refer to a regular file: it could for example -refer to a device or named pipe. - -=item B<fd:number> - -read the password from the file descriptor B<number>. This can be used to -send the data via a pipe for example. - -=item B<stdin> - -read the password from standard input. - -=back - -=head1 SEE ALSO - -L<asn1parse(1)|asn1parse(1)>, L<ca(1)|ca(1)>, L<config(5)|config(5)>, -L<crl(1)|crl(1)>, L<crl2pkcs7(1)|crl2pkcs7(1)>, L<dgst(1)|dgst(1)>, -L<dhparam(1)|dhparam(1)>, L<dsa(1)|dsa(1)>, L<dsaparam(1)|dsaparam(1)>, -L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, L<genpkey(1)|genpkey(1)>, -L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>, -L<passwd(1)|passwd(1)>, -L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>, -L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>, -L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>, -L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>, -L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>, -L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>, -L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)>, L<x509v3_config(5)|x509v3_config(5)> - -=head1 HISTORY - -The openssl(1) document appeared in OpenSSL 0.9.2. -The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3; -The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0; -the B<no->I<XXX> pseudo-commands were added in OpenSSL 0.9.5a. -For notes on the availability of other commands, see their individual -manual pages. - -=cut diff --git a/openssl/doc/apps/passwd.pod b/openssl/doc/apps/passwd.pod deleted file mode 100644 index f449825..0000000 --- a/openssl/doc/apps/passwd.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -passwd - compute password hashes - -=head1 SYNOPSIS - -B<openssl passwd> -[B<-crypt>] -[B<-1>] -[B<-apr1>] -[B<-salt> I<string>] -[B<-in> I<file>] -[B<-stdin>] -[B<-noverify>] -[B<-quiet>] -[B<-table>] -{I<password>} - -=head1 DESCRIPTION - -The B<passwd> command computes the hash of a password typed at -run-time or the hash of each password in a list. The password list is -taken from the named file for option B<-in file>, from stdin for -option B<-stdin>, or from the command line, or from the terminal otherwise. -The Unix standard algorithm B<crypt> and the MD5-based BSD password -algorithm B<1> and its Apache variant B<apr1> are available. - -=head1 OPTIONS - -=over 4 - -=item B<-crypt> - -Use the B<crypt> algorithm (default). - -=item B<-1> - -Use the MD5 based BSD password algorithm B<1>. - -=item B<-apr1> - -Use the B<apr1> algorithm (Apache variant of the BSD algorithm). - -=item B<-salt> I<string> - -Use the specified salt. -When reading a password from the terminal, this implies B<-noverify>. - -=item B<-in> I<file> - -Read passwords from I<file>. - -=item B<-stdin> - -Read passwords from B<stdin>. - -=item B<-noverify> - -Don't verify when reading a password from the terminal. - -=item B<-quiet> - -Don't output warnings when passwords given at the command line are truncated. - -=item B<-table> - -In the output list, prepend the cleartext password and a TAB character -to each password hash. - -=back - -=head1 EXAMPLES - -B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>. - -B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>. - -B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>. - -=cut diff --git a/openssl/doc/apps/pkcs12.pod b/openssl/doc/apps/pkcs12.pod deleted file mode 100644 index 7449848..0000000 --- a/openssl/doc/apps/pkcs12.pod +++ /dev/null @@ -1,368 +0,0 @@ - -=pod - -=head1 NAME - -pkcs12 - PKCS#12 file utility - -=head1 SYNOPSIS - -B<openssl> B<pkcs12> -[B<-export>] -[B<-chain>] -[B<-inkey filename>] -[B<-certfile filename>] -[B<-name name>] -[B<-caname name>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-nomacver>] -[B<-nocerts>] -[B<-clcerts>] -[B<-cacerts>] -[B<-nokeys>] -[B<-info>] -[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>] -[B<-noiter>] -[B<-maciter | -nomaciter | -nomac>] -[B<-twopass>] -[B<-descert>] -[B<-certpbe cipher>] -[B<-keypbe cipher>] -[B<-macalg digest>] -[B<-keyex>] -[B<-keysig>] -[B<-password arg>] -[B<-passin arg>] -[B<-passout arg>] -[B<-rand file(s)>] -[B<-CAfile file>] -[B<-CApath dir>] -[B<-CSP name>] - -=head1 DESCRIPTION - -The B<pkcs12> command allows PKCS#12 files (sometimes referred to as -PFX files) to be created and parsed. PKCS#12 files are used by several -programs including Netscape, MSIE and MS Outlook. - -=head1 COMMAND OPTIONS - -There are a lot of options the meaning of some depends of whether a PKCS#12 file -is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 -file can be created by using the B<-export> option (see below). - -=head1 PARSING OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies filename of the PKCS#12 file to be parsed. Standard input is used -by default. - -=item B<-out filename> - -The filename to write certificates and private keys to, standard output by -default. They are all written in PEM format. - -=item B<-passin arg> - -the PKCS#12 file (i.e. input file) password source. For more information about -the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in -L<openssl(1)|openssl(1)>. - -=item B<-passout arg> - -pass phrase source to encrypt any outputted private keys with. For more -information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section -in L<openssl(1)|openssl(1)>. - -=item B<-password arg> - -With -export, -password is equivalent to -passout. -Otherwise, -password is equivalent to -passin. - -=item B<-noout> - -this option inhibits output of the keys and certificates to the output file -version of the PKCS#12 file. - -=item B<-clcerts> - -only output client certificates (not CA certificates). - -=item B<-cacerts> - -only output CA certificates (not client certificates). - -=item B<-nocerts> - -no certificates at all will be output. - -=item B<-nokeys> - -no private keys will be output. - -=item B<-info> - -output additional information about the PKCS#12 file structure, algorithms used and -iteration counts. - -=item B<-des> - -use DES to encrypt private keys before outputting. - -=item B<-des3> - -use triple DES to encrypt private keys before outputting, this is the default. - -=item B<-idea> - -use IDEA to encrypt private keys before outputting. - -=item B<-aes128>, B<-aes192>, B<-aes256> - -use AES to encrypt private keys before outputting. - -=item B<-camellia128>, B<-camellia192>, B<-camellia256> - -use Camellia to encrypt private keys before outputting. - -=item B<-nodes> - -don't encrypt the private keys at all. - -=item B<-nomacver> - -don't attempt to verify the integrity MAC before reading the file. - -=item B<-twopass> - -prompt for separate integrity and encryption passwords: most software -always assumes these are the same so this option will render such -PKCS#12 files unreadable. - -=back - -=head1 FILE CREATION OPTIONS - -=over 4 - -=item B<-export> - -This option specifies that a PKCS#12 file will be created rather than -parsed. - -=item B<-out filename> - -This specifies filename to write the PKCS#12 file to. Standard output is used -by default. - -=item B<-in filename> - -The filename to read certificates and private keys from, standard input by -default. They must all be in PEM format. The order doesn't matter but one -private key and its corresponding certificate should be present. If additional -certificates are present they will also be included in the PKCS#12 file. - -=item B<-inkey filename> - -file to read private key from. If not present then a private key must be present -in the input file. - -=item B<-name friendlyname> - -This specifies the "friendly name" for the certificate and private key. This -name is typically displayed in list boxes by software importing the file. - -=item B<-certfile filename> - -A filename to read additional certificates from. - -=item B<-caname friendlyname> - -This specifies the "friendly name" for other certificates. This option may be -used multiple times to specify names for all certificates in the order they -appear. Netscape ignores friendly names on other certificates whereas MSIE -displays them. - -=item B<-pass arg>, B<-passout arg> - -the PKCS#12 file (i.e. output file) password source. For more information about -the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in -L<openssl(1)|openssl(1)>. - -=item B<-passin password> - -pass phrase source to decrypt any input private keys with. For more information -about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in -L<openssl(1)|openssl(1)>. - -=item B<-chain> - -if this option is present then an attempt is made to include the entire -certificate chain of the user certificate. The standard CA store is used -for this search. If the search fails it is considered a fatal error. - -=item B<-descert> - -encrypt the certificate using triple DES, this may render the PKCS#12 -file unreadable by some "export grade" software. By default the private -key is encrypted using triple DES and the certificate using 40 bit RC2. - -=item B<-keypbe alg>, B<-certpbe alg> - -these options allow the algorithm used to encrypt the private key and -certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name -can be used (see B<NOTES> section for more information). If a cipher name -(as output by the B<list-cipher-algorithms> command is specified then it -is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only -use PKCS#12 algorithms. - -=item B<-keyex|-keysig> - -specifies that the private key is to be used for key exchange or just signing. -This option is only interpreted by MSIE and similar MS software. Normally -"export grade" software will only allow 512 bit RSA keys to be used for -encryption purposes but arbitrary length keys for signing. The B<-keysig> -option marks the key for signing only. Signing only keys can be used for -S/MIME signing, authenticode (ActiveX control signing) and SSL client -authentication, however due to a bug only MSIE 5.0 and later support -the use of signing only keys for SSL client authentication. - -=item B<-macalg digest> - -specify the MAC digest algorithm. If not included them SHA1 will be used. - -=item B<-nomaciter>, B<-noiter> - -these options affect the iteration counts on the MAC and key algorithms. -Unless you wish to produce files compatible with MSIE 4.0 you should leave -these options alone. - -To discourage attacks by using large dictionaries of common passwords the -algorithm that derives keys from passwords can have an iteration count applied -to it: this causes a certain part of the algorithm to be repeated and slows it -down. The MAC is used to check the file integrity but since it will normally -have the same password as the keys and certificates it could also be attacked. -By default both MAC and encryption iteration counts are set to 2048, using -these options the MAC and encryption iteration counts can be set to 1, since -this reduces the file security you should not use these options unless you -really have to. Most software supports both MAC and key iteration counts. -MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> -option. - -=item B<-maciter> - -This option is included for compatibility with previous versions, it used -to be needed to use MAC iterations counts but they are now used by default. - -=item B<-nomac> - -don't attempt to provide the MAC integrity. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-CAfile file> - -CA storage as a file. - -=item B<-CApath dir> - -CA storage as a directory. This directory must be a standard certificate -directory: that is a hash of each subject name (using B<x509 -hash>) should be -linked to each certificate. - -=item B<-CSP name> - -write B<name> as a Microsoft CSP name. - -=back - -=head1 NOTES - -Although there are a large number of options most of them are very rarely -used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used -for PKCS#12 file creation B<-export> and B<-name> are also used. - -If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present -then all certificates will be output in the order they appear in the input -PKCS#12 files. There is no guarantee that the first certificate present is -the one corresponding to the private key. Certain software which requires -a private key and certificate and assumes the first certificate in the -file is the one corresponding to the private key: this may not always -be the case. Using the B<-clcerts> option will solve this problem by only -outputting the certificate corresponding to the private key. If the CA -certificates are required then they can be output to a separate file using -the B<-nokeys -cacerts> options to just output CA certificates. - -The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption -algorithms for private keys and certificates to be specified. Normally -the defaults are fine but occasionally software can't handle triple DES -encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can -be used to reduce the private key encryption to 40 bit RC2. A complete -description of all algorithms is contained in the B<pkcs8> manual page. - -=head1 EXAMPLES - -Parse a PKCS#12 file and output it to a file: - - openssl pkcs12 -in file.p12 -out file.pem - -Output only client certificates to a file: - - openssl pkcs12 -in file.p12 -clcerts -out file.pem - -Don't encrypt the private key: - - openssl pkcs12 -in file.p12 -out file.pem -nodes - -Print some info about a PKCS#12 file: - - openssl pkcs12 -in file.p12 -info -noout - -Create a PKCS#12 file: - - openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" - -Include some extra certificates: - - openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ - -certfile othercerts.pem - -=head1 BUGS - -Some would argue that the PKCS#12 standard is one big bug :-) - -Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation -routines. Under rare circumstances this could produce a PKCS#12 file encrypted -with an invalid key. As a result some PKCS#12 files which triggered this bug -from other implementations (MSIE or Netscape) could not be decrypted -by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could -not be decrypted by other implementations. The chances of producing such -a file are relatively small: less than 1 in 256. - -A side effect of fixing this bug is that any old invalidly encrypted PKCS#12 -files cannot no longer be parsed by the fixed version. Under such circumstances -the B<pkcs12> utility will report that the MAC is OK but fail with a decryption -error when extracting private keys. - -This problem can be resolved by extracting the private keys and certificates -from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12 -file from the keys and certificates using a newer version of OpenSSL. For example: - - old-openssl -in bad.p12 -out keycerts.pem - openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12 - -=head1 SEE ALSO - -L<pkcs8(1)|pkcs8(1)> - diff --git a/openssl/doc/apps/pkcs7.pod b/openssl/doc/apps/pkcs7.pod deleted file mode 100644 index acfb810..0000000 --- a/openssl/doc/apps/pkcs7.pod +++ /dev/null @@ -1,105 +0,0 @@ -=pod - -=head1 NAME - -pkcs7 - PKCS#7 utility - -=head1 SYNOPSIS - -B<openssl> B<pkcs7> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-print_certs>] -[B<-text>] -[B<-noout>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<pkcs7> command processes PKCS#7 files in DER or PEM format. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. B<DER> format is DER encoded PKCS#7 -v1.5 structure.B<PEM> (the default) is a base64 encoded version of -the DER form with header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read from or standard input if this -option is not specified. - -=item B<-out filename> - -specifies the output filename to write to or standard output by -default. - -=item B<-print_certs> - -prints out any certificates or CRLs contained in the file. They are -preceded by their subject and issuer names in one line format. - -=item B<-text> - -prints out certificates details in full rather than just subject and -issuer names. - -=item B<-noout> - -don't output the encoded version of the PKCS#7 structure (or certificates -is B<-print_certs> is set). - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<pkcs7> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 EXAMPLES - -Convert a PKCS#7 file from PEM to DER: - - openssl pkcs7 -in file.pem -outform DER -out file.der - -Output all certificates in a file: - - openssl pkcs7 -in file.pem -print_certs -out certs.pem - -=head1 NOTES - -The PEM PKCS#7 format uses the header and footer lines: - - -----BEGIN PKCS7----- - -----END PKCS7----- - -For compatibility with some CAs it will also accept: - - -----BEGIN CERTIFICATE----- - -----END CERTIFICATE----- - -=head1 RESTRICTIONS - -There is no option to print out all the fields of a PKCS#7 file. - -This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they -cannot currently parse, for example, the new CMS as described in RFC2630. - -=head1 SEE ALSO - -L<crl2pkcs7(1)|crl2pkcs7(1)> - -=cut diff --git a/openssl/doc/apps/pkcs8.pod b/openssl/doc/apps/pkcs8.pod deleted file mode 100644 index 6901f1f..0000000 --- a/openssl/doc/apps/pkcs8.pod +++ /dev/null @@ -1,255 +0,0 @@ -=pod - -=head1 NAME - -pkcs8 - PKCS#8 format private key conversion tool - -=head1 SYNOPSIS - -B<openssl> B<pkcs8> -[B<-topk8>] -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-noiter>] -[B<-nocrypt>] -[B<-nooct>] -[B<-embed>] -[B<-nsdb>] -[B<-v2 alg>] -[B<-v2prf alg>] -[B<-v1 alg>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<pkcs8> command processes private keys in PKCS#8 format. It can handle -both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo -format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-topk8> - -Normally a PKCS#8 private key is expected on input and a traditional format -private key will be written. With the B<-topk8> option the situation is -reversed: it reads a traditional format private key and writes a PKCS#8 -format key. - -=item B<-inform DER|PEM> - -This specifies the input format. If a PKCS#8 format key is expected on input -then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be -expected. Otherwise the B<DER> or B<PEM> format of the traditional format -private key is used. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read a key from or standard input if this -option is not specified. If the key is encrypted a pass phrase will be -prompted for. - -=item B<-passin arg> - -the input file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output by -default. If any encryption options are set then a pass phrase will be -prompted for. The output filename should B<not> be the same as the input -filename. - -=item B<-passout arg> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-nocrypt> - -PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo -structures using an appropriate password based encryption algorithm. With -this option an unencrypted PrivateKeyInfo structure is expected or output. -This option does not encrypt private keys at all and should only be used -when absolutely necessary. Certain software such as some versions of Java -code signing software used unencrypted private keys. - -=item B<-nooct> - -This option generates RSA private keys in a broken format that some software -uses. Specifically the private key should be enclosed in a OCTET STRING -but some software just includes the structure itself without the -surrounding OCTET STRING. - -=item B<-embed> - -This option generates DSA keys in a broken format. The DSA parameters are -embedded inside the PrivateKey structure. In this form the OCTET STRING -contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing -the parameters and an ASN1 INTEGER containing the private key. - -=item B<-nsdb> - -This option generates DSA keys in a broken format compatible with Netscape -private key databases. The PrivateKey contains a SEQUENCE consisting of -the public and private keys respectively. - -=item B<-v2 alg> - -This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8 -private keys are encrypted with the password based encryption algorithm -called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it -was the strongest encryption algorithm supported in PKCS#5 v1.5. Using -the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any -encryption algorithm such as 168 bit triple DES or 128 bit RC2 however -not many implementations support PKCS#5 v2.0 yet. If you are just using -private keys with OpenSSL then this doesn't matter. - -The B<alg> argument is the encryption algorithm to use, valid values include -B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used. - -=item B<-v2prf alg> - -This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value -values would be B<hmacWithSHA256>. If this option isn't set then the default -for the cipher is used or B<hmacWithSHA1> if there is no default. - -=item B<-v1 alg> - -This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete -list of possible algorithms is included below. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<pkcs8> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 NOTES - -The encrypted form of a PEM encode PKCS#8 files uses the following -headers and footers: - - -----BEGIN ENCRYPTED PRIVATE KEY----- - -----END ENCRYPTED PRIVATE KEY----- - -The unencrypted form uses: - - -----BEGIN PRIVATE KEY----- - -----END PRIVATE KEY----- - -Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration -counts are more secure that those encrypted using the traditional -SSLeay compatible formats. So if additional security is considered -important the keys should be converted. - -The default encryption is only 56 bits because this is the encryption -that most current implementations of PKCS#8 will support. - -Some software may use PKCS#12 password based encryption algorithms -with PKCS#8 format private keys: these are handled automatically -but there is no option to produce them. - -It is possible to write out DER encoded encrypted private keys in -PKCS#8 format because the encryption details are included at an ASN1 -level whereas the traditional format includes them at a PEM level. - -=head1 PKCS#5 v1.5 and PKCS#12 algorithms. - -Various algorithms can be used with the B<-v1> command line option, -including PKCS#5 v1.5 and PKCS#12. These are described in more detail -below. - -=over 4 - -=item B<PBE-MD2-DES PBE-MD5-DES> - -These algorithms were included in the original PKCS#5 v1.5 specification. -They only offer 56 bits of protection since they both use DES. - -=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES> - -These algorithms are not mentioned in the original PKCS#5 v1.5 specification -but they use the same key derivation algorithm and are supported by some -software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or -56 bit DES. - -=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40> - -These algorithms use the PKCS#12 password based encryption algorithm and -allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. - -=back - -=head1 EXAMPLES - -Convert a private from traditional to PKCS#5 v2.0 format using triple -DES: - - openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem - -Convert a private from traditional to PKCS#5 v2.0 format using AES with -256 bits in CBC mode and B<hmacWithSHA256> PRF: - - openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem - -Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm -(DES): - - openssl pkcs8 -in key.pem -topk8 -out enckey.pem - -Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm -(3DES): - - openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES - -Read a DER unencrypted PKCS#8 format private key: - - openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem - -Convert a private key from any PKCS#8 format to traditional format: - - openssl pkcs8 -in pk8.pem -out key.pem - -=head1 STANDARDS - -Test vectors from this PKCS#5 v2.0 implementation were posted to the -pkcs-tng mailing list using triple DES, DES and RC2 with high iteration -counts, several people confirmed that they could decrypt the private -keys produced and Therefore it can be assumed that the PKCS#5 v2.0 -implementation is reasonably accurate at least as far as these -algorithms are concerned. - -The format of PKCS#8 DSA (and other) private keys is not well documented: -it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA -PKCS#8 private key format complies with this standard. - -=head1 BUGS - -There should be an option that prints out the encryption algorithm -in use and other details such as the iteration count. - -PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private -key format for OpenSSL: for compatibility several of the utilities use -the old format at present. - -=head1 SEE ALSO - -L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/pkey.pod b/openssl/doc/apps/pkey.pod deleted file mode 100644 index 4851223..0000000 --- a/openssl/doc/apps/pkey.pod +++ /dev/null @@ -1,135 +0,0 @@ - -=pod - -=head1 NAME - -pkey - public or private key processing tool - -=head1 SYNOPSIS - -B<openssl> B<pkey> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-cipher>] -[B<-text>] -[B<-text_pub>] -[B<-noout>] -[B<-pubin>] -[B<-pubout>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<pkey> command processes public or private keys. They can be converted -between various forms and their components printed out. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format DER or PEM. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read a key from or standard input if this -option is not specified. If the key is encrypted a pass phrase will be -prompted for. - -=item B<-passin arg> - -the input file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output if this -option is not specified. If any encryption options are set then a pass phrase -will be prompted for. The output filename should B<not> be the same as the input -filename. - -=item B<-passout password> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-cipher> - -These options encrypt the private key with the supplied cipher. Any algorithm -name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. - -=item B<-text> - -prints out the various public or private key components in -plain text in addition to the encoded version. - -=item B<-text_pub> - -print out only public key components even if a private key is being processed. - -=item B<-noout> - -do not output the encoded version of the key. - -=item B<-pubin> - -by default a private key is read from the input file: with this -option a public key is read instead. - -=item B<-pubout> - -by default a private key is output: with this option a public -key will be output instead. This option is automatically set if -the input is a public key. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<pkey> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 EXAMPLES - -To remove the pass phrase on an RSA private key: - - openssl pkey -in key.pem -out keyout.pem - -To encrypt a private key using triple DES: - - openssl pkey -in key.pem -des3 -out keyout.pem - -To convert a private key from PEM to DER format: - - openssl pkey -in key.pem -outform DER -out keyout.der - -To print out the components of a private key to standard output: - - openssl pkey -in key.pem -text -noout - -To print out the public components of a private key to standard output: - - openssl pkey -in key.pem -text_pub -noout - -To just output the public part of a private key: - - openssl pkey -in key.pem -pubout -out pubkey.pem - -=head1 SEE ALSO - -L<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>, -L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/pkeyparam.pod b/openssl/doc/apps/pkeyparam.pod deleted file mode 100644 index 154f672..0000000 --- a/openssl/doc/apps/pkeyparam.pod +++ /dev/null @@ -1,69 +0,0 @@ - -=pod - -=head1 NAME - -pkeyparam - public key algorithm parameter processing tool - -=head1 SYNOPSIS - -B<openssl> B<pkeyparam> -[B<-in filename>] -[B<-out filename>] -[B<-text>] -[B<-noout>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<pkey> command processes public or private keys. They can be converted -between various forms and their components printed out. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read parameters from or standard input if -this option is not specified. - -=item B<-out filename> - -This specifies the output filename to write parameters to or standard output if -this option is not specified. - -=item B<-text> - -prints out the parameters in plain text in addition to the encoded version. - -=item B<-noout> - -do not output the encoded version of the parameters. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<pkeyparam> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 EXAMPLE - -Print out text version of parameters: - - openssl pkeyparam -in param.pem -text - -=head1 NOTES - -There are no B<-inform> or B<-outform> options for this command because only -PEM format is supported because the key type is determined by the PEM headers. - -=head1 SEE ALSO - -L<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>, -L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/pkeyutl.pod b/openssl/doc/apps/pkeyutl.pod deleted file mode 100644 index 5da347c..0000000 --- a/openssl/doc/apps/pkeyutl.pod +++ /dev/null @@ -1,235 +0,0 @@ -=pod - -=head1 NAME - -pkeyutl - public key algorithm utility - -=head1 SYNOPSIS - -B<openssl> B<pkeyutl> -[B<-in file>] -[B<-out file>] -[B<-sigfile file>] -[B<-inkey file>] -[B<-keyform PEM|DER>] -[B<-passin arg>] -[B<-peerkey file>] -[B<-peerform PEM|DER>] -[B<-pubin>] -[B<-certin>] -[B<-rev>] -[B<-sign>] -[B<-verify>] -[B<-verifyrecover>] -[B<-encrypt>] -[B<-decrypt>] -[B<-derive>] -[B<-pkeyopt opt:value>] -[B<-hexdump>] -[B<-asn1parse>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<pkeyutl> command can be used to perform public key operations using -any supported algorithm. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read data from or standard input -if this option is not specified. - -=item B<-out filename> - -specifies the output filename to write to or standard output by -default. - -=item B<-inkey file> - -the input key file, by default it should be a private key. - -=item B<-keyform PEM|DER> - -the key format PEM, DER or ENGINE. - -=item B<-passin arg> - -the input key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - - -=item B<-peerkey file> - -the peer key file, used by key derivation (agreement) operations. - -=item B<-peerform PEM|DER> - -the peer key format PEM, DER or ENGINE. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<pkeyutl> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - - -=item B<-pubin> - -the input file is a public key. - -=item B<-certin> - -the input is a certificate containing a public key. - -=item B<-rev> - -reverse the order of the input buffer. This is useful for some libraries -(such as CryptoAPI) which represent the buffer in little endian format. - -=item B<-sign> - -sign the input data and output the signed result. This requires -a private key. - -=item B<-verify> - -verify the input data against the signature file and indicate if the -verification succeeded or failed. - -=item B<-verifyrecover> - -verify the input data and output the recovered data. - -=item B<-encrypt> - -encrypt the input data using a public key. - -=item B<-decrypt> - -decrypt the input data using a private key. - -=item B<-derive> - -derive a shared secret using the peer key. - -=item B<-hexdump> - -hex dump the output data. - -=item B<-asn1parse> - -asn1parse the output data, this is useful when combined with the -B<-verifyrecover> option when an ASN1 structure is signed. - -=back - -=head1 NOTES - -The operations and options supported vary according to the key algorithm -and its implementation. The OpenSSL operations and options are indicated below. - -Unless otherwise mentioned all algorithms support the B<digest:alg> option -which specifies the digest in use for sign, verify and verifyrecover operations. -The value B<alg> should represent a digest name as used in the -EVP_get_digestbyname() function for example B<sha1>. -This value is used only for sanity-checking the lengths of data passed in to -the B<pkeyutl> and for creating the structures that make up the signature -(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures). -In case of RSA, ECDSA and DSA signatures, this utility -will not perform hashing on input data but rather use the data directly as -input of signature algorithm. Depending on key type, signature type and mode -of padding, the maximum acceptable lengths of input data differ. In general, -with RSA the signed data can't be longer than the key modulus, in case of ECDSA -and DSA the data shouldn't be longer than field size, otherwise it will be -silently truncated to field size. - -In other words, if the value of digest is B<sha1> the input should be 20 bytes -long binary encoding of SHA-1 hash function output. - -=head1 RSA ALGORITHM - -The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover -operations in general. Some padding modes only support some of these -operations however. - -=over 4 - -=item -B<rsa_padding_mode:mode> - -This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for -PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep> -for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS. - -In PKCS#1 padding if the message digest is not set then the supplied data is -signed or verified directly instead of using a B<DigestInfo> structure. If a -digest is set then the a B<DigestInfo> structure is used and its the length -must correspond to the digest type. - -For B<oeap> mode only encryption and decryption is supported. - -For B<x931> if the digest type is set it is used to format the block data -otherwise the first byte is used to specify the X9.31 digest ID. Sign, -verify and verifyrecover are can be performed in this mode. - -For B<pss> mode only sign and verify are supported and the digest type must be -specified. - -=item B<rsa_pss_saltlen:len> - -For B<pss> mode only this option specifies the salt length. Two special values -are supported: -1 sets the salt length to the digest length. When signing -2 -sets the salt length to the maximum permissible value. When verifying -2 causes -the salt length to be automatically determined based on the B<PSS> block -structure. - -=back - -=head1 DSA ALGORITHM - -The DSA algorithm supports signing and verification operations only. Currently -there are no additional options other than B<digest>. Only the SHA1 -digest can be used and this digest is assumed by default. - -=head1 DH ALGORITHM - -The DH algorithm only supports the derivation operation and no additional -options. - -=head1 EC ALGORITHM - -The EC algorithm supports sign, verify and derive operations. The sign and -verify operations use ECDSA and derive uses ECDH. Currently there are no -additional options other than B<digest>. Only the SHA1 digest can be used and -this digest is assumed by default. - -=head1 EXAMPLES - -Sign some data using a private key: - - openssl pkeyutl -sign -in file -inkey key.pem -out sig - -Recover the signed data (e.g. if an RSA key is used): - - openssl pkeyutl -verifyrecover -in sig -inkey key.pem - -Verify the signature (e.g. a DSA key): - - openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem - -Sign data using a message digest value (this is currently only valid for RSA): - - openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 - -Derive a shared secret value: - - openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret - -=head1 SEE ALSO - -L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)> -L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> diff --git a/openssl/doc/apps/rand.pod b/openssl/doc/apps/rand.pod deleted file mode 100644 index d1d213e..0000000 --- a/openssl/doc/apps/rand.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -rand - generate pseudo-random bytes - -=head1 SYNOPSIS - -B<openssl rand> -[B<-out> I<file>] -[B<-rand> I<file(s)>] -[B<-base64>] -[B<-hex>] -I<num> - -=head1 DESCRIPTION - -The B<rand> command outputs I<num> pseudo-random bytes after seeding -the random number generator once. As in other B<openssl> command -line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd> -in addition to the files given in the B<-rand> option. A new -I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough -seeding was obtained from these sources. - -=head1 OPTIONS - -=over 4 - -=item B<-out> I<file> - -Write to I<file> instead of standard output. - -=item B<-rand> I<file(s)> - -Use specified file or files or EGD socket (see L<RAND_egd(3)|RAND_egd(3)>) -for seeding the random number generator. -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-base64> - -Perform base64 encoding on the output. - -=item B<-hex> - -Show the output as a hex string. - -=back - -=head1 SEE ALSO - -L<RAND_bytes(3)|RAND_bytes(3)> - -=cut diff --git a/openssl/doc/apps/req.pod b/openssl/doc/apps/req.pod deleted file mode 100644 index 30653e5..0000000 --- a/openssl/doc/apps/req.pod +++ /dev/null @@ -1,680 +0,0 @@ - -=pod - -=head1 NAME - -req - PKCS#10 certificate request and certificate generating utility. - -=head1 SYNOPSIS - -B<openssl> B<req> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-text>] -[B<-pubkey>] -[B<-noout>] -[B<-verify>] -[B<-modulus>] -[B<-new>] -[B<-rand file(s)>] -[B<-newkey rsa:bits>] -[B<-newkey alg:file>] -[B<-nodes>] -[B<-key filename>] -[B<-keyform PEM|DER>] -[B<-keyout filename>] -[B<-keygen_engine id>] -[B<-[digest]>] -[B<-config filename>] -[B<-multivalue-rdn>] -[B<-x509>] -[B<-days n>] -[B<-set_serial n>] -[B<-asn1-kludge>] -[B<-no-asn1-kludge>] -[B<-newhdr>] -[B<-extensions section>] -[B<-reqexts section>] -[B<-utf8>] -[B<-nameopt>] -[B<-reqopt>] -[B<-subject>] -[B<-subj arg>] -[B<-batch>] -[B<-verbose>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<req> command primarily creates and processes certificate requests -in PKCS#10 format. It can additionally create self signed certificates -for use as root CAs for example. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B<DER> option uses an ASN1 DER encoded -form compatible with the PKCS#10. The B<PEM> form is the default format: it -consists of the B<DER> format base64 encoded with additional header and -footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read a request from or standard input -if this option is not specified. A request is only read if the creation -options (B<-new> and B<-newkey>) are not specified. - -=item B<-passin arg> - -the input file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-out filename> - -This specifies the output filename to write to or standard output by -default. - -=item B<-passout arg> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-text> - -prints out the certificate request in text form. - -=item B<-subject> - -prints out the request subject (or certificate subject if B<-x509> is -specified) - -=item B<-pubkey> - -outputs the public key. - -=item B<-noout> - -this option prevents output of the encoded version of the request. - -=item B<-modulus> - -this option prints out the value of the modulus of the public key -contained in the request. - -=item B<-verify> - -verifies the signature on the request. - -=item B<-new> - -this option generates a new certificate request. It will prompt -the user for the relevant field values. The actual fields -prompted for and their maximum and minimum sizes are specified -in the configuration file and any requested extensions. - -If the B<-key> option is not used it will generate a new RSA private -key using information specified in the configuration file. - -=item B<-subj arg> - -Replaces subject field of input request with specified data and outputs -modified request. The arg must be formatted as -I</type0=value0/type1=value1/type2=...>, -characters may be escaped by \ (backslash), no spaces are skipped. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-newkey arg> - -this option creates a new certificate request and a new private -key. The argument takes one of several forms. B<rsa:nbits>, where -B<nbits> is the number of bits, generates an RSA key B<nbits> -in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified, -the default key size, specified in the configuration file is used. - -All other algorithms support the B<-newkey alg:file> form, where file may be -an algorithm parameter file, created by the B<genpkey -genparam> command -or and X.509 certificate for a key with approriate algorithm. - -B<param:file> generates a key using the parameter file or certificate B<file>, -the algorithm is determined by the parameters. B<algname:file> use algorithm -B<algname> and parameter file B<file>: the two algorithms must match or an -error occurs. B<algname> just uses algorithm B<algname>, and parameters, -if neccessary should be specified via B<-pkeyopt> parameter. - -B<dsa:filename> generates a DSA key using the parameters -in the file B<filename>. B<ec:filename> generates EC key (usable both with -ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R -34.10-2001 key (requires B<ccgost> engine configured in the configuration -file). If just B<gost2001> is specified a parameter set should be -specified by B<-pkeyopt paramset:X> - - -=item B<-pkeyopt opt:value> - -set the public key algorithm option B<opt> to B<value>. The precise set of -options supported depends on the public key algorithm used and its -implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page -for more details. - -=item B<-key filename> - -This specifies the file to read the private key from. It also -accepts PKCS#8 format private keys for PEM format files. - -=item B<-keyform PEM|DER> - -the format of the private key file specified in the B<-key> -argument. PEM is the default. - -=item B<-keyout filename> - -this gives the filename to write the newly created private key to. -If this option is not specified then the filename present in the -configuration file is used. - -=item B<-nodes> - -if this option is specified then if a private key is created it -will not be encrypted. - -=item B<-[digest]> - -this specifies the message digest to sign the request with (such as -B<-md5>, B<-sha1>). This overrides the digest algorithm specified in -the configuration file. - -Some public key algorithms may override this choice. For instance, DSA -signatures always use SHA1, GOST R 34.10 signatures always use -GOST R 34.11-94 (B<-md_gost94>). - -=item B<-config filename> - -this allows an alternative configuration file to be specified, -this overrides the compile time filename or any specified in -the B<OPENSSL_CONF> environment variable. - -=item B<-subj arg> - -sets subject name for new request or supersedes the subject name -when processing a request. -The arg must be formatted as I</type0=value0/type1=value1/type2=...>, -characters may be escaped by \ (backslash), no spaces are skipped. - -=item B<-multivalue-rdn> - -this option causes the -subj argument to be interpreted with full -support for multivalued RDNs. Example: - -I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> - -If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. - -=item B<-x509> - -this option outputs a self signed certificate instead of a certificate -request. This is typically used to generate a test certificate or -a self signed root CA. The extensions added to the certificate -(if any) are specified in the configuration file. Unless specified -using the B<set_serial> option, a large random number will be used for -the serial number. - -=item B<-days n> - -when the B<-x509> option is being used this specifies the number of -days to certify the certificate for. The default is 30 days. - -=item B<-set_serial n> - -serial number to use when outputting a self signed certificate. This -may be specified as a decimal value or a hex value if preceded by B<0x>. -It is possible to use negative serial numbers but this is not recommended. - -=item B<-extensions section> - -=item B<-reqexts section> - -these options specify alternative sections to include certificate -extensions (if the B<-x509> option is present) or certificate -request extensions. This allows several different sections to -be used in the same configuration file to specify requests for -a variety of purposes. - -=item B<-utf8> - -this option causes field values to be interpreted as UTF8 strings, by -default they are interpreted as ASCII. This means that the field -values, whether prompted from a terminal or obtained from a -configuration file, must be valid UTF8 strings. - -=item B<-nameopt option> - -option which determines how the subject or issuer names are displayed. The -B<option> argument can be a single option or multiple options separated by -commas. Alternatively the B<-nameopt> switch may be used more than once to -set multiple options. See the L<x509(1)|x509(1)> manual page for details. - -=item B<-reqopt> - -customise the output format used with B<-text>. The B<option> argument can be -a single option or multiple options separated by commas. - -See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)> -command. - - -=item B<-asn1-kludge> - -by default the B<req> command outputs certificate requests containing -no attributes in the correct PKCS#10 format. However certain CAs will only -accept requests containing no attributes in an invalid form: this -option produces this invalid format. - -More precisely the B<Attributes> in a PKCS#10 certificate request -are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so -if no attributes are present then they should be encoded as an -empty B<SET OF>. The invalid form does not include the empty -B<SET OF> whereas the correct form does. - -It should be noted that very few CAs still require the use of this option. - -=item B<-no-asn1-kludge> - -Reverses effect of B<-asn1-kludge> - -=item B<-newhdr> - -Adds the word B<NEW> to the PEM file header and footer lines on the outputted -request. Some software (Netscape certificate server) and some CAs need this. - -=item B<-batch> - -non-interactive mode. - -=item B<-verbose> - -print extra details about the operations being performed. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<req> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=item B<-keygen_engine id> - -specifies an engine (by its unique B<id> string) which would be used -for key generation operations. - -=back - -=head1 CONFIGURATION FILE FORMAT - -The configuration options are specified in the B<req> section of -the configuration file. As with all configuration files if no -value is specified in the specific section (i.e. B<req>) then -the initial unnamed or B<default> section is searched too. - -The options available are described in detail below. - -=over 4 - -=item B<input_password output_password> - -The passwords for the input private key file (if present) and -the output private key file (if one will be created). The -command line options B<passin> and B<passout> override the -configuration file values. - -=item B<default_bits> - -Specifies the default key size in bits. - -This option is used in conjunction with the B<-new> option to generate -a new key. It can be overridden by specifying an explicit key size in -the B<-newkey> option. The smallest accepted key size is 512 bits. If -no key size is specified then 2048 bits is used. - -=item B<default_keyfile> - -This is the default filename to write a private key to. If not -specified the key is written to standard output. This can be -overridden by the B<-keyout> option. - -=item B<oid_file> - -This specifies a file containing additional B<OBJECT IDENTIFIERS>. -Each line of the file should consist of the numerical form of the -object identifier followed by white space then the short name followed -by white space and finally the long name. - -=item B<oid_section> - -This specifies a section in the configuration file containing extra -object identifiers. Each line should consist of the short name of the -object identifier followed by B<=> and the numerical form. The short -and long names are the same when this option is used. - -=item B<RANDFILE> - -This specifies a filename in which random number seed information is -placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -It is used for private key generation. - -=item B<encrypt_key> - -If this is set to B<no> then if a private key is generated it is -B<not> encrypted. This is equivalent to the B<-nodes> command line -option. For compatibility B<encrypt_rsa_key> is an equivalent option. - -=item B<default_md> - -This option specifies the digest algorithm to use. Possible values -include B<md5 sha1 mdc2>. If not present then MD5 is used. This -option can be overridden on the command line. - -=item B<string_mask> - -This option masks out the use of certain string types in certain -fields. Most users will not need to change this option. - -It can be set to several values B<default> which is also the default -option uses PrintableStrings, T61Strings and BMPStrings if the -B<pkix> value is used then only PrintableStrings and BMPStrings will -be used. This follows the PKIX recommendation in RFC2459. If the -B<utf8only> option is used then only UTF8Strings will be used: this -is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr> -option just uses PrintableStrings and T61Strings: certain software has -problems with BMPStrings and UTF8Strings: in particular Netscape. - -=item B<req_extensions> - -this specifies the configuration file section containing a list of -extensions to add to the certificate request. It can be overridden -by the B<-reqexts> command line switch. See the -L<x509v3_config(5)|x509v3_config(5)> manual page for details of the -extension section format. - -=item B<x509_extensions> - -this specifies the configuration file section containing a list of -extensions to add to certificate generated when the B<-x509> switch -is used. It can be overridden by the B<-extensions> command line switch. - -=item B<prompt> - -if set to the value B<no> this disables prompting of certificate fields -and just takes values from the config file directly. It also changes the -expected format of the B<distinguished_name> and B<attributes> sections. - -=item B<utf8> - -if set to the value B<yes> then field values to be interpreted as UTF8 -strings, by default they are interpreted as ASCII. This means that -the field values, whether prompted from a terminal or obtained from a -configuration file, must be valid UTF8 strings. - -=item B<attributes> - -this specifies the section containing any request attributes: its format -is the same as B<distinguished_name>. Typically these may contain the -challengePassword or unstructuredName types. They are currently ignored -by OpenSSL's request signing utilities but some CAs might want them. - -=item B<distinguished_name> - -This specifies the section containing the distinguished name fields to -prompt for when generating a certificate or certificate request. The format -is described in the next section. - -=back - -=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT - -There are two separate formats for the distinguished name and attribute -sections. If the B<prompt> option is set to B<no> then these sections -just consist of field names and values: for example, - - CN=My Name - OU=My Organization - emailAddress=someone@somewhere.org - -This allows external programs (e.g. GUI based) to generate a template file -with all the field names and values and just pass it to B<req>. An example -of this kind of configuration file is contained in the B<EXAMPLES> section. - -Alternatively if the B<prompt> option is absent or not set to B<no> then the -file contains field prompting information. It consists of lines of the form: - - fieldName="prompt" - fieldName_default="default field value" - fieldName_min= 2 - fieldName_max= 4 - -"fieldName" is the field name being used, for example commonName (or CN). -The "prompt" string is used to ask the user to enter the relevant -details. If the user enters nothing then the default value is used if no -default value is present then the field is omitted. A field can -still be omitted if a default value is present if the user just -enters the '.' character. - -The number of characters entered must be between the fieldName_min and -fieldName_max limits: there may be additional restrictions based -on the field being used (for example countryName can only ever be -two characters long and must fit in a PrintableString). - -Some fields (such as organizationName) can be used more than once -in a DN. This presents a problem because configuration files will -not recognize the same name occurring twice. To avoid this problem -if the fieldName contains some characters followed by a full stop -they will be ignored. So for example a second organizationName can -be input by calling it "1.organizationName". - -The actual permitted field names are any object identifier short or -long names. These are compiled into OpenSSL and include the usual -values such as commonName, countryName, localityName, organizationName, -organizationalUnitName, stateOrProvinceName. Additionally emailAddress -is include as well as name, surname, givenName initials and dnQualifier. - -Additional object identifiers can be defined with the B<oid_file> or -B<oid_section> options in the configuration file. Any additional fields -will be treated as though they were a DirectoryString. - - -=head1 EXAMPLES - -Examine and verify certificate request: - - openssl req -in req.pem -text -verify -noout - -Create a private key and then generate a certificate request from it: - - openssl genrsa -out key.pem 2048 - openssl req -new -key key.pem -out req.pem - -The same but just using req: - - openssl req -newkey rsa:2048 -keyout key.pem -out req.pem - -Generate a self signed root certificate: - - openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem - -Example of a file pointed to by the B<oid_file> option: - - 1.2.3.4 shortName A longer Name - 1.2.3.6 otherName Other longer Name - -Example of a section pointed to by B<oid_section> making use of variable -expansion: - - testoid1=1.2.3.5 - testoid2=${testoid1}.6 - -Sample configuration file prompting for field values: - - [ req ] - default_bits = 2048 - default_keyfile = privkey.pem - distinguished_name = req_distinguished_name - attributes = req_attributes - x509_extensions = v3_ca - - dirstring_type = nobmp - - [ req_distinguished_name ] - countryName = Country Name (2 letter code) - countryName_default = AU - countryName_min = 2 - countryName_max = 2 - - localityName = Locality Name (eg, city) - - organizationalUnitName = Organizational Unit Name (eg, section) - - commonName = Common Name (eg, YOUR name) - commonName_max = 64 - - emailAddress = Email Address - emailAddress_max = 40 - - [ req_attributes ] - challengePassword = A challenge password - challengePassword_min = 4 - challengePassword_max = 20 - - [ v3_ca ] - - subjectKeyIdentifier=hash - authorityKeyIdentifier=keyid:always,issuer:always - basicConstraints = CA:true - -Sample configuration containing all field values: - - - RANDFILE = $ENV::HOME/.rnd - - [ req ] - default_bits = 2048 - default_keyfile = keyfile.pem - distinguished_name = req_distinguished_name - attributes = req_attributes - prompt = no - output_password = mypass - - [ req_distinguished_name ] - C = GB - ST = Test State or Province - L = Test Locality - O = Organization Name - OU = Organizational Unit Name - CN = Common Name - emailAddress = test@email.address - - [ req_attributes ] - challengePassword = A challenge password - - -=head1 NOTES - -The header and footer lines in the B<PEM> format are normally: - - -----BEGIN CERTIFICATE REQUEST----- - -----END CERTIFICATE REQUEST----- - -some software (some versions of Netscape certificate server) instead needs: - - -----BEGIN NEW CERTIFICATE REQUEST----- - -----END NEW CERTIFICATE REQUEST----- - -which is produced with the B<-newhdr> option but is otherwise compatible. -Either form is accepted transparently on input. - -The certificate requests generated by B<Xenroll> with MSIE have extensions -added. It includes the B<keyUsage> extension which determines the type of -key (signature only or general purpose) and any additional OIDs entered -by the script in an extendedKeyUsage extension. - -=head1 DIAGNOSTICS - -The following messages are frequently asked about: - - Using configuration from /some/path/openssl.cnf - Unable to load config info - -This is followed some time later by... - - unable to find 'distinguished_name' in config - problems making Certificate Request - -The first error message is the clue: it can't find the configuration -file! Certain operations (like examining a certificate request) don't -need a configuration file so its use isn't enforced. Generation of -certificates or requests however does need a configuration file. This -could be regarded as a bug. - -Another puzzling message is this: - - Attributes: - a0:00 - -this is displayed when no attributes are present and the request includes -the correct empty B<SET OF> structure (the DER encoding of which is 0xa0 -0x00). If you just see: - - Attributes: - -then the B<SET OF> is missing and the encoding is technically invalid (but -it is tolerated). See the description of the command line option B<-asn1-kludge> -for more information. - -=head1 ENVIRONMENT VARIABLES - -The variable B<OPENSSL_CONF> if defined allows an alternative configuration -file location to be specified, it will be overridden by the B<-config> command -line switch if it is present. For compatibility reasons the B<SSLEAY_CONF> -environment variable serves the same purpose but its use is discouraged. - -=head1 BUGS - -OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively -treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. -This can cause problems if you need characters that aren't available in -PrintableStrings and you don't want to or can't use BMPStrings. - -As a consequence of the T61String handling the only correct way to represent -accented characters in OpenSSL is to use a BMPString: unfortunately Netscape -currently chokes on these. If you have to use accented characters with Netscape -and MSIE then you currently need to use the invalid T61String form. - -The current prompting is not very friendly. It doesn't allow you to confirm what -you've just entered. Other things like extensions in certificate requests are -statically defined in the configuration file. Some of these: like an email -address in subjectAltName should be input by the user. - -=head1 SEE ALSO - -L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>, -L<x509v3_config(5)|x509v3_config(5)> - -=cut diff --git a/openssl/doc/apps/rsa.pod b/openssl/doc/apps/rsa.pod deleted file mode 100644 index 21cbf8e..0000000 --- a/openssl/doc/apps/rsa.pod +++ /dev/null @@ -1,210 +0,0 @@ - -=pod - -=head1 NAME - -rsa - RSA key processing tool - -=head1 SYNOPSIS - -B<openssl> B<rsa> -[B<-inform PEM|NET|DER>] -[B<-outform PEM|NET|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-sgckey>] -[B<-aes128>] -[B<-aes192>] -[B<-aes256>] -[B<-camellia128>] -[B<-camellia192>] -[B<-camellia256>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[B<-text>] -[B<-noout>] -[B<-modulus>] -[B<-check>] -[B<-pubin>] -[B<-pubout>] -[B<-RSAPublicKey_in>] -[B<-RSAPublicKey_out>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<rsa> command processes RSA keys. They can be converted between various -forms and their components printed out. B<Note> this command uses the -traditional SSLeay compatible format for private key encryption: newer -applications should use the more secure PKCS#8 format using the B<pkcs8> -utility. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|NET|PEM> - -This specifies the input format. The B<DER> option uses an ASN1 DER encoded -form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format. -The B<PEM> form is the default format: it consists of the B<DER> format base64 -encoded with additional header and footer lines. On input PKCS#8 format private -keys are also accepted. The B<NET> form is a format is described in the B<NOTES> -section. - -=item B<-outform DER|NET|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read a key from or standard input if this -option is not specified. If the key is encrypted a pass phrase will be -prompted for. - -=item B<-passin arg> - -the input file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-out filename> - -This specifies the output filename to write a key to or standard output if this -option is not specified. If any encryption options are set then a pass phrase -will be prompted for. The output filename should B<not> be the same as the input -filename. - -=item B<-passout password> - -the output file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-sgckey> - -use the modified NET algorithm used with some versions of Microsoft IIS and SGC -keys. - -=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> - -These options encrypt the private key with the specified -cipher before outputting it. A pass phrase is prompted for. -If none of these options is specified the key is written in plain text. This -means that using the B<rsa> utility to read in an encrypted key with no -encryption option can be used to remove the pass phrase from a key, or by -setting the encryption options it can be use to add or change the pass phrase. -These options can only be used with PEM format output files. - -=item B<-text> - -prints out the various public or private key components in -plain text in addition to the encoded version. - -=item B<-noout> - -this option prevents output of the encoded version of the key. - -=item B<-modulus> - -this option prints out the value of the modulus of the key. - -=item B<-check> - -this option checks the consistency of an RSA private key. - -=item B<-pubin> - -by default a private key is read from the input file: with this -option a public key is read instead. - -=item B<-pubout> - -by default a private key is output: with this option a public -key will be output instead. This option is automatically set if -the input is a public key. - -=item B<-RSAPublicKey_in>, B<-RSAPublicKey_out> - -like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<rsa> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 NOTES - -The PEM private key format uses the header and footer lines: - - -----BEGIN RSA PRIVATE KEY----- - -----END RSA PRIVATE KEY----- - -The PEM public key format uses the header and footer lines: - - -----BEGIN PUBLIC KEY----- - -----END PUBLIC KEY----- - -The PEM B<RSAPublicKey> format uses the header and footer lines: - - -----BEGIN RSA PUBLIC KEY----- - -----END RSA PUBLIC KEY----- - -The B<NET> form is a format compatible with older Netscape servers -and Microsoft IIS .key files, this uses unsalted RC4 for its encryption. -It is not very secure and so should only be used when necessary. - -Some newer version of IIS have additional data in the exported .key -files. To use these with the utility, view the file with a binary editor -and look for the string "private-key", then trace back to the byte -sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data -from this point onwards to another file and use that as the input -to the B<rsa> utility with the B<-inform NET> option. If you get -an error after entering the password try the B<-sgckey> option. - -=head1 EXAMPLES - -To remove the pass phrase on an RSA private key: - - openssl rsa -in key.pem -out keyout.pem - -To encrypt a private key using triple DES: - - openssl rsa -in key.pem -des3 -out keyout.pem - -To convert a private key from PEM to DER format: - - openssl rsa -in key.pem -outform DER -out keyout.der - -To print out the components of a private key to standard output: - - openssl rsa -in key.pem -text -noout - -To just output the public part of a private key: - - openssl rsa -in key.pem -pubout -out pubkey.pem - -Output the public part of a private key in B<RSAPublicKey> format: - - openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem - -=head1 BUGS - -The command line password arguments don't currently work with -B<NET> format. - -There should be an option that automatically handles .key files, -without having to manually edit them. - -=head1 SEE ALSO - -L<pkcs8(1)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/rsautl.pod b/openssl/doc/apps/rsautl.pod deleted file mode 100644 index 1a498c2..0000000 --- a/openssl/doc/apps/rsautl.pod +++ /dev/null @@ -1,183 +0,0 @@ -=pod - -=head1 NAME - -rsautl - RSA utility - -=head1 SYNOPSIS - -B<openssl> B<rsautl> -[B<-in file>] -[B<-out file>] -[B<-inkey file>] -[B<-pubin>] -[B<-certin>] -[B<-sign>] -[B<-verify>] -[B<-encrypt>] -[B<-decrypt>] -[B<-pkcs>] -[B<-ssl>] -[B<-raw>] -[B<-hexdump>] -[B<-asn1parse>] - -=head1 DESCRIPTION - -The B<rsautl> command can be used to sign, verify, encrypt and decrypt -data using the RSA algorithm. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read data from or standard input -if this option is not specified. - -=item B<-out filename> - -specifies the output filename to write to or standard output by -default. - -=item B<-inkey file> - -the input key file, by default it should be an RSA private key. - -=item B<-pubin> - -the input file is an RSA public key. - -=item B<-certin> - -the input is a certificate containing an RSA public key. - -=item B<-sign> - -sign the input data and output the signed result. This requires -and RSA private key. - -=item B<-verify> - -verify the input data and output the recovered data. - -=item B<-encrypt> - -encrypt the input data using an RSA public key. - -=item B<-decrypt> - -decrypt the input data using an RSA private key. - -=item B<-pkcs, -oaep, -ssl, -raw> - -the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP, -special padding used in SSL v2 backwards compatible handshakes, -or no padding, respectively. -For signatures, only B<-pkcs> and B<-raw> can be used. - -=item B<-hexdump> - -hex dump the output data. - -=item B<-asn1parse> - -asn1parse the output data, this is useful when combined with the -B<-verify> option. - -=back - -=head1 NOTES - -B<rsautl> because it uses the RSA algorithm directly can only be -used to sign or verify small pieces of data. - -=head1 EXAMPLES - -Sign some data using a private key: - - openssl rsautl -sign -in file -inkey key.pem -out sig - -Recover the signed data - - openssl rsautl -verify -in sig -inkey key.pem - -Examine the raw signed data: - - openssl rsautl -verify -in file -inkey key.pem -raw -hexdump - - 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ - 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world - -The PKCS#1 block formatting is evident from this. If this was done using -encrypt and decrypt the block would have been of type 2 (the second byte) -and random padding data visible instead of the 0xff bytes. - -It is possible to analyse the signature of certificates using this -utility in conjunction with B<asn1parse>. Consider the self signed -example in certs/pca-cert.pem . Running B<asn1parse> as follows yields: - - openssl asn1parse -in pca-cert.pem - - 0:d=0 hl=4 l= 742 cons: SEQUENCE - 4:d=1 hl=4 l= 591 cons: SEQUENCE - 8:d=2 hl=2 l= 3 cons: cont [ 0 ] - 10:d=3 hl=2 l= 1 prim: INTEGER :02 - 13:d=2 hl=2 l= 1 prim: INTEGER :00 - 16:d=2 hl=2 l= 13 cons: SEQUENCE - 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption - 29:d=3 hl=2 l= 0 prim: NULL - 31:d=2 hl=2 l= 92 cons: SEQUENCE - 33:d=3 hl=2 l= 11 cons: SET - 35:d=4 hl=2 l= 9 cons: SEQUENCE - 37:d=5 hl=2 l= 3 prim: OBJECT :countryName - 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU - .... - 599:d=1 hl=2 l= 13 cons: SEQUENCE - 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption - 612:d=2 hl=2 l= 0 prim: NULL - 614:d=1 hl=3 l= 129 prim: BIT STRING - - -The final BIT STRING contains the actual signature. It can be extracted with: - - openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614 - -The certificate public key can be extracted with: - - openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem - -The signature can be analysed with: - - openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin - - 0:d=0 hl=2 l= 32 cons: SEQUENCE - 2:d=1 hl=2 l= 12 cons: SEQUENCE - 4:d=2 hl=2 l= 8 prim: OBJECT :md5 - 14:d=2 hl=2 l= 0 prim: NULL - 16:d=1 hl=2 l= 16 prim: OCTET STRING - 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%.. - -This is the parsed version of an ASN1 DigestInfo structure. It can be seen that -the digest used was md5. The actual part of the certificate that was signed can -be extracted with: - - openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4 - -and its digest computed with: - - openssl md5 -c tbs - MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5 - -which it can be seen agrees with the recovered value above. - -=head1 SEE ALSO - -L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> diff --git a/openssl/doc/apps/s_client.pod b/openssl/doc/apps/s_client.pod deleted file mode 100644 index 29675dd..0000000 --- a/openssl/doc/apps/s_client.pod +++ /dev/null @@ -1,370 +0,0 @@ - -=pod - -=head1 NAME - -s_client - SSL/TLS client program - -=head1 SYNOPSIS - -B<openssl> B<s_client> -[B<-connect host:port>] -[B<-servername name>] -[B<-verify depth>] -[B<-verify_return_error>] -[B<-cert filename>] -[B<-certform DER|PEM>] -[B<-key filename>] -[B<-keyform DER|PEM>] -[B<-pass arg>] -[B<-CApath directory>] -[B<-CAfile filename>] -[B<-no_alt_chains>] -[B<-reconnect>] -[B<-pause>] -[B<-showcerts>] -[B<-debug>] -[B<-msg>] -[B<-nbio_test>] -[B<-state>] -[B<-nbio>] -[B<-crlf>] -[B<-ign_eof>] -[B<-no_ign_eof>] -[B<-quiet>] -[B<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[B<-no_ssl2>] -[B<-no_ssl3>] -[B<-no_tls1>] -[B<-no_tls1_1>] -[B<-no_tls1_2>] -[B<-fallback_scsv>] -[B<-bugs>] -[B<-cipher cipherlist>] -[B<-serverpref>] -[B<-starttls protocol>] -[B<-engine id>] -[B<-tlsextdebug>] -[B<-no_ticket>] -[B<-sess_out filename>] -[B<-sess_in filename>] -[B<-rand file(s)>] -[B<-serverinfo types>] -[B<-status>] -[B<-alpn protocols>] -[B<-nextprotoneg protocols>] - -=head1 DESCRIPTION - -The B<s_client> command implements a generic SSL/TLS client which connects -to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for -SSL servers. - -=head1 OPTIONS - -=over 4 - -=item B<-connect host:port> - -This specifies the host and optional port to connect to. If not specified -then an attempt is made to connect to the local host on port 4433. - -=item B<-servername name> - -Set the TLS SNI (Server Name Indication) extension in the ClientHello message. - -=item B<-cert certname> - -The certificate to use, if one is requested by the server. The default is -not to use a certificate. - -=item B<-certform format> - -The certificate format to use: DER or PEM. PEM is the default. - -=item B<-key keyfile> - -The private key to use. If not specified then the certificate file will -be used. - -=item B<-keyform format> - -The private format to use: DER or PEM. PEM is the default. - -=item B<-pass arg> - -the private key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-verify depth> - -The verify depth to use. This specifies the maximum length of the -server certificate chain and turns on server certificate verification. -Currently the verify operation continues after errors so all the problems -with a certificate chain can be seen. As a side effect the connection -will never fail due to a server certificate verify failure. - -=item B<-verify_return_error> - -Return verification errors instead of continuing. This will typically -abort the handshake with a fatal error. - -=item B<-CApath directory> - -The directory to use for server certificate verification. This directory -must be in "hash format", see B<verify> for more information. These are -also used when building the client certificate chain. - -=item B<-CAfile file> - -A file containing trusted certificates to use during server authentication -and to use when attempting to build the client certificate chain. - -=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> - -Set various certificate chain valiadition option. See the -L<B<verify>|verify(1)> manual page for details. - -=item B<-reconnect> - -reconnects to the same server 5 times using the same session ID, this can -be used as a test that session caching is working. - -=item B<-pause> - -pauses 1 second between each read and write call. - -=item B<-showcerts> - -display the whole server certificate chain: normally only the server -certificate itself is displayed. - -=item B<-prexit> - -print session information when the program exits. This will always attempt -to print out information even if the connection fails. Normally information -will only be printed out once if the connection succeeds. This option is useful -because the cipher in use may be renegotiated or the connection may fail -because a client certificate is required or is requested only after an -attempt is made to access a certain URL. Note: the output produced by this -option is not always accurate because a connection might never have been -established. - -=item B<-state> - -prints out the SSL session states. - -=item B<-debug> - -print extensive debugging information including a hex dump of all traffic. - -=item B<-msg> - -show all protocol messages with hex dump. - -=item B<-nbio_test> - -tests non-blocking I/O - -=item B<-nbio> - -turns on non-blocking I/O - -=item B<-crlf> - -this option translated a line feed from the terminal into CR+LF as required -by some servers. - -=item B<-ign_eof> - -inhibit shutting down the connection when end of file is reached in the -input. - -=item B<-quiet> - -inhibit printing of session and certificate information. This implicitly -turns on B<-ign_eof> as well. - -=item B<-no_ign_eof> - -shut down the connection when end of file is reached in the input. -Can be used to override the implicit B<-ign_eof> after B<-quiet>. - -=item B<-psk_identity identity> - -Use the PSK identity B<identity> when using a PSK cipher suite. - -=item B<-psk key> - -Use the PSK key B<key> when using a PSK cipher suite. The key is -given as a hexadecimal number without leading 0x, for example -psk -1a2b3c4d. - -=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> - -These options require or disable the use of the specified SSL or TLS protocols. -By default the initial handshake uses a I<version-flexible> method which will -negotiate the highest mutually supported protocol version. - -=item B<-fallback_scsv> - -Send TLS_FALLBACK_SCSV in the ClientHello. - -=item B<-bugs> - -there are several known bug in SSL and TLS implementations. Adding this -option enables various workarounds. - -=item B<-cipher cipherlist> - -this allows the cipher list sent by the client to be modified. Although -the server determines which cipher suite is used it should take the first -supported cipher in the list sent by the client. See the B<ciphers> -command for more information. - -=item B<-serverpref> - -use the server's cipher preferences; only used for SSLV2. - -=item B<-starttls protocol> - -send the protocol-specific message(s) to switch to TLS for communication. -B<protocol> is a keyword for the intended protocol. Currently, the only -supported keywords are "smtp", "pop3", "imap", and "ftp". - -=item B<-tlsextdebug> - -print out a hex dump of any TLS extensions received from the server. - -=item B<-no_ticket> - -disable RFC4507bis session ticket support. - -=item B<-sess_out filename> - -output SSL session to B<filename> - -=item B<-sess_in sess.pem> - -load SSL session from B<filename>. The client will attempt to resume a -connection from this session. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<s_client> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-serverinfo types> - -a list of comma-separated TLS Extension Types (numbers between 0 and -65535). Each type will be sent as an empty ClientHello TLS Extension. -The server's response (if any) will be encoded and displayed as a PEM -file. - -=item B<-status> - -sends a certificate status request to the server (OCSP stapling). The server -response (if any) is printed out. - -=item B<-alpn protocols>, B<-nextprotoneg protocols> - -these flags enable the -Enable the Application-Layer Protocol Negotiation or Next Protocol -Negotiation extension, respectively. ALPN is the IETF standard and -replaces NPN. -The B<protocols> list is a -comma-separated protocol names that the client should advertise -support for. The list should contain most wanted protocols first. -Protocol names are printable ASCII strings, for example "http/1.1" or -"spdy/3". -Empty list of protocols is treated specially and will cause the client to -advertise support for the TLS extension but disconnect just after -reciving ServerHello with a list of server supported protocols. - -=back - -=head1 CONNECTED COMMANDS - -If a connection is established with an SSL server then any data received -from the server is displayed and any key presses will be sent to the -server. When used interactively (which means neither B<-quiet> nor B<-ign_eof> -have been given), the session will be renegotiated if the line begins with an -B<R>, and if the line begins with a B<Q> or if end of file is reached, the -connection will be closed down. - -=head1 NOTES - -B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP -server the command: - - openssl s_client -connect servername:443 - -would typically be used (https uses port 443). If the connection succeeds -then an HTTP command can be given such as "GET /" to retrieve a web page. - -If the handshake fails then there are several possible causes, if it is -nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, -B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> options can be tried -in case it is a buggy server. In particular you should play with these -options B<before> submitting a bug report to an OpenSSL mailing list. - -A frequent problem when attempting to get client certificates working -is that a web client complains it has no certificates or gives an empty -list to choose from. This is normally because the server is not sending -the clients certificate authority in its "acceptable CA list" when it -requests a certificate. By using B<s_client> the CA list can be viewed -and checked. However some servers only request client authentication -after a specific URL is requested. To obtain the list in this case it -is necessary to use the B<-prexit> option and send an HTTP request -for an appropriate page. - -If a certificate is specified on the command line using the B<-cert> -option it will not be used unless the server specifically requests -a client certificate. Therefor merely including a client certificate -on the command line is no guarantee that the certificate works. - -If there are problems verifying a server certificate then the -B<-showcerts> option can be used to show the whole chain. - -Since the SSLv23 client hello cannot include compression methods or extensions -these will only be supported if its use is disabled, for example by using the -B<-no_sslv2> option. - -The B<s_client> utility is a test tool and is designed to continue the -handshake after any certificate verification errors. As a result it will -accept any certificate chain (trusted or not) sent by the peer. None test -applications should B<not> do this as it makes them vulnerable to a MITM -attack. This behaviour can be changed by with the B<-verify_return_error> -option: any verify errors are then returned aborting the handshake. - -=head1 BUGS - -Because this program has a lot of options and also because some of -the techniques used are rather old, the C source of s_client is rather -hard to read and not a model of how things should be done. A typical -SSL client program would be much simpler. - -The B<-prexit> option is a bit of a hack. We should really report -information whenever a session is renegotiated. - -=head1 SEE ALSO - -L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> - -=head1 HISTORY - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/s_server.pod b/openssl/doc/apps/s_server.pod deleted file mode 100644 index fa17488..0000000 --- a/openssl/doc/apps/s_server.pod +++ /dev/null @@ -1,423 +0,0 @@ - -=pod - -=head1 NAME - -s_server - SSL/TLS server program - -=head1 SYNOPSIS - -B<openssl> B<s_server> -[B<-accept port>] -[B<-context id>] -[B<-verify depth>] -[B<-Verify depth>] -[B<-crl_check>] -[B<-crl_check_all>] -[B<-cert filename>] -[B<-certform DER|PEM>] -[B<-key keyfile>] -[B<-keyform DER|PEM>] -[B<-pass arg>] -[B<-dcert filename>] -[B<-dcertform DER|PEM>] -[B<-dkey keyfile>] -[B<-dkeyform DER|PEM>] -[B<-dpass arg>] -[B<-dhparam filename>] -[B<-nbio>] -[B<-nbio_test>] -[B<-crlf>] -[B<-debug>] -[B<-msg>] -[B<-state>] -[B<-CApath directory>] -[B<-CAfile filename>] -[B<-no_alt_chains>] -[B<-nocert>] -[B<-cipher cipherlist>] -[B<-serverpref>] -[B<-quiet>] -[B<-no_tmp_rsa>] -[B<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[B<-no_ssl2>] -[B<-no_ssl3>] -[B<-no_tls1>] -[B<-no_dhe>] -[B<-bugs>] -[B<-hack>] -[B<-www>] -[B<-WWW>] -[B<-HTTP>] -[B<-engine id>] -[B<-tlsextdebug>] -[B<-no_ticket>] -[B<-id_prefix arg>] -[B<-rand file(s)>] -[B<-serverinfo file>] -[B<-no_resumption_on_reneg>] -[B<-status>] -[B<-status_verbose>] -[B<-status_timeout nsec>] -[B<-status_url url>] -[B<-alpn protocols>] -[B<-nextprotoneg protocols>] - -=head1 DESCRIPTION - -The B<s_server> command implements a generic SSL/TLS server which listens -for connections on a given port using SSL/TLS. - -=head1 OPTIONS - -=over 4 - -=item B<-accept port> - -the TCP port to listen on for connections. If not specified 4433 is used. - -=item B<-context id> - -sets the SSL context id. It can be given any string value. If this option -is not present a default value will be used. - -=item B<-cert certname> - -The certificate to use, most servers cipher suites require the use of a -certificate and some require a certificate with a certain public key type: -for example the DSS cipher suites require a certificate containing a DSS -(DSA) key. If not specified then the filename "server.pem" will be used. - -=item B<-certform format> - -The certificate format to use: DER or PEM. PEM is the default. - -=item B<-key keyfile> - -The private key to use. If not specified then the certificate file will -be used. - -=item B<-keyform format> - -The private format to use: DER or PEM. PEM is the default. - -=item B<-pass arg> - -the private key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-dcert filename>, B<-dkey keyname> - -specify an additional certificate and private key, these behave in the -same manner as the B<-cert> and B<-key> options except there is no default -if they are not specified (no additional certificate and key is used). As -noted above some cipher suites require a certificate containing a key of -a certain type. Some cipher suites need a certificate carrying an RSA key -and some a DSS (DSA) key. By using RSA and DSS certificates and keys -a server can support clients which only support RSA or DSS cipher suites -by using an appropriate certificate. - -=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg> - -additional certificate and private key format and passphrase respectively. - -=item B<-nocert> - -if this option is set then no certificate is used. This restricts the -cipher suites available to the anonymous ones (currently just anonymous -DH). - -=item B<-dhparam filename> - -the DH parameter file to use. The ephemeral DH cipher suites generate keys -using a set of DH parameters. If not specified then an attempt is made to -load the parameters from the server certificate file. If this fails then -a static set of parameters hard coded into the s_server program will be used. - -=item B<-no_dhe> - -if this option is set then no DH parameters will be loaded effectively -disabling the ephemeral DH cipher suites. - -=item B<-no_tmp_rsa> - -certain export cipher suites sometimes use a temporary RSA key, this option -disables temporary RSA key generation. - -=item B<-verify depth>, B<-Verify depth> - -The verify depth to use. This specifies the maximum length of the -client certificate chain and makes the server request a certificate from -the client. With the B<-verify> option a certificate is requested but the -client does not have to send one, with the B<-Verify> option the client -must supply a certificate or an error occurs. - -If the ciphersuite cannot request a client certificate (for example an -anonymous ciphersuite or PSK) this option has no effect. - -=item B<-crl_check>, B<-crl_check_all> - -Check the peer certificate has not been revoked by its CA. -The CRL(s) are appended to the certificate file. With the B<-crl_check_all> -option all CRLs of all CAs in the chain are checked. - -=item B<-CApath directory> - -The directory to use for client certificate verification. This directory -must be in "hash format", see B<verify> for more information. These are -also used when building the server certificate chain. - -=item B<-CAfile file> - -A file containing trusted certificates to use during client authentication -and to use when attempting to build the server certificate chain. The list -is also used in the list of acceptable client CAs passed to the client when -a certificate is requested. - -=item B<-no_alt_chains> - -See the L<B<verify>|verify(1)> manual page for details. - -=item B<-state> - -prints out the SSL session states. - -=item B<-debug> - -print extensive debugging information including a hex dump of all traffic. - -=item B<-msg> - -show all protocol messages with hex dump. - -=item B<-nbio_test> - -tests non blocking I/O - -=item B<-nbio> - -turns on non blocking I/O - -=item B<-crlf> - -this option translated a line feed from the terminal into CR+LF. - -=item B<-quiet> - -inhibit printing of session and certificate information. - -=item B<-psk_hint hint> - -Use the PSK identity hint B<hint> when using a PSK cipher suite. - -=item B<-psk key> - -Use the PSK key B<key> when using a PSK cipher suite. The key is -given as a hexadecimal number without leading 0x, for example -psk -1a2b3c4d. - -=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> - -These options require or disable the use of the specified SSL or TLS protocols. -By default the initial handshake uses a I<version-flexible> method which will -negotiate the highest mutually supported protocol version. - -=item B<-bugs> - -there are several known bug in SSL and TLS implementations. Adding this -option enables various workarounds. - -=item B<-hack> - -this option enables a further workaround for some some early Netscape -SSL code (?). - -=item B<-cipher cipherlist> - -this allows the cipher list used by the server to be modified. When -the client sends a list of supported ciphers the first client cipher -also included in the server list is used. Because the client specifies -the preference order, the order of the server cipherlist irrelevant. See -the B<ciphers> command for more information. - -=item B<-serverpref> - -use the server's cipher preferences, rather than the client's preferences. - -=item B<-tlsextdebug> - -print out a hex dump of any TLS extensions received from the server. - -=item B<-no_ticket> - -disable RFC4507bis session ticket support. - -=item B<-www> - -sends a status message back to the client when it connects. This includes -lots of information about the ciphers used and various session parameters. -The output is in HTML format so this option will normally be used with a -web browser. - -=item B<-WWW> - -emulates a simple web server. Pages will be resolved relative to the -current directory, for example if the URL https://myhost/page.html is -requested the file ./page.html will be loaded. - -=item B<-HTTP> - -emulates a simple web server. Pages will be resolved relative to the -current directory, for example if the URL https://myhost/page.html is -requested the file ./page.html will be loaded. The files loaded are -assumed to contain a complete and correct HTTP response (lines that -are part of the HTTP response line and headers must end with CRLF). - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<s_server> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=item B<-id_prefix arg> - -generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful -for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple -servers, when each of which might be generating a unique range of session -IDs (eg. with a certain prefix). - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-serverinfo file> - -a file containing one or more blocks of PEM data. Each PEM block -must encode a TLS ServerHello extension (2 bytes type, 2 bytes length, -followed by "length" bytes of extension data). If the client sends -an empty TLS ClientHello extension matching the type, the corresponding -ServerHello extension will be returned. - -=item B<-no_resumption_on_reneg> - -set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. - -=item B<-status> - -enables certificate status request support (aka OCSP stapling). - -=item B<-status_verbose> - -enables certificate status request support (aka OCSP stapling) and gives -a verbose printout of the OCSP response. - -=item B<-status_timeout nsec> - -sets the timeout for OCSP response to B<nsec> seconds. - -=item B<-status_url url> - -sets a fallback responder URL to use if no responder URL is present in the -server certificate. Without this option an error is returned if the server -certificate does not contain a responder address. - -=item B<-alpn protocols>, B<-nextprotoneg protocols> - -these flags enable the -Enable the Application-Layer Protocol Negotiation or Next Protocol -Negotiation extension, respectively. ALPN is the IETF standard and -replaces NPN. -The B<protocols> list is a -comma-separated list of supported protocol names. -The list should contain most wanted protocols first. -Protocol names are printable ASCII strings, for example "http/1.1" or -"spdy/3". - -=back - -=head1 CONNECTED COMMANDS - -If a connection request is established with an SSL client and neither the -B<-www> nor the B<-WWW> option has been used then normally any data received -from the client is displayed and any key presses will be sent to the client. - -Certain single letter commands are also recognized which perform special -operations: these are listed below. - -=over 4 - -=item B<q> - -end the current SSL connection but still accept new connections. - -=item B<Q> - -end the current SSL connection and exit. - -=item B<r> - -renegotiate the SSL session. - -=item B<R> - -renegotiate the SSL session and request a client certificate. - -=item B<P> - -send some plain text down the underlying TCP connection: this should -cause the client to disconnect due to a protocol violation. - -=item B<S> - -print out some session cache status information. - -=back - -=head1 NOTES - -B<s_server> can be used to debug SSL clients. To accept connections from -a web browser the command: - - openssl s_server -accept 443 -www - -can be used for example. - -Most web browsers (in particular Netscape and MSIE) only support RSA cipher -suites, so they cannot connect to servers which don't use a certificate -carrying an RSA key or a version of OpenSSL with RSA disabled. - -Although specifying an empty list of CAs when requesting a client certificate -is strictly speaking a protocol violation, some SSL clients interpret this to -mean any CA is acceptable. This is useful for debugging purposes. - -The session parameters can printed out using the B<sess_id> program. - -=head1 BUGS - -Because this program has a lot of options and also because some of -the techniques used are rather old, the C source of s_server is rather -hard to read and not a model of how things should be done. A typical -SSL server program would be much simpler. - -The output of common ciphers is wrong: it just gives the list of ciphers that -OpenSSL recognizes and the client supports. - -There should be a way for the B<s_server> program to print out details of any -unknown cipher suites a client says it supports. - -=head1 SEE ALSO - -L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)> - -=head1 HISTORY - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/s_time.pod b/openssl/doc/apps/s_time.pod deleted file mode 100644 index 9082d87..0000000 --- a/openssl/doc/apps/s_time.pod +++ /dev/null @@ -1,173 +0,0 @@ - -=pod - -=head1 NAME - -s_time - SSL/TLS performance timing program - -=head1 SYNOPSIS - -B<openssl> B<s_time> -[B<-connect host:port>] -[B<-www page>] -[B<-cert filename>] -[B<-key filename>] -[B<-CApath directory>] -[B<-CAfile filename>] -[B<-reuse>] -[B<-new>] -[B<-verify depth>] -[B<-nbio>] -[B<-time seconds>] -[B<-ssl2>] -[B<-ssl3>] -[B<-bugs>] -[B<-cipher cipherlist>] - -=head1 DESCRIPTION - -The B<s_time> command implements a generic SSL/TLS client which connects to a -remote host using SSL/TLS. It can request a page from the server and includes -the time to transfer the payload data in its timing measurements. It measures -the number of connections within a given timeframe, the amount of data -transferred (if any), and calculates the average time spent for one connection. - -=head1 OPTIONS - -=over 4 - -=item B<-connect host:port> - -This specifies the host and optional port to connect to. - -=item B<-www page> - -This specifies the page to GET from the server. A value of '/' gets the -index.htm[l] page. If this parameter is not specified, then B<s_time> will only -perform the handshake to establish SSL connections but not transfer any -payload data. - -=item B<-cert certname> - -The certificate to use, if one is requested by the server. The default is -not to use a certificate. The file is in PEM format. - -=item B<-key keyfile> - -The private key to use. If not specified then the certificate file will -be used. The file is in PEM format. - -=item B<-verify depth> - -The verify depth to use. This specifies the maximum length of the -server certificate chain and turns on server certificate verification. -Currently the verify operation continues after errors so all the problems -with a certificate chain can be seen. As a side effect the connection -will never fail due to a server certificate verify failure. - -=item B<-CApath directory> - -The directory to use for server certificate verification. This directory -must be in "hash format", see B<verify> for more information. These are -also used when building the client certificate chain. - -=item B<-CAfile file> - -A file containing trusted certificates to use during server authentication -and to use when attempting to build the client certificate chain. - -=item B<-new> - -performs the timing test using a new session ID for each connection. -If neither B<-new> nor B<-reuse> are specified, they are both on by default -and executed in sequence. - -=item B<-reuse> - -performs the timing test using the same session ID; this can be used as a test -that session caching is working. If neither B<-new> nor B<-reuse> are -specified, they are both on by default and executed in sequence. - -=item B<-nbio> - -turns on non-blocking I/O. - -=item B<-ssl2>, B<-ssl3> - -these options disable the use of certain SSL or TLS protocols. By default -the initial handshake uses a method which should be compatible with all -servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. -The timing program is not as rich in options to turn protocols on and off as -the L<s_client(1)|s_client(1)> program and may not connect to all servers. - -Unfortunately there are a lot of ancient and broken servers in use which -cannot handle this technique and will fail to connect. Some servers only -work if TLS is turned off with the B<-ssl3> option; others -will only support SSL v2 and may need the B<-ssl2> option. - -=item B<-bugs> - -there are several known bug in SSL and TLS implementations. Adding this -option enables various workarounds. - -=item B<-cipher cipherlist> - -this allows the cipher list sent by the client to be modified. Although -the server determines which cipher suite is used it should take the first -supported cipher in the list sent by the client. -See the L<ciphers(1)|ciphers(1)> command for more information. - -=item B<-time length> - -specifies how long (in seconds) B<s_time> should establish connections and -optionally transfer payload data from a server. Server and client performance -and the link speed determine how many connections B<s_time> can establish. - -=back - -=head1 NOTES - -B<s_time> can be used to measure the performance of an SSL connection. -To connect to an SSL HTTP server and get the default page the command - - openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3] - -would typically be used (https uses port 443). 'commoncipher' is a cipher to -which both client and server can agree, see the L<ciphers(1)|ciphers(1)> command -for details. - -If the handshake fails then there are several possible causes, if it is -nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, -B<-ssl3> options can be tried -in case it is a buggy server. In particular you should play with these -options B<before> submitting a bug report to an OpenSSL mailing list. - -A frequent problem when attempting to get client certificates working -is that a web client complains it has no certificates or gives an empty -list to choose from. This is normally because the server is not sending -the clients certificate authority in its "acceptable CA list" when it -requests a certificate. By using L<s_client(1)|s_client(1)> the CA list can be -viewed and checked. However some servers only request client authentication -after a specific URL is requested. To obtain the list in this case it -is necessary to use the B<-prexit> option of L<s_client(1)|s_client(1)> and -send an HTTP request for an appropriate page. - -If a certificate is specified on the command line using the B<-cert> -option it will not be used unless the server specifically requests -a client certificate. Therefor merely including a client certificate -on the command line is no guarantee that the certificate works. - -=head1 BUGS - -Because this program does not have all the options of the -L<s_client(1)|s_client(1)> program to turn protocols on and off, you may not be -able to measure the performance of all protocols with all servers. - -The B<-verify> option should really exit if the server verification -fails. - -=head1 SEE ALSO - -L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> - -=cut diff --git a/openssl/doc/apps/sess_id.pod b/openssl/doc/apps/sess_id.pod deleted file mode 100644 index 9988d2c..0000000 --- a/openssl/doc/apps/sess_id.pod +++ /dev/null @@ -1,151 +0,0 @@ - -=pod - -=head1 NAME - -sess_id - SSL/TLS session handling utility - -=head1 SYNOPSIS - -B<openssl> B<sess_id> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-text>] -[B<-noout>] -[B<-context ID>] - -=head1 DESCRIPTION - -The B<sess_id> process the encoded version of the SSL session structure -and optionally prints out SSL session details (for example the SSL session -master key) in human readable format. Since this is a diagnostic tool that -needs some knowledge of the SSL protocol to use properly, most users will -not need to use it. - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B<DER> option uses an ASN1 DER encoded -format containing session details. The precise format can vary from one version -to the next. The B<PEM> form is the default format: it consists of the B<DER> -format base64 encoded with additional header and footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read session information from or standard -input by default. - -=item B<-out filename> - -This specifies the output filename to write session information to or standard -output if this option is not specified. - -=item B<-text> - -prints out the various public or private key components in -plain text in addition to the encoded version. - -=item B<-cert> - -if a certificate is present in the session it will be output using this option, -if the B<-text> option is also present then it will be printed out in text form. - -=item B<-noout> - -this option prevents output of the encoded version of the session. - -=item B<-context ID> - -this option can set the session id so the output session information uses the -supplied ID. The ID can be any string of characters. This option wont normally -be used. - -=back - -=head1 OUTPUT - -Typical output: - - SSL-Session: - Protocol : TLSv1 - Cipher : 0016 - Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED - Session-ID-ctx: 01000000 - Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD - Key-Arg : None - Start Time: 948459261 - Timeout : 300 (sec) - Verify return code 0 (ok) - -Theses are described below in more detail. - -=over 4 - -=item B<Protocol> - -this is the protocol in use TLSv1, SSLv3 or SSLv2. - -=item B<Cipher> - -the cipher used this is the actual raw SSL or TLS cipher code, see the SSL -or TLS specifications for more information. - -=item B<Session-ID> - -the SSL session ID in hex format. - -=item B<Session-ID-ctx> - -the session ID context in hex format. - -=item B<Master-Key> - -this is the SSL session master key. - -=item B<Key-Arg> - -the key argument, this is only used in SSL v2. - -=item B<Start Time> - -this is the session start time represented as an integer in standard Unix format. - -=item B<Timeout> - -the timeout in seconds. - -=item B<Verify return code> - -this is the return code when an SSL client certificate is verified. - -=back - -=head1 NOTES - -The PEM encoded session format uses the header and footer lines: - - -----BEGIN SSL SESSION PARAMETERS----- - -----END SSL SESSION PARAMETERS----- - -Since the SSL session output contains the master key it is possible to read the contents -of an encrypted session using this information. Therefore appropriate security precautions -should be taken if the information is being output by a "real" application. This is -however strongly discouraged and should only be used for debugging purposes. - -=head1 BUGS - -The cipher and start time should be printed out in human readable form. - -=head1 SEE ALSO - -L<ciphers(1)|ciphers(1)>, L<s_server(1)|s_server(1)> - -=cut diff --git a/openssl/doc/apps/smime.pod b/openssl/doc/apps/smime.pod deleted file mode 100644 index 04a83ca..0000000 --- a/openssl/doc/apps/smime.pod +++ /dev/null @@ -1,450 +0,0 @@ -=pod - -=head1 NAME - -smime - S/MIME utility - -=head1 SYNOPSIS - -B<openssl> B<smime> -[B<-encrypt>] -[B<-decrypt>] -[B<-sign>] -[B<-resign>] -[B<-verify>] -[B<-pk7out>] -[B<-[cipher]>] -[B<-in file>] -[B<-no_alt_chains>] -[B<-certfile file>] -[B<-signer file>] -[B<-recip file>] -[B<-inform SMIME|PEM|DER>] -[B<-passin arg>] -[B<-inkey file>] -[B<-out file>] -[B<-outform SMIME|PEM|DER>] -[B<-content file>] -[B<-to addr>] -[B<-from ad>] -[B<-subject s>] -[B<-text>] -[B<-indef>] -[B<-noindef>] -[B<-stream>] -[B<-rand file(s)>] -[B<-md digest>] -[cert.pem]... - -=head1 DESCRIPTION - -The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and -verify S/MIME messages. - -=head1 COMMAND OPTIONS - -There are six operation options that set the type of operation to be performed. -The meaning of the other options varies according to the operation type. - -=over 4 - -=item B<-encrypt> - -encrypt mail for the given recipient certificates. Input file is the message -to be encrypted. The output file is the encrypted mail in MIME format. - -Note that no revocation check is done for the recipient cert, so if that -key has been compromised, others may be able to decrypt the text. - -=item B<-decrypt> - -decrypt mail using the supplied certificate and private key. Expects an -encrypted mail message in MIME format for the input file. The decrypted mail -is written to the output file. - -=item B<-sign> - -sign mail using the supplied certificate and private key. Input file is -the message to be signed. The signed message in MIME format is written -to the output file. - -=item B<-verify> - -verify signed mail. Expects a signed mail message on input and outputs -the signed data. Both clear text and opaque signing is supported. - -=item B<-pk7out> - -takes an input message and writes out a PEM encoded PKCS#7 structure. - -=item B<-resign> - -resign a message: take an existing message and one or more new signers. - -=item B<-in filename> - -the input message to be encrypted or signed or the MIME message to -be decrypted or verified. - -=item B<-inform SMIME|PEM|DER> - -this specifies the input format for the PKCS#7 structure. The default -is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> -format change this to expect PEM and DER format PKCS#7 structures -instead. This currently only affects the input format of the PKCS#7 -structure, if no PKCS#7 structure is being input (for example with -B<-encrypt> or B<-sign>) this option has no effect. - -=item B<-out filename> - -the message text that has been decrypted or verified or the output MIME -format message that has been signed or verified. - -=item B<-outform SMIME|PEM|DER> - -this specifies the output format for the PKCS#7 structure. The default -is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> -format change this to write PEM and DER format PKCS#7 structures -instead. This currently only affects the output format of the PKCS#7 -structure, if no PKCS#7 structure is being output (for example with -B<-verify> or B<-decrypt>) this option has no effect. - -=item B<-stream -indef -noindef> - -the B<-stream> and B<-indef> options are equivalent and enable streaming I/O -for encoding operations. This permits single pass processing of data without -the need to hold the entire contents in memory, potentially supporting very -large files. Streaming is automatically set for S/MIME signing with detached -data if the output format is B<SMIME> it is currently off by default for all -other operations. - -=item B<-noindef> - -disable streaming I/O where it would produce and indefinite length constructed -encoding. This option currently has no effect. In future streaming will be -enabled by default on all relevant operations and this option will disable it. - -=item B<-content filename> - -This specifies a file containing the detached content, this is only -useful with the B<-verify> command. This is only usable if the PKCS#7 -structure is using the detached signature form where the content is -not included. This option will override any content if the input format -is S/MIME and it uses the multipart/signed MIME content type. - -=item B<-text> - -this option adds plain text (text/plain) MIME headers to the supplied -message if encrypting or signing. If decrypting or verifying it strips -off text headers: if the decrypted or verified message is not of MIME -type text/plain then an error occurs. - -=item B<-CAfile file> - -a file containing trusted CA certificates, only used with B<-verify>. - -=item B<-CApath dir> - -a directory containing trusted CA certificates, only used with -B<-verify>. This directory must be a standard certificate directory: that -is a hash of each subject name (using B<x509 -hash>) should be linked -to each certificate. - -=item B<-md digest> - -digest algorithm to use when signing or resigning. If not present then the -default digest algorithm for the signing key will be used (usually SHA1). - -=item B<-[cipher]> - -the encryption algorithm to use. For example DES (56 bits) - B<-des>, -triple DES (168 bits) - B<-des3>, -EVP_get_cipherbyname() function) can also be used preceded by a dash, for -example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers -supported by your version of OpenSSL. - -If not specified triple DES is used. Only used with B<-encrypt>. - -=item B<-nointern> - -when verifying a message normally certificates (if any) included in -the message are searched for the signing certificate. With this option -only the certificates specified in the B<-certfile> option are used. -The supplied certificates can still be used as untrusted CAs however. - -=item B<-noverify> - -do not verify the signers certificate of a signed message. - -=item B<-nochain> - -do not do chain verification of signers certificates: that is don't -use the certificates in the signed message as untrusted CAs. - -=item B<-nosigs> - -don't try to verify the signatures on the message. - -=item B<-nocerts> - -when signing a message the signer's certificate is normally included -with this option it is excluded. This will reduce the size of the -signed message but the verifier must have a copy of the signers certificate -available locally (passed using the B<-certfile> option for example). - -=item B<-noattr> - -normally when a message is signed a set of attributes are included which -include the signing time and supported symmetric algorithms. With this -option they are not included. - -=item B<-binary> - -normally the input message is converted to "canonical" format which is -effectively using CR and LF as end of line: as required by the S/MIME -specification. When this option is present no translation occurs. This -is useful when handling binary data which may not be in MIME format. - -=item B<-nodetach> - -when signing a message use opaque signing: this form is more resistant -to translation by mail relays but it cannot be read by mail agents that -do not support S/MIME. Without this option cleartext signing with -the MIME type multipart/signed is used. - -=item B<-certfile file> - -allows additional certificates to be specified. When signing these will -be included with the message. When verifying these will be searched for -the signers certificates. The certificates should be in PEM format. - -=item B<-signer file> - -a signing certificate when signing or resigning a message, this option can be -used multiple times if more than one signer is required. If a message is being -verified then the signers certificates will be written to this file if the -verification was successful. - -=item B<-recip file> - -the recipients certificate when decrypting a message. This certificate -must match one of the recipients of the message or an error occurs. - -=item B<-inkey file> - -the private key to use when signing or decrypting. This must match the -corresponding certificate. If this option is not specified then the -private key must be included in the certificate file specified with -the B<-recip> or B<-signer> file. When signing this option can be used -multiple times to specify successive keys. - -=item B<-passin arg> - -the private key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-rand file(s)> - -a file or files containing random data used to seed the random number -generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<cert.pem...> - -one or more certificates of message recipients: used when encrypting -a message. - -=item B<-to, -from, -subject> - -the relevant mail headers. These are included outside the signed -portion of a message so they may be included manually. If signing -then many S/MIME mail clients check the signers certificate's email -address matches that specified in the From: address. - -=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> - -Set various options of certificate chain verification. See -L<B<verify>|verify(1)> manual page for details. - -=back - -=head1 NOTES - -The MIME message must be sent without any blank lines between the -headers and the output. Some mail programs will automatically add -a blank line. Piping the mail directly to sendmail is one way to -achieve the correct format. - -The supplied message to be signed or encrypted must include the -necessary MIME headers or many S/MIME clients wont display it -properly (if at all). You can use the B<-text> option to automatically -add plain text headers. - -A "signed and encrypted" message is one where a signed message is -then encrypted. This can be produced by encrypting an already signed -message: see the examples section. - -This version of the program only allows one signer per message but it -will verify multiple signers on received messages. Some S/MIME clients -choke if a message contains multiple signers. It is possible to sign -messages "in parallel" by signing an already signed message. - -The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME -clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 -encrypted data is used for other purposes. - -The B<-resign> option uses an existing message digest when adding a new -signer. This means that attributes must be present in at least one existing -signer using the same message digest or this operation will fail. - -The B<-stream> and B<-indef> options enable experimental streaming I/O support. -As a result the encoding is BER using indefinite length constructed encoding -and no longer DER. Streaming is supported for the B<-encrypt> operation and the -B<-sign> operation if the content is not detached. - -Streaming is always used for the B<-sign> operation with detached data but -since the content is no longer part of the PKCS#7 structure the encoding -remains DER. - -=head1 EXIT CODES - -=over 4 - -=item Z<>0 - -the operation was completely successfully. - -=item Z<>1 - -an error occurred parsing the command options. - -=item Z<>2 - -one of the input files could not be read. - -=item Z<>3 - -an error occurred creating the PKCS#7 file or when reading the MIME -message. - -=item Z<>4 - -an error occurred decrypting or verifying the message. - -=item Z<>5 - -the message was verified correctly but an error occurred writing out -the signers certificates. - -=back - -=head1 EXAMPLES - -Create a cleartext signed message: - - openssl smime -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem - -Create an opaque signed message: - - openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ - -signer mycert.pem - -Create a signed message, include some additional certificates and -read the private key from another file: - - openssl smime -sign -in in.txt -text -out mail.msg \ - -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem - -Create a signed message with two signers: - - openssl smime -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem -signer othercert.pem - -Send a signed message under Unix directly to sendmail, including headers: - - openssl smime -sign -in in.txt -text -signer mycert.pem \ - -from steve@openssl.org -to someone@somewhere \ - -subject "Signed message" | sendmail someone@somewhere - -Verify a message and extract the signer's certificate if successful: - - openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt - -Send encrypted mail using triple DES: - - openssl smime -encrypt -in in.txt -from steve@openssl.org \ - -to someone@somewhere -subject "Encrypted message" \ - -des3 user.pem -out mail.msg - -Sign and encrypt mail: - - openssl smime -sign -in ml.txt -signer my.pem -text \ - | openssl smime -encrypt -out mail.msg \ - -from steve@openssl.org -to someone@somewhere \ - -subject "Signed and Encrypted message" -des3 user.pem - -Note: the encryption command does not include the B<-text> option because the -message being encrypted already has MIME headers. - -Decrypt mail: - - openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem - -The output from Netscape form signing is a PKCS#7 structure with the -detached signature format. You can use this program to verify the -signature by line wrapping the base64 encoded structure and surrounding -it with: - - -----BEGIN PKCS7----- - -----END PKCS7----- - -and using the command: - - openssl smime -verify -inform PEM -in signature.pem -content content.txt - -Alternatively you can base64 decode the signature and use: - - openssl smime -verify -inform DER -in signature.der -content content.txt - -Create an encrypted message using 128 bit Camellia: - - openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem - -Add a signer to an existing message: - - openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg - -=head1 BUGS - -The MIME parser isn't very clever: it seems to handle most messages that I've -thrown at it but it may choke on others. - -The code currently will only write out the signer's certificate to a file: if -the signer has a separate encryption certificate this must be manually -extracted. There should be some heuristic that determines the correct -encryption certificate. - -Ideally a database should be maintained of a certificates for each email -address. - -The code doesn't currently take note of the permitted symmetric encryption -algorithms as supplied in the SMIMECapabilities signed attribute. This means the -user has to manually include the correct encryption algorithm. It should store -the list of permitted ciphers in a database and only use those. - -No revocation checking is done on the signer's certificate. - -The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 -structures may cause parsing errors. - -=head1 HISTORY - -The use of multiple B<-signer> options and the B<-resign> command were first -added in OpenSSL 1.0.0 - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/speed.pod b/openssl/doc/apps/speed.pod deleted file mode 100644 index 1cd1998..0000000 --- a/openssl/doc/apps/speed.pod +++ /dev/null @@ -1,59 +0,0 @@ -=pod - -=head1 NAME - -speed - test library performance - -=head1 SYNOPSIS - -B<openssl speed> -[B<-engine id>] -[B<md2>] -[B<mdc2>] -[B<md5>] -[B<hmac>] -[B<sha1>] -[B<rmd160>] -[B<idea-cbc>] -[B<rc2-cbc>] -[B<rc5-cbc>] -[B<bf-cbc>] -[B<des-cbc>] -[B<des-ede3>] -[B<rc4>] -[B<rsa512>] -[B<rsa1024>] -[B<rsa2048>] -[B<rsa4096>] -[B<dsa512>] -[B<dsa1024>] -[B<dsa2048>] -[B<idea>] -[B<rc2>] -[B<des>] -[B<rsa>] -[B<blowfish>] - -=head1 DESCRIPTION - -This command is used to test the performance of cryptographic algorithms. - -=head1 OPTIONS - -=over 4 - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<speed> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=item B<[zero or more test algorithms]> - -If any options are given, B<speed> tests those algorithms, otherwise all of -the above are tested. - -=back - -=cut diff --git a/openssl/doc/apps/spkac.pod b/openssl/doc/apps/spkac.pod deleted file mode 100644 index 97fb80e..0000000 --- a/openssl/doc/apps/spkac.pod +++ /dev/null @@ -1,133 +0,0 @@ -=pod - -=head1 NAME - -spkac - SPKAC printing and generating utility - -=head1 SYNOPSIS - -B<openssl> B<spkac> -[B<-in filename>] -[B<-out filename>] -[B<-key keyfile>] -[B<-passin arg>] -[B<-challenge string>] -[B<-pubkey>] -[B<-spkac spkacname>] -[B<-spksect section>] -[B<-noout>] -[B<-verify>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<spkac> command processes Netscape signed public key and challenge -(SPKAC) files. It can print out their contents, verify the signature and -produce its own SPKACs from a supplied private key. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-in filename> - -This specifies the input filename to read from or standard input if this -option is not specified. Ignored if the B<-key> option is used. - -=item B<-out filename> - -specifies the output filename to write to or standard output by -default. - -=item B<-key keyfile> - -create an SPKAC file using the private key in B<keyfile>. The -B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if -present. - -=item B<-passin password> - -the input file password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-challenge string> - -specifies the challenge string if an SPKAC is being created. - -=item B<-spkac spkacname> - -allows an alternative name form the variable containing the -SPKAC. The default is "SPKAC". This option affects both -generated and input SPKAC files. - -=item B<-spksect section> - -allows an alternative name form the section containing the -SPKAC. The default is the default section. - -=item B<-noout> - -don't output the text version of the SPKAC (not used if an -SPKAC is being created). - -=item B<-pubkey> - -output the public key of an SPKAC (not used if an SPKAC is -being created). - -=item B<-verify> - -verifies the digital signature on the supplied SPKAC. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<spkac> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 EXAMPLES - -Print out the contents of an SPKAC: - - openssl spkac -in spkac.cnf - -Verify the signature of an SPKAC: - - openssl spkac -in spkac.cnf -noout -verify - -Create an SPKAC using the challenge string "hello": - - openssl spkac -key key.pem -challenge hello -out spkac.cnf - -Example of an SPKAC, (long lines split up for clarity): - - SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\ - PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\ - PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\ - 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\ - 4= - -=head1 NOTES - -A created SPKAC with suitable DN components appended can be fed into -the B<ca> utility. - -SPKACs are typically generated by Netscape when a form is submitted -containing the B<KEYGEN> tag as part of the certificate enrollment -process. - -The challenge string permits a primitive form of proof of possession -of private key. By checking the SPKAC signature and a random challenge -string some guarantee is given that the user knows the private key -corresponding to the public key being certified. This is important in -some applications. Without this it is possible for a previous SPKAC -to be used in a "replay attack". - -=head1 SEE ALSO - -L<ca(1)|ca(1)> - -=cut diff --git a/openssl/doc/apps/ts.pod b/openssl/doc/apps/ts.pod deleted file mode 100644 index d6aa47d..0000000 --- a/openssl/doc/apps/ts.pod +++ /dev/null @@ -1,594 +0,0 @@ -=pod - -=head1 NAME - -ts - Time Stamping Authority tool (client/server) - -=head1 SYNOPSIS - -B<openssl> B<ts> -B<-query> -[B<-rand> file:file...] -[B<-config> configfile] -[B<-data> file_to_hash] -[B<-digest> digest_bytes] -[B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>] -[B<-policy> object_id] -[B<-no_nonce>] -[B<-cert>] -[B<-in> request.tsq] -[B<-out> request.tsq] -[B<-text>] - -B<openssl> B<ts> -B<-reply> -[B<-config> configfile] -[B<-section> tsa_section] -[B<-queryfile> request.tsq] -[B<-passin> password_src] -[B<-signer> tsa_cert.pem] -[B<-inkey> private.pem] -[B<-chain> certs_file.pem] -[B<-policy> object_id] -[B<-in> response.tsr] -[B<-token_in>] -[B<-out> response.tsr] -[B<-token_out>] -[B<-text>] -[B<-engine> id] - -B<openssl> B<ts> -B<-verify> -[B<-data> file_to_hash] -[B<-digest> digest_bytes] -[B<-queryfile> request.tsq] -[B<-in> response.tsr] -[B<-token_in>] -[B<-CApath> trusted_cert_path] -[B<-CAfile> trusted_certs.pem] -[B<-untrusted> cert_file.pem] - -=head1 DESCRIPTION - -The B<ts> command is a basic Time Stamping Authority (TSA) client and server -application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A -TSA can be part of a PKI deployment and its role is to provide long -term proof of the existence of a certain datum before a particular -time. Here is a brief description of the protocol: - -=over 4 - -=item 1. - -The TSA client computes a one-way hash value for a data file and sends -the hash to the TSA. - -=item 2. - -The TSA attaches the current date and time to the received hash value, -signs them and sends the time stamp token back to the client. By -creating this token the TSA certifies the existence of the original -data file at the time of response generation. - -=item 3. - -The TSA client receives the time stamp token and verifies the -signature on it. It also checks if the token contains the same hash -value that it had sent to the TSA. - -=back - -There is one DER encoded protocol data unit defined for transporting a time -stamp request to the TSA and one for sending the time stamp response -back to the client. The B<ts> command has three main functions: -creating a time stamp request based on a data file, -creating a time stamp response based on a request, verifying if a -response corresponds to a particular request or a data file. - -There is no support for sending the requests/responses automatically -over HTTP or TCP yet as suggested in RFC 3161. The users must send the -requests either by ftp or e-mail. - -=head1 OPTIONS - -=head2 Time Stamp Request generation - -The B<-query> switch can be used for creating and printing a time stamp -request with the following options: - -=over 4 - -=item B<-rand> file:file... - -The files containing random data for seeding the random number -generator. Multiple files can be specified, the separator is B<;> for -MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) - -=item B<-config> configfile - -The configuration file to use, this option overrides the -B<OPENSSL_CONF> environment variable. Only the OID section -of the config file is used with the B<-query> command. (Optional) - -=item B<-data> file_to_hash - -The data file for which the time stamp request needs to be -created. stdin is the default if neither the B<-data> nor the B<-digest> -parameter is specified. (Optional) - -=item B<-digest> digest_bytes - -It is possible to specify the message imprint explicitly without the data -file. The imprint must be specified in a hexadecimal format, two characters -per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or -1AF601...). The number of bytes must match the message digest algorithm -in use. (Optional) - -=item B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...> - -The message digest to apply to the data file, it supports all the message -digest algorithms that are supported by the openssl B<dgst> command. -The default is SHA-1. (Optional) - -=item B<-policy> object_id - -The policy that the client expects the TSA to use for creating the -time stamp token. Either the dotted OID notation or OID names defined -in the config file can be used. If no policy is requested the TSA will -use its own default policy. (Optional) - -=item B<-no_nonce> - -No nonce is specified in the request if this option is -given. Otherwise a 64 bit long pseudo-random none is -included in the request. It is recommended to use nonce to -protect against replay-attacks. (Optional) - -=item B<-cert> - -The TSA is expected to include its signing certificate in the -response. (Optional) - -=item B<-in> request.tsq - -This option specifies a previously created time stamp request in DER -format that will be printed into the output file. Useful when you need -to examine the content of a request in human-readable - -format. (Optional) - -=item B<-out> request.tsq - -Name of the output file to which the request will be written. Default -is stdout. (Optional) - -=item B<-text> - -If this option is specified the output is human-readable text format -instead of DER. (Optional) - -=back - -=head2 Time Stamp Response generation - -A time stamp response (TimeStampResp) consists of a response status -and the time stamp token itself (ContentInfo), if the token generation was -successful. The B<-reply> command is for creating a time stamp -response or time stamp token based on a request and printing the -response/token in human-readable format. If B<-token_out> is not -specified the output is always a time stamp response (TimeStampResp), -otherwise it is a time stamp token (ContentInfo). - -=over 4 - -=item B<-config> configfile - -The configuration file to use, this option overrides the -B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE -OPTIONS> for configurable variables. (Optional) - -=item B<-section> tsa_section - -The name of the config file section conatining the settings for the -response generation. If not specified the default TSA section is -used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional) - -=item B<-queryfile> request.tsq - -The name of the file containing a DER encoded time stamp request. (Optional) - -=item B<-passin> password_src - -Specifies the password source for the private key of the TSA. See -B<PASS PHRASE ARGUMENTS> in L<openssl(1)|openssl(1)>. (Optional) - -=item B<-signer> tsa_cert.pem - -The signer certificate of the TSA in PEM format. The TSA signing -certificate must have exactly one extended key usage assigned to it: -timeStamping. The extended key usage must also be critical, otherwise -the certificate is going to be refused. Overrides the B<signer_cert> -variable of the config file. (Optional) - -=item B<-inkey> private.pem - -The signer private key of the TSA in PEM format. Overrides the -B<signer_key> config file option. (Optional) - -=item B<-chain> certs_file.pem - -The collection of certificates in PEM format that will all -be included in the response in addition to the signer certificate if -the B<-cert> option was used for the request. This file is supposed to -contain the certificate chain for the signer certificate from its -issuer upwards. The B<-reply> command does not build a certificate -chain automatically. (Optional) - -=item B<-policy> object_id - -The default policy to use for the response unless the client -explicitly requires a particular TSA policy. The OID can be specified -either in dotted notation or with its name. Overrides the -B<default_policy> config file option. (Optional) - -=item B<-in> response.tsr - -Specifies a previously created time stamp response or time stamp token -(if B<-token_in> is also specified) in DER format that will be written -to the output file. This option does not require a request, it is -useful e.g. when you need to examine the content of a response or -token or you want to extract the time stamp token from a response. If -the input is a token and the output is a time stamp response a default -'granted' status info is added to the token. (Optional) - -=item B<-token_in> - -This flag can be used together with the B<-in> option and indicates -that the input is a DER encoded time stamp token (ContentInfo) instead -of a time stamp response (TimeStampResp). (Optional) - -=item B<-out> response.tsr - -The response is written to this file. The format and content of the -file depends on other options (see B<-text>, B<-token_out>). The default is -stdout. (Optional) - -=item B<-token_out> - -The output is a time stamp token (ContentInfo) instead of time stamp -response (TimeStampResp). (Optional) - -=item B<-text> - -If this option is specified the output is human-readable text format -instead of DER. (Optional) - -=item B<-engine> id - -Specifying an engine (by its unique B<id> string) will cause B<ts> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. Default is builtin. (Optional) - -=back - -=head2 Time Stamp Response verification - -The B<-verify> command is for verifying if a time stamp response or time -stamp token is valid and matches a particular time stamp request or -data file. The B<-verify> command does not use the configuration file. - -=over 4 - -=item B<-data> file_to_hash - -The response or token must be verified against file_to_hash. The file -is hashed with the message digest algorithm specified in the token. -The B<-digest> and B<-queryfile> options must not be specified with this one. -(Optional) - -=item B<-digest> digest_bytes - -The response or token must be verified against the message digest specified -with this option. The number of bytes must match the message digest algorithm -specified in the token. The B<-data> and B<-queryfile> options must not be -specified with this one. (Optional) - -=item B<-queryfile> request.tsq - -The original time stamp request in DER format. The B<-data> and B<-digest> -options must not be specified with this one. (Optional) - -=item B<-in> response.tsr - -The time stamp response that needs to be verified in DER format. (Mandatory) - -=item B<-token_in> - -This flag can be used together with the B<-in> option and indicates -that the input is a DER encoded time stamp token (ContentInfo) instead -of a time stamp response (TimeStampResp). (Optional) - -=item B<-CApath> trusted_cert_path - -The name of the directory containing the trused CA certificates of the -client. See the similar option of L<verify(1)|verify(1)> for additional -details. Either this option or B<-CAfile> must be specified. (Optional) - - -=item B<-CAfile> trusted_certs.pem - -The name of the file containing a set of trusted self-signed CA -certificates in PEM format. See the similar option of -L<verify(1)|verify(1)> for additional details. Either this option -or B<-CApath> must be specified. -(Optional) - -=item B<-untrusted> cert_file.pem - -Set of additional untrusted certificates in PEM format which may be -needed when building the certificate chain for the TSA's signing -certificate. This file must contain the TSA signing certificate and -all intermediate CA certificates unless the response includes them. -(Optional) - -=back - -=head1 CONFIGURATION FILE OPTIONS - -The B<-query> and B<-reply> commands make use of a configuration file -defined by the B<OPENSSL_CONF> environment variable. See L<config(5)|config(5)> -for a general description of the syntax of the config file. The -B<-query> command uses only the symbolic OID names section -and it can work without it. However, the B<-reply> command needs the -config file for its operation. - -When there is a command line switch equivalent of a variable the -switch always overrides the settings in the config file. - -=over 4 - -=item B<tsa> section, B<default_tsa> - -This is the main section and it specifies the name of another section -that contains all the options for the B<-reply> command. This default -section can be overridden with the B<-section> command line switch. (Optional) - -=item B<oid_file> - -See L<ca(1)|ca(1)> for description. (Optional) - -=item B<oid_section> - -See L<ca(1)|ca(1)> for description. (Optional) - -=item B<RANDFILE> - -See L<ca(1)|ca(1)> for description. (Optional) - -=item B<serial> - -The name of the file containing the hexadecimal serial number of the -last time stamp response created. This number is incremented by 1 for -each response. If the file does not exist at the time of response -generation a new file is created with serial number 1. (Mandatory) - -=item B<crypto_device> - -Specifies the OpenSSL engine that will be set as the default for -all available algorithms. The default value is builtin, you can specify -any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM). -(Optional) - -=item B<signer_cert> - -TSA signing certificate in PEM format. The same as the B<-signer> -command line option. (Optional) - -=item B<certs> - -A file containing a set of PEM encoded certificates that need to be -included in the response. The same as the B<-chain> command line -option. (Optional) - -=item B<signer_key> - -The private key of the TSA in PEM format. The same as the B<-inkey> -command line option. (Optional) - -=item B<default_policy> - -The default policy to use when the request does not mandate any -policy. The same as the B<-policy> command line option. (Optional) - -=item B<other_policies> - -Comma separated list of policies that are also acceptable by the TSA -and used only if the request explicitly specifies one of them. (Optional) - -=item B<digests> - -The list of message digest algorithms that the TSA accepts. At least -one algorithm must be specified. (Mandatory) - -=item B<accuracy> - -The accuracy of the time source of the TSA in seconds, milliseconds -and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of -the components is missing zero is assumed for that field. (Optional) - -=item B<clock_precision_digits> - -Specifies the maximum number of digits, which represent the fraction of -seconds, that need to be included in the time field. The trailing zeroes -must be removed from the time, so there might actually be fewer digits, -or no fraction of seconds at all. Supported only on UNIX platforms. -The maximum value is 6, default is 0. -(Optional) - -=item B<ordering> - -If this option is yes the responses generated by this TSA can always -be ordered, even if the time difference between two responses is less -than the sum of their accuracies. Default is no. (Optional) - -=item B<tsa_name> - -Set this option to yes if the subject name of the TSA must be included in -the TSA name field of the response. Default is no. (Optional) - -=item B<ess_cert_id_chain> - -The SignedData objects created by the TSA always contain the -certificate identifier of the signing certificate in a signed -attribute (see RFC 2634, Enhanced Security Services). If this option -is set to yes and either the B<certs> variable or the B<-chain> option -is specified then the certificate identifiers of the chain will also -be included in the SigningCertificate signed attribute. If this -variable is set to no, only the signing certificate identifier is -included. Default is no. (Optional) - -=back - -=head1 ENVIRONMENT VARIABLES - -B<OPENSSL_CONF> contains the path of the configuration file and can be -overridden by the B<-config> command line option. - -=head1 EXAMPLES - -All the examples below presume that B<OPENSSL_CONF> is set to a proper -configuration file, e.g. the example configuration file -openssl/apps/openssl.cnf will do. - -=head2 Time Stamp Request - -To create a time stamp request for design1.txt with SHA-1 -without nonce and policy and no certificate is required in the response: - - openssl ts -query -data design1.txt -no_nonce \ - -out design1.tsq - -To create a similar time stamp request with specifying the message imprint -explicitly: - - openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ - -no_nonce -out design1.tsq - -To print the content of the previous request in human readable format: - - openssl ts -query -in design1.tsq -text - -To create a time stamp request which includes the MD-5 digest -of design2.txt, requests the signer certificate and nonce, -specifies a policy id (assuming the tsa_policy1 name is defined in the -OID section of the config file): - - openssl ts -query -data design2.txt -md5 \ - -policy tsa_policy1 -cert -out design2.tsq - -=head2 Time Stamp Response - -Before generating a response a signing certificate must be created for -the TSA that contains the B<timeStamping> critical extended key usage extension -without any other key usage extensions. You can add the -'extendedKeyUsage = critical,timeStamping' line to the user certificate section -of the config file to generate a proper certificate. See L<req(1)|req(1)>, -L<ca(1)|ca(1)>, L<x509(1)|x509(1)> for instructions. The examples -below assume that cacert.pem contains the certificate of the CA, -tsacert.pem is the signing certificate issued by cacert.pem and -tsakey.pem is the private key of the TSA. - -To create a time stamp response for a request: - - openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \ - -signer tsacert.pem -out design1.tsr - -If you want to use the settings in the config file you could just write: - - openssl ts -reply -queryfile design1.tsq -out design1.tsr - -To print a time stamp reply to stdout in human readable format: - - openssl ts -reply -in design1.tsr -text - -To create a time stamp token instead of time stamp response: - - openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out - -To print a time stamp token to stdout in human readable format: - - openssl ts -reply -in design1_token.der -token_in -text -token_out - -To extract the time stamp token from a response: - - openssl ts -reply -in design1.tsr -out design1_token.der -token_out - -To add 'granted' status info to a time stamp token thereby creating a -valid response: - - openssl ts -reply -in design1_token.der -token_in -out design1.tsr - -=head2 Time Stamp Verification - -To verify a time stamp reply against a request: - - openssl ts -verify -queryfile design1.tsq -in design1.tsr \ - -CAfile cacert.pem -untrusted tsacert.pem - -To verify a time stamp reply that includes the certificate chain: - - openssl ts -verify -queryfile design2.tsq -in design2.tsr \ - -CAfile cacert.pem - -To verify a time stamp token against the original data file: - openssl ts -verify -data design2.txt -in design2.tsr \ - -CAfile cacert.pem - -To verify a time stamp token against a message imprint: - openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ - -in design2.tsr -CAfile cacert.pem - -You could also look at the 'test' directory for more examples. - -=head1 BUGS - -If you find any bugs or you have suggestions please write to -Zoltan Glozik <zglozik@opentsa.org>. Known issues: - -=over 4 - -=item * No support for time stamps over SMTP, though it is quite easy -to implement an automatic e-mail based TSA with L<procmail(1)|procmail(1)> -and L<perl(1)|perl(1)>. HTTP server support is provided in the form of -a separate apache module. HTTP client support is provided by -L<tsget(1)|tsget(1)>. Pure TCP/IP protocol is not supported. - -=item * The file containing the last serial number of the TSA is not -locked when being read or written. This is a problem if more than one -instance of L<openssl(1)|openssl(1)> is trying to create a time stamp -response at the same time. This is not an issue when using the apache -server module, it does proper locking. - -=item * Look for the FIXME word in the source files. - -=item * The source code should really be reviewed by somebody else, too. - -=item * More testing is needed, I have done only some basic tests (see -test/testtsa). - -=back - -=cut - -=head1 AUTHOR - -Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) - -=head1 SEE ALSO - -L<tsget(1)|tsget(1)>, L<openssl(1)|openssl(1)>, L<req(1)|req(1)>, -L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<config(5)|config(5)> - -=cut diff --git a/openssl/doc/apps/tsget.pod b/openssl/doc/apps/tsget.pod deleted file mode 100644 index 56db985..0000000 --- a/openssl/doc/apps/tsget.pod +++ /dev/null @@ -1,194 +0,0 @@ -=pod - -=head1 NAME - -tsget - Time Stamping HTTP/HTTPS client - -=head1 SYNOPSIS - -B<tsget> -B<-h> server_url -[B<-e> extension] -[B<-o> output] -[B<-v>] -[B<-d>] -[B<-k> private_key.pem] -[B<-p> key_password] -[B<-c> client_cert.pem] -[B<-C> CA_certs.pem] -[B<-P> CA_path] -[B<-r> file:file...] -[B<-g> EGD_socket] -[request]... - -=head1 DESCRIPTION - -The B<tsget> command can be used for sending a time stamp request, as -specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing -the time stamp response in a file. This tool cannot be used for creating the -requests and verifying responses, you can use the OpenSSL B<ts(1)> command to -do that. B<tsget> can send several requests to the server without closing -the TCP connection if more than one requests are specified on the command -line. - -The tool sends the following HTTP request for each time stamp request: - - POST url HTTP/1.1 - User-Agent: OpenTSA tsget.pl/<version> - Host: <host>:<port> - Pragma: no-cache - Content-Type: application/timestamp-query - Accept: application/timestamp-reply - Content-Length: length of body - - ...binary request specified by the user... - -B<tsget> expects a response of type application/timestamp-reply, which is -written to a file without any interpretation. - -=head1 OPTIONS - -=over 4 - -=item B<-h> server_url - -The URL of the HTTP/HTTPS server listening for time stamp requests. - -=item B<-e> extension - -If the B<-o> option is not given this argument specifies the extension of the -output files. The base name of the output file will be the same as those of -the input files. Default extension is '.tsr'. (Optional) - -=item B<-o> output - -This option can be specified only when just one request is sent to the -server. The time stamp response will be written to the given output file. '-' -means standard output. In case of multiple time stamp requests or the absence -of this argument the names of the output files will be derived from the names -of the input files and the default or specified extension argument. (Optional) - -=item B<-v> - -The name of the currently processed request is printed on standard -error. (Optional) - -=item B<-d> - -Switches on verbose mode for the underlying B<curl> library. You can see -detailed debug messages for the connection. (Optional) - -=item B<-k> private_key.pem - -(HTTPS) In case of certificate-based client authentication over HTTPS -<private_key.pem> must contain the private key of the user. The private key -file can optionally be protected by a passphrase. The B<-c> option must also -be specified. (Optional) - -=item B<-p> key_password - -(HTTPS) Specifies the passphrase for the private key specified by the B<-k> -argument. If this option is omitted and the key is passphrase protected B<tsget> -will ask for it. (Optional) - -=item B<-c> client_cert.pem - -(HTTPS) In case of certificate-based client authentication over HTTPS -<client_cert.pem> must contain the X.509 certificate of the user. The B<-k> -option must also be specified. If this option is not specified no -certificate-based client authentication will take place. (Optional) - -=item B<-C> CA_certs.pem - -(HTTPS) The trusted CA certificate store. The certificate chain of the peer's -certificate must include one of the CA certificates specified in this file. -Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional) - -=item B<-P> CA_path - -(HTTPS) The path containing the trusted CA certificates to verify the peer's -certificate. The directory must be prepared with the B<c_rehash> -OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of -HTTPS. (Optional) - -=item B<-rand> file:file... - -The files containing random data for seeding the random number -generator. Multiple files can be specified, the separator is B<;> for -MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) - -=item B<-g> EGD_socket - -The name of an EGD socket to get random data from. (Optional) - -=item [request]... - -List of files containing B<RFC 3161> DER-encoded time stamp requests. If no -requests are specified only one request will be sent to the server and it will be -read from the standard input. (Optional) - -=back - -=head1 ENVIRONMENT VARIABLES - -The B<TSGET> environment variable can optionally contain default -arguments. The content of this variable is added to the list of command line -arguments. - -=head1 EXAMPLES - -The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid -time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests -and at port 8443 for HTTPS requests, the TSA service is available at the /tsa -absolute path. - -Get a time stamp response for file1.tsq over HTTP, output is written to -file1.tsr: - - tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq - -Get a time stamp response for file1.tsq and file2.tsq over HTTP showing -progress, output is written to file1.reply and file2.reply respectively: - - tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ - file1.tsq file2.tsq - -Create a time stamp request, write it to file3.tsq, send it to the server and -write the response to file3.tsr: - - openssl ts -query -data file3.txt -cert | tee file3.tsq \ - | tsget -h http://tsa.opentsa.org:8080/tsa \ - -o file3.tsr - -Get a time stamp response for file1.tsq over HTTPS without client -authentication: - - tsget -h https://tsa.opentsa.org:8443/tsa \ - -C cacerts.pem file1.tsq - -Get a time stamp response for file1.tsq over HTTPS with certificate-based -client authentication (it will ask for the passphrase if client_key.pem is -protected): - - tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ - -k client_key.pem -c client_cert.pem file1.tsq - -You can shorten the previous command line if you make use of the B<TSGET> -environment variable. The following commands do the same as the previous -example: - - TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ - -k client_key.pem -c client_cert.pem' - export TSGET - tsget file1.tsq - -=head1 AUTHOR - -Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) - -=head1 SEE ALSO - -L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>, -B<RFC 3161> - -=cut diff --git a/openssl/doc/apps/verify.pod b/openssl/doc/apps/verify.pod deleted file mode 100644 index b376732..0000000 --- a/openssl/doc/apps/verify.pod +++ /dev/null @@ -1,457 +0,0 @@ -=pod - -=head1 NAME - -verify - Utility to verify certificates. - -=head1 SYNOPSIS - -B<openssl> B<verify> -[B<-CApath directory>] -[B<-CAfile file>] -[B<-purpose purpose>] -[B<-policy arg>] -[B<-ignore_critical>] -[B<-attime timestamp>] -[B<-check_ss_sig>] -[B<-crlfile file>] -[B<-crl_download>] -[B<-crl_check>] -[B<-crl_check_all>] -[B<-policy_check>] -[B<-explicit_policy>] -[B<-inhibit_any>] -[B<-inhibit_map>] -[B<-x509_strict>] -[B<-extended_crl>] -[B<-use_deltas>] -[B<-policy_print>] -[B<-no_alt_chains>] -[B<-allow_proxy_certs>] -[B<-untrusted file>] -[B<-help>] -[B<-issuer_checks>] -[B<-trusted file>] -[B<-verbose>] -[B<->] -[certificates] - - -=head1 DESCRIPTION - -The B<verify> command verifies certificate chains. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-CApath directory> - -A directory of trusted certificates. The certificates should have names -of the form: hash.0 or have symbolic links to them of this -form ("hash" is the hashed certificate subject name: see the B<-hash> option -of the B<x509> utility). Under Unix the B<c_rehash> script will automatically -create symbolic links to a directory of certificates. - -=item B<-CAfile file> -A file of trusted certificates. The file should contain multiple certificates -in PEM format concatenated together. - -=item B<-attime timestamp> - -Perform validation checks using time specified by B<timestamp> and not -current system time. B<timestamp> is the number of seconds since -01.01.1970 (UNIX time). - -=item B<-check_ss_sig> - -Verify the signature on the self-signed root CA. This is disabled by default -because it doesn't add any security. - -=item B<-crlfile file> - -File containing one or more CRL's (in PEM format) to load. - -=item B<-crl_download> - -Attempt to download CRL information for this certificate. - -=item B<-crl_check> - -Checks end entity certificate validity by attempting to look up a valid CRL. -If a valid CRL cannot be found an error occurs. - -=item B<-untrusted file> - -A file of untrusted certificates. The file should contain multiple certificates -in PEM format concatenated together. - -=item B<-purpose purpose> - -The intended use for the certificate. If this option is not specified, -B<verify> will not consider certificate purpose during chain verification. -Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, -B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more -information. - -=item B<-help> - -Print out a usage message. - -=item B<-verbose> - -Print extra information about the operations being performed. - -=item B<-issuer_checks> - -Print out diagnostics relating to searches for the issuer certificate of the -current certificate. This shows why each candidate issuer certificate was -rejected. The presence of rejection messages does not itself imply that -anything is wrong; during the normal verification process, several -rejections may take place. - -=item B<-policy arg> - -Enable policy processing and add B<arg> to the user-initial-policy-set (see -RFC5280). The policy B<arg> can be an object name an OID in numeric form. -This argument can appear more than once. - -=item B<-policy_check> - -Enables certificate policy processing. - -=item B<-explicit_policy> - -Set policy variable require-explicit-policy (see RFC5280). - -=item B<-inhibit_any> - -Set policy variable inhibit-any-policy (see RFC5280). - -=item B<-inhibit_map> - -Set policy variable inhibit-policy-mapping (see RFC5280). - -=item B<-no_alt_chains> - -When building a certificate chain, if the first certificate chain found is not -trusted, then OpenSSL will continue to check to see if an alternative chain can -be found that is trusted. With this option that behaviour is suppressed so that -only the first chain found is ever used. Using this option will force the -behaviour to match that of previous OpenSSL versions. - -=item B<-allow_proxy_certs> - -Allow the verification of proxy certificates. - -=item B<-trusted file> - -A file of additional trusted certificates. The file should contain multiple -certificates in PEM format concatenated together. - -=item B<-policy_print> - -Print out diagnostics related to policy processing. - -=item B<-crl_check> - -Checks end entity certificate validity by attempting to look up a valid CRL. -If a valid CRL cannot be found an error occurs. - -=item B<-crl_check_all> - -Checks the validity of B<all> certificates in the chain by attempting -to look up valid CRLs. - -=item B<-ignore_critical> - -Normally if an unhandled critical extension is present which is not -supported by OpenSSL the certificate is rejected (as required by RFC5280). -If this option is set critical extensions are ignored. - -=item B<-x509_strict> - -For strict X.509 compliance, disable non-compliant workarounds for broken -certificates. - -=item B<-extended_crl> - -Enable extended CRL features such as indirect CRLs and alternate CRL -signing keys. - -=item B<-use_deltas> - -Enable support for delta CRLs. - -=item B<-check_ss_sig> - -Verify the signature on the self-signed root CA. This is disabled by default -because it doesn't add any security. - -=item B<-> - -Indicates the last option. All arguments following this are assumed to be -certificate files. This is useful if the first certificate filename begins -with a B<->. - -=item B<certificates> - -One or more certificates to verify. If no certificates are given, B<verify> -will attempt to read a certificate from standard input. Certificates must be -in PEM format. - -=back - -=head1 VERIFY OPERATION - -The B<verify> program uses the same functions as the internal SSL and S/MIME -verification, therefore this description applies to these verify operations -too. - -There is one crucial difference between the verify operations performed -by the B<verify> program: wherever possible an attempt is made to continue -after an error whereas normally the verify operation would halt on the -first error. This allows all the problems with a certificate chain to be -determined. - -The verify operation consists of a number of separate steps. - -Firstly a certificate chain is built up starting from the supplied certificate -and ending in the root CA. It is an error if the whole chain cannot be built -up. The chain is built up by looking up the issuers certificate of the current -certificate. If a certificate is found which is its own issuer it is assumed -to be the root CA. - -The process of 'looking up the issuers certificate' itself involves a number -of steps. In versions of OpenSSL before 0.9.5a the first certificate whose -subject name matched the issuer of the current certificate was assumed to be -the issuers certificate. In OpenSSL 0.9.6 and later all certificates -whose subject name matches the issuer name of the current certificate are -subject to further tests. The relevant authority key identifier components -of the current certificate (if present) must match the subject key identifier -(if present) and issuer and serial number of the candidate issuer, in addition -the keyUsage extension of the candidate issuer (if present) must permit -certificate signing. - -The lookup first looks in the list of untrusted certificates and if no match -is found the remaining lookups are from the trusted certificates. The root CA -is always looked up in the trusted certificate list: if the certificate to -verify is a root certificate then an exact match must be found in the trusted -list. - -The second operation is to check every untrusted certificate's extensions for -consistency with the supplied purpose. If the B<-purpose> option is not included -then no checks are done. The supplied or "leaf" certificate must have extensions -compatible with the supplied purpose and all other certificates must also be valid -CA certificates. The precise extensions required are described in more detail in -the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility. - -The third operation is to check the trust settings on the root CA. The root -CA should be trusted for the supplied purpose. For compatibility with previous -versions of SSLeay and OpenSSL a certificate with no trust settings is considered -to be valid for all purposes. - -The final operation is to check the validity of the certificate chain. The validity -period is checked against the current system time and the notBefore and notAfter -dates in the certificate. The certificate signatures are also checked at this -point. - -If all operations complete successfully then certificate is considered valid. If -any operation fails then the certificate is not valid. - -=head1 DIAGNOSTICS - -When a verify operation fails the output messages can be somewhat cryptic. The -general form of the error message is: - - server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) - error 24 at 1 depth lookup:invalid CA certificate - -The first line contains the name of the certificate being verified followed by -the subject name of the certificate. The second line contains the error number -and the depth. The depth is number of the certificate being verified when a -problem was detected starting with zero for the certificate being verified itself -then 1 for the CA that signed the certificate and so on. Finally a text version -of the error number is presented. - -An exhaustive list of the error codes and messages is shown below, this also -includes the name of the error code as defined in the header file x509_vfy.h -Some of the error codes are defined but never returned: these are described -as "unused". - -=over 4 - -=item B<0 X509_V_OK: ok> - -the operation was successful. - -=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> - -the issuer certificate of a looked up certificate could not be found. This -normally means the list of trusted certificates is not complete. - -=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> - -the CRL of a certificate could not be found. - -=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> - -the certificate signature could not be decrypted. This means that the actual signature value -could not be determined rather than it not matching the expected value, this is only -meaningful for RSA keys. - -=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> - -the CRL signature could not be decrypted: this means that the actual signature value -could not be determined rather than it not matching the expected value. Unused. - -=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> - -the public key in the certificate SubjectPublicKeyInfo could not be read. - -=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> - -the signature of the certificate is invalid. - -=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> - -the signature of the certificate is invalid. - -=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> - -the certificate is not yet valid: the notBefore date is after the current time. - -=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> - -the certificate has expired: that is the notAfter date is before the current time. - -=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> - -the CRL is not yet valid. - -=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> - -the CRL has expired. - -=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> - -the certificate notBefore field contains an invalid time. - -=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> - -the certificate notAfter field contains an invalid time. - -=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> - -the CRL lastUpdate field contains an invalid time. - -=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> - -the CRL nextUpdate field contains an invalid time. - -=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> - -an error occurred trying to allocate memory. This should never happen. - -=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> - -the passed certificate is self signed and the same certificate cannot be found in the list of -trusted certificates. - -=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> - -the certificate chain could be built up using the untrusted certificates but the root could not -be found locally. - -=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> - -the issuer certificate could not be found: this occurs if the issuer -certificate of an untrusted certificate cannot be found. - -=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> - -no signatures could be verified because the chain contains only one certificate and it is not -self signed. - -=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> - -the certificate chain length is greater than the supplied maximum depth. Unused. - -=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> - -the certificate has been revoked. - -=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> - -a CA certificate is invalid. Either it is not a CA or its extensions are not consistent -with the supplied purpose. - -=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> - -the basicConstraints pathlength parameter has been exceeded. - -=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> - -the supplied certificate cannot be used for the specified purpose. - -=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> - -the root CA is not marked as trusted for the specified purpose. - -=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> - -the root CA is marked to reject the specified purpose. - -=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> - -the current candidate issuer certificate was rejected because its subject name -did not match the issuer name of the current certificate. Only displayed when -the B<-issuer_checks> option is set. - -=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> - -the current candidate issuer certificate was rejected because its subject key -identifier was present and did not match the authority key identifier current -certificate. Only displayed when the B<-issuer_checks> option is set. - -=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> - -the current candidate issuer certificate was rejected because its issuer name -and serial number was present and did not match the authority key identifier -of the current certificate. Only displayed when the B<-issuer_checks> option is set. - -=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> - -the current candidate issuer certificate was rejected because its keyUsage extension -does not permit certificate signing. - -=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> - -an application specific error. Unused. - -=back - -=head1 BUGS - -Although the issuer checks are a considerable improvement over the old technique they still -suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that -trusted certificates with matching subject name must either appear in a file (as specified by the -B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only -the certificates in the file will be recognised. - -Previous versions of OpenSSL assume certificates with matching subject name are identical and -mishandled them. - -Previous versions of this documentation swapped the meaning of the -B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and -B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. - -=head1 SEE ALSO - -L<x509(1)|x509(1)> - -=head1 HISTORY - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/version.pod b/openssl/doc/apps/version.pod deleted file mode 100644 index 58f543b..0000000 --- a/openssl/doc/apps/version.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -version - print OpenSSL version information - -=head1 SYNOPSIS - -B<openssl version> -[B<-a>] -[B<-v>] -[B<-b>] -[B<-o>] -[B<-f>] -[B<-p>] -[B<-d>] - -=head1 DESCRIPTION - -This command is used to print out version information about OpenSSL. - -=head1 OPTIONS - -=over 4 - -=item B<-a> - -all information, this is the same as setting all the other flags. - -=item B<-v> - -the current OpenSSL version. - -=item B<-b> - -the date the current version of OpenSSL was built. - -=item B<-o> - -option information: various options set when the library was built. - -=item B<-f> - -compilation flags. - -=item B<-p> - -platform setting. - -=item B<-d> - -OPENSSLDIR setting. - -=back - -=head1 NOTES - -The output of B<openssl version -a> would typically be used when sending -in a bug report. - -=head1 HISTORY - -The B<-d> option was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/apps/x509.pod b/openssl/doc/apps/x509.pod deleted file mode 100644 index 1479a74..0000000 --- a/openssl/doc/apps/x509.pod +++ /dev/null @@ -1,890 +0,0 @@ - -=pod - -=head1 NAME - -x509 - Certificate display and signing utility - -=head1 SYNOPSIS - -B<openssl> B<x509> -[B<-inform DER|PEM|NET>] -[B<-outform DER|PEM|NET>] -[B<-keyform DER|PEM>] -[B<-CAform DER|PEM>] -[B<-CAkeyform DER|PEM>] -[B<-in filename>] -[B<-out filename>] -[B<-serial>] -[B<-hash>] -[B<-subject_hash>] -[B<-issuer_hash>] -[B<-ocspid>] -[B<-subject>] -[B<-issuer>] -[B<-nameopt option>] -[B<-email>] -[B<-ocsp_uri>] -[B<-startdate>] -[B<-enddate>] -[B<-purpose>] -[B<-dates>] -[B<-checkend num>] -[B<-modulus>] -[B<-pubkey>] -[B<-fingerprint>] -[B<-alias>] -[B<-noout>] -[B<-trustout>] -[B<-clrtrust>] -[B<-clrreject>] -[B<-addtrust arg>] -[B<-addreject arg>] -[B<-setalias arg>] -[B<-days arg>] -[B<-set_serial n>] -[B<-signkey filename>] -[B<-passin arg>] -[B<-x509toreq>] -[B<-req>] -[B<-CA filename>] -[B<-CAkey filename>] -[B<-CAcreateserial>] -[B<-CAserial filename>] -[B<-force_pubkey key>] -[B<-text>] -[B<-certopt option>] -[B<-C>] -[B<-md2|-md5|-sha1|-mdc2>] -[B<-clrext>] -[B<-extfile filename>] -[B<-extensions section>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<x509> command is a multi purpose certificate utility. It can be -used to display certificate information, convert certificates to -various forms, sign certificate requests like a "mini CA" or edit -certificate trust settings. - -Since there are a large number of options they will split up into -various sections. - -=head1 OPTIONS - -=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS - -=over 4 - -=item B<-inform DER|PEM|NET> - -This specifies the input format normally the command will expect an X509 -certificate but this can change if other options such as B<-req> are -present. The DER format is the DER encoding of the certificate and PEM -is the base64 encoding of the DER encoding with header and footer lines -added. The NET option is an obscure Netscape server format that is now -obsolete. - -=item B<-outform DER|PEM|NET> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -This specifies the input filename to read a certificate from or standard input -if this option is not specified. - -=item B<-out filename> - -This specifies the output filename to write to or standard output by -default. - -=item B<-md2|-md5|-sha1|-mdc2> - -the digest to use. This affects any signing or display option that uses a message -digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not -specified then SHA1 is used. If the key being used to sign with is a DSA key -then this option has no effect: SHA1 is always used with DSA keys. - -=item B<-engine id> - -specifying an engine (by its unique B<id> string) will cause B<x509> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head2 DISPLAY OPTIONS - -Note: the B<-alias> and B<-purpose> options are also display options -but are described in the B<TRUST SETTINGS> section. - -=over 4 - -=item B<-text> - -prints out the certificate in text form. Full details are output including the -public key, signature algorithms, issuer and subject names, serial number -any extensions present and any trust settings. - -=item B<-certopt option> - -customise the output format used with B<-text>. The B<option> argument can be -a single option or multiple options separated by commas. The B<-certopt> switch -may be also be used more than once to set multiple options. See the B<TEXT OPTIONS> -section for more information. - -=item B<-noout> - -this option prevents output of the encoded version of the request. - -=item B<-pubkey> - -outputs the the certificate's SubjectPublicKeyInfo block in PEM format. - -=item B<-modulus> - -this option prints out the value of the modulus of the public key -contained in the certificate. - -=item B<-serial> - -outputs the certificate serial number. - -=item B<-subject_hash> - -outputs the "hash" of the certificate subject name. This is used in OpenSSL to -form an index to allow certificates in a directory to be looked up by subject -name. - -=item B<-issuer_hash> - -outputs the "hash" of the certificate issuer name. - -=item B<-ocspid> - -outputs the OCSP hash values for the subject name and public key. - -=item B<-hash> - -synonym for "-subject_hash" for backward compatibility reasons. - -=item B<-subject_hash_old> - -outputs the "hash" of the certificate subject name using the older algorithm -as used by OpenSSL versions before 1.0.0. - -=item B<-issuer_hash_old> - -outputs the "hash" of the certificate issuer name using the older algorithm -as used by OpenSSL versions before 1.0.0. - -=item B<-subject> - -outputs the subject name. - -=item B<-issuer> - -outputs the issuer name. - -=item B<-nameopt option> - -option which determines how the subject or issuer names are displayed. The -B<option> argument can be a single option or multiple options separated by -commas. Alternatively the B<-nameopt> switch may be used more than once to -set multiple options. See the B<NAME OPTIONS> section for more information. - -=item B<-email> - -outputs the email address(es) if any. - -=item B<-ocsp_uri> - -outputs the OCSP responder address(es) if any. - -=item B<-startdate> - -prints out the start date of the certificate, that is the notBefore date. - -=item B<-enddate> - -prints out the expiry date of the certificate, that is the notAfter date. - -=item B<-dates> - -prints out the start and expiry dates of a certificate. - -=item B<-checkend arg> - -checks if the certificate expires within the next B<arg> seconds and exits -non-zero if yes it will expire or zero if not. - -=item B<-fingerprint> - -prints out the digest of the DER encoded version of the whole certificate -(see digest options). - -=item B<-C> - -this outputs the certificate in the form of a C source file. - -=back - -=head2 TRUST SETTINGS - -Please note these options are currently experimental and may well change. - -A B<trusted certificate> is an ordinary certificate which has several -additional pieces of information attached to it such as the permitted -and prohibited uses of the certificate and an "alias". - -Normally when a certificate is being verified at least one certificate -must be "trusted". By default a trusted certificate must be stored -locally and must be a root CA: any certificate chain ending in this CA -is then usable for any purpose. - -Trust settings currently are only used with a root CA. They allow a finer -control over the purposes the root CA can be used for. For example a CA -may be trusted for SSL client but not SSL server use. - -See the description of the B<verify> utility for more information on the -meaning of trust settings. - -Future versions of OpenSSL will recognize trust settings on any -certificate: not just root CAs. - - -=over 4 - -=item B<-trustout> - -this causes B<x509> to output a B<trusted> certificate. An ordinary -or trusted certificate can be input but by default an ordinary -certificate is output and any trust settings are discarded. With the -B<-trustout> option a trusted certificate is output. A trusted -certificate is automatically output if any trust settings are modified. - -=item B<-setalias arg> - -sets the alias of the certificate. This will allow the certificate -to be referred to using a nickname for example "Steve's Certificate". - -=item B<-alias> - -outputs the certificate alias, if any. - -=item B<-clrtrust> - -clears all the permitted or trusted uses of the certificate. - -=item B<-clrreject> - -clears all the prohibited or rejected uses of the certificate. - -=item B<-addtrust arg> - -adds a trusted certificate use. Any object name can be used here -but currently only B<clientAuth> (SSL client use), B<serverAuth> -(SSL server use) and B<emailProtection> (S/MIME email) are used. -Other OpenSSL applications may define additional uses. - -=item B<-addreject arg> - -adds a prohibited use. It accepts the same values as the B<-addtrust> -option. - -=item B<-purpose> - -this option performs tests on the certificate extensions and outputs -the results. For a more complete description see the B<CERTIFICATE -EXTENSIONS> section. - -=back - -=head2 SIGNING OPTIONS - -The B<x509> utility can be used to sign certificates and requests: it -can thus behave like a "mini CA". - -=over 4 - -=item B<-signkey filename> - -this option causes the input file to be self signed using the supplied -private key. - -If the input file is a certificate it sets the issuer name to the -subject name (i.e. makes it self signed) changes the public key to the -supplied value and changes the start and end dates. The start date is -set to the current time and the end date is set to a value determined -by the B<-days> option. Any certificate extensions are retained unless -the B<-clrext> option is supplied. - -If the input is a certificate request then a self signed certificate -is created using the supplied private key using the subject name in -the request. - -=item B<-passin arg> - -the key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-clrext> - -delete any extensions from a certificate. This option is used when a -certificate is being created from another certificate (for example with -the B<-signkey> or the B<-CA> options). Normally all extensions are -retained. - -=item B<-keyform PEM|DER> - -specifies the format (DER or PEM) of the private key file used in the -B<-signkey> option. - -=item B<-days arg> - -specifies the number of days to make a certificate valid for. The default -is 30 days. - -=item B<-x509toreq> - -converts a certificate into a certificate request. The B<-signkey> option -is used to pass the required private key. - -=item B<-req> - -by default a certificate is expected on input. With this option a -certificate request is expected instead. - -=item B<-set_serial n> - -specifies the serial number to use. This option can be used with either -the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA> -option the serial number file (as specified by the B<-CAserial> or -B<-CAcreateserial> options) is not used. - -The serial number can be decimal or hex (if preceded by B<0x>). Negative -serial numbers can also be specified but their use is not recommended. - -=item B<-CA filename> - -specifies the CA certificate to be used for signing. When this option is -present B<x509> behaves like a "mini CA". The input file is signed by this -CA using this option: that is its issuer name is set to the subject name -of the CA and it is digitally signed using the CAs private key. - -This option is normally combined with the B<-req> option. Without the -B<-req> option the input is a certificate which must be self signed. - -=item B<-CAkey filename> - -sets the CA private key to sign a certificate with. If this option is -not specified then it is assumed that the CA private key is present in -the CA certificate file. - -=item B<-CAserial filename> - -sets the CA serial number file to use. - -When the B<-CA> option is used to sign a certificate it uses a serial -number specified in a file. This file consist of one line containing -an even number of hex digits with the serial number to use. After each -use the serial number is incremented and written out to the file again. - -The default filename consists of the CA certificate file base name with -".srl" appended. For example if the CA certificate file is called -"mycacert.pem" it expects to find a serial number file called "mycacert.srl". - -=item B<-CAcreateserial> - -with this option the CA serial number file is created if it does not exist: -it will contain the serial number "02" and the certificate being signed will -have the 1 as its serial number. Normally if the B<-CA> option is specified -and the serial number file does not exist it is an error. - -=item B<-extfile filename> - -file containing certificate extensions to use. If not specified then -no extensions are added to the certificate. - -=item B<-extensions section> - -the section to add certificate extensions from. If this option is not -specified then the extensions should either be contained in the unnamed -(default) section or the default section should contain a variable called -"extensions" which contains the section to use. See the -L<x509v3_config(5)|x509v3_config(5)> manual page for details of the -extension section format. - -=item B<-force_pubkey key> - -when a certificate is created set its public key to B<key> instead of the -key in the certificate or certificate request. This option is useful for -creating certificates where the algorithm can't normally sign requests, for -example DH. - -The format or B<key> can be specified using the B<-keyform> option. - -=back - -=head2 NAME OPTIONS - -The B<nameopt> command line switch determines how the subject and issuer -names are displayed. If no B<nameopt> switch is present the default "oneline" -format is used which is compatible with previous versions of OpenSSL. -Each option is described in detail below, all options can be preceded by -a B<-> to turn the option off. Only the first four will normally be used. - -=over 4 - -=item B<compat> - -use the old format. This is equivalent to specifying no name options at all. - -=item B<RFC2253> - -displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>, -B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>, -B<sep_comma_plus>, B<dn_rev> and B<sname>. - -=item B<oneline> - -a oneline format which is more readable than RFC2253. It is equivalent to -specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>, -B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname> -options. - -=item B<multiline> - -a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, -B<space_eq>, B<lname> and B<align>. - -=item B<esc_2253> - -escape the "special" characters required by RFC2253 in a field That is -B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string -and a space character at the beginning or end of a string. - -=item B<esc_ctrl> - -escape control characters. That is those with ASCII values less than -0x20 (space) and the delete (0x7f) character. They are escaped using the -RFC2253 \XX notation (where XX are two hex digits representing the -character value). - -=item B<esc_msb> - -escape characters with the MSB set, that is with ASCII values larger than -127. - -=item B<use_quote> - -escapes some characters by surrounding the whole string with B<"> characters, -without the option all escaping is done with the B<\> character. - -=item B<utf8> - -convert all strings to UTF8 format first. This is required by RFC2253. If -you are lucky enough to have a UTF8 compatible terminal then the use -of this option (and B<not> setting B<esc_msb>) may result in the correct -display of multibyte (international) characters. Is this option is not -present then multibyte characters larger than 0xff will be represented -using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits. -Also if this option is off any UTF8Strings will be converted to their -character form first. - -=item B<ignore_type> - -this option does not attempt to interpret multibyte characters in any -way. That is their content octets are merely dumped as though one octet -represents each character. This is useful for diagnostic purposes but -will result in rather odd looking output. - -=item B<show_type> - -show the type of the ASN1 character string. The type precedes the -field contents. For example "BMPSTRING: Hello World". - -=item B<dump_der> - -when this option is set any fields that need to be hexdumped will -be dumped using the DER encoding of the field. Otherwise just the -content octets will be displayed. Both options use the RFC2253 -B<#XXXX...> format. - -=item B<dump_nostr> - -dump non character string types (for example OCTET STRING) if this -option is not set then non character string types will be displayed -as though each content octet represents a single character. - -=item B<dump_all> - -dump all fields. This option when used with B<dump_der> allows the -DER encoding of the structure to be unambiguously determined. - -=item B<dump_unknown> - -dump any field whose OID is not recognised by OpenSSL. - -=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>, -B<sep_multiline> - -these options determine the field separators. The first character is -between RDNs and the second between multiple AVAs (multiple AVAs are -very rare and their use is discouraged). The options ending in -"space" additionally place a space after the separator to make it -more readable. The B<sep_multiline> uses a linefeed character for -the RDN separator and a spaced B<+> for the AVA separator. It also -indents the fields by four characters. If no field separator is specified -then B<sep_comma_plus_space> is used by default. - -=item B<dn_rev> - -reverse the fields of the DN. This is required by RFC2253. As a side -effect this also reverses the order of multiple AVAs but this is -permissible. - -=item B<nofname>, B<sname>, B<lname>, B<oid> - -these options alter how the field name is displayed. B<nofname> does -not display the field at all. B<sname> uses the "short name" form -(CN for commonName for example). B<lname> uses the long form. -B<oid> represents the OID in numerical form and is useful for -diagnostic purpose. - -=item B<align> - -align field values for a more readable output. Only usable with -B<sep_multiline>. - -=item B<space_eq> - -places spaces round the B<=> character which follows the field -name. - -=back - -=head2 TEXT OPTIONS - -As well as customising the name output format, it is also possible to -customise the actual fields printed using the B<certopt> options when -the B<text> option is present. The default behaviour is to print all fields. - -=over 4 - -=item B<compatible> - -use the old format. This is equivalent to specifying no output options at all. - -=item B<no_header> - -don't print header information: that is the lines saying "Certificate" and "Data". - -=item B<no_version> - -don't print out the version number. - -=item B<no_serial> - -don't print out the serial number. - -=item B<no_signame> - -don't print out the signature algorithm used. - -=item B<no_validity> - -don't print the validity, that is the B<notBefore> and B<notAfter> fields. - -=item B<no_subject> - -don't print out the subject name. - -=item B<no_issuer> - -don't print out the issuer name. - -=item B<no_pubkey> - -don't print out the public key. - -=item B<no_sigdump> - -don't give a hexadecimal dump of the certificate signature. - -=item B<no_aux> - -don't print out certificate trust information. - -=item B<no_extensions> - -don't print out any X509V3 extensions. - -=item B<ext_default> - -retain default extension behaviour: attempt to print out unsupported certificate extensions. - -=item B<ext_error> - -print an error message for unsupported certificate extensions. - -=item B<ext_parse> - -ASN1 parse unsupported extensions. - -=item B<ext_dump> - -hex dump unsupported extensions. - -=item B<ca_default> - -the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>, -B<no_header>, and B<no_version>. - -=back - -=head1 EXAMPLES - -Note: in these examples the '\' means the example should be all on one -line. - -Display the contents of a certificate: - - openssl x509 -in cert.pem -noout -text - -Display the certificate serial number: - - openssl x509 -in cert.pem -noout -serial - -Display the certificate subject name: - - openssl x509 -in cert.pem -noout -subject - -Display the certificate subject name in RFC2253 form: - - openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 - -Display the certificate subject name in oneline form on a terminal -supporting UTF8: - - openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb - -Display the certificate MD5 fingerprint: - - openssl x509 -in cert.pem -noout -fingerprint - -Display the certificate SHA1 fingerprint: - - openssl x509 -sha1 -in cert.pem -noout -fingerprint - -Convert a certificate from PEM to DER format: - - openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER - -Convert a certificate to a certificate request: - - openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem - -Convert a certificate request into a self signed certificate using -extensions for a CA: - - openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \ - -signkey key.pem -out cacert.pem - -Sign a certificate request using the CA certificate above and add user -certificate extensions: - - openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \ - -CA cacert.pem -CAkey key.pem -CAcreateserial - - -Set a certificate to be trusted for SSL client use and change set its alias to -"Steve's Class 1 CA" - - openssl x509 -in cert.pem -addtrust clientAuth \ - -setalias "Steve's Class 1 CA" -out trust.pem - -=head1 NOTES - -The PEM format uses the header and footer lines: - - -----BEGIN CERTIFICATE----- - -----END CERTIFICATE----- - -it will also handle files containing: - - -----BEGIN X509 CERTIFICATE----- - -----END X509 CERTIFICATE----- - -Trusted certificates have the lines - - -----BEGIN TRUSTED CERTIFICATE----- - -----END TRUSTED CERTIFICATE----- - -The conversion to UTF8 format used with the name options assumes that -T61Strings use the ISO8859-1 character set. This is wrong but Netscape -and MSIE do this as do many certificates. So although this is incorrect -it is more likely to display the majority of certificates correctly. - -The B<-fingerprint> option takes the digest of the DER encoded certificate. -This is commonly called a "fingerprint". Because of the nature of message -digests the fingerprint of a certificate is unique to that certificate and -two certificates with the same fingerprint can be considered to be the same. - -The Netscape fingerprint uses MD5 whereas MSIE uses SHA1. - -The B<-email> option searches the subject name and the subject alternative -name extension. Only unique email addresses will be printed out: it will -not print the same address more than once. - -=head1 CERTIFICATE EXTENSIONS - -The B<-purpose> option checks the certificate extensions and determines -what the certificate can be used for. The actual checks done are rather -complex and include various hacks and workarounds to handle broken -certificates and software. - -The same code is used when verifying untrusted certificates in chains -so this section is useful if a chain is rejected by the verify code. - -The basicConstraints extension CA flag is used to determine whether the -certificate can be used as a CA. If the CA flag is true then it is a CA, -if the CA flag is false then it is not a CA. B<All> CAs should have the -CA flag set to true. - -If the basicConstraints extension is absent then the certificate is -considered to be a "possible CA" other extensions are checked according -to the intended use of the certificate. A warning is given in this case -because the certificate should really not be regarded as a CA: however -it is allowed to be a CA to work around some broken software. - -If the certificate is a V1 certificate (and thus has no extensions) and -it is self signed it is also assumed to be a CA but a warning is again -given: this is to work around the problem of Verisign roots which are V1 -self signed certificates. - -If the keyUsage extension is present then additional restraints are -made on the uses of the certificate. A CA certificate B<must> have the -keyCertSign bit set if the keyUsage extension is present. - -The extended key usage extension places additional restrictions on the -certificate uses. If this extension is present (whether critical or not) -the key can only be used for the purposes specified. - -A complete description of each test is given below. The comments about -basicConstraints and keyUsage and V1 certificates above apply to B<all> -CA certificates. - - -=over 4 - -=item B<SSL Client> - -The extended key usage extension must be absent or include the "web client -authentication" OID. keyUsage must be absent or it must have the -digitalSignature bit set. Netscape certificate type must be absent or it must -have the SSL client bit set. - -=item B<SSL Client CA> - -The extended key usage extension must be absent or include the "web client -authentication" OID. Netscape certificate type must be absent or it must have -the SSL CA bit set: this is used as a work around if the basicConstraints -extension is absent. - -=item B<SSL Server> - -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. keyUsage must be absent or it -must have the digitalSignature, the keyEncipherment set or both bits set. -Netscape certificate type must be absent or have the SSL server bit set. - -=item B<SSL Server CA> - -The extended key usage extension must be absent or include the "web server -authentication" and/or one of the SGC OIDs. Netscape certificate type must -be absent or the SSL CA bit must be set: this is used as a work around if the -basicConstraints extension is absent. - -=item B<Netscape SSL Server> - -For Netscape SSL clients to connect to an SSL server it must have the -keyEncipherment bit set if the keyUsage extension is present. This isn't -always valid because some cipher suites use the key for digital signing. -Otherwise it is the same as a normal SSL server. - -=item B<Common S/MIME Client Tests> - -The extended key usage extension must be absent or include the "email -protection" OID. Netscape certificate type must be absent or should have the -S/MIME bit set. If the S/MIME bit is not set in netscape certificate type -then the SSL client bit is tolerated as an alternative but a warning is shown: -this is because some Verisign certificates don't set the S/MIME bit. - -=item B<S/MIME Signing> - -In addition to the common S/MIME client tests the digitalSignature bit must -be set if the keyUsage extension is present. - -=item B<S/MIME Encryption> - -In addition to the common S/MIME tests the keyEncipherment bit must be set -if the keyUsage extension is present. - -=item B<S/MIME CA> - -The extended key usage extension must be absent or include the "email -protection" OID. Netscape certificate type must be absent or must have the -S/MIME CA bit set: this is used as a work around if the basicConstraints -extension is absent. - -=item B<CRL Signing> - -The keyUsage extension must be absent or it must have the CRL signing bit -set. - -=item B<CRL Signing CA> - -The normal CA tests apply. Except in this case the basicConstraints extension -must be present. - -=back - -=head1 BUGS - -Extensions in certificates are not transferred to certificate requests and -vice versa. - -It is possible to produce invalid certificates or requests by specifying the -wrong private key or using inconsistent options in some cases: these should -be checked. - -There should be options to explicitly set such things as start and end -dates rather than an offset from the current time. - -The code to implement the verify behaviour described in the B<TRUST SETTINGS> -is currently being developed. It thus describes the intended behaviour rather -than the current behaviour. It is hoped that it will represent reality in -OpenSSL 0.9.5 and later. - -=head1 SEE ALSO - -L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>, -L<x509v3_config(5)|x509v3_config(5)> - -=head1 HISTORY - -Before OpenSSL 0.9.8, the default digest for RSA keys was MD5. - -The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options -before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding -of the distinguished name. In OpenSSL 1.0.0 and later it is based on a -canonical version of the DN using SHA1. This means that any directories using -the old form must have their links rebuilt using B<c_rehash> or similar. - -=cut diff --git a/openssl/doc/apps/x509v3_config.pod b/openssl/doc/apps/x509v3_config.pod deleted file mode 100644 index fb5f79c..0000000 --- a/openssl/doc/apps/x509v3_config.pod +++ /dev/null @@ -1,529 +0,0 @@ -=pod - -=for comment openssl_manual_section:5 - -=head1 NAME - -x509v3_config - X509 V3 certificate extension configuration format - -=head1 DESCRIPTION - -Several of the OpenSSL utilities can add extensions to a certificate or -certificate request based on the contents of a configuration file. - -Typically the application will contain an option to point to an extension -section. Each line of the extension section takes the form: - - extension_name=[critical,] extension_options - -If B<critical> is present then the extension will be critical. - -The format of B<extension_options> depends on the value of B<extension_name>. - -There are four main types of extension: I<string> extensions, I<multi-valued> -extensions, I<raw> and I<arbitrary> extensions. - -String extensions simply have a string which contains either the value itself -or how it is obtained. - -For example: - - nsComment="This is a Comment" - -Multi-valued extensions have a short form and a long form. The short form -is a list of names and values: - - basicConstraints=critical,CA:true,pathlen:1 - -The long form allows the values to be placed in a separate section: - - basicConstraints=critical,@bs_section - - [bs_section] - - CA=true - pathlen=1 - -Both forms are equivalent. - -The syntax of raw extensions is governed by the extension code: it can -for example contain data in multiple sections. The correct syntax to -use is defined by the extension code itself: check out the certificate -policies extension for an example. - -If an extension type is unsupported then the I<arbitrary> extension syntax -must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details. - -=head1 STANDARD EXTENSIONS - -The following sections describe each supported extension in detail. - -=head2 Basic Constraints. - -This is a multi valued extension which indicates whether a certificate is -a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or -B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an -non-negative value can be included. - -For example: - - basicConstraints=CA:TRUE - - basicConstraints=CA:FALSE - - basicConstraints=critical,CA:TRUE, pathlen:0 - -A CA certificate B<must> include the basicConstraints value with the CA field -set to TRUE. An end user certificate must either set CA to FALSE or exclude the -extension entirely. Some software may require the inclusion of basicConstraints -with CA set to FALSE for end entity certificates. - -The pathlen parameter indicates the maximum number of CAs that can appear -below this one in a chain. So if you have a CA with a pathlen of zero it can -only be used to sign end user certificates and not further CAs. - - -=head2 Key Usage. - -Key usage is a multi valued extension consisting of a list of names of the -permitted key usages. - -The supporte names are: digitalSignature, nonRepudiation, keyEncipherment, -dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly -and decipherOnly. - -Examples: - - keyUsage=digitalSignature, nonRepudiation - - keyUsage=critical, keyCertSign - - -=head2 Extended Key Usage. - -This extensions consists of a list of usages indicating purposes for which -the certificate public key can be used for, - -These can either be object short names or the dotted numerical form of OIDs. -While any OID can be used only certain values make sense. In particular the -following PKIX, NS and MS values are meaningful: - - Value Meaning - ----- ------- - serverAuth SSL/TLS Web Server Authentication. - clientAuth SSL/TLS Web Client Authentication. - codeSigning Code signing. - emailProtection E-mail Protection (S/MIME). - timeStamping Trusted Timestamping - msCodeInd Microsoft Individual Code Signing (authenticode) - msCodeCom Microsoft Commercial Code Signing (authenticode) - msCTLSign Microsoft Trust List Signing - msSGC Microsoft Server Gated Crypto - msEFS Microsoft Encrypted File System - nsSGC Netscape Server Gated Crypto - -Examples: - - extendedKeyUsage=critical,codeSigning,1.2.3.4 - extendedKeyUsage=nsSGC,msSGC - - -=head2 Subject Key Identifier. - -This is really a string extension and can take two possible values. Either -the word B<hash> which will automatically follow the guidelines in RFC3280 -or a hex string giving the extension value to include. The use of the hex -string is strongly discouraged. - -Example: - - subjectKeyIdentifier=hash - - -=head2 Authority Key Identifier. - -The authority key identifier extension permits two options. keyid and issuer: -both can take the optional value "always". - -If the keyid option is present an attempt is made to copy the subject key -identifier from the parent certificate. If the value "always" is present -then an error is returned if the option fails. - -The issuer option copies the issuer and serial number from the issuer -certificate. This will only be done if the keyid option fails or -is not included unless the "always" flag will always include the value. - -Example: - - authorityKeyIdentifier=keyid,issuer - - -=head2 Subject Alternative Name. - -The subject alternative name extension allows various literal values to be -included in the configuration file. These include B<email> (an email address) -B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a -registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName> -(a distinguished name) and otherName. - -The email option include a special 'copy' value. This will automatically -include and email addresses contained in the certificate subject name in -the extension. - -The IP address used in the B<IP> options can be in either IPv4 or IPv6 format. - -The value of B<dirName> should point to a section containing the distinguished -name to use as a set of name value pairs. Multi values AVAs can be formed by -prefacing the name with a B<+> character. - -otherName can include arbitrary data associated with an OID: the value -should be the OID followed by a semicolon and the content in standard -L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. - -Examples: - - subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ - subjectAltName=IP:192.168.7.1 - subjectAltName=IP:13::17 - subjectAltName=email:my@other.address,RID:1.2.3.4 - subjectAltName=otherName:1.2.3.4;UTF8:some other identifier - - subjectAltName=dirName:dir_sect - - [dir_sect] - C=UK - O=My Organization - OU=My Unit - CN=My Name - - -=head2 Issuer Alternative Name. - -The issuer alternative name option supports all the literal options of -subject alternative name. It does B<not> support the email:copy option because -that would not make sense. It does support an additional issuer:copy option -that will copy all the subject alternative name values from the issuer -certificate (if possible). - -Example: - - issuserAltName = issuer:copy - - -=head2 Authority Info Access. - -The authority information access extension gives details about how to access -certain information relating to the CA. Its syntax is accessOID;location -where I<location> has the same syntax as subject alternative name (except -that email:copy is not supported). accessOID can be any valid OID but only -certain values are meaningful, for example OCSP and caIssuers. - -Example: - - authorityInfoAccess = OCSP;URI:http://ocsp.my.host/ - authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html - - -=head2 CRL distribution points. - -This is a multi-valued extension whose options can be either in name:value pair -using the same form as subject alternative name or a single value representing -a section name containing all the distribution point fields. - -For a name:value pair a new DistributionPoint with the fullName field set to -the given value both the cRLissuer and reasons fields are omitted in this case. - -In the single option case the section indicated contains values for each -field. In this section: - -If the name is "fullname" the value field should contain the full name -of the distribution point in the same format as subject alternative name. - -If the name is "relativename" then the value field should contain a section -name whose contents represent a DN fragment to be placed in this field. - -The name "CRLIssuer" if present should contain a value for this field in -subject alternative name format. - -If the name is "reasons" the value field should consist of a comma -separated field containing the reasons. Valid reasons are: "keyCompromise", -"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation", -"certificateHold", "privilegeWithdrawn" and "AACompromise". - - -Simple examples: - - crlDistributionPoints=URI:http://myhost.com/myca.crl - crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl - -Full distribution point example: - - crlDistributionPoints=crldp1_section - - [crldp1_section] - - fullname=URI:http://myhost.com/myca.crl - CRLissuer=dirName:issuer_sect - reasons=keyCompromise, CACompromise - - [issuer_sect] - C=UK - O=Organisation - CN=Some Name - -=head2 Issuing Distribution Point - -This extension should only appear in CRLs. It is a multi valued extension -whose syntax is similar to the "section" pointed to by the CRL distribution -points extension with a few differences. - -The names "reasons" and "CRLissuer" are not recognized. - -The name "onlysomereasons" is accepted which sets this field. The value is -in the same format as the CRL distribution point "reasons" field. - -The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted -the values should be a boolean value (TRUE or FALSE) to indicate the value of -the corresponding field. - -Example: - - issuingDistributionPoint=critical, @idp_section - - [idp_section] - - fullname=URI:http://myhost.com/myca.crl - indirectCRL=TRUE - onlysomereasons=keyCompromise, CACompromise - - [issuer_sect] - C=UK - O=Organisation - CN=Some Name - - -=head2 Certificate Policies. - -This is a I<raw> extension. All the fields of this extension can be set by -using the appropriate syntax. - -If you follow the PKIX recommendations and just using one OID then you just -include the value of that OID. Multiple OIDs can be set separated by commas, -for example: - - certificatePolicies= 1.2.4.5, 1.1.3.4 - -If you wish to include qualifiers then the policy OID and qualifiers need to -be specified in a separate section: this is done by using the @section syntax -instead of a literal OID value. - -The section referred to must include the policy OID using the name -policyIdentifier, cPSuri qualifiers can be included using the syntax: - - CPS.nnn=value - -userNotice qualifiers can be set using the syntax: - - userNotice.nnn=@notice - -The value of the userNotice qualifier is specified in the relevant section. -This section can include explicitText, organization and noticeNumbers -options. explicitText and organization are text strings, noticeNumbers is a -comma separated list of numbers. The organization and noticeNumbers options -(if included) must BOTH be present. If you use the userNotice option with IE5 -then you need the 'ia5org' option at the top level to modify the encoding: -otherwise it will not be interpreted properly. - -Example: - - certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect - - [polsect] - - policyIdentifier = 1.3.5.8 - CPS.1="http://my.host.name/" - CPS.2="http://my.your.name/" - userNotice.1=@notice - - [notice] - - explicitText="Explicit Text Here" - organization="Organisation Name" - noticeNumbers=1,2,3,4 - -The B<ia5org> option changes the type of the I<organization> field. In RFC2459 -it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible. -Some software (for example some versions of MSIE) may require ia5org. - -=head2 Policy Constraints - -This is a multi-valued extension which consisting of the names -B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger -value. At least one component must be present. - -Example: - - policyConstraints = requireExplicitPolicy:3 - - -=head2 Inhibit Any Policy - -This is a string extension whose value must be a non negative integer. - -Example: - - inhibitAnyPolicy = 2 - - -=head2 Name Constraints - -The name constraints extension is a multi-valued extension. The name should -begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of -the name and the value follows the syntax of subjectAltName except email:copy -is not supported and the B<IP> form should consist of an IP addresses and -subnet mask separated by a B</>. - -Examples: - - nameConstraints=permitted;IP:192.168.0.0/255.255.0.0 - - nameConstraints=permitted;email:.somedomain.com - - nameConstraints=excluded;email:.com - - -=head2 OCSP No Check - -The OCSP No Check extension is a string extension but its value is ignored. - -Example: - - noCheck = ignored - - -=head1 DEPRECATED EXTENSIONS - -The following extensions are non standard, Netscape specific and largely -obsolete. Their use in new applications is discouraged. - -=head2 Netscape String extensions. - -Netscape Comment (B<nsComment>) is a string extension containing a comment -which will be displayed when the certificate is viewed in some browsers. - -Example: - - nsComment = "Some Random Comment" - -Other supported extensions in this category are: B<nsBaseUrl>, -B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> -and B<nsSslServerName>. - - -=head2 Netscape Certificate Type - -This is a multi-valued extensions which consists of a list of flags to be -included. It was used to indicate the purposes for which a certificate could -be used. The basicConstraints, keyUsage and extended key usage extensions are -now used instead. - -Acceptable values for nsCertType are: B<client>, B<server>, B<email>, -B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. - - -=head1 ARBITRARY EXTENSIONS - -If an extension is not supported by the OpenSSL code then it must be encoded -using the arbitrary extension format. It is also possible to use the arbitrary -format for supported extensions. Extreme care should be taken to ensure that -the data is formatted correctly for the given extension type. - -There are two ways to encode arbitrary extensions. - -The first way is to use the word ASN1 followed by the extension content -using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>. -For example: - - 1.2.3.4=critical,ASN1:UTF8String:Some random data - - 1.2.3.4=ASN1:SEQUENCE:seq_sect - - [seq_sect] - - field1 = UTF8:field1 - field2 = UTF8:field2 - -It is also possible to use the word DER to include the raw encoded data in any -extension. - - 1.2.3.4=critical,DER:01:02:03:04 - 1.2.3.4=DER:01020304 - -The value following DER is a hex dump of the DER encoding of the extension -Any extension can be placed in this form to override the default behaviour. -For example: - - basicConstraints=critical,DER:00:01:02:03 - -=head1 WARNING - -There is no guarantee that a specific implementation will process a given -extension. It may therefore be sometimes possible to use certificates for -purposes prohibited by their extensions because a specific application does -not recognize or honour the values of the relevant extensions. - -The DER and ASN1 options should be used with caution. It is possible to create -totally invalid extensions if they are not used carefully. - - -=head1 NOTES - -If an extension is multi-value and a field value must contain a comma the long -form must be used otherwise the comma would be misinterpreted as a field -separator. For example: - - subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar - -will produce an error but the equivalent form: - - subjectAltName=@subject_alt_section - - [subject_alt_section] - subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar - -is valid. - -Due to the behaviour of the OpenSSL B<conf> library the same field name -can only occur once in a section. This means that: - - subjectAltName=@alt_section - - [alt_section] - - email=steve@here - email=steve@there - -will only recognize the last value. This can be worked around by using the form: - - [alt_section] - - email.1=steve@here - email.2=steve@there - -=head1 HISTORY - -The X509v3 extension code was first added to OpenSSL 0.9.2. - -Policy mappings, inhibit any policy and name constraints support was added in -OpenSSL 0.9.8 - -The B<directoryName> and B<otherName> option as well as the B<ASN1> option -for arbitrary extensions was added in OpenSSL 0.9.8 - -=head1 SEE ALSO - -L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>, -L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> - - -=cut |