:-'Generic Commit'

dropshell-tool/openssl-1.1.1w/doc/man1/CA.pl.pod

@@ -0,0 +1,214 @@
+=pod
+
+=head1 NAME
+
+CA.pl - friendlier interface for OpenSSL certificate programs
+
+=head1 SYNOPSIS
+
+B<CA.pl>
+B<-?> |
+B<-h> |
+B<-help>
+
+B<CA.pl>
+B<-newcert> |
+B<-newreq> |
+B<-newreq-nodes> |
+B<-xsign> |
+B<-sign> |
+B<-signCA> |
+B<-signcert> |
+B<-crl> |
+B<-newca>
+[B<-extra-cmd> extra-params]
+
+B<CA.pl> B<-pkcs12> [B<-extra-pkcs12> extra-params] [B<certname>]
+
+B<CA.pl> B<-verify> [B<-extra-verify> extra-params] B<certfile>...
+
+B<CA.pl> B<-revoke> [B<-extra-ca> extra-params] B<certfile> [B<reason>]
+
+=head1 DESCRIPTION
+
+The B<CA.pl> script is a perl script that supplies the relevant command line
+arguments to the B<openssl> command for some common certificate operations.
+It is intended to simplify the process of certificate creation and management
+by the use of some simple options.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<?>, B<-h>, B<-help>
+
+Prints a usage message.
+
+=item B<-newcert>
+
+Creates a new self signed certificate. The private key is written to the file
+"newkey.pem" and the request written to the file "newreq.pem".
+This argument invokes B<openssl req> command.
+
+=item B<-newreq>
+
+Creates a new certificate request. The private key is written to the file
+"newkey.pem" and the request written to the file "newreq.pem".
+Executes B<openssl req> command below the hood.
+
+=item B<-newreq-nodes>
+
+Is like B<-newreq> except that the private key will not be encrypted.
+Uses B<openssl req> command.
+
+=item B<-newca>
+
+Creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert>
+and B<-xsign> options). The user is prompted to enter the filename of the CA
+certificates (which should also contain the private key) or by hitting ENTER
+details of the CA will be prompted for. The relevant files and directories
+are created in a directory called "demoCA" in the current directory.
+B<openssl req> and B<openssl ca> commands are get invoked.
+
+=item B<-pkcs12>
+
+Create a PKCS#12 file containing the user certificate, private key and CA
+certificate. It expects the user certificate and private key to be in the
+file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem,
+it creates a file "newcert.p12". This command can thus be called after the
+B<-sign> option. The PKCS#12 file can be imported directly into a browser.
+If there is an additional argument on the command line it will be used as the
+"friendly name" for the certificate (which is typically displayed in the browser
+list box), otherwise the name "My Certificate" is used.
+Delegates work to B<openssl pkcs12> command.
+
+=item B<-sign>, B<-signcert>, B<-xsign>
+
+Calls the B<ca> program to sign a certificate request. It expects the request
+to be in the file "newreq.pem". The new certificate is written to the file
+"newcert.pem" except in the case of the B<-xsign> option when it is written
+to standard output. Leverages B<openssl ca> command.
+
+=item B<-signCA>
+
+This option is the same as the B<-sign> option except it uses the
+configuration file section B<v3_ca> and so makes the signed request a
+valid CA certificate. This is useful when creating intermediate CA from
+a root CA.  Extra params are passed on to B<openssl ca> command.
+
+=item B<-signcert>
+
+This option is the same as B<-sign> except it expects a self signed certificate
+to be present in the file "newreq.pem".
+Extra params are passed on to B<openssl x509> and B<openssl ca> commands.
+
+=item B<-crl>
+
+Generate a CRL. Executes B<openssl ca> command.
+
+=item B<-revoke certfile [reason]>
+
+Revoke the certificate contained in the specified B<certfile>. An optional
+reason may be specified, and must be one of: B<unspecified>,
+B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
+B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
+Leverages B<openssl ca> command.
+
+=item B<-verify>
+
+Verifies certificates against the CA certificate for "demoCA". If no
+certificates are specified on the command line it tries to verify the file
+"newcert.pem".  Invokes B<openssl verify> command.
+
+=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> <extra-params>
+
+The purpose of these parameters is to allow optional parameters to be supplied
+to B<openssl> that this command executes. The B<-extra-cmd> are specific to the
+option being used and the B<openssl> command getting invoked. For example
+when this command invokes B<openssl req> extra parameters can be passed on
+with the B<-extra-req> parameter. The
+B<openssl> commands being invoked per option are documented below.
+Users should consult B<openssl> command documentation for more information.
+
+=back
+
+=head1 EXAMPLES
+
+Create a CA hierarchy:
+
+ CA.pl -newca
+
+Complete certificate creation example: create a CA, create a request, sign
+the request and finally create a PKCS#12 file containing it.
+
+ CA.pl -newca
+ CA.pl -newreq
+ CA.pl -sign
+ CA.pl -pkcs12 "My Test Certificate"
+
+=head1 DSA CERTIFICATES
+
+Although the B<CA.pl> creates RSA CAs and requests it is still possible to
+use it with DSA certificates and requests using the L<req(1)> command
+directly. The following example shows the steps that would typically be taken.
+
+Create some DSA parameters:
+
+ openssl dsaparam -out dsap.pem 1024
+
+Create a DSA CA certificate and private key:
+
+ openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem
+
+Create the CA directories and files:
+
+ CA.pl -newca
+
+enter cacert.pem when prompted for the CA filename.
+
+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 -sign
+
+=head1 NOTES
+
+Most of the filenames mentioned can be modified by editing the B<CA.pl> script.
+
+If the demoCA directory already exists then the B<-newca> command will not
+overwrite it and will do nothing. This can happen if a previous call using
+the B<-newca> option terminated abnormally. To get the correct behaviour
+delete the demoCA directory if it already exists.
+
+Under some environments it may not be possible to run the B<CA.pl> script
+directly (for example Win32) and the default configuration file location may
+be wrong. In this case the command:
+
+ perl -S CA.pl
+
+can be used and the B<OPENSSL_CONF> environment variable changed to point to
+the correct path of the configuration file.
+
+The script is intended as a simple front end for the B<openssl> program for use
+by a beginner. Its behaviour isn't always what is wanted. For more control over the
+behaviour of the certificate commands call the B<openssl> command directly.
+
+=head1 SEE ALSO
+
+L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>,
+L<config(5)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut