This repository holds open-source code for functionality related to certificate transparency (CT). The main areas covered are:
The supported platforms are:
First, ensure that the build machine has all of the required build dependencies. Then use gclient to retrieve and build the other software needed by the Log, and then use (GNU) make
to build and test the CT code:
export CXX=clang++ CC=clang mkdir ct # or whatever directory you prefer cd ct gclient config --name="certificate-transparency" https://github.com/google/certificate-transparency.git gclient sync # retrieve and build dependencies # substitute gmake or gnumake below if that's what your platform calls it: make -C certificate-transparency check # build the CT software & self-test
The source code is generally arranged according to implementation language, in the cpp
, go
, java
and python
subdirectories. The key subdirectories are:
cpp/log
: Main distributed CT Log implementation.cpp/merkletree
: Merkle tree implementation.cpp/server
: Top-level code for server implementations.cpp/monitoring
: Code to export operation statistics from CT Log.cpp/fetcher
: Code to fetch entries from another Logcpp/client
: CT Log client code in C++go/client
: CT Log client code in Gopython/ct
: CT Log client code in Pythonjava/src/org/certificatetransparency/ctlog
: CT Log client code in Javago/fixchain
: Tool to fix up certificate chainsgo/gossip
: Code to allow gossip-based synchronization of cert infogo/scanner
: CT Log scanner toolgo/merkletree
: Merkle tree implementation in Go.The CT software in this repository relies on a number of other open-source projects, and we recommend that:
The supported build system uses the gclient tool from the Chromium project to handle these requirements and to ensure a reliable, reproducible build. Older build instructions for using Ubuntu or Fedora packages and for manually building dependencies from source are no longer supported.
Within a main top-level directory, gclient handles the process of:
install/
subdirectoryUnder the covers, this gclient build process is controlled by:
install/
directory, where it is available for the build of the CT code itself.The following tools are needed to build the CT software and its dependencies.
The exact packages required to install these tools depends on the platform. For a Debian-based system, the relevant packages are: autoconf automake libtool shtool cmake clang git make tcl pkg-config python2.7
The following collections of additional software are used by the main CT Log codebase.
malloc
replacement optimized for multi-threaded useSSL
build variable.The extra (experimental) CT projects in this repo involve additional dependencies:
The CT C++ codebase is built with the Clang -Werror
flag so that the codebase stays warning-free. However, this can cause build errors when newer/different versions of the C++ compiler are used, as any newly created warnings are treated as errors. To fix this, add the appropriate -Wno-error=<warning-name>
option to CXXFLAGS
.
For example, on errors involving unused variables try using:
CXXFLAGS="-O2 -Wno-error=unused-variable" gclient sync
If an error about an unused typedef in a glog
header file occurs, try this:
CXXFLAGS="-O2 -Wno-error=unused-variable -Wno-error=unused-local-typedefs" gclient sync
When changing CXXFLAGS
it's safer to remove the existing build directories in case not all dependencies are properly accounted for and rebuilt. If problems persist, check that the Makefile in certificate-transparency
contains the options that were passed in CXXFLAGS
.
If you‘re trying to clone from a branch on the CT repository then you’ll need to substitute the following command for the gclient config
command above, replacing branch
as appropriate
gclient config --name="certificate-transparency" https://github.com/google/certificate-transparency.git@branch
The BoringSSL fork of OpenSSL can be used in place of OpenSSL (but note that the experimental CT DNS server does not support this configuration). To enable this, after the first step (gclient config ...
) in the gclient build process, modify the top-level .gclient
to add:
"custom_vars": { "ssl_impl": "boringssl" } },
Then continue the build process with the gclient sync
step.
The unit tests for the CT code can be run with the make check
target of certificate-transparency/Makefile
.
Note that several tests write files on disk. The default directory for storing temporary testdata is /tmp
. You can change this by setting TMPDIR=<tmpdir>
for make.
End-to-end tests also create temporary certificate and server files in test/tmp
. All these files are cleaned up after a successful test run.
For logging options, see the glog documentation.
By default, unit tests log to stderr
, and log only messages with a FATAL level (i.e., those that result in abnormal program termination). You can override the defaults with command-line flags.
The build process described so far generates a set of executables; however, other components and configuration is needed to set up a running CT Log. In particular, as shown in the following diagram:
Configuring and setting up a distributed production Log is covered in a separate document.
Running a successful, trusted, certificate transparency Log involves more than just deploying a set of binaries. Information and advice on operating a running CT Log is covered in a separate document