github.com/ojongerius/docker@v1.11.2/docs/security/trust/trust_key_mng.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Manage keys for content trust"
     4  description = "Manage keys for content trust"
     5  keywords = ["trust, security, root,  keys, repository"]
     6  [menu.main]
     7  parent= "smn_content_trust"
     8  +++
     9  <![end-metadata]-->
    10  
    11  # Manage keys for content trust
    12  
    13  Trust for an image tag is managed through the use of keys. Docker's content
    14  trust makes use of five different types of keys:
    15  
    16  | Key                 | Description                                                                                                                                                                                                                                                                                                                                                                         |
    17  |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    18  | root key         | Root of content trust for a image tag. When content trust is enabled, you create the root key once. Also known as the offline key, because it should be kept offline. |
    19  | targets          | This key allows you to sign image tags, to manage delegations including delegated keys or permitted delegation paths. Also known as the repository key, since this key determines what tags can be signed into an image repository. |
    20  | snapshot         | This key signs the current collection of image tags, preventing mix and match attacks.
    21  | timestamp        | This key allows Docker image repositories to have freshness security guarantees without requiring periodic content refreshes on the client's side. |
    22  | delegation       | Delegation keys are optional tagging keys and allow you to delegate signing image tags to other publishers without having to share your targets key. |
    23  
    24  When doing a `docker push` with Content Trust enabled for the first time, the
    25  root, targets, snapshot, and timestamp keys are generated automatically for
    26  the image repository:
    27  
    28  - The root and targets key are generated and stored locally client-side.
    29  
    30  - The timestamp and snapshot keys are safely generated and stored in a signing server
    31  	that is deployed alongside the Docker registry. These keys are generated in a backend
    32  	service that isn't directly exposed to the internet and are encrypted at rest.
    33  
    34  Delegation keys are optional, and not generated as part of the normal `docker`
    35  workflow.  They need to be
    36  [manually generated and added to the repository](trust_delegation.md#generating-delegation-keys).
    37  
    38  Note: Prior to Docker Engine 1.11, the snapshot key was also generated and stored
    39  locally client-side. [Use the Notary CLI to manage your snapshot key locally
    40  again](https://docs.docker.com/notary/advanced_usage/#rotate-keys) for
    41  repositories created with newer versions of Docker.
    42  
    43  ## Choosing a passphrase
    44  
    45  The passphrases you chose for both the root key and your repository key should
    46  be randomly generated and stored in a password manager.  Having the repository key
    47  allow users to sign image tags on a repository. Passphrases are used to encrypt
    48  your keys at rest and ensures that a lost laptop or an unintended backup doesn't
    49  put the private key material at risk.
    50  
    51  ## Back up your keys
    52  
    53  All the Docker trust keys are stored encrypted using the passphrase you provide
    54  on creation. Even so, you should still take care of the location where you back them up.
    55  Good practice is to create two encrypted USB keys.
    56  
    57  It is very important that you backup your keys to a safe, secure location. Loss
    58  of the repository key is recoverable; loss of the root key is not.
    59  
    60  The Docker client stores the keys in the `~/.docker/trust/private` directory.
    61  Before backing them up, you should `tar` them into an archive:
    62  
    63  ```bash
    64  $ umask 077; tar -zcvf private_keys_backup.tar.gz ~/.docker/trust/private; umask 022
    65  ```
    66  
    67  ## Lost keys
    68  
    69  If a publisher loses keys it means losing the ability to sign trusted content for
    70  your repositories.  If you lose a key, contact [Docker
    71  Support](https://support.docker.com) (support@docker.com) to reset the repository
    72  state.
    73  
    74  This loss also requires **manual intervention** from every consumer that pulled
    75  the tagged image prior to the loss. Image consumers would get an error for
    76  content that they already downloaded:
    77  
    78  ```
    79  could not validate the path to a trusted root: failed to validate data with current trusted certificates
    80  ```
    81  
    82  To correct this, they need to download a new image tag with that is signed with
    83  the new key.
    84  
    85  ## Related information
    86  
    87  * [Content trust in Docker](content_trust.md)
    88  * [Automation with content trust](trust_automation.md)
    89  * [Delegations for content trust](trust_delegation.md)
    90  * [Play in a content trust sandbox](trust_sandbox.md)