From 654e89e67fa294f8e5a6ae8fc394819f7091cc86 Mon Sep 17 00:00:00 2001 From: Shiwei Zhang Date: Tue, 15 Feb 2022 19:35:24 +0800 Subject: [PATCH] update readme Signed-off-by: Shiwei Zhang --- .gitignore | 1 + Makefile | 1 + README.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 221 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 66fd13c..e7c16df 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ *.dll *.so *.dylib +bin/ # Test binary, built with `go test -c` *.test diff --git a/Makefile b/Makefile index 610f0a3..69d7c31 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/README.md b/README.md index e63e84b..dd53121 100644 --- a/README.md +++ b/README.md @@ -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 +```