kellya/checkcert
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

docs: update docs to reflect all current options

Browse source
This commit is contained in:
Alex Kelly 2021-10-04 14:00:55 -04:00
parent d3ce964ded
commit ddf0614712
7 changed files with 216 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
Makefile
View file

@ -18,6 +18,7 @@ dir:
clean:
rm -rf $(BUILDDIR)
find . -name __pycache__|xargs rm -rf
rm -rf docs/build
docs:
cd docs && make html

BIN
docs/source/images/basic.png Normal file
View file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
docs/source/images/multi.png Normal file
View file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

BIN
docs/source/images/san.png Normal file
View file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
docs/source/images/valid.png Normal file
View file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

10
docs/source/index.rst
View file

@ -12,12 +12,4 @@ Welcome to checkcert's documentation!
introduction
install
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
running

214
docs/source/running.rst Normal file
View file

@ -0,0 +1,214 @@
Running checkcert
=================
This section assumes that checkcert is installed via pypi, and the ``certcheck`` entry-point in the path (which ``pip install checkcert`` should do automatically). If running from source, the full path to python and the checkcert.py script itself would need to be specified.
Basic query
-----------
To do a simple validation, run something like ``checkcert www.example.com``. You should get output like:
.. figure:: images/basic.png
:alt: basic output example
Basic command output
The green text is showing that the certificate is valid. If the certificate had expired, the text would be displayed in Red. The ``--valid`` option may be specified to display a text represention of the cert validity in addtion to just coloring the output to show validity. When run with ``--valid``, the output will look like:
.. figure:: images/valid.png
:alt: output with valid option
Display cert validity in output text
.. note:: Output color is generated via Click's styling which should be aware of how the text is being handled and appropriately strip out the color sequences if output is being piped to another command, for example. The plain text output may be enforced with the ``--no-color`` option
Querying multiple domains
-------------------------
Multiple domains can be checked from a single command. Simply separate them on the command line with a space. So to check `www.example.com` and `www.example.org`, this can be run as:
``checkcert www.example.com www.example.org``
Which will generate:
.. figure:: images/multi.png
:alt: multi-domain output
Mutliple domains specified
Specify alternate ports
-----------------------
By default, the standard port `443` will be used. If a service is running on an alternate port, simply append `:portnum` to the domain. So if example.com was listening on 444 instead of 443, anywhere the domain is specified, the format ``example.com:444`` may be used instead.
Domains from a file
-------------------
While specifying a few domains on the commanline is fine, if there are many domains to check, an input file may be specified instead. Each domain should be on its own line. Alternate ports may be specified in this file too. For example, if a file named `domains.txt` is created with the following content:
.. code-block:: text
www.example.com
example.org
example.com:444
Then checkcert may be run as follows:
``checkcert --filename domains.txt``
Each line in the file will be parsed and checked the same as if it were run on the command line.
SubjectAlternateName handling
-----------------------------
checkcert has a `--san` option that will optionally show the subjectAlternateNames for a domain. This will output the same as previous iterations, but will add a list of SANs associated with the certificate retrieved.
.. figure:: images/san.png
:alt: subjectalternatename example
output with the SAN line
Just the SANs
^^^^^^^^^^^^^
It may be useful to output just the SANs for a given domain. This may be done by specifying the ``--san-only`` option. By default this will output all of SANs, separated by a space.
Running ``checkcert --san-only www.example.com`` will yield::
www.example.org example.com example.edu example.net example.org www.example.com www.example.edu www.example.net
If an alternate separator is desired, add the ``--sep <separator>`` option, so for comma separated, run ``checkcert --san-only --sep , www.example.com`` which will yield::
www.example.org,example.com,example.edu,example.net,example.org,www.example.com,www.example.edu,www.example.net
If it is desired to output that list to another command as commandline options (for example when migrating from a managed PKI front-end to using ACME/certbot). Certbot wants the domains specified as -d. checkcert may run as: ``checkcert --san-only --sep " -d "- www.example.com`` which will return::
www.example.org -d example.com -d example.edu -d example.net -d example.org -d www.example.com -d www.example.edu -d www.example.net
.. note:: the documentation for certbot specifies multiple domains should be specified each with their own '-d' option. certbot in particular seems to work with a comma-separated list too, even though the docs don't specify that it works that way.
Notice that the " -d " is used as a **separator** and therefore the first entry does not have a -d before it. To make -d show up before every entry (as would be required in this case) you must also add --pre to "prefix" the entry with the separator; thus, running ``checkcert --san-only --sep " -d " --pre www.example.com`` will yield::
-d www.example.org -d example.com -d example.edu -d example.net -d example.org -d www.example.com -d www.example.edu -d www.example.net
.. note:: Since this is utilizing separator in a slightly different way, the space before the option must be specified, otherwise everything would run together. checkcert is aware of this and will strip off the space at the beginning if ``--pre`` is used.
This output could be directly included into certbot as ``certbot $(checkcert --san-only --sep " -d " --pre www.example.com")``
.. note:: Certbot was the specific reason this was added. As such, it will prepend the name queried to the list. The domain itself is not always included in the SAN list, checkcert will verify if the domain is in the list and will always prefix it if not. If example.com was not in the list of SANS, but ``checkcert --san --pre --sep " -d " example.com`` was used, '-d example.com' will be the first entry even if it was not part of the SANs.
Dumping the text version of a cert
----------------------------------
``--dump`` will give you the textual version of the certificate presented. Running ``checkcert --dump www.example.com`` will return::
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
0f:be:08:b0:85:4d:05:73:8a:b0:cc:e1:c9:af:ee:c9
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=US, O=DigiCert Inc, CN=DigiCert TLS RSA SHA256 2020 CA1
Validity
Not Before: Nov 24 00:00:00 2020 GMT
Not After : Dec 25 23:59:59 2021 GMT
Subject: C=US, ST=California, L=Los Angeles, O=Internet Corporation for Assigned Names and Numbers, CN=www.example.org
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
00:ba:fc:ee:cc:ca:0a:08:ff:0e:93:1d:b3:be:0b:
9c:03:96:22:9e:b1:4f:10:ae:51:40:fd:53:5f:b3:
c4:61:40:28:04:ee:a2:e6:12:00:b0:82:85:98:5c:
6d:5b:6b:20:84:44:62:95:4e:6b:76:7c:50:70:5d:
df:13:1d:ec:63:83:ad:63:a5:52:04:f2:cf:84:ba:
db:2a:8c:c7:2e:b4:3c:64:df:eb:61:36:fe:86:03:
54:79:3e:cd:03:59:8f:ef:c2:04:93:10:23:e2:a1:
b9:b6:58:b8:26:ae:35:68:26:d4:94:2b:7b:7a:ab:
86:5e:89:08:9a:10:be:51:8e:48:a5:01:19:4b:4b:
4a:0f:8b:ee:da:4b:19:d3:84:1e:b6:9d:24:f2:35:
9d:02:f3:00:db:b5:b7:13:08:07:1c:d7:95:19:66:
c9:3c:2d:03:9f:b4:6a:3f:0d:77:af:b8:45:c9:2e:
53:a6:57:b2:c2:37:58:d6:70:7b:69:de:a4:71:95:
d9:6c:47:1a:15:9e:d9:b9:ea:c0:e9:19:0f:18:4f:
8f:b2:76:51:6f:5a:05:26:46:28:5e:29:ac:ba:f9:
15:16:15:9e:1d:05:c2:18:2d:5c:b8:35:92:ac:cd:
dc:a5:0b:ce:cc:a1:f6:bd:2e:dd:d7:9f:b3:1a:5b:
38:23
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Authority Key Identifier:
keyid:B7:6B:A2:EA:A8:AA:84:8C:79:EA:B4:DA:0F:98:B2:C5:95:76:B9:F4
X509v3 Subject Key Identifier:
26:1A:F8:E4:B1:B0:72:84:CE:DA:81:06:D2:27:98:FB:ED:3A:3D:17
X509v3 Subject Alternative Name:
DNS:www.example.org, DNS:example.com, DNS:example.edu, DNS:example.net, DNS:example.org, DNS:www.example.com, DNS:www.example.edu, DNS:www.example.net
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication
X509v3 CRL Distribution Points:
Full Name:
URI:http://crl3.digicert.com/DigiCertTLSRSASHA2562020CA1.crl
Full Name:
URI:http://crl4.digicert.com/DigiCertTLSRSASHA2562020CA1.crl
X509v3 Certificate Policies:
Policy: 2.16.840.1.114412.1.1
CPS: https://www.digicert.com/CPS
Policy: 2.23.140.1.2.2
Authority Information Access:
OCSP - URI:http://ocsp.digicert.com
CA Issuers - URI:http://cacerts.digicert.com/DigiCertTLSRSASHA2562020CA1.crt
X509v3 Basic Constraints: critical
CA:FALSE
CT Precertificate SCTs:
Signed Certificate Timestamp:
Version : v1 (0x0)
Log ID : F6:5C:94:2F:D1:77:30:22:14:54:18:08:30:94:56:8E:
E3:4D:13:19:33:BF:DF:0C:2F:20:0B:CC:4E:F1:64:E3
Timestamp : Nov 24 19:32:04.334 2020 GMT
Extensions: none
Signature : ecdsa-with-SHA256
30:46:02:21:00:A4:6B:A8:D0:43:A4:F1:07:32:2D:ED:
9C:39:7D:77:E8:73:C1:9F:ED:22:4A:00:C5:BE:9A:C9:
B5:B6:12:DC:B1:02:21:00:8D:E8:5F:8A:C7:52:CD:0D:
A1:23:D5:B5:BB:DB:DB:62:13:88:22:D6:70:EC:83:5E:
3F:C9:AC:94:4C:8C:58:3A
Signed Certificate Timestamp:
Version : v1 (0x0)
Log ID : 5C:DC:43:92:FE:E6:AB:45:44:B1:5E:9A:D4:56:E6:10:
37:FB:D5:FA:47:DC:A1:73:94:B2:5E:E6:F6:C7:0E:CA
Timestamp : Nov 24 19:32:04.429 2020 GMT
Extensions: none
Signature : ecdsa-with-SHA256
30:45:02:20:6A:AC:11:FA:05:09:12:FF:9B:8E:89:30:
DF:0E:05:6E:CA:8E:59:CC:ED:B5:C2:0A:3C:33:34:A8:
B0:33:DA:AC:02:21:00:DA:D8:5C:51:6D:64:0A:A6:AA:
3D:8B:35:20:13:3A:6A:97:4F:76:B9:67:CB:BE:FC:CC:
A4:57:67:B4:3F:1B:BD
Signature Algorithm: sha256WithRSAEncryption
a7:2a:10:30:5c:b8:6b:7a:1b:f8:66:38:f6:e9:a0:0a:d5:13:
82:82:f8:65:89:57:a5:b8:eb:13:29:1d:84:6c:ec:fb:e3:05:
11:d7:1e:31:5e:0e:e2:c0:00:e5:6d:06:48:be:3d:55:6f:ba:
b7:11:35:b6:ea:c4:cf:84:f1:30:4c:bb:33:9e:11:17:2b:c9:
d2:19:4b:2c:d0:ad:5f:17:23:84:e1:df:17:a2:3b:a8:7f:69:
29:7c:48:a6:61:5f:26:3f:75:e2:3b:5b:a3:36:b3:1c:cd:e3:
04:57:30:1f:fc:c9:fa:4b:8e:48:80:58:27:9c:a2:c7:c3:26:
dc:17:02:fa:e6:6c:ea:81:01:5c:92:8f:d3:18:08:17:70:7a:
c2:a3:4b:6c:3a:fa:e3:cf:f6:fe:7e:c9:56:e5:a5:4e:1b:14:
4f:a9:98:9d:79:b1:1e:c3:ab:b1:0d:15:85:a9:46:b6:e5:c2:
58:e8:5a:fe:c8:14:28:68:90:c6:b8:c8:94:7f:e1:0f:89:fa:
a7:d6:09:37:a1:62:b7:00:27:b5:be:f1:b1:5e:45:28:06:b3:
54:15:e6:c3:c8:ac:82:01:ce:86:e2:2b:e1:7a:e4:bd:4c:cb:
9c:5e:d0:62:c2:61:bd:8b:5a:62:b6:76:30:bc:46:0f:e3:45:
23:c0:64:5f