gimmecert Changeset - 08ba658f3c35

Changeset - 08ba658f3c35

Parent rev.

Child rev.

[Not reviewed]

0 2 0

Branko Majic (branko) - 8 years ago 2018-05-04 22:45:43
branko@majic.rs

GC-23: Updated documentation related to move of --update-dns-option from server to renew command:

- Updated the server command usage instructions to include reference
to --update-dns-option in the renew command.
- Added relevant documentation on use of the --update-dns-names option
to the usage instructions for renew command.
- Update the CLI examples.

2 files changed with 25 insertions and 26 deletions:

docs/usage.rst

gimmecert/cli.py

0 comments (0 inline, 0 general)

docs/usage.rst

➞

Show inline comments

 where ``NAME`` is passed-in via positional argument.
 By default the certificate will include the passed-in server name as
 one of its DNS subject alternative names, but additional DNS names can
 be passed-in as well. For example::
   gimmecert server myserver myserver.local service.example.com
 Key usage and extended key usage in certificate are set typical TLS
 server use (e.g. *digital signature* + *key encipherment* for KU, and
 *TLS WWW server authentication* for EKU).
 Rerunning the command will not overwrite existing data. However, if
 you made a mistake with additional DNS subject alternative names, you
 can easily fix this with the ``--update-dns-names`` option::
   # Replace existing additional names.
   gimmecert server --update-dns-names myserver correctname.example.com
   # Remove additional names altogether.
   gimmecert server --update-dns-names myserver
 Rerunning the command will not overwrite existing data.
 The ``--update-dns-command`` will keep the private key intact - only
 the certificate will be renewed. If you haven't issued any certificate
 for this server entity before, though, the option is ignored, and the
 command behaves as if it was not specified (so you still get a private
 key and certificate).
 .. note::
    For changing the list of additional subject alternative names
    included in already issued server certificates, see the
    ``--update-dns-names`` option in the ``gimmecert renew`` command.
 In addition to generating a private key, it is also possible to
 pass-in a certificate signing request (CSR). If specified path is a
 dash (``-``), CSR is read from standard input. The resulting
 certificate will contain public key from the CSR. All other
 information stored in the CSR (naming, extensions) is ignored. For
 example::
   # Issue server certificate by passing-in path to a generated CSR.
   gimmecert server --csr /tmp/myown.csr.pem myserver
   # Issue server certificate by reading the CSR from standard input.
 requires two positional argumensts::
   gimmecert renew (server|client) NAME
 The command will:
 - By default keep the existing private key generated for end entity
   (new one can be requested as well).
 - Re-use naming and any extensions stored in existing certificate.
 - Overwrite the existing certificate with a new one.
 - Show information where the artifacts can be grabbed from.
 .. note::
    For changing the list of additional subject alternative names
    included in server certificates, see the ``--update-dns-names`` for
    the ``gimmecert server`` command.
 To also generate a new private key during renewal, use the
 ``--new-private-key`` or ``-p`` option. For example::
   gimmecert renew --new-private-key server myserver
   gimmecert renew -p server my server
 To replace the existing private key or CSR during renewal with a new
 CSR, use the ``--csr`` option and pass along path to the file. If
 specified path is a dash (``-``), CSR is read from standard input. For
 example::
   gimmecert renew --csr /tmp/myserver.csr.pem server myserver
   gimmecert renew --csr - server myserver < /tmp/myserver.csr.pem
   gimmecert renew --csr - client myclient
 If you initially made a mistake when providing additional DNS subject
 alternative names for a server certificate, you can easily fix this
 with the ``--update-dns-names`` or ``-u`` option::
   # Replace existing additional names with just one name.
   gimmecert renew server --update-dns-names "correctname.example.com" myserver
   # Replace existing additional names with mutliple names.
   gimmecert renew server --update-dns-names "correctname1.example.com,correctname2.example.com" myserver
   # Remove additional names altogether.
   gimmecert renew server --update-dns-names "" myserver
 Getting information about CA hierarchy and issued certificates
 --------------------------------------------------------------
 In order to show information about the CA hierarchy and issued
 certificates simply run the status command::
   gimmecert status
 The command will:
 - Show information about every CA in generated hierarchy (subject DN,

gimmecert/cli.py

➞

Show inline comments

@@ @@ -48,34 +48,34 @@ Examples: @@
     # Issue a TLS server certificate with additional DNS subject alternative names.
     gimmecert server myserver extradns1.local extradns2.example.com
     # Issue a TLS server certificate by using public key from the CSR (naming/extensions are ignored).
     gimmecert server myserver --csr /tmp/myserver.csr.pem
     # Issue a TLS client certificate.
     gimmecert client myclient
     # Issue a TLS client certificate by using public key from the CSR (naming/extensions are ignored).
     gimmecert client myclient --csr /tmp/myclient.csr.pem
     # Renew a TLS server certificate with updated DNS subject alternative names. Keeps the private key if any.
     # Renew a TLS server certificate, preserving naming and private key.
     gimmecert renew server myserver
     # Renew a TLS server certificate, replacing the extra DNS names, but keeping the private key.
     gimmecert server myserver wrongdns.local
-    gimmecert server --update-dns-names myserver correctdns1.local correctdns2.local
+    gimmecert renew server myserver --update-dns-names "correctdns1.local,correctdns2.local"
-    # Renew a TLS server certificate removing extra DNS subject alternative names. Keeps the private key if any.
+    # Renew a TLS server certificate, removing extra DNS subject alternative names, but keeping the private key.
     gimmecert server myserver dontneedthisname.local
     gimmecert server myserver --update-dns-names
     # Renew a TLS server certificate, preserving naming and private key.
     gimmecert renew server myserver
     gimmecert renew server myserver --update-dns-names ""
     # Renew a TLS client certificate, preserving naming and private key.
     gimmecert renew client myclient
     # Show information about CA hierarchy and issued certificates.
     gimmecert status
 """
 @subcommand_parser
 def setup_init_subcommand_parser(parser, subparsers):
     subparser = subparsers.add_parser('init', description='Initialise CA hierarchy.')

0 comments (0 inline, 0 general)