diff --git a/docs/images/metadata-sequence.svg b/docs/images/metadata-sequence.svg index 0cfc351465..7882e6818d 100644 --- a/docs/images/metadata-sequence.svg +++ b/docs/images/metadata-sequence.svg @@ -1,3 +1,335 @@ - + - Produced by OmniGraffle 6.5 2016-02-24 08:38:31 +0000SequenceLayer 1credentialsauthXTUFserver>_Upload new metadata401 - please authbearer tokenverify(metadata)get metadatagenerate( timestamp,snapshot)sign( timestamp, snapshot)private keystimestamp/snapshotsignaturesToken + Upload new metadatatimestamp/snapshotstore metadata200 OKToken + Get new metadataget metadata200 OK + Latest metadata1234567 + + + + + + credentials + + + + + + + auth + + + + + + + + X + + + + + + + + + + + + + + TUF + + + + + + server + + + + + + + + + + + + + + + + + + >_ + + + + + + + + + + + + + + + + Upload new metadata + + + + + + + + + + + 401 - please auth + + + + + + + + + + + + bearer token + + + + + + + + + + + + verify(metadata) + + + + + + + + + + get + + + metadata + + + + + + + + + + + generate( + + + timestamp,snapshot) + + + + + + + + + + + + sign( + + + timestamp, snapshot) + + + + + + + + + + private + + + keys + + + + + + timestamp/snapshot + + + signatures + + + + + + + T + + + oken + Upload new metadata + + + + + + + timestamp/snapshot + + + + + + + + + + store + + + metadata + + + + + + + 200 OK + + + + + + + + + + + T + + + oken + Get new metadata + + + + + + + + + + + + + + + get + + + metadata + + + + + + + 200 OK + Latest metadata + + + + + + + + + 1 + + + + + + + 2 + + + + + + + 3 + + + + + + + 4 + + + + + + + 5 + + + + + + + 6 + + + + + + + 7 + + + + + + + + + + + + + (signer) + + + + + (server DB) + + + + + (signer DB) + + + + + (client) + + + + diff --git a/docs/images/service-architecture.svg b/docs/images/service-architecture.svg index 5ad2e29c92..7117a701fc 100644 --- a/docs/images/service-architecture.svg +++ b/docs/images/service-architecture.svg @@ -1,3 +1,92 @@ - + - Produced by OmniGraffle 6.5 2016-02-25 18:03:20 +0000ArchitectureLayer 1TUFserver>_>_>_ + + + + + + server + + + + + + + + + + + >_ + + + + + + + >_ + + + + + + + >_ + + + + + + + + clients + + + + + + + + + + + + + + TUF + + + + + (server DB) + + + + + + + + + + + + + + + (signer DB) + + + + + + + + + + + + + (signer) + + + + diff --git a/docs/images/service-deployment.svg b/docs/images/service-deployment.svg index 65d16eeac9..e79cf3faf9 100644 --- a/docs/images/service-deployment.svg +++ b/docs/images/service-deployment.svg @@ -1,3 +1,3 @@ - Produced by OmniGraffle 6.5 2016-02-24 08:05:17 +0000DeploymentLayer 1TUFNotary ServersserverserverNotary Signers + Produced by OmniGraffle 6.5.2 2016-04-08 01:10:50 +0000DeploymentLayer 1Notary ServersserverserverNotary SignersTUF(server DB)(signer DB) diff --git a/docs/running_a_service.md b/docs/running_a_service.md index 19e57680ad..53e7a85e6b 100644 --- a/docs/running_a_service.md +++ b/docs/running_a_service.md @@ -225,7 +225,7 @@ independently. The database may also be scaled independently but this is left as and exercise for experienced DBAs and Operations teams. A typical deployment will look like the below diagram: -![Notary server Deployment Diagram](images/service-deployment.svg) +![Notary server Deployment Diagram](https://cdn.rawgit.com/docker/notary/09f81717080f53276e6881ece57cbbbf91b8e2a7/docs/images/service-deployment.svg) In the diagram, a load balancer routes external traffic to a cluster of Notary server instances. These may make requests to Notary signer instances if either a) signing diff --git a/docs/service_architecture.md b/docs/service_architecture.md index b6a72392f4..7944042668 100644 --- a/docs/service_architecture.md +++ b/docs/service_architecture.md @@ -20,7 +20,7 @@ This document assumes familiarity with The Update Framework, but here is a brief recap of the TUF roles and corresponding key hierarchy: -
TUF Key Hierarchy
+
TUF Key Hierarchy
- The root key is the root of all trust. It signs the root metadata file, @@ -77,7 +77,7 @@ for multiple trusted collections in an associated database, and a Notary signer, stores private keys for and signs metadata for the Notary server. The following diagram illustrates this architecture: -![Notary Service Architecture Diagram](images/service-architecture.svg) +![Notary Service Architecture Diagram](https://cdn.rawgit.com/docker/notary/09f81717080f53276e6881ece57cbbbf91b8e2a7/docs/images/service-architecture.svg) Root, targets, and (sometimes) snapshot metadata are generated and signed by clients, who upload the metadata to the Notary server. The server is @@ -101,20 +101,20 @@ The Notary signer is responsible for: The following diagram illustrates the interactions between the Notary client, server, and signer: -![Notary Service Sequence Diagram](images/metadata-sequence.svg) +![Notary Service Sequence Diagram](https://cdn.rawgit.com/docker/notary/09f81717080f53276e6881ece57cbbbf91b8e2a7/docs/images/metadata-sequence.svg) 1. Notary server optionally supports authentication from clients using JWT tokens. This requires an authorization server that manages access controls, and a cert bundle from this authorization server containing the public key it uses to sign tokens. - If token authentication is enabled on Notary server, then any connecting - client that does not have a token will be redirected to the authorization - server. + If token authentication is enabled on Notary server, then any connecting + client that does not have a token will be redirected to the authorization + server. - Please see the docs for [Docker Registry v2 authentication]( - https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md) - for more information. + Please see the docs for [Docker Registry v2 authentication]( + https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md) + for more information. 2. The client will log in to the authorization server via basic auth over HTTPS, obtain a bearer token, and then present the token to Notary server on future @@ -137,17 +137,17 @@ server, and signer: database. The generated timestamp and snapshot metadata certify that the metadata files the client uploaded are the most recent for that trusted collection. - Finally, Notary server will notify the client that their upload was successful. + Finally, Notary server will notify the client that their upload was successful. 7. The client can now immediately download the latest metadata from the server, using the still-valid bearer token to connect. Notary server only needs to obtain the metadata from the database, since none of the metadata has expired. - In the case that the timestamp has expired, Notary server would go through - the entire sequence where it generates a new timestamp, request Notary signer - for a signature, stores the newly signed timestamp in the database. It then - sends this new timestamp, along with the rest of the stored metadata, to the - requesting client. + In the case that the timestamp has expired, Notary server would go through + the entire sequence where it generates a new timestamp, request Notary signer + for a signature, stores the newly signed timestamp in the database. It then + sends this new timestamp, along with the rest of the stored metadata, to the + requesting client. ## Threat model