1
Lynx SSL support for certificates - README.sslcerts file
5
The original README.ssl document for lynx stated:
7
Note that the server... may not have a valid certificate. Lynx will not
8
complain, as it does not yet support certificates...
10
Such lack of support is no longer the case. Lynx now features excellent
11
certificate management through the openssl project. There is almost no
12
online documentation available regarding how to use openssl's certificate
13
management with other programs, so this will accompany lynx and hopefully
14
encourage good practical security for unix clients.
16
Lynx relies on openssl to not only encrypt connections over https, but also to
17
determine whether it should even accept a certificate and establish a secure
18
connection with a remote host. Because of this reliance upon openssl by lynx,
19
most of this tutorial deals with how to use openssl to "install" both
20
commercial CA cert bundles as well as self-signed certs from trusted sources
21
and, most importantly, how to get them recognized by lynx.
23
While lynx on many systems will transparently accept valid certificates, not
24
all systems enjoy such functionality. Further, as noted above, older versions
25
of lynx do not perform any validity checks on a certificate.
27
There is also the common case of wanting to trust, use and install a
28
self-signed certificate from a known server source and have it be trusted by
31
Briefly, the procedure will involve confirming the default system location for
32
certificates, possibly setting values for SSL_CERT_DIR and SSL_CERT_FILE in
33
the environment, and converting and hashing the certificates using openssl
34
utilities to enable recognition.
36
THE CURRENT SITUATION:
38
Prior to lynx2.8.5dev9, lynx did not check at all for certificate validity.
40
Since lynx2.8.5.dev9, lynx has reported this openssl error:
42
SSL error:unable to get local issuer certificate-Continue? (y)
44
whenever an https connection was initiated and the certificate could not be
45
found, for whatever reason, by openssl, and therefore lynx.
47
This checking for a certificate is an enhancement to security, but rather
48
tediously generates errors at each https browser request.
50
The ability to turn off reporting of this error to the user was added to
51
lynx2.8.5dev16 as the FORCE_SSL_PROMPT setting in lynx.cfg as noted in the
54
This lets the user decide whether to ignore prompting for questionable
55
aspects of an SSL connection.
57
While this is a convenient setting to employ when using lynx to script
58
https -dumps, it by definition ignores the issue of certificate validity
59
altogether. Those concerned with proper certificate management and
60
the maintenance of a store of updated CA certificates will be uncomfortable
61
with this relaxed security setting.
63
PRELIMINARY PROCEDURES:
65
It is assumed that openssl has been installed correctly, that the default
66
cert directory is /usr/local/ssl/certs, (it's often /etc/ssl/certs, but we
67
need a point of departure for the discussion) and that lynx has been compiled
70
The default location for certs on your system may be different, or there may not
71
be one. You will have to substitute that location for /usr/local/ssl/certs in
72
the following instructions, and/or set environment variables.
74
To determine the default location for certs on your system you may run the
77
strings libcrypto.a | grep -in cert | less
79
Look in this output for SSL_CERT_DIR and SSL_CERT_FILE, and the lines just
80
above them. This is your default location, respectively, for certificates,
81
and the CA cert bundle, cert.pem. You will need to know where libcrypto.a is
88
7491:/etc/ssl/cert.pem
93
Other possible example output:
96
31555:/usr/local/ssl/certs
97
31556:/usr/local/ssl/cert.pem
102
Note that when OpenSSL is installed, the c_rehash utility is installed in a
103
binary directory (default /usr/local/ssl/bin). You will need to know where it
104
is on your system. The command:
108
will probably give useful results.
110
Note also that there is no CA cert bundle distributed with OpenSSL. The
111
OpenSSL team specifically decided NOT to do that. Getting a set of trusted
112
certificates is left up to the installer.
114
It is a fairly trivial procedure to pull the bundle of trusted root certs out
115
of a recent version of Internet Explorer. The mod_ssl project also provides
116
them. The procedure to convert and install them is detailed later in this
117
document, and if you simply need to have commercially provided certificates
118
trusted by lynx, you can skip down a few lines to the INSTALLING OR UPDATING
119
THE CA BUNDLE section.
121
INSTALLING A SELF-SIGNED CERTIFICATE:
123
When you would like to trust a self-signed (non-commercial) certificate you will
124
need to get hold of the actual file. If it's a cert local to your network you
125
can ask the sysadmin to make it available for download as a link on a webpage.
127
If such file is not human-readable it's probably DER formatted and will need to
128
be converted to PEM format to allow openssl to use it.
130
To convert DER formatted certificates into something openssl can deal with:
132
Save the cert as site_name.crt in a directory. In that directory, type:
134
openssl x509 -inform DER -in site_name.crt -outform PEM -out site_name.pem
136
You can now copy this individual cert into the directory for that, usually
137
/usr/local/ssl/certs. The alternative is to concatenate the individual certs
138
to the cert.pem bundle in /usr/local/ssl. (Please see INSTALLING OR UPDATING
139
THE CA BUNDLE below).
141
The cert file will now be in an acceptable format to openssl, PEM encoded.
142
However, openssl, and by extension lynx, will not know about it until that
143
cert is present in a file named after the hash value of that cert, in the
144
default directory /usr/local/ssl/certs.
146
So the next thing to do is to hash the cert using c_rehash.
148
INSTALLING OR UPDATING THE CA BUNDLE:
150
Now would be a good time to check to see if you have the bundle of CA certs
151
/usr/local/ssl/cert.pem, or to update them.
153
CA bundles are available in various places, such as the modssl distribution,
154
for those who want to take that route, or you can extract the current bundle
155
from a current version of Netscape or Internet Explorer (export them all from
156
IE and transfer it onto your system).
158
From IE it extracts as a PKCS7 file and needs to be converted with something
161
openssl pkcs7 -inform DER -in bundle.crt -outform PEM -out cert.pem \
164
The resulting cert.pem file should be copied to the default directory for
165
bundles (usually /usr/local/ssl) and renamed to "cert.pem". It will also
166
process just fine if it is present and hashed in /usr/local/ssl/certs.
168
We now have all of the individual certs we wish to trust in our certs
169
directory, and the most recent bundle of CA certs as well.
171
Confirm that you have the script c_rehash (See PRELIMINARY PROCEDURES; if it is
172
not found, a copy is usually located in the tools directory of the openssl
173
source tree. If you use this copy, it needs the execute bit set or it will not
180
The c_rehash utility is a perl script that runs openssl commands which creates
181
the files named after the hash values of the certs in the default directory
184
Its output looks like this:
186
Doing /usr/local/ssl/certs
187
vsignss.pem => f73e89fd.0
188
vsign3.pem => 7651b327.0
192
All pem encoded certs in /usr/local/ssl/certs will now be recognized.
194
SETTING AND EXPORTING ENVIRONMENT VARIABLES:
196
If lynx is still not recognizing certs, environment variables may need
197
to be set; if on a sh type shell, the variables also need to be exported.
199
The environment variables SSL_CERT_DIR and SSL_CERT_FILE only need to be set
200
if a non-default location is used for certificates, or if certs just can't be
201
found by lynx. They may be set as follows in /etc/profile, or a shell
202
initialization .profile or .*shrc, if we run a non csh type shell, according
203
to the results of the search for the default location for certs procedure
204
(See PRELIMINARY PROCEDURES):
206
SSL_CERT_DIR="/usr/local/ssl/certs"
207
SSL_CERT_FILE="/usr/local/ssl/cert.pem"
208
export SSL_CERT_DIR SSL_CERT_FILE
210
On csh type shells, you can use:
211
setenv SSL_CERT_DIR "/usr/local/ssl/certs"
212
setenv SSL_CERT_FILE "/usr/local/ssl/cert.pem"
214
On some systems setting and exporting them makes all the difference. Apparently
215
this is often not an issue on other systems, but this might help someone
218
Note that the environment variable SSL_CERT_FILE applies to the cert-bundle
219
if used outside of the default location (/usr/local/ssl/cert.pem) compiled
220
into OpenSSL. There are issues with SSL_CERT_FILE in 0.9.6x versions of openssl.
222
Make sure you have FORCE_SSL_PROMPT set to PROMPT in lynx.cfg like so:
224
FORCE_SSL_PROMPT:PROMPT
226
You will now connect without error to https servers with trusted certs, but
227
will still get this error for untrusted certs:
229
SSL error:self signed certificate-Continue? (y)
231
A quick check confirms that these procedures have the same effect with ssl
232
errors in the pine program.
234
--Stef Caunter <cauntes@mail.mohawkc.on.ca>
235
Mohawk College Department of Computer Science
236
Hamilton Ontario Canada