Skip to content
Client library and utilities for the Convergence SSL certificate validation system.
Python Shell
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
cuivre
demo
man
COPYING
README.markdown
TODO
clean.sh
cuivre-stub.py
cuivre.py
env.sh
setup.py

README.markdown

Cuivre

An implementation of the Convergence system for SSL certificate validation.

Project page: https://github.com/loris0/Cuivre

Features

Software library, the Cuivre package:

  • SSL certificate fingerprint validation against the Convergence notary system
  • Full SSL certificate validation
  • Creation of validation reports for both certificate and fingerprint validation processes.
  • Anonymization of notary requests, multiple validation policy options, caching of fingerprint verifications, and configurability of each parameter.
  • All concurrent operations take advantage of the Linux event-driven epoll
  • A simple HTTP library used to create and parse request and response messages
  • A validated Connection class, with the same interface as Python's socket
  • A validated HTTPSGet class, permitting to directly retrieve HTTPS URLs.
  • Demo programs to concisely explain the usage of these modules

CLI Client:

  • A command line interface client implementing all the cuivre package's infrastructure. Allows for full certificate and fingerprint validation Demonstrates the simple use of callbacks in the validation process.
  • Management and update of notary entities
  • Updating of notaries' information

Validation stub:

  • A long running process taking advantage of the cuivre package, providing a simplified interface to the Convergence system to local processes, thus removing the need for every user client to directly use the Cuivre package.
  • Communication with the validation stub is achieved through a local network interface, such as a TCP connection or a UNIX socket.

Help

This is a quick run of the software's functionality, but always remember there's an --help option, showing more options:

$ ./cuivre.py [ -h | --help ]

Usage

To avoid littering the filesystem with files untracked by our distro's package management system, we can simply change to the Cuivre directory and enter the development environment by running:

$ ./env.sh

This sets the CUIVRE_DEMO and PYTHONPATH environment variables, so that we can work with this package even by changing to the demo directory.

We can now start using the cuivre client right away.

Installing notary information bundles

The very first thing we have to do is choosing the notaries entities we want to install and use. In order to do that, we point our Web browser to the "Notaries" page on Convergence's github wiki, at the following URL:

https://github.com/moxie0/Convergence/wiki/Notaries

As a side note to the beginners, we really want to prefer high availability notaries to low availability ones. The formers assure us a greater uptime by having multiple hosts for a single entity.

Old style notaries are deprecated, but support will temporarily be given if many notaries will not update in a sane timeframe.

To install a notary bundle, download it with a Web browser, or a network retriever utility like wget. Note that browsers and other client software that aren't using the Convergence system may not like self-signed certificates.

Since we are still not protected by network perspective, we call this first step a "leap of faith", like the first time we connect to an SSH host with a still-unknown fingerprint.

To allow wget to download the file without screaming with a certificate error, we run it with the --no-check-certificate:

$ wget --no-check-certificate $notary_bundle_url

We can now install the notary bundle in our local database with:

$ ./cuivre.py --add-notary $notary_bundle_filename

The option --add-notary may be abbreviated with -A. To show the list of currently installed notaries along with further information, we use:

$ ./cuivre.py -l

We proceed installing at least two or three notary entities, so that we can benefit of a wider range of network perspective and other validation methods notaries may choose to adopt.

Print certificate information

To analyze a server's certificate, we can run:

$ ./cuivre.py --print-certificate-info -s <www.domain.tld> [ -p <port> ]

The short option format for --print-certificate-info is -i. We can specify a port different from the HTTPS default onen (443), using the --port (-p) option.

Every field and extensions is shown in a console-readable format, removing newline and carriage return characters from field values.

Validation of an SSL server's certificate

The validation of a server's certificate from the command line is simplified through the --validate-certificate option.

The short form of --validate-certificate is -c, the -a option enables anonymization of notary queries, while the -v (--verbose) option shows the detailed report of the validation process:

$ ./cuivre.py -c -a -v -s <www.domain.tld> [ -p <port> ]

The client will then proceed fetching the server's certificate, checking its validity for an SSL server and for the validity timeframe, contacting the installed notary servers, and then showing information about the process.

Certificate fingerprints and response signatures are verified for each notary connection.

The adopted fingerprint verification policy is printed along with the validation statement at the end of the report.

Furthermore, to simplify the use of this utility in other scripts, the client sets the exit status according to the validation success (exit code 0, true) or failure.

Following validations of the same certificate will take advantage of the local cache of verified fingerprints, which takes into account the certificate's expiration date and time.

Validation of an SSL server's certificate fingerprint

The validation of the only fingerprint of a server's certificate cannot check for the entire certificate validity, but just of its fingerprint, which however is cryptographically bound to coincide with the same certificate.

The fingerprint is first looked for in the local cache, and if not found, it is looked up against the installed notary entities, by means of the same validation routine used for a full certificate validation.

The syntax for a fingerprint validation is the following:

$ ./cuivre.py -f <00:11:22:...> -v -s <www.domain.tld> [ -p <port> ]

The -f option's long form is --validate-fingerprint.

Anonymity

Notary queries can be anonymized if more than one notary is in the database. This is because queries are sent encrypted through a forwarding "relay notary", to the end notaries used for validation, so that the unencrypted requests don't have identifying information about the originating client, and the relay cannot have a look at the certificates and hosts the client is interested with.

To enable anonymization of notary queries, use the --anonymity option:

$ ./cuivre.py [ -a | --anonymity ] [ -v ] -c -s <host> [ -p <port> ]

Anonymization is the default behaviour, and we can enable or disable it through the configuration file.

Validation policy

The default validation policy (unanimity) is the recommended one. You can set other values editing the configuration file, or with the [ -P | --policy ] command line option.

Fingerprint cache management

To show the content of the certificate fingerprints cache (--show-cache):

$ ./cuivre.py -S

To delete information relative to a server's host and port:

$ ./cuivre.py -D -s <host> -p <port>

To empty the cache of all entries (--empty-cache):

$ ./cuivre.py -E

Notary entities database management

To disable or enable notary entities:

$ ./cuivre.py [ -d | --disable-notary ] <notary_index>
$ ./cuivre.py [ -e | --enable-notary ] <notary_index>

To remove a notary entity:

$ ./cuivre.py [ -R | --remove-notary ] <notary_index>

To update the notary entities' information:

$ ./cuivre.py [ -U | --update-notaries ]
Something went wrong with that request. Please try again.