Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update readme to align with TUF #1685

Merged
merged 3 commits into from
Jul 25, 2023
Merged

Update readme to align with TUF #1685

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
faeb70b
Update readme to align with TUF
sajayantony Jun 22, 2023
07dd138
Added note for DCT and first release date.
sajayantony Jun 27, 2023
069eda7
fix pr feedback
sajayantony Jul 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 25 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,39 @@
<img src="docs/images/notary-blk.svg" alt="Notary" width="400px"/>

[![GoDoc](https://godoc.org/github.com/theupdateframework/notary?status.svg)](https://godoc.org/github.com/theupdateframework/notary)
[![Circle CI](https://circleci.com/gh/theupdateframework/notary/tree/master.svg?style=shield)](https://circleci.com/gh/theupdateframework/notary/tree/master) [![CodeCov](https://codecov.io/github/theupdateframework/notary/coverage.svg?branch=master)](https://codecov.io/github/theupdateframework/notary) [![GoReportCard](https://goreportcard.com/badge/theupdateframework/notary)](https://goreportcard.com/report/github.com/theupdateframework/notary)
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Ftheupdateframework%2Fnotary.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Ftheupdateframework%2Fnotary?ref=badge_shield)

# Notice

The Notary project has officially been accepted in to the Cloud Native Computing Foundation (CNCF).
It has moved to https://github.com/theupdateframework/notary. Any downstream consumers should update
their Go imports to use this new location, which will be the canonical location going forward.

We have moved the repo in GitHub, which will allow existing importers to continue using the old
location via GitHub's redirect.
This repository provides an implementation of
*[The Update Framework specification](https://github.com/theupdateframework/specification)*
and all references to `notary` in this repository refer to the implementation of the client
and server aligning with the [TUF](https://github.com/theupdateframework/specification) specification.
sajayantony marked this conversation as resolved.
Show resolved Hide resolved
The most prominent use of this implementation is in Docker Content Trust (DCT).
The first release [v0.1](https://github.com/notaryproject/notary/releases/tag/v0.1) was released in November, 2015.

# Overview

The Notary project comprises a [server](cmd/notary-server) and a [client](cmd/notary) for running and interacting
This repository comprises of a [server](cmd/notary-server) and a [client](cmd/notary) for running and interacting
with trusted collections. See the [service architecture](docs/service_architecture.md) documentation
for more information.

Notary aims to make the internet more secure by making it easy for people to
The aim is 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
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.
push their signed trusted collection to the `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
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.

## Goals

Notary is based on [The Update Framework](https://www.theupdateframework.com/), a secure general design for the problem of software distribution and updates. By using TUF, Notary achieves a number of key advantages:
The `notary` client and server is based on [The Update Framework](https://www.theupdateframework.com/), a secure general design for the problem of software distribution and updates. By using TUF, the `notary` client and server achieves a number of key advantages:

* **Survivable Key Compromise**: Content publishers must manage keys in order to sign their content. Signing keys may be compromised or lost so systems must be designed in order to be flexible and recoverable in the case of key compromise. TUF's notion of key roles is utilized to separate responsibilities across a hierarchy of keys such that loss of any particular key (except the root role) by itself is not fatal to the security of the system.
* **Freshness Guarantees**: Replay attacks are a common problem in designing secure systems, where previously valid payloads are replayed to trick another system. The same problem exists in the software update systems, where old signed can be presented as the most recent. Notary makes use of timestamping on publishing so that consumers can know that they are receiving the most up to date content. This is particularly important when dealing with software update where old vulnerable versions could be used to attack users.
Expand All @@ -48,32 +46,32 @@ Notary is based on [The Update Framework](https://www.theupdateframework.com/),

Any security vulnerabilities can be reported to [email protected].

See Notary's [service architecture docs](docs/service_architecture.md#threat-model) for more information about our threat model, which details the varying survivability and severities for key compromise as well as mitigations.
See [service architecture docs](docs/service_architecture.md#threat-model) for more information about our threat model, which details the varying survivability and severities for key compromise as well as mitigations.

### Security Audits

Notary has had two public security audits:
Below are the two public security audits:

* [August 7, 2018 by Cure53](docs/resources/cure53_tuf_notary_audit_2018_08_07.pdf) covering TUF and Notary
* [July 31, 2015 by NCC](docs/resources/ncc_docker_notary_audit_2015_07_31.pdf) covering Notary
* [August 7, 2018 by Cure53](docs/resources/cure53_tuf_notary_audit_2018_08_07.pdf) covering TUF and the `notary` client and server.
* [July 31, 2015 by NCC](docs/resources/ncc_docker_notary_audit_2015_07_31.pdf) covering `notary` client and server.

# Getting started with the Notary CLI
# Getting started with the notary CLI

Get the Notary Client CLI binary from [the official releases page](https://github.com/theupdateframework/notary/releases) or you can [build one yourself](#building-notary).
The version of the Notary server and signer should be greater than or equal to Notary CLI's version to ensure feature compatibility (ex: CLI version 0.2, server/signer version >= 0.2), and all official releases are associated with GitHub tags.
Get the `notary` client CLI binary from [the official releases page](https://github.com/theupdateframework/notary/releases) or you can [build one yourself](#building-notary).
The version of the `notary` server and signer should be greater than or equal to notary CLI's version to ensure feature compatibility (ex: CLI version 0.2, server/signer version >= 0.2), and all official releases are associated with GitHub tags.

To use the Notary CLI with Docker hub images, have a look at Notary's
To use the notary CLI with Docker hub images, have a look at notary's
[getting started docs](docs/getting_started.md).

For more advanced usage, see the
[advanced usage docs](docs/advanced_usage.md).

To use the CLI against a local Notary server rather than against Docker Hub:
To use the CLI against a local `notary` server rather than against Docker Hub:

1. Ensure that you have [docker and docker-compose](https://docs.docker.com/compose/install/) installed.
1. `git clone https://github.com/theupdateframework/notary.git` and from the cloned repository path,
start up a local Notary server and signer and copy the config file and testing certs to your
local Notary config directory:
start up a local `notary` server and signer and copy the config file and testing certs to your
local notary config directory:

```sh
$ docker-compose build
Expand Down Expand Up @@ -108,9 +106,9 @@ git commit -m "Upgraded github.com/spf13/viper"

The `buildscripts/circle-validate-vendor.sh` runs `go mod tidy` and `go mod vendor` using the given version of Go to prevent differences if you are for example running on a different version of Go.

## Building Notary
## Building notary

Note that Notary's [latest stable release](https://github.com/theupdateframework/notary/releases) is at the head of the
Note that the [latest stable release](https://github.com/theupdateframework/notary/releases) is at the head of the
[releases branch](https://github.com/theupdateframework/notary/tree/releases). The master branch is the development
branch and contains features for the next release.

Expand Down