Changeset - 7c58f3f776f6
Parent rev.
Child rev.
[Not reviewed]
0 2 0
Branko Majic (branko) - 6 years ago 2018-04-28 00:23:09
branko@majic.rs
GC-22: Updated CLI and regular documentation for the new CSR options:

- Updated quick usage instructions to give an example of issuing a
server certificate using CSR.
- Updated documentation for server, client, and renew commands.
- Updated CLI examples to include some usage of the --csr option.
- Updated CLI CSR documentation to emphasize that only the public key
is taken from the CSR.
2 files changed with 71 insertions and 5 deletions:
docs/usage.rst
62
2
gimmecert/cli.py
9
3
0 comments (0 inline, 0 general)
docs/usage.rst
➞
Show inline comments
 
@@ -92,6 +92,17 @@ This time around, the ``myserver2`` certificate will include
 
``myserver2``, ``myserver2.local``, and ``service.example.com`` as DNS
 
subject alternative names.
 

			




	
	
	
		
 
Issue a server certificate by passing-in certificate signing request

			




	
	
	
		
 
(CSR) from which the public key should be extracted::

			




	
	
	
		
 

			




	
	
	
		
 
  openssl req -new -newkey rsa:2048 -nodes -keyout "/tmp/myserver3.key.pem" -subj "/CN=ignoredname" -out "/tmp/myserver3.csr.pem"

			




	
	
	
		
 
  gimmecert server --csr /tmp/myserver3.csr.pem myserver3

			




	
	
	
		
 

			




	
	
	
		
 
This will create the following artifacts for the server:

			




	
	
	
		
 

			




	
	
	
		
 
- ``.gimmecert/server/myserver3.csr.pem`` (CSR)

			




	
	
	
		
 
- ``.gimmecert/server/myserver3.cert.pem`` (certificate)

			




	
	
	
		
 

			




	
	
	
		
 
Renew existing certificates, keeping the same private key and naming::

			




	
	
	
		
 

			




	
	
	
		
 
  gimmecert renew server myserver1

			




	
	
		
 
@@ -219,6 +230,26 @@ 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).

			




	
	
	
		
 

			




	
	
	
		
 
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.

			




	
	
	
		
 
  gimmecert server --csr - myserver

			




	
	
	
		
 

			




	
	
	
		
 
  # Issue server certificate by reading the CSR from standard input,

			




	
	
	
		
 
  # using redirection.

			




	
	
	
		
 
  gimmecert server --csr - myserver < /tmp/myown.csr.pem

			




	
	
	
		
 

			




	
	
	
		
 
The passed-in CSR will be stored alongside certificate, under

			




	
	
	
		
 
``.gimmecert/server/NAME.csr.pem``.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Issuing client certificates

			




	
	
	
		
 
---------------------------

			




	
	
		
 
@@ -249,6 +280,26 @@ Key usage and extended key usage in certificate are set typical TLS

			




	
	
	
		
 
client use (e.g. *digital signature* + *key encipherment* for KU, and

			




	
	
	
		
 
*TLS WWW client authentication* for EKU).

			




	
	
	
		
 

			




	
	
	
		
 
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 client certificate by passing-in path to a generated CSR.

			




	
	
	
		
 
  gimmecert client --csr /tmp/myown.csr.pem myclient

			




	
	
	
		
 

			




	
	
	
		
 
  # Issue client certificate by reading the CSR from standard input.

			




	
	
	
		
 
  gimmecert client --csr - myclient

			




	
	
	
		
 

			




	
	
	
		
 
  # Issue client certificate by reading the CSR from standard input,

			




	
	
	
		
 
  # using redirection.

			




	
	
	
		
 
  gimmecert client --csr - myclient < /tmp/myown.csr.pem

			




	
	
	
		
 

			




	
	
	
		
 
The passed-in CSR will be stored alongside certificate, under

			




	
	
	
		
 
``.gimmecert/client/NAME.csr.pem``.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Renewing certificates

			




	
	
	
		
 
---------------------

			




	
	
		
 
@@ -279,6 +330,15 @@ To also generate a new private key during renewal, use the

			




	
	
	
		
 
  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

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Getting information about CA hierarchy and issued certificates

			




	
	
	
		
 
--------------------------------------------------------------

			




	
	
		
 
@@ -294,10 +354,10 @@ The command will:

			




	
	
	
		
 
  validity, certificate paths, whether the CA is used for issuing end

			




	
	
	
		
 
  entity certificates).

			




	
	
	
		
 
- Show information about all issued server certificates (subject DN,

			




	
	
	
		
 
  DNS subject alternative names, validity, private key path,

			




	
	
	
		
 
  DNS subject alternative names, validity, private key or CSR path,

			




	
	
	
		
 
  certificate path).

			




	
	
	
		
 
- Show information about all issued client certificates (subject DN,

			




	
	
	
		
 
  validity, private key path, certificate path).

			




	
	
	
		
 
  validity, private key or CSR path, certificate path).

			




	
	
	
		
 

			




	
	
	
		
 
Validity of all certificates is shown in UTC.

			




	
	
	
		
 

			




        

    


    
    

    

        

                

                    gimmecert/cli.py
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -48,9 +48,15 @@ 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.

			




	
	
	
		
 
    gimmecert server myserver wrongdns.local

			




	
	
	
		
 
    gimmecert server --update-dns-names myserver correctdns1.local correctdns2.local

			




	
	
		
 
@@ -109,7 +115,7 @@ def setup_server_subcommand_parser(parser, subparsers):

			




	
	
	
		
 
    the private key, but replacing the DNS subject alternative names with listed values (if any). \

			




	
	
	
		
 
    If entity does not exist, this option has no effect, and a new private key/certificate will be generated as usual.''')

			




	
	
	
		
 
    subparser.add_argument('--csr', '-c', type=str, default=None, help='''Do not generate server private key locally, and use the passed-in \

			




	
	
	
		
 
    certificate signing request (CSR) instead. Use dash (-) to read from standard input.''')

			




	
	
	
		
 
    certificate signing request (CSR) instead. Use dash (-) to read from standard input. Only the public key is taken from the CSR.''')

			




	
	
	
		
 

			




	
	
	
		
 
    def server_wrapper(args):

			




	
	
	
		
 
        project_directory = os.getcwd()

			




	
	
		
 
@@ -126,7 +132,7 @@ def setup_client_subcommand_parser(parser, subparsers):

			




	
	
	
		
 
    subparser = subparsers.add_parser('client', description='Issue client certificate.')

			




	
	
	
		
 
    subparser.add_argument('entity_name', help='Name of the client entity.')

			




	
	
	
		
 
    subparser.add_argument('--csr', '-c', type=str, default=None, help='''Do not generate client private key locally, and use the passed-in \

			




	
	
	
		
 
    certificate signing request (CSR) instead. Use dash (-) to read from standard input.''')

			




	
	
	
		
 
    certificate signing request (CSR) instead. Use dash (-) to read from standard input. Only the public key is taken from the CSR.''')

			




	
	
	
		
 

			




	
	
	
		
 
    def client_wrapper(args):

			




	
	
	
		
 
        project_directory = os.getcwd()

			




	
	
		
 
@@ -150,7 +156,7 @@ def setup_renew_subcommand_parser(parser, subparsers):

			




	
	
	
		
 
    Default is to keep the existing key. Mutually exclusive with the --csr option.''')

			




	
	
	
		
 
    new_private_key_or_csr_group.add_argument('--csr', '-c', type=str, default=None, help='''Do not use local private key and public key information from \

			




	
	
	
		
 
    existing certificate, and use the passed-in certificate signing request (CSR) instead. Use dash (-) to read from standard input. \

			




	
	
	
		
 
    If private key exists, it will be removed. Mutually exclusive with the --new-private-key option.''')

			




	
	
	
		
 
    If private key exists, it will be removed. Mutually exclusive with the --new-private-key option. Only the public key is taken from the CSR.''')

			




	
	
	
		
 

			




	
	
	
		
 
    def renew_wrapper(args):

			




	
	
	
		
 
        project_directory = os.getcwd()

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








    
        
    
    
        This site is powered by
            Kallithea 0.7.0,
        which is
        © 2010–2023 by various authors & licensed under GPLv3.