Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history 
Signed-off-by: Shiwei Zhang <[email protected]>
  • Loading branch information
@shizhMSFT
shizhMSFT committed Feb 15, 2022
1 parent 6a9a44c commit 654e89e
Show file tree
Hide file tree
Showing 3 changed files with 221 additions and 1 deletion.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
*.dll
*.so
*.dylib
bin/

# Test binary, built with `go test -c`
*.test
Expand Down
1 change: 1 addition & 0 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,5 @@ install: install-notation-cose ## install the notation plugins

.PHONY: install-notation-cose
install-notation-cose: bin/notation-cose ## installs the notation cose plugin
mkdir -p ~/.config/notation/plugins/cose
cp $< ~/.config/notation/plugins/cose/notation-cose
220 changes: 219 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,220 @@
# notation-cose
Notation plugin for COSE

A *minimum viable prototype* of notation plugin for [COSE](https://datatracker.ietf.org/doc/html/rfc8152) signatures.

This plugin works only with the notation [release](https://github.com/notaryproject/notation/releases/tag/feat-kv-extensibility) built from the [feat-kv-extensibility](https://github.com/notaryproject/notation/tree/feat-kv-extensibility) feature branch.

## Getting Started

The following bash script block summaries the steps to configure the `cose` plugin, sign and verify a container image against COSE signatures.

```bash
# Configure notation with the COSE plugin
notation plugin add cose ~/.config/notation/plugins/cose/notation-cose

# Add signing and verification keys to the notation configuration policy
KEY_INFO="$KEY_PATH:${CERT_PATH}"
# Uncomment below for configuring timestamp server
# KEY_INFO="${KEY_INFO}:${TSA_URL}"
notation key add --name ${KEY_NAME} --plugin cose --id ${KEY_INFO} --kms
notation cert add --name ${KEY_NAME} --plugin cose --id ${CERT_PATH} --kms

# Sign image and generate COSE signature
notation sign --key ${KEY_NAME} ${IMAGE}

# Verify image against the COSE signature generated above
notation verify --cert ${KEY_NAME} ${IMAGE}
```

## Sample COSE Signature

A COSE signature generated by the `notation-cose` plugin looks like

```
$ xxd -g1 sample.sig
00000000: d2 84 58 39 a4 01 38 24 02 81 03 03 78 26 61 70 ..X9..8$....x&ap
00000010: 70 6c 69 63 61 74 69 6f 6e 2f 76 6e 64 2e 6f 63 plication/vnd.oc
00000020: 69 2e 64 65 73 63 72 69 70 74 6f 72 2e 76 31 2b i.descriptor.v1+
00000030: 6a 73 6f 6e 63 69 61 74 1a 62 0b 5f 8a a1 63 78 jsonciat.b._..cx
00000040: 35 63 81 59 03 02 30 82 02 fe 30 82 01 e6 a0 03 5c.Y..0...0.....
00000050: 02 01 02 02 11 00 af ba 5c 63 66 e1 c1 59 95 91 ........\cf..Y..
00000060: 4a 95 cd 26 cf c6 30 0d 06 09 2a 86 48 86 f7 0d J..&..0...*.H...
00000070: 01 01 0b 05 00 30 14 31 12 30 10 06 03 55 04 03 .....0.1.0...U..
00000080: 0c 09 63 6f 73 65 5f 74 65 73 74 30 1e 17 0d 32 ..cose_test0...2
00000090: 32 30 32 31 35 30 37 35 38 30 32 5a 17 0d 32 33 20215075802Z..23
000000a0: 30 32 31 35 30 37 35 38 30 32 5a 30 14 31 12 30 0215075802Z0.1.0
000000b0: 10 06 03 55 04 03 0c 09 63 6f 73 65 5f 74 65 73 ...U....cose_tes
000000c0: 74 30 82 01 22 30 0d 06 09 2a 86 48 86 f7 0d 01 t0.."0...*.H....
000000d0: 01 01 05 00 03 82 01 0f 00 30 82 01 0a 02 82 01 .........0......
000000e0: 01 00 bf 6f 1b 78 b9 52 98 7a 31 74 00 92 6b 3e ...o.x.R.z1t..k>
000000f0: 83 4a 6e ce cc 9b 1d ac 3d fd 48 24 2a 0d f9 b6 .Jn.....=.H$*...
00000100: d8 53 11 d2 67 af 14 03 3e e6 d6 06 28 88 17 ed .S..g...>...(...
00000110: 68 31 48 e2 d8 ab dc 64 49 dd 00 a0 7d 68 e9 3f h1H....dI...}h.?
00000120: 7f 46 34 c5 81 ee 79 fb e0 a9 4a 65 ec 49 f5 2b .F4...y...Je.I.+
00000130: 7a c8 8b d4 6c 82 85 d8 18 ad ff c8 f7 d6 3c 2b z...l.........<+
00000140: 03 08 b8 da a7 f3 c2 00 84 99 a8 0d cf ec e5 65 ...............e
00000150: e1 a7 7c 5b 60 0d 4c 97 52 f5 f8 89 5e 3d e1 8b ..|[`.L.R...^=..
00000160: 17 8e 6d 2b d1 cf be 7a 10 09 3c 7c 5f b6 2d e9 ..m+...z..<|_.-.
00000170: 65 69 d1 61 19 65 c2 23 73 43 d0 70 58 47 b9 25 ei.a.e.#sC.pXG.%
00000180: 88 ce cf ce 91 f8 e4 fe fe d0 b3 e1 35 4a 89 09 ............5J..
00000190: 6d d4 68 b1 74 c0 86 34 03 70 7b 9a 94 15 e3 33 m.h.t..4.p{....3
000001a0: 13 4a de fb f5 24 7e de 07 70 05 4f 0d 50 f0 7f .J...$~..p.O.P..
000001b0: 78 22 b7 79 e9 be e7 dc ae 7f be 0e 28 cc 1e 77 x".y........(..w
000001c0: 13 c2 9d 41 62 ad 63 67 49 95 c1 0a 28 ed 2e 1b ...Ab.cgI...(...
000001d0: fd 04 22 c3 96 8f 4c 36 88 2b 18 25 22 51 b2 19 .."...L6.+.%"Q..
000001e0: d1 37 02 03 01 00 01 a3 4b 30 49 30 0e 06 03 55 .7......K0I0...U
000001f0: 1d 0f 01 01 ff 04 04 03 02 07 80 30 13 06 03 55 ...........0...U
00000200: 1d 25 04 0c 30 0a 06 08 2b 06 01 05 05 07 03 03 .%..0...+.......
00000210: 30 0c 06 03 55 1d 13 01 01 ff 04 02 30 00 30 14 0...U.......0.0.
00000220: 06 03 55 1d 11 04 0d 30 0b 82 09 63 6f 73 65 5f ..U....0...cose_
00000230: 74 65 73 74 30 0d 06 09 2a 86 48 86 f7 0d 01 01 test0...*.H.....
00000240: 0b 05 00 03 82 01 01 00 9e 35 c0 3b f8 f3 85 fc .........5.;....
00000250: 56 56 73 68 e7 bd 2d 13 76 3c a8 35 12 1e 5e 22 VVsh..-.v<.5..^"
00000260: a6 d0 f4 a8 1b 44 a5 d9 eb c1 0c 88 0c cd bf f7 .....D..........
00000270: fe 70 4d 7c 6c 2e eb 78 c2 51 18 77 de 92 35 7c .pM|l..x.Q.w..5|
00000280: 45 09 53 92 c1 2d 00 6e b9 cb 36 d2 0f 9a 8e 10 E.S..-.n..6.....
00000290: fe ea 2d e3 9e b4 35 8b 0d 23 ab a0 31 a0 67 4c ..-...5..#..1.gL
000002a0: 35 7d e8 36 7f a2 4f d1 2b 14 c3 f3 90 17 42 f2 5}.6..O.+.....B.
000002b0: b0 a1 f7 51 87 01 2e a7 a4 4b 44 14 48 38 eb a2 ...Q.....KD.H8..
000002c0: 78 5f bc 43 43 aa 67 9f 3b bc 9a 3a 5d b3 04 26 x_.CC.g.;..:]..&
000002d0: 78 6a 34 7c 22 be a2 46 42 51 8a 3b fd b5 31 c1 xj4|"..FBQ.;..1.
000002e0: 2b ed 4a b7 8a a2 e4 5f 8d 55 2b 89 55 b7 de a2 +.J...._.U+.U...
000002f0: 20 09 93 da cf f8 6b b7 9d 85 ad c2 34 db ba fe .....k.....4...
00000300: fa 7f 55 4e 36 db 3f 67 16 8d a4 c4 e8 80 6b 9e ..UN6.?g......k.
00000310: 27 42 98 ea 7f 46 39 76 71 89 ba 28 52 90 64 03 'B...F9vq..(R.d.
00000320: 18 0a 1e 38 41 06 b8 36 01 b6 55 f0 a4 e4 70 ba ...8A..6..U...p.
00000330: ee b6 0d 5a 09 4d c8 52 47 78 0f c7 07 ed 42 0e ...Z.M.RGx....B.
00000340: c6 7f 84 1b 47 8a 87 b1 58 a2 7b 22 6d 65 64 69 ....G...X.{"medi
00000350: 61 54 79 70 65 22 3a 22 61 70 70 6c 69 63 61 74 aType":"applicat
00000360: 69 6f 6e 2f 76 6e 64 2e 64 6f 63 6b 65 72 2e 64 ion/vnd.docker.d
00000370: 69 73 74 72 69 62 75 74 69 6f 6e 2e 6d 61 6e 69 istribution.mani
00000380: 66 65 73 74 2e 76 32 2b 6a 73 6f 6e 22 2c 22 64 fest.v2+json","d
00000390: 69 67 65 73 74 22 3a 22 73 68 61 32 35 36 3a 65 igest":"sha256:e
000003a0: 37 64 38 38 64 65 37 33 64 62 33 64 33 66 64 39 7d88de73db3d3fd9
000003b0: 62 32 64 36 33 61 61 37 66 34 34 37 61 31 30 66 b2d63aa7f447a10f
000003c0: 64 30 32 32 30 62 37 63 62 66 33 39 38 30 33 63 d0220b7cbf39803c
000003d0: 38 30 33 66 32 61 66 39 62 61 32 35 36 62 33 22 803f2af9ba256b3"
000003e0: 2c 22 73 69 7a 65 22 3a 35 32 38 7d 59 01 00 3c ,"size":528}Y..<
000003f0: e0 42 15 3c aa c5 8f 93 c4 43 e6 9d c8 8b 07 11 .B.<.....C......
00000400: 14 8f 5d 0b 82 a8 02 6c 44 82 2c 93 46 b6 c5 13 ..]....lD.,.F...
00000410: 39 a3 e8 09 e0 b2 35 83 5e 11 04 41 96 5e 85 22 9.....5.^..A.^."
00000420: c2 fa 29 f4 71 be da 11 97 a9 35 e2 ef 85 07 c1 ..).q.....5.....
00000430: b1 b4 10 7a d2 5b 23 9f fa f0 c1 76 3b 8e 93 af ...z.[#....v;...
00000440: e3 dd 1b bb 6c 19 71 1a 4b 2f 30 ce 65 4c b0 ee ....l.q.K/0.eL..
00000450: 7f 63 8a 06 1f d6 d4 1f f3 6c e8 f7 ea 0e b2 bf .c.......l......
00000460: 66 e7 e7 6b 07 cf 25 2a be f0 73 d4 ab b6 7f 03 f..k..%*..s.....
00000470: 79 fa 47 87 a7 58 a4 6f 68 6a 39 2f 54 22 8a 4c y.G..X.ohj9/T".L
00000480: 1e ad e7 a0 4e c6 16 14 bd bc 2f 7c 68 d9 3e cb ....N...../|h.>.
00000490: b3 8d 19 c6 4f 7e 11 13 d4 6c 78 55 c8 98 10 bc ....O~...lxU....
000004a0: 98 f0 d3 ee a3 85 82 26 79 a5 df 2b c4 69 8a 56 .......&y..+.i.V
000004b0: 44 4d 5d 41 6f ae 59 0a 34 8a ab 81 09 24 ba 4f DM]Ao.Y.4....$.O
000004c0: e4 ad ad 11 d7 c0 67 7e 44 6e c8 c0 17 61 59 cd ......g~Dn...aY.
000004d0: 8c f9 a2 1a 27 d6 63 5b 55 2f 53 6e e5 ba a4 94 ....'.c[U/Sn....
000004e0: 04 1f ec 3b 8c 38 94 07 8a 5d d2 4a fa 44 eb ...;.8...].J.D.
```

Segmented:

```sql
d2 -- Tag 18: cose-sign1
84 -- COSE_Sign1 object: Array of length 4
58 39 -- protected: 57 bytes
a4 -- map of size 4
01 -- Key: 1 alg
38 24 -- Value: -36 ES512
02 -- Key: 2 crit
81 -- Value: Array of length 1
03 -- 3 content type
03 -- Key: 3 content type
78 26 -- Value: UTF-8 text of length 38
61 70 70 6c 69 63 61 74 69 6f 6e 2f 76 6e 64 -- application/vnd
2e 6f 63 69 2e 64 65 73 63 72 69 70 74 6f 72 -- .oci.descriptor
2e 76 31 2b 6a 73 6f 6e -- .v1+json
63 -- Key: UTF-8 text of length 3
69 61 74 -- iat
1a -- Value: int32
62 0b 5f 8a -- 1644912522 -- 20220215T092104Z
a1 -- unprotected: map of size 1
63 -- Key: 1 alg
78 35 63 -- x5c
81 -- Value: Array of length 1
59 03 02 -- Binary string of 770 bytes
30 82 02 fe 30 82 01 e6 a0 03 02 01 02 02 11 00
af ba 5c 63 66 e1 c1 59 95 91 4a 95 cd 26 cf c6
30 0d 06 09 2a 86 48 86 f7 0d 01 01 0b 05 00 30
14 31 12 30 10 06 03 55 04 03 0c 09 63 6f 73 65
5f 74 65 73 74 30 1e 17 0d 32 32 30 32 31 35 30
37 35 38 30 32 5a 17 0d 32 33 30 32 31 35 30 37
35 38 30 32 5a 30 14 31 12 30 10 06 03 55 04 03
0c 09 63 6f 73 65 5f 74 65 73 74 30 82 01 22 30
0d 06 09 2a 86 48 86 f7 0d 01 01 01 05 00 03 82
01 0f 00 30 82 01 0a 02 82 01 01 00 bf 6f 1b 78
b9 52 98 7a 31 74 00 92 6b 3e 83 4a 6e ce cc 9b
1d ac 3d fd 48 24 2a 0d f9 b6 d8 53 11 d2 67 af
14 03 3e e6 d6 06 28 88 17 ed 68 31 48 e2 d8 ab
dc 64 49 dd 00 a0 7d 68 e9 3f 7f 46 34 c5 81 ee
79 fb e0 a9 4a 65 ec 49 f5 2b 7a c8 8b d4 6c 82
85 d8 18 ad ff c8 f7 d6 3c 2b 03 08 b8 da a7 f3
c2 00 84 99 a8 0d cf ec e5 65 e1 a7 7c 5b 60 0d
4c 97 52 f5 f8 89 5e 3d e1 8b 17 8e 6d 2b d1 cf
be 7a 10 09 3c 7c 5f b6 2d e9 65 69 d1 61 19 65
c2 23 73 43 d0 70 58 47 b9 25 88 ce cf ce 91 f8
e4 fe fe d0 b3 e1 35 4a 89 09 6d d4 68 b1 74 c0
86 34 03 70 7b 9a 94 15 e3 33 13 4a de fb f5 24
7e de 07 70 05 4f 0d 50 f0 7f 78 22 b7 79 e9 be
e7 dc ae 7f be 0e 28 cc 1e 77 13 c2 9d 41 62 ad
63 67 49 95 c1 0a 28 ed 2e 1b fd 04 22 c3 96 8f
4c 36 88 2b 18 25 22 51 b2 19 d1 37 02 03 01 00
01 a3 4b 30 49 30 0e 06 03 55 1d 0f 01 01 ff 04
04 03 02 07 80 30 13 06 03 55 1d 25 04 0c 30 0a
06 08 2b 06 01 05 05 07 03 03 30 0c 06 03 55 1d
13 01 01 ff 04 02 30 00 30 14 06 03 55 1d 11 04
0d 30 0b 82 09 63 6f 73 65 5f 74 65 73 74 30 0d
06 09 2a 86 48 86 f7 0d 01 01 0b 05 00 03 82 01
01 00 9e 35 c0 3b f8 f3 85 fc 56 56 73 68 e7 bd
2d 13 76 3c a8 35 12 1e 5e 22 a6 d0 f4 a8 1b 44
a5 d9 eb c1 0c 88 0c cd bf f7 fe 70 4d 7c 6c 2e
eb 78 c2 51 18 77 de 92 35 7c 45 09 53 92 c1 2d
00 6e b9 cb 36 d2 0f 9a 8e 10 fe ea 2d e3 9e b4
35 8b 0d 23 ab a0 31 a0 67 4c 35 7d e8 36 7f a2
4f d1 2b 14 c3 f3 90 17 42 f2 b0 a1 f7 51 87 01
2e a7 a4 4b 44 14 48 38 eb a2 78 5f bc 43 43 aa
67 9f 3b bc 9a 3a 5d b3 04 26 78 6a 34 7c 22 be
a2 46 42 51 8a 3b fd b5 31 c1 2b ed 4a b7 8a a2
e4 5f 8d 55 2b 89 55 b7 de a2 20 09 93 da cf f8
6b b7 9d 85 ad c2 34 db ba fe fa 7f 55 4e 36 db
3f 67 16 8d a4 c4 e8 80 6b 9e 27 42 98 ea 7f 46
39 76 71 89 ba 28 52 90 64 03 18 0a 1e 38 41 06
b8 36 01 b6 55 f0 a4 e4 70 ba ee b6 0d 5a 09 4d
c8 52 47 78 0f c7 07 ed 42 0e c6 7f 84 1b 47 8a
87 b1
58 a2 -- payload: 162 bytes
7b 22 6d 65 64 69 61 54 79 70 65 22 3a 22 61 70 -- {"mediaType":"ap
70 6c 69 63 61 74 69 6f 6e 2f 76 6e 64 2e 64 6f -- plication/vnd.do
63 6b 65 72 2e 64 69 73 74 72 69 62 75 74 69 6f -- cker.distributio
6e 2e 6d 61 6e 69 66 65 73 74 2e 76 32 2b 6a 73 -- n.manifest.v2+js
6f 6e 22 2c 22 64 69 67 65 73 74 22 3a 22 73 68 -- on","digest":"sh
61 32 35 36 3a 65 37 64 38 38 64 65 37 33 64 62 -- a256:e7d88de73db
33 64 33 66 64 39 62 32 64 36 33 61 61 37 66 34 -- 3d3fd9b2d63aa7f4
34 37 61 31 30 66 64 30 32 32 30 62 37 63 62 66 -- 47a10fd0220b7cbf
33 39 38 30 33 63 38 30 33 66 32 61 66 39 62 61 -- 39803c803f2af9ba
32 35 36 62 33 22 2c 22 73 69 7a 65 22 3a 35 32 -- 256b3","size":52
38 7d -- 8}
59 01 00 -- signature: 256 bytes
3c e0 42 15 3c aa c5 8f 93 c4 43 e6 9d c8 8b 07
11 14 8f 5d 0b 82 a8 02 6c 44 82 2c 93 46 b6 c5
13 39 a3 e8 09 e0 b2 35 83 5e 11 04 41 96 5e 85
22 c2 fa 29 f4 71 be da 11 97 a9 35 e2 ef 85 07
c1 b1 b4 10 7a d2 5b 23 9f fa f0 c1 76 3b 8e 93
af e3 dd 1b bb 6c 19 71 1a 4b 2f 30 ce 65 4c b0
ee 7f 63 8a 06 1f d6 d4 1f f3 6c e8 f7 ea 0e b2
bf 66 e7 e7 6b 07 cf 25 2a be f0 73 d4 ab b6 7f
03 79 fa 47 87 a7 58 a4 6f 68 6a 39 2f 54 22 8a
4c 1e ad e7 a0 4e c6 16 14 bd bc 2f 7c 68 d9 3e
cb b3 8d 19 c6 4f 7e 11 13 d4 6c 78 55 c8 98 10
bc 98 f0 d3 ee a3 85 82 26 79 a5 df 2b c4 69 8a
56 44 4d 5d 41 6f ae 59 0a 34 8a ab 81 09 24 ba
4f e4 ad ad 11 d7 c0 67 7e 44 6e c8 c0 17 61 59
cd 8c f9 a2 1a 27 d6 63 5b 55 2f 53 6e e5 ba a4
94 04 1f ec 3b 8c 38 94 07 8a 5d d2 4a fa 44 eb
```

0 comments on commit 654e89e

Please sign in to comment.