github.com/rentongzhang/docker@v1.8.2-rc1/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 four different keys: 
    15  
    16  | Key                 | Description                                                                                                                                                                                                                                                                                                                                                                         |
    17  |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    18  | offline key         | Root of content trust for a image tag. When content trust is enabled, you create the offline key once. |
    19  | target and snapshot | These two keys are known together as the "tagging" key. When content trust is enabled, you create this key when you add a new image repository. If you have the offline key, you can export the tagging key and allow other publishers to sign the image tags.    |
    20  | timestamp           | This key applies to a repository. It allows Docker repositories to have freshness security guarantees without requiring periodic content refreshes on the client's side.                                                                                                              |
    21  
    22  With the exception of the timestamp, all the keys are generated and stored locally
    23  client-side. The timestamp is safely generated and stored in a signing server that
    24  is deployed alongside the Docker registry. All keys are generated in a backend
    25  service that isn't directly exposed to the internet and are encrypted at rest.
    26  
    27  ## Choosing a passphrase
    28  
    29  The passphrases you chose for both the offline key and your tagging key should
    30  be randomly generated and stored in a password manager.  Having the tagging key
    31  allow users to sign image tags on a repository. Passphrases are used to encrypt
    32  your keys at rest and ensures that a lost laptop or an unintended backup doesn't
    33  put the private key material at risk. 
    34  
    35  ## Back up your keys
    36  
    37  All the Docker trust keys are stored encrypted using the passphrase you provide
    38  on creation. Even so, you should still take care of the location where you back them up.
    39  Good practice is to create two encrypted USB keys.
    40  
    41  It is very important that you backup your keys to a safe, secure location. Loss
    42  of the tagging key is recoverable; loss of the offline key is not. 
    43  
    44  The Docker client stores the keys in the `~/.docker/trust/private` directory.
    45  Before backing them up, you should `tar` them into an archive:
    46  
    47  ```bash
    48  $ tar -zcvf private_keys_backup.tar.gz ~/.docker/trust/private
    49  $ chmod 600 private_keys_backup.tar.gz
    50  ```
    51  
    52  ## Lost keys
    53  
    54  If a publisher loses keys it means losing the ability to sign trusted content for
    55  your repositories.  If you lose a key, contact [Docker
    56  Support](https://support.docker.com) (support@docker.com) to reset the repository
    57  state. 
    58  
    59  This loss also requires **manual intervention** from every consumer that pulled
    60  the tagged image prior to the loss. Image consumers would get an error for
    61  content that they already downloaded:
    62  
    63  ```
    64  could not validate the path to a trusted root: failed to validate data with current trusted certificates
    65  ```
    66  
    67  To correct this, they need to download a new image tag with that is signed with
    68  the new key. 
    69  
    70  ## Related information
    71  
    72  * [Content trust in Docker](/security/trust/content_trust) 
    73  * [Automation with content trust](/security/trust/trust_automation)
    74  * [Play in a content trust sandbox](/security/trust/trust_sandbox)