diff --git a/docs/signature.md b/docs/signature.md new file mode 100644 index 0000000000..ead80e79e9 --- /dev/null +++ b/docs/signature.md @@ -0,0 +1,93 @@ +# Image Signature Specification + +**Version 0.1** + +## Introduction + +This document defines a detached container image signature object and signing methods. + +## Signature Format + +```js +{ + "critical": {/* required fields */ + "identity": {/* identity reference */}, + "image": {/* signed object reference */ }, + "type": "..." + }, + "optional": {/* optional metadata fields */} + } +} +``` + +### Fields + +There are two top-level fields, **critical** (required) and **optional** (optional). + +#### `critical` + +**identity** (string): + +```js +{ + "docker-reference": imageName +} +``` + +`imageName` per [V2 API](https://docs.docker.com/registry/spec/api/#/overview) Required. + +**image** (string): + +```js +{ + "docker-manifest-digest": manifestDigest +} +``` + +`manifestDigest` in the form of `:` + +**type** (string): Only supported value is "atomic container signature" + +#### `optional` + +**creator** (string): Creator ID. This refers to the tooling used to generate the signature. + +**timestamp** (int64): timestamp epoch + +### Example + +```js +{ + "critical": { + "identity": { + "docker-reference": "busybox" + }, + "image": { + "docker-manifest-digest": "sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6" + }, + "type": "atomic container signature" + }, + "optional": { + "creator": "atomic 0.1.0-dev", + "timestamp": 1471035347 + } +} +``` + +### Encryption and Decryption + +The signature data is written to a file that is encrypted and signed with a private key. The file may be decrypted (verified) using the corresponding public key. + +**Example GPG Sign command** + +Given signature file busybox.sig formatted per above: + +``` +$ gpg2 -r KEYID --encrypt --sign busybox.sig +``` + +**Example GPG Verify command** + +``` +$ gpg2 --decrypt busybox.sig.gpg +```