clrtrust
========

:Manual section: 1

SYNOPSIS
--------

**clrtrust** is a tool for generating and managing a centralized trusted
certificate store.

``clrtrust [-v|--verbose] [-h|--help] [-c|--internal-rehash] <command> [options]``

DESCRIPTION
-----------

A trust store contains a set of X.509 certificates which the operating
system and applications should consider trustworthy.

The ``clrtrust`` tool provides a frontend for centralized trust store
management. It allows for adding (trusting) and removing (distrusting)
certificate authorities (CAs). It also provides maintenance commands for
viewing and re-generating the trust store.

Certificates can be provided by the operating system for out-of-box
functionality. Certificates can also be provided and modified by
privileged users.

It is up to each application to make use of the trust store generated by
``clrtrust``.

OPTIONS
-------

::

   Usage: clrtrust [-v|--verbose] [-h|--help] [-c|--internal-rehash] <command> [options]

       -v | --verbose          Shows more details about execution
       -c | --internal-rehash  Forces use of internal implementation of c_rehash
       -h | --help             Prints this message

       Commands
           generate    generates the trust store
           list        list CAs
           add         add trust to a CA
           remove      remove trust to a CA
           restore     restore trust to previously removed CA
           check       sanity/consistency check of the trust store

   clrtrust <command> --help to get help on specific command.

**Commands that modify the trust store require root privileges.**

-  ``clrtrust generate [-f|--force]``

   The ``generate`` command has no arguments and generates a unified
   trust store composed of system-provided and user-provided
   certificates, if any. The optional ``--force`` parameter will
   forcibly generate the trust store, even if it results in an empty
   store. See the FILES section for paths used for trust store
   generation.

-  ``clrtrust list``

   The ``list`` command has no arguments and outputs a list of trusted
   certificates with the following fields:

   ``id`` uniquely identifies the certificate. It can be used as input
   to other ``clrtrust`` commands such as ``remove`` or ``restore``.

   ``File`` contains the file path of the certificate in the trust
   store.

   ``Authority`` shows the name of the organization that issued the
   certificate. This field is extracted from the certificate file.

   ``Expires`` shows the expiration date of the certificate. This field
   is extracted from the certificate file.

-  ``clrtust add [<certificateFile> ...] [-f|--force]``

   The ``add`` command takes one or more certificates as required
   argument(s). The certificate is identified by a file path. The
   certificate file(s) must be PEM-encoded with only one certificate per
   file. The optional ``--force`` parameter will forcibly add the
   certificate to the trust store, even if it is not a root CA.

   Adding a root CA to the trust store allows applications using the
   trust store to trust the root CA certificate, trust certificate
   chains issued by the authority, verify the authenticity of peer’s
   certificate, and establish a connection.

-  ``clrtrust remove [<certificateFile|id> ...]``

   The ``remove`` command takes one or more certificates as required
   argument(s). The certificate is identified by a file path or ``id``.
   The argument can be an ``id`` of the certificate (see the ``list``
   command) or the file path of the certificate.

   Removing a root CA from the trust store distrusts the certificate for
   applications using the trust store. Certificate chains issued by the
   authority will no longer be trusted, authenticity of the peer’s
   certificate will no longer be verified, and a connection will not be
   established.

-  ``clrtrust check``

   The ``check`` command has no arguments and validate the consistency
   of a previously generated unified trust store.

EXAMPLES
--------

View the list of trusted CAs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``clrtrust list``

The command above outputs a list of trusted certificates in the format
below:

::

   id: FA:B7:EE:36:97:26:62:FB:2D:B0:2A:F6:BF:03:FD:E8:7C:4B:2F:9B
   File: /var/cache/ca-certs/anchors/certSIGN_ROOT_CA.crt
   Authority: /C=RO/O=certSIGN/OU=certSIGN ROOT CA
   Expires: Jul  4 17:20:04 2031 GMT

The certificate can be further inspected using the ``openssl x509``
command. For example:

::

   openssl x509 -in /var/cache/ca-certs/anchors/certSIGN_ROOT_CA.crt -noout -text

Add (trust) a root CA
~~~~~~~~~~~~~~~~~~~~~

``clrtrust add ~/PrivateCA.pem``

The command above will add a root CA certificate located in the
``~/PrivateCA.pem`` file. If the certificate file is not in the PEM
format, use ``openssl x509`` command to convert to PEM first. For
example:

::

   openssl x509 -in PrivateCA.cer -inform der -out PrivateCA.pem -outform pem

Remove (distrust) a root CA
~~~~~~~~~~~~~~~~~~~~~~~~~~~

``clrtrust remove ~/PrivateCA.pem``

The command above will remove a root CA certificate located in the
``~/PrivateCA.pem`` file from the trust store and distrust it.

FILES
-----

*/var/cache/ca-certs*

Generated directory of certificates and verification keys. Do not modify
contents outside of ``clrtrust``.

*/usr/share/ca-certs/*

Operating-system provided certificates and keys. Do not modify contents
outside of ``clrtrust``.

*/etc/ca-certs/*

Generated directory of user-supplied certificates and verification keys.
Do not modify contents outside of ``clrtrust``.

BUGS
----

See GitHub Issues: https://github.com/clearlinux/clrtrust/issues

SEE ALSO
--------

**openssl(1)**
