From: Rich Salz Date: Wed, 26 Oct 2016 17:56:48 +0000 (-0400) Subject: Move manpages to man[1357] structure. X-Git-Tag: OpenSSL_1_1_1-pre1~3328 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=99d63d4;p=oweals%2Fopenssl.git Move manpages to man[1357] structure. Move manpages to manX directories Add Windows/VMS install fix from Richard Levitte Update README Fix typo's Remove some duplicates Reviewed-by: Richard Levitte --- diff --git a/Configurations/unix-Makefile.tmpl b/Configurations/unix-Makefile.tmpl index 8d1dfbefcf..c24ba622ad 100644 --- a/Configurations/unix-Makefile.tmpl +++ b/Configurations/unix-Makefile.tmpl @@ -573,12 +573,9 @@ PROCESS_PODS=\ set -e; \ here=`cd $(SRCDIR); pwd`; \ point=$$here/util/point.sh; \ - for ds in apps:1 crypto:3 ssl:3; do \ - defdir=`echo $$ds | cut -f1 -d:`; \ - defsec=`echo $$ds | cut -f2 -d:`; \ - for p in $(SRCDIR)/doc/$$defdir/*.pod; do \ - SEC=`sed -ne 's/^=for *comment *openssl_manual_section: *\([0-9]\) *$$/\1/p' $$p`; \ - [ -z "$$SEC" ] && SEC=$$defsec; \ + for ds in man1 man3 man5 man7 ; do \ + SEC=`echo $$ds | sed -e s/man//`; \ + for p in $(SRCDIR)/doc/$$ds/*.pod; do \ fn=`basename $$p .pod`; \ Name=$$fn; \ NAME=`echo $$fn | tr '[a-z]' '[A-Z]'`; \ @@ -608,12 +605,9 @@ PROCESS_PODS=\ UNINSTALL_DOCS=\ set -e; \ here=`cd $(SRCDIR); pwd`; \ - for ds in apps:1 crypto:3 ssl:3; do \ - defdir=`echo $$ds | cut -f1 -d:`; \ - defsec=`echo $$ds | cut -f2 -d:`; \ - for p in $(SRCDIR)/doc/$$defdir/*.pod; do \ - SEC=`sed -ne 's/^=for *comment *openssl_manual_section: *\([0-9]\) *$$/\1/p' $$p`; \ - [ -z "$$SEC" ] && SEC=$$defsec; \ + for ds in man1 man3 man5 man7 ; do \ + SEC=`echo $$ds | sed -e s/man//`; \ + for p in $(SRCDIR)/doc/$$ds/*.pod; do \ fn=`basename $$p .pod`; \ suf=`eval "echo $$OUTSUFFIX"`; \ top=`eval "echo $$OUTTOP"`; \ diff --git a/doc/README b/doc/README index 5931290230..ead1be278a 100644 --- a/doc/README +++ b/doc/README @@ -9,12 +9,18 @@ standards.txt HOWTO/ A few how-to documents; not necessarily up-to-date -apps/ + +man1/ The openssl command-line tools; start with openssl.pod -ssl/ - The SSL library; start with ssl.pod -crypto/ - The cryptographic library; start with crypto.pod + +man3/ + The SSL library and the crypto library + +man5/ + File formats + +man7/ + Overviews; start with crypto.pod and ssl.pod, for example Formatted versions of the manpages (apps,ssl,crypto) can be found at https://www.openssl.org/docs/manpages.html diff --git a/doc/apps/CA.pl.pod b/doc/apps/CA.pl.pod deleted file mode 100644 index ed30d6a2d1..0000000000 --- a/doc/apps/CA.pl.pod +++ /dev/null @@ -1,198 +0,0 @@ -=pod - -=head1 NAME - -CA.pl - friendlier interface for OpenSSL certificate programs - -=head1 SYNOPSIS - -B -[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] - -=head1 DESCRIPTION - -The B script is a perl script that supplies the relevant command line -arguments to the B 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 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 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 and so makes the signed request a valid CA certificate. This -is useful when creating intermediate CA from a root CA. - -=item B<-signcert> - -this option is the same as B<-sign> except it expects a self signed certificate -to be present in the file "newreq.pem". - -=item B<-crl> - -generate a CRL - -=item B<-revoke certfile [reason]> - -revoke the certificate contained in the specified B. An optional -reason may be specified, and must be one of: B, -B, B, B, B, -B, B, or B. - -=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 - -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 creates RSA CAs and requests it is still possible to -use it with DSA certificates and requests using the L 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 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 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 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 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 command directly. - -=head1 ENVIRONMENT VARIABLES - -The variable B 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, L, L, L, -L - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/apps/asn1parse.pod b/doc/apps/asn1parse.pod deleted file mode 100644 index ee09a83cf7..0000000000 --- a/doc/apps/asn1parse.pod +++ /dev/null @@ -1,214 +0,0 @@ -=pod - -=head1 NAME - -asn1parse - ASN.1 parsing tool - -=head1 SYNOPSIS - -B B -[B<-help>] -[B<-inform PEM|DER>] -[B<-in filename>] -[B<-out filename>] -[B<-noout>] -[B<-offset number>] -[B<-length number>] -[B<-i>] -[B<-oid filename>] -[B<-dump>] -[B<-dlimit num>] -[B<-strparse offset>] -[B<-genstr string>] -[B<-genconf file>] -[B<-strictpem>] -[B<-item name>] - -=head1 DESCRIPTION - -The B command is a diagnostic utility that can parse ASN.1 -structures. It can also be used to extract data from ASN.1 formatted data. - -=head1 OPTIONS - -=over 4 - -=item B<-help> - -Print out a usage message. - -=item B<-inform> B - -the input format. B is binary format and B (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 bytes are output. - -=item B<-strparse offset> - -parse the contents octets of the ASN.1 object starting at B. 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, B or both using -L format. If B only is -present then the string is obtained from the default section using the name -B. 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 option. - -=item B<-strictpem> - -If this option is used then B<-inform> will be ignored. Without this option any -data in a PEM format input file will be treated as being base64 encoded and -processed whether it has the normal PEM BEGIN and END markers or not. This -option will ignore any data prior to the start of the BEGIN marker, or after an -END marker in a PEM file. - -=item B<-item name> - -attempt to decode and print the data as B. This can be used to -print out the fields of any supported ASN.1 structure if the type is known. - -=back - -=head2 Output - -The output will typically contain lines like this: - - 0:d=0 hl=4 l= 681 cons: SEQUENCE - -..... - - 229:d=3 hl=3 l= 141 prim: BIT STRING - 373:d=2 hl=3 l= 162 cons: cont [ 3 ] - 376:d=3 hl=3 l= 159 cons: SEQUENCE - 379:d=4 hl=2 l= 29 cons: SEQUENCE - 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier - 386:d=5 hl=2 l= 22 prim: OCTET STRING - 410:d=4 hl=2 l= 112 cons: SEQUENCE - 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier - 417:d=5 hl=2 l= 105 prim: OCTET STRING - 524:d=4 hl=2 l= 12 cons: SEQUENCE - -..... - -This example is part of a self-signed certificate. Each line starts with the -offset in decimal. B specifies the current depth. The depth is increased -within the scope of any SET or SEQUENCE. B gives the header length -(tag and length octets) of the current type. B 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 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 - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod deleted file mode 100644 index 3be6979588..0000000000 --- a/doc/apps/ca.pod +++ /dev/null @@ -1,722 +0,0 @@ -=pod - -=head1 NAME - -ca - sample minimal CA application - -=head1 SYNOPSIS - -B B -[B<-help>] -[B<-verbose>] -[B<-config filename>] -[B<-name section>] -[B<-gencrl>] -[B<-revoke file>] -[B<-valid file>] -[B<-status serial>] -[B<-updatedb>] -[B<-crl_reason reason>] -[B<-crl_hold instruction>] -[B<-crl_compromise time>] -[B<-crl_CA_compromise time>] -[B<-crldays days>] -[B<-crlhours hours>] -[B<-crlexts section>] -[B<-startdate date>] -[B<-enddate date>] -[B<-days arg>] -[B<-md arg>] -[B<-policy arg>] -[B<-keyfile arg>] -[B<-keyform PEM|DER>] -[B<-key arg>] -[B<-passin arg>] -[B<-cert file>] -[B<-selfsign>] -[B<-in file>] -[B<-out file>] -[B<-notext>] -[B<-outdir dir>] -[B<-infiles>] -[B<-spkac file>] -[B<-ss_cert file>] -[B<-preserveDN>] -[B<-noemailDN>] -[B<-batch>] -[B<-msie_hack>] -[B<-extensions section>] -[B<-extfile section>] -[B<-engine id>] -[B<-subj arg>] -[B<-utf8>] -[B<-create_serial>] -[B<-multivalue-rdn>] - -=head1 DESCRIPTION - -The B command is a minimal CA application. It can be used -to sign certificate requests in a variety of forms and generate -CRLs it also maintains a text database of issued certificates -and their status. - -The options descriptions will be divided into each purpose. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-help> - -Print out a usage message. - -=item B<-verbose> - -this prints extra details about the operations being performed. - -=item B<-config filename> - -specifies the configuration file to use. - -=item B<-name section> - -specifies the configuration file section to use (overrides -B in the B 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 -section for information on the required input and output format. - -=item B<-infiles> - -if present this should be the last option, all subsequent arguments -are taken as the names of files containing certificate requests. - -=item B<-out filename> - -the output file to output certificates to. The default is standard -output. The certificate details will also be printed out to this -file in PEM format (except that B<-spkac> outputs DER format). - -=item B<-outdir directory> - -the directory to output certificates to. The certificate will be -written to a filename consisting of the serial number in hex with -".pem" appended. - -=item B<-cert> - -the CA certificate file. - -=item B<-keyfile filename> - -the private key to sign requests with. - -=item B<-keyform PEM|DER> - -the format of the data in the private key file. -The default is PEM. - -=item B<-key password> - -the password used to encrypt the private key. Since on some -systems the command line arguments are visible (e.g. Unix with -the 'ps' utility) this option should be used with caution. - -=item B<-selfsign> - -indicates the issued certificates are to be signed with the key -the certificate requests were signed with (given with B<-keyfile>). -Certificate requests signed with a different key are ignored. If -B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is -ignored. - -A consequence of using B<-selfsign> is that the self-signed -certificate appears among the entries in the certificate database -(see the configuration option B), 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 -see the B section in L. - -=item B<-notext> - -don't output the text form of a certificate to the output file. - -=item B<-startdate date> - -this allows the start date to be explicitly set. The format of the -date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). - -=item B<-enddate date> - -this allows the expiry date to be explicitly set. The format of the -date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). - -=item B<-days arg> - -the number of days to certify the certificate for. - -=item B<-md alg> - -the message digest to use. -Any digest supported by the OpenSSL B command can be used. -This option also applies to CRLs. - -=item B<-policy arg> - -this option defines the CA "policy" to use. This is a section in -the configuration file which decides which fields should be mandatory -or match the CA certificate. Check out the B section -for more information. - -=item B<-msie_hack> - -this is a legacy option to make B 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 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 -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 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 string) will cause B -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, -characters may be escaped by \ (backslash), no spaces are skipped. - -=item B<-utf8> - -this option causes field values to be interpreted as UTF8 strings, by -default they are interpreted as ASCII. This means that the field -values, whether prompted from a terminal or obtained from a -configuration file, must be valid UTF8 strings. - -=item B<-create_serial> - -if reading serial from the text file as specified in the configuration -fails, specifying this option creates a new random serial to be used as next -serial number. - -=item B<-multivalue-rdn> - -This option causes the -subj argument to be interpreted with full -support for multivalued RDNs. Example: - -I - -If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. - -=back - -=head1 CRL OPTIONS - -=over 4 - -=item B<-gencrl> - -this option generates a CRL based on information in the index file. - -=item B<-crldays num> - -the number of days before the next CRL is due. That is the days from -now to place in the CRL nextUpdate field. - -=item B<-crlhours num> - -the number of hours before the next CRL is due. - -=item B<-revoke filename> - -a filename containing a certificate to revoke. - -=item B<-valid filename> - -a filename containing a certificate to add a Valid certificate entry. - -=item B<-status serial> - -displays the revocation status of the certificate with the specified -serial number and exits. - -=item B<-updatedb> - -Updates the database index to purge expired certificates. - -=item B<-crl_reason reason> - -revocation reason, where B is one of: B, B, -B, B, B, B, -B or B. The matching of B is case -insensitive. Setting any revocation reason will make the CRL v2. - -In practice B 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 and the hold -instruction to B which must be an OID. Although any OID can be -used only B (the use of which is discouraged by RFC2459) -B or B will normally be used. - -=item B<-crl_compromise time> - -This sets the revocation reason to B and the compromise time to -B