The Notary project comprises a server and a client for running and interacting with trusted collections.
Notary aims to make the internet more secure by making it easy for people to publish and verify content. We often rely on TLS to secure our communications with a web server which is inherently flawed, as any compromise of the server enables malicious content to be substituted for the legitimate content.
With Notary, publishers can sign their content offline using keys kept highly secure. Once the publisher is ready to make the content available, they can push their signed trusted collection to a Notary Server.
Consumers, having acquired the publisher‘s public key through a secure channel, can then communicate with any notary server or (insecure) mirror, relying only on the publisher’s key to determine the validity and integrity of the received content.
Notary is based on The Update Framework, a secure general design for the problem of software distribution and updates. By using TUF, notary achieves a number of key advantages:
Notary is a tool for publishing and managing trusted collections of content. Publishers can digitally sign collections and consumers can verify integrity and origin of content. This ability is built on a straightforward key management and signing interface to create signed collections and configure trusted publishers.
Lets try using notary.
Prerequisites:
As setup, let‘s build notary and then start up a local notary-server (don’t forget to add 127.0.0.1 notary-server
to your /etc/hosts
, or if using docker-machine, add $(docker-machine ip) notary-server
).
make binaries docker-compose build docker-compose up -d
Note: In order to have notary use the local notary server and development root CA we can load the local development configuration by appending -c cmd/notary/config.json
to every command. If you would rather not have to use -c
on every command, copy cmd/notary/config.json and cmd/notary/root-ca.crt
to ~/.notary
.
First, let's initiate a notary collection called example.com/scripts
notary init example.com/scripts
Now, look at the keys you created as a result of initialization
notary key list
Cool, now add a local file install.sh
and call it v1
notary add example.com/scripts v1 install.sh
Wouldn‘t it be nice if others could know that you’ve signed this content? Use publish
to publish your collection to your default notary-server
notary publish example.com/scripts
Now, others can pull your trusted collection
notary list example.com/scripts
More importantly, they can verify the content of your script by using notary verify
:
curl example.com/install.sh | notary verify example.com/scripts v1 | sh
Notary Server manages TUF data over an HTTP API compatible with the notary client.
It may be configured to use either JWT or HTTP Basic Auth for authentication. Currently it only supports MySQL for storage of the TUF data, we intend to expand this to other storage options.
The notary repository comes with Dockerfiles and a docker-compose file to facilitate development. Simply run the following commands to start a notary server with a temporary MySQL database in containers:
$ docker-compose build $ docker-compose up
If you are on Mac OSX with boot2docker or kitematic, you'll need to update your hosts file such that the name notary
is associated with the IP address of your VM (for boot2docker, this can be determined by running boot2docker ip
, with kitematic, echo $DOCKER_HOST
should show the IP of the VM). If you are using the default Linux setup, you need to add 127.0.0.1 notary
to your hosts file.
By default notary-server runs with TLS with certificates signed by a local CA. In order to be able to successfully connect to it using either curl
or openssl
, you will have to use the root CA file in fixtures/root-ca.crt
.
OpenSSL example:
openssl s_client -connect notary-server:4443 -CAfile fixtures/root-ca.crt
Prerequisites:
Install dependencies by running godep restore
.
From the root of this git repository, run make binaries
. This will compile the notary
, notary-server
, and notary-signer
applications and place them in a bin
directory at the root of the git repository (the bin
directory is ignored by the .gitignore file).
notary-signer
depends upon pkcs11
, which requires that libtool headers be installed (libtool-dev
on Ubuntu, libtool-ltdl-devel
on CentOS/RedHat). If you are using Mac OS, you can brew install libtool
, and run make binaries
with the following environment variables (assuming a standard installation of Homebrew):
export CPATH=/usr/local/include:${CPATH} export LIBRARY_PATH=/usr/local/lib:${LIBRARY_PATH}
The notary-server
application has the following usage:
$ bin/notary-server --help usage: bin/notary-serve -config="": Path to configuration file -debug=false: Enable the debugging server on localhost:8080
The configuration file must be a json file with the following format:
{ "server": { "addr": ":4443", "tls_cert_file": "./fixtures/notary-server.crt", "tls_key_file": "./fixtures/notary-server.key" }, "logging": { "level": 5 } }
The pem and key provided in fixtures are purely for local development and testing. For production, you must create your own keypair and certificate, either via the CA of your choice, or a self signed certificate.
If using the pem and key provided in fixtures, either:
Add fixtures/root-ca.crt
to your trusted root certificates
Use the default configuration for notary client that loads the CA root for you by using the flag -c ./cmd/notary/config.json
Disable TLS verification by adding the following option notary configuration file in ~/.notary/config.json
:
"skipTLSVerify": true
Otherwise, you will see TLS errors or X509 errors upon initializing the notary collection:
$ notary list diogomonica.com/openvpn * fatal: Get https://notary-server:4443/v2/: x509: certificate signed by unknown authority $ notary list diogomonica.com/openvpn -c cmd/notary/config.json latest b1df2ad7cbc19f06f08b69b4bcd817649b509f3e5420cdd2245a85144288e26d 4056