Skip to content

Commit 6802c80

Browse files
tlhackquetlhackque
committed
Update documentation for release
1 parent 8096dab commit 6802c80

6 files changed

Lines changed: 707 additions & 4 deletions

File tree

‎.gitattributes‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,7 @@
55
README.md.in export-ignore
66
makereadme export-ignore
77
Makefile export-ignore
8+
9+
# Used only for GitHub
10+
ssl_check_chain.md export-ignore
11+
ssl_status.md export-ignore

‎Makefile‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1-
# Updates README and creates MD from Perl code's POD
1+
# Updates README and creates MD and man (.1) from Perl code's POD
22
# Version $Id$
33

4-
all: ssl_status.md ssl_check_chain.md README.md
4+
all: ssl_status.md ssl_check_chain.md ssl_status.1 ssl_check_chain.1 README.md
55

66
README.md : README.md.in getcert ssl_info makereadme
77
./makereadme getcert ssl_info <README.md.in >$@
88

99
%.md : %
1010
cat $^ | pod2markdown - $@
1111

12+
%.1 : %
13+
pod2man --section 1 --center "Certificate Tools" --release "" --date "$(shell date -r $< +'%d-%b-%Y %T')" $< $@

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
This repository contains a number of tools that make managing X.509
44
certificates easier. Note that the description in this README may
55
not reflect the latest version. Use the -h option for current
6-
information.
6+
information. Full documentation for `ssl_check_chain` and `ssl_status`
7+
is available by using th `--man` option. The corresponding `.md` files
8+
[ssl_check_chain.md](https://github.com/tlhackque/certtools/blob/master/ssl_check_chain.md) and [ssl_status.md](https://github.com/tlhackque/certtools/blob/master/ssl_status.md) in the repository have identical content, and can be consulted without installing the tools.
79

810
Recent updates:
911
- Added ssl_status reporting tool
@@ -13,6 +15,14 @@ Recent updates:
1315
- Non-Unix OS optimizations
1416
- Miscellaneous improvements
1517

18+
## Installation
19+
20+
- Download the `.tar.gz` file from [GitHub](https://github.com/tlhackque/certtools/releases).
21+
- Unpack the archive, and move the script(s) to a directory on your path
22+
- If desired, move the `.1` files to someplace in `MANPATH` (or man's config). The `--man` option's output is identical.
23+
- `ssl_status_prereqs` may be used to verify that you have the Perl modules used by `ssl_status`
24+
- It is **not** necessary to clone the repository unless you wish to contribute patches. The repository contains some files used to build the distribution, which are not required to install or use the tools.
25+
1626
## getcert
1727
Get server's TLS certificate
1828

‎README.md.in‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
This repository contains a number of tools that make managing X.509
44
certificates easier. Note that the description in this README may
55
not reflect the latest version. Use the -h option for current
6-
information.
6+
information. Full documentation for `ssl_check_chain` and `ssl_status`
7+
is available by using th `--man` option. The corresponding `.md` files
8+
[ssl_check_chain.md](https://github.com/tlhackque/certtools/blob/master/ssl_check_chain.md) and [ssl_status.md](https://github.com/tlhackque/certtools/blob/master/ssl_status.md) in the repository have identical content, and can be consulted without installing the tools.
79

810
Recent updates:
911
- Added ssl_status reporting tool
@@ -13,6 +15,14 @@ Recent updates:
1315
- Non-Unix OS optimizations
1416
- Miscellaneous improvements
1517

18+
## Installation
19+
20+
- Download the `.tar.gz` file from [GitHub](https://github.com/tlhackque/certtools/releases).
21+
- Unpack the archive, and move the script(s) to a directory on your path
22+
- If desired, move the `.1` files to someplace in `MANPATH` (or man's config). The `--man` option's output is identical.
23+
- `ssl_status_prereqs` may be used to verify that you have the Perl modules used by `ssl_status`
24+
- It is **not** necessary to clone the repository unless you wish to contribute patches. The repository contains some files used to build the distribution, which are not required to install or use the tools.
25+
1626
## getcert
1727
Get server's TLS certificate
1828

‎ssl_check_chain.1‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
2+
.\"
3+
.\" Standard preamble:
4+
.\" ========================================================================
5+
.de Sp \" Vertical space (when we can't use .PP)
6+
.if t .sp .5v
7+
.if n .sp
8+
..
9+
.de Vb \" Begin verbatim text
10+
.ft CW
11+
.nf
12+
.ne \\$1
13+
..
14+
.de Ve \" End verbatim text
15+
.ft R
16+
.fi
17+
..
18+
.\" Set up some character translations and predefined strings. \*(-- will
19+
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20+
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21+
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22+
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23+
.\" nothing in troff, for use with C<>.
24+
.tr \(*W-
25+
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26+
.ie n \{\
27+
. ds -- \(*W-
28+
. ds PI pi
29+
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30+
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31+
. ds L" ""
32+
. ds R" ""
33+
. ds C` ""
34+
. ds C' ""
35+
'br\}
36+
.el\{\
37+
. ds -- \|\(em\|
38+
. ds PI \(*p
39+
. ds L" ``
40+
. ds R" ''
41+
. ds C`
42+
. ds C'
43+
'br\}
44+
.\"
45+
.\" Escape single quotes in literal strings from groff's Unicode transform.
46+
.ie \n(.g .ds Aq \(aq
47+
.el .ds Aq '
48+
.\"
49+
.\" If the F register is >0, we'll generate index entries on stderr for
50+
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51+
.\" entries marked with X<> in POD. Of course, you'll have to process the
52+
.\" output yourself in some meaningful fashion.
53+
.\"
54+
.\" Avoid warning from groff about undefined register 'F'.
55+
.de IX
56+
..
57+
.if !\nF .nr F 0
58+
.if \nF>0 \{\
59+
. de IX
60+
. tm Index:\\$1\t\\n%\t"\\$2"
61+
..
62+
. if !\nF==2 \{\
63+
. nr % 0
64+
. nr F 2
65+
. \}
66+
.\}
67+
.\"
68+
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69+
.\" Fear. Run. Save yourself. No user-serviceable parts.
70+
. \" fudge factors for nroff and troff
71+
.if n \{\
72+
. ds #H 0
73+
. ds #V .8m
74+
. ds #F .3m
75+
. ds #[ \f1
76+
. ds #] \fP
77+
.\}
78+
.if t \{\
79+
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80+
. ds #V .6m
81+
. ds #F 0
82+
. ds #[ \&
83+
. ds #] \&
84+
.\}
85+
. \" simple accents for nroff and troff
86+
.if n \{\
87+
. ds ' \&
88+
. ds ` \&
89+
. ds ^ \&
90+
. ds , \&
91+
. ds ~ ~
92+
. ds /
93+
.\}
94+
.if t \{\
95+
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96+
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97+
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98+
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99+
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100+
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101+
.\}
102+
. \" troff and (daisy-wheel) nroff accents
103+
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104+
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105+
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106+
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107+
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108+
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109+
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110+
.ds ae a\h'-(\w'a'u*4/10)'e
111+
.ds Ae A\h'-(\w'A'u*4/10)'E
112+
. \" corrections for vroff
113+
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114+
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115+
. \" for low resolution devices (crt and lpr)
116+
.if \n(.H>23 .if \n(.V>19 \
117+
\{\
118+
. ds : e
119+
. ds 8 ss
120+
. ds o a
121+
. ds d- d\h'-1'\(ga
122+
. ds D- D\h'-1'\(hy
123+
. ds th \o'bp'
124+
. ds Th \o'LP'
125+
. ds ae ae
126+
. ds Ae AE
127+
.\}
128+
.rm #[ #] #H #V #F C
129+
.\" ========================================================================
130+
.\"
131+
.IX Title "SSL_CHECK_CHAIN 1"
132+
.TH SSL_CHECK_CHAIN 1 "14-Nov-2021 08:48:02" "" "Certificate Tools"
133+
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
134+
.\" way too many mistakes in technical documents.
135+
.if n .ad l
136+
.nh
137+
.SH "SSL_CHECK_CHAIN"
138+
.IX Header "SSL_CHECK_CHAIN"
139+
ssl_check_chain \- check the certificate chain for hosts
140+
.SH "SYNOPSIS"
141+
.IX Header "SYNOPSIS"
142+
ssl_check_chain [options] [host[:port] ...] [file:FILE] [@file...]
143+
.PP
144+
.Vb 10
145+
\& Options:
146+
\& \-\-CAfile=file Specify bundle file of trusted CA certificates for verification
147+
\& \-\-CApath=dir Specify a hashed directory containing trusted CA certificates for verification.
148+
\& \-\-starttls=proto Specify that STARTTLS should be used in the connection.
149+
\& \-\-timeout=secs Specify timeout for TLS connections
150+
\& \-\-tlsversion=ver Specify the version TLS to connect with
151+
\& \-\-type=type Specify the certificate type desired from the server
152+
\& \-\-[no\-]warnings Display or suppress warnings
153+
\& \-\-help brief help message
154+
\& \-\-man full documentation
155+
.Ve
156+
.SH "OPTIONS"
157+
.IX Header "OPTIONS"
158+
.IP "\fB\-\-CAfile\fR=\fIfile\fR" 8
159+
.IX Item "--CAfile=file"
160+
Specify a file containing one or more trusted \s-1CA\s0 certificates to verify the host's certificate chain.
161+
.Sp
162+
If not specified, the environment variables \s-1SSL_CERT_FILE\s0 and \s-1CURL_CA_BUNDLE\s0 will be tried, and if neither of them is set, OpenSSL's default will be used.
163+
.IP "\fB\-\-CApath\fR=\fIfile\fR \fB\-\-CAdir\fR=\fIfile\fR" 8
164+
.IX Item "--CApath=file --CAdir=file"
165+
Specify a directory containing hashed links to one or more trusted \s-1CA\s0 certificates to verify the host's certificate chain.
166+
.Sp
167+
If not specified, the environment variable \s-1SSL_CERT_DIR\s0 will be tried. If it is not set, OpenSSL's default will be used.
168+
.IP "\fB\-\-starttls\fR=\fIprotocol\fR" 8
169+
.IX Item "--starttls=protocol"
170+
Specifies that \s-1STARTTLS\s0 is required to make the \s-1TLS\s0 connection.
171+
.Sp
172+
\&\fIprotocol\fR is one of the following: \*(L"smtp\*(R", \*(L"pop3\*(R", \*(L"imap\*(R", \*(L"ftp\*(R", \*(L"xmpp\*(R",
173+
\*(L"xmpp-server\*(R", \*(L"irc\*(R", \*(L"postgres\*(R", \*(L"mysql\*(R", \*(L"lmtp\*(R", \*(L"nntp\*(R", \*(L"sieve\*(R", or \*(L"ldap\*(R"
174+
.IP "\fB\-\-timeout\fR=\fIsecs\fR \fI\f(CI@file\fI\fR" 8
175+
.IX Item "--timeout=secs @file"
176+
Speciries the maximum amount of time that \fIssl_check_chain\fR will wait for a \s-1TLS\s0 connection.
177+
.Sp
178+
The default is 120 seconds.
179+
.IP "\fB\-\-tlsversion\fR=\fIversion\fR" 8
180+
.IX Item "--tlsversion=version"
181+
Specify the \s-1TLS\s0 protocol version to use: 1.1, 1.2, or 1.3.
182+
.IP "\fB\-\-type\fR=\fItype\fR" 8
183+
.IX Item "--type=type"
184+
Specify that an \fIec\fR (\fIecdsa\fR) or \fIrsa\fR certificate is desired.
185+
.IP "\fB\-\-[no\-]warnings\fR" 8
186+
.IX Item "--[no-]warnings"
187+
Controls whether warning messages are displayed. The default is \fB\-\-warnings\fR.
188+
.Sp
189+
Warnings include duplicated files and hosts, which are skipped, and other recoverable conditions.
190+
.IP "\fB\-\-help\fR" 8
191+
.IX Item "--help"
192+
Print a brief help message and exits.
193+
.IP "\fB\-\-man\fR" 8
194+
.IX Item "--man"
195+
Prints the manual page and exits.
196+
.PP
197+
When options require keyword values, the keyword may be abbreviated providing that the abbreviation is unique.
198+
.SH "DESCRIPTION"
199+
.IX Header "DESCRIPTION"
200+
\&\fBssl_check_chain\fR will connect to each host specified and obtain its certificate and any intermediate certificate chain.
201+
.PP
202+
Port can be numeric, or a service name (e.g. from /etc/services).
203+
.PP
204+
If a port is not specified: if \-\-starttls is specified, the default port for the \s-1STARTTLS\s0 protocol is used, otherwise 443 (https) is assumed.
205+
.PP
206+
If the port is specified as \fI\s-1FILE\s0\fR, \fBssl_check_chain\fR will open the specified file and process it as if the certificates were received from a server.
207+
The certificate chain must be in \s-1PEM\s0 format. If a filename begins with '.', '/', or '~', or if it contains a '/', the \fI:FILE\fR is inferred, since
208+
no \s-1DNS\s0 hostname or \s-1IP\s0 address can have those forms.
209+
.PP
210+
If an argument is of the form \fI\f(CI@file\fI\fR, the file is processed as a list of arguments, one per line, in any of the forms described previously.
211+
\&\fI\f(CI@file\fI\fRs can be nested, but attempting to process the same file more than once is an error. In an \fI\f(CI@file\fI\fR, blank lines and lines beginning with \fI#\fR are ignored.
212+
.PP
213+
\&\fI\s-1FILE\s0\fR and \fI\f(CI@file\fI\fR names support tilde expansion, but not wildcards.
214+
.PP
215+
The validity dates of each certificate returned will be verified, as will its chain.
216+
.PP
217+
To request the desired certificate from dual-certificate servers, you can specify \fB\-\-type\fR=\fIec\fR or \fB\-\-type\fR=\fIrsa\fR.
218+
This is done by providing a list of acceptable signature algorithms; the connecion will fail if the server doesn't have a matching certificate.
219+
.PP
220+
You can also specify \fB\-\-tlsversion\fR=\fI1.1\fR, \fB\-\-tlsversion\fR=\fI1.2\fR, or \fB\-\-tlsversion\fR=\fI1.3\fR to select the protocol version.
221+
.PP
222+
Each certificate is analyzed in the order received from the server or contained in the file, which should be from leaf (the server) toward the root (trusted \s-1CA\s0).
223+
The trust root is not sent by the server, but is located by OpenSSL via \-CAfile or \-CApath.
224+
.PP
225+
Any date or verification errors will be reported.
226+
.PP
227+
Note that if a trusted (root) certificate has expired, only the root name is available.
228+
.PP
229+
This automates the manual process of determining where and why a certificate chain is broken.
230+
.SH "BUGS"
231+
.IX Header "BUGS"
232+
Report any bugs, feature requests and/or patches on the issue tracker,
233+
located at \fIhttps://github.com/tlhackque/certtools/issues\fR. In the
234+
event that the project moves, contact the author directly.
235+
.SH "AUTHOR"
236+
.IX Header "AUTHOR"
237+
Timothe Litt <litt@acm.org>
238+
.SH "COPYRIGHT and LICENSE"
239+
.IX Header "COPYRIGHT and LICENSE"
240+
Copyright (c) 2021 Timothe Litt
241+
.PP
242+
Permission is hereby granted, free of charge, to any person obtaining a
243+
copy of this software and associated documentation files (the \*(L"Software\*(R"),
244+
to deal in the Software without restriction, including without limitation
245+
the rights to use, copy, modify, merge, publish, distribute, sublicense,
246+
and/or sell copies of the Software, and to permit persons to whom the
247+
Software is furnished to do so, subject to the following conditions:
248+
.PP
249+
The above copyright notice and this permission notice shall be included
250+
in all copies or substantial portions of the Software.
251+
.PP
252+
\&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS
253+
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
254+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
255+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
256+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
257+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
258+
DEALINGS IN THE SOFTWARE.\s0
259+
.PP
260+
Except as contained in this notice, the name of the author shall not be
261+
used in advertising or otherwise to promote the sale, use or other dealings
262+
in this Software without prior written authorization from the author.
263+
.PP
264+
Any modifications to this software must be clearly documented by and
265+
attributed to their author, who is responsible for their effects.
266+
.PP
267+
Bug reports, suggestions and patches are welcomed by the original author.
268+
.SH "SEE ALSO"
269+
.IX Header "SEE ALSO"
270+
\&\fI\fIopenssl\fI\|(1)\fR
271+
.PP
272+
\&\fI\s-1POD\s0 version \f(CI$Id$\fR

0 commit comments

Comments
 (0)