From 7f55380b30722d3f5309af7d4bb490f2b76c3f39 Mon Sep 17 00:00:00 2001 From: Gabe <7622243+decentralgabe@users.noreply.github.com> Date: Wed, 9 Oct 2024 14:55:09 -0700 Subject: [PATCH] Update README.md --- tests/README.md | 220 ++++++++++++++++++------------------------------ 1 file changed, 80 insertions(+), 140 deletions(-) diff --git a/tests/README.md b/tests/README.md index 61e5d1b..87c6f6d 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,141 +1,81 @@ -# Normative Statements from VC JOSE COSE Specification - -## 1. Securing with JOSE - -1. A conforming JWS issuer implementation MUST use [[RFC7515]] to secure this media type. -2. The `typ` header parameter SHOULD be `vc-ld+jwt`. -3. When present, the `cty` header parameter SHOULD be `vc`. -4. A conforming JWS verifier implementation MUST use [[RFC7515]] to verify conforming JWS documents that use this media - type. -5. The `typ` header parameter SHOULD be `vp-ld+jwt` (for verifiable presentations). -6. When present, the `cty` header parameter SHOULD be `vp` (for verifiable presentations). -7. Verifiable Credentials secured in verifiable presentations MUST use the Enveloped Verifiable Credential type defined - by the [[VC-DATA-MODEL-2.0]]. -8. Verifiable Presentations in verifiable presentations MUST use the Enveloped Verifiable Presentation type defined by - the [[VC-DATA-MODEL-2.0]]. +# Test Cases + +## JWT (JOSE) Section + +### For Verifiable Credentials + +1. A conforming JWS issuer implementation MUST use RFC7515 to secure this media type. +2. A conforming JWS verifier implementation MUST use RFC7515 to verify conforming JWS documents that use this media type. +3. Issuers, Holders, and Verifiers MUST ignore all JWT Claims Sets that have no integrity protection. +4. The JWT Claim Names `vc` and `vp` MUST NOT be present in any JWT Claims Set that comprises a verifiable credential. + +### For Verifiable Presentations + +5. A conforming JWS issuer implementation MUST use RFC7515 to secure this media type. +6. A conforming JWS verifier implementation MUST use RFC7515 to verify conforming JWS documents that use this media type. +7. Verifiable Credentials secured in verifiable presentations MUST use the Enveloped Verifiable Credential type defined by the VC-DATA-MODEL-2.0. +8. Verifiable Presentations in verifiable presentations MUST use the Enveloped Verifiable Presentation type defined by the VC-DATA-MODEL-2.0. 9. Credentials in verifiable presentations MUST be secured. -10. Implementations MUST support the JWS compact serialization. -11. Use of the JWS JSON serialization is NOT RECOMMENDED. - -## 2. JOSE Header Parameters and JWT Claims - -12. When present in the JOSE Header or the JWT Claims Set, members registered in the IANA JSON Web Token Claims registry - or the IANA JSON Web Signature and Encryption Header Parameters registry are to be interpreted as defined by the - specifications referenced in the registries. -13. The unencoded JOSE Header is JSON (`application/json`), not JSON-LD (`application/ld+json`). -14. It is RECOMMENDED to use the IANA JSON Web Token Claims registry and the IANA JSON Web Signature and Encryption - Header Parameters registry to identify any claims and header parameters that might be confused with members defined - by [[VC-DATA-MODEL-2.0]]. -15. Implementers SHOULD avoid setting JWT claims to values that conflict with the values of verifiable credential - properties when a claim and property pair refer to the same conceptual entity. -16. The JWT Claim Names `vc` and `vp` MUST NOT be present. -17. Additional members may be present as header parameters and claims. If they are not understood, they MUST be ignored. - -## 3. Securing with SD-JWT - -18. A conforming SD-JWT issuer implementation MUST use [[SD-JWT]] to secure this media type. -19. The `typ` header parameter SHOULD be `vc-ld+sd-jwt`. -20. When present, the `cty` header parameter SHOULD be `vc`. -21. A conforming SD-JWT verifier implementation MUST use [[SD-JWT]] to verify conforming JWS documents that use this - media type. -22. The `typ` header parameter SHOULD be `vp-ld+sd-jwt` (for verifiable presentations). -23. When present, the `cty` header parameter SHOULD be `vp` (for verifiable presentations). -24. Verifiable Credentials secured in verifiable presentations MUST use the Enveloped Verifiable Credential type defined - by the [[VC-DATA-MODEL-2.0]]. -25. Verifiable Presentations in verifiable presentations MUST use the Enveloped Verifiable Presentation type defined by - the [[VC-DATA-MODEL-2.0]]. -26. Credentials in verifiable presentations MUST be secured. -27. Implementations MUST support the compact serialization (`application/sd-jwt`). -28. Implementations MAY support the JSON serialization (`application/sd-jwt+json`). - -## 4. Securing with COSE - -29. A conforming COSE issuer implementation MUST use COSE_Sign1 as specified in [[RFC9052]] to secure this media type. -30. The `typ` header parameter SHOULD be `application/vc-ld+cose`. -31. When present, the `content type (3)` header parameter SHOULD be `application/vc`. -32. A conforming COSE verifier implementation MUST use COSE_Sign1 as specified in [[RFC9052]] to verify conforming COSE - documents that use this media type. -33. The `typ` header parameter SHOULD be `application/vp-ld+cose` (for verifiable presentations). -34. When present, the `cty` header parameter SHOULD be `application/vp` (for verifiable presentations). -35. Verifiable Credentials secured in verifiable presentations MUST use the Enveloped Verifiable Credential type defined - by the [[VC-DATA-MODEL-2.0]]. -36. Verifiable Presentations in verifiable presentations MUST use the Enveloped Verifiable Presentation type defined by - the [[VC-DATA-MODEL-2.0]]. -37. Credentials in verifiable presentations MUST be secured. - -## 5. Key Discovery - -38. When `iss` is absent and the issuer is identified as a DID Subject, the `kid` MUST be an absolute DID URL. -39. When `iss` is absent, and the holder is identified as a DID Subject, the `kid` MUST be an absolute DID URL. -40. When `iss` is absent, and the issuer is identified as a [[URL]], the `kid` MUST be an absolute [[URL]] to a - verification method listed in a controller document. -41. When the holder is identified as a [[URL]], and `iss` is absent, the `kid` MUST be an absolute [[URL]] to a - verification method listed in a controller document. -42. When `iss` is present and is a [[URL]], the `kid` MUST match a key discovered via a JWT Issuer Metadata Request, as - described in [[SD-JWT-VC]]. -43. `kid` MUST be present when the key of the issuer or subject is expressed as a DID URL. -44. When issuer value is a string, `iss` value, if present, MUST match issuer value. -45. When issuer value is an object with an `id` value, `iss` value, if present, MUST match `issuer.id` value. - -## 6. Verification Methods - -46. The `verificationMethod` property is OPTIONAL. If present, its value MUST be a set of verification methods, where - each verification method is expressed using a map. -47. The verification method map MUST include the `id`, `type`, `controller`, and specific verification material - properties that are determined by the value of `type`. -48. The value of the `id` property for a verification method MUST be a string that conforms to the [[URL]] syntax. -49. The value of the `type` property MUST be a string that references exactly one verification method type. -50. The value of the `controller` property MUST be a string that conforms to the [[URL]] syntax. -51. The `revoked` property is OPTIONAL. If present, its value MUST be an [[XMLSCHEMA11-2]] combined date and time string - specifying when the verification method SHOULD cease to be used. -52. A verification method MUST NOT contain multiple verification material properties for the same material. - -## 7. Verification Relationships - -53. The `authentication` property is OPTIONAL. If present, its value MUST be a set of one or more verification methods. - Each verification method MAY be embedded or referenced. -54. The `assertionMethod` property is OPTIONAL. If present, its value MUST be a set of one or more verification methods. - Each verification method MAY be embedded or referenced. - -## 8. Conformance Classes - -55. A conforming JWS document is one that conforms to all of the "MUST" statements in Section "Secure with JOSE". -56. A conforming JWS issuer implementation produces conforming JWS documents and MUST secure them as described in - Section "Secure with JOSE". -57. A conforming JWS verifier implementation verifies conforming JWS documents as described in Section "Secure with - JOSE". -58. A conforming SD-JWT document is one that conforms to all of the "MUST" statements in Section "Secure with SD-JWT". -59. A conforming SD-JWT issuer implementation produces conforming SD-JWT documents and MUST secure them as described in - Section "Secure with SD-JWT". -60. A conforming SD-JWT verifier implementation verifies conforming SD-JWT documents as described in Section "Secure - with SD-JWT". -61. A conforming COSE document is one that conforms to all of the "MUST" statements in Section "Secure with COSE". -62. A conforming COSE issuer implementation produces conforming COSE documents and MUST secure them as described in - Section "Secure with COSE". -63. A conforming COSE verifier implementation verifies conforming COSE documents as described in Section "Secure with - COSE". - -## 9. Securing Verifiable Credentials - -64. If implementations do not know which media type to use, media types defined in this specification MUST be used. -65. Accordingly, Issuers, Holders, and Verifiers MUST understand the JSON Web Token header parameter `"alg": "none"` - when securing [[VC-DATA-MODEL-2.0]] with JSON Web Tokens. -66. When content types from [[VC-DATA-MODEL-2.0]] are secured using JSON Web Tokens, the header parameter - `"alg": "none"`, MUST be used to communicate that a JWT Claims Set (a Verifiable Credential or a Verifiable - Presentation) has no integrity protection. -67. When a JWT Claims Set (a Verifiable Credential or a Verifiable Presentation) contains `proof`, and the JSON Web - Token header contains `"alg": "none"`, the JWT Claims Set MUST be considered to have no integrity protection. -68. Issuers, Holders, and Verifiers MUST ignore all JWT Claims Sets that have no integrity protection. -69. The JWT Claim Names `vc` and `vp` MUST NOT be present in any JWT Claims Set. - -## 10. Validation Algorithm - -70. All claims expected for the `typ` MUST be present. -71. All claims that are understood MUST be evaluated according the verifier's validation policies. -72. All claims that are not understood MUST be ignored. -73. The verified `document` returned from verification MUST be a well-formed compact JSON-LD document, as described in - Verifiable Credentials Data Model v2.0. -74. Schema extension mechanisms such as `credentialSchema` SHOULD be checked. -75. If the extension mechanism `type` is not understood, this property MUST be ignored. -76. Status extension mechanisms such as `credentialStatus` SHOULD be checked. -77. If the extension mechanism `type` is not understood, this property MUST be ignored. + +## SD-JWT Section + +### For Verifiable Credentials + +10. A conforming SD-JWT issuer implementation MUST use SD-JWT to secure this media type. +11. A conforming SD-JWT verifier implementation MUST use SD-JWT to verify conforming JWS documents that use this media type. + +### For Verifiable Presentations + +12. A conforming SD-JWT issuer implementation MUST use SD-JWT to secure this media type. +13. A conforming SD-JWT verifier implementation MUST use SD-JWT to verify conforming JWS documents that use this media type. +14. Verifiable Credentials secured in verifiable presentations MUST use the Enveloped Verifiable Credential type defined by the VC-DATA-MODEL-2.0. +15. Verifiable Presentations in verifiable presentations MUST use the Enveloped Verifiable Presentation type defined by the VC-DATA-MODEL-2.0. +16. Credentials in verifiable presentations MUST be secured. + +## COSE Section + +### For Verifiable Credentials + +17. A conforming COSE issuer implementation MUST use COSE_Sign1 as specified in RFC9052 to secure this media type. +18. A conforming COSE verifier implementation MUST use COSE_Sign1 as specified in RFC9052 to verify conforming COSE documents that use this media type. +19. When including verifiable credentials secured with COSE in verifiable presentations as Enveloped Verifiable Credentials, the credentials MUST be encoded using base64 as specified in RFC2397. + +### For Verifiable Presentations + +20. A conforming COSE issuer implementation MUST use COSE_Sign1 as specified in RFC9052 to secure this media type. +21. A conforming COSE verifier implementation MUST use COSE_Sign1 as specified in RFC9052 to verify conforming COSE documents that use this media type. +22. Verifiable Credentials secured in verifiable presentations MUST use the Enveloped Verifiable Credential type defined by the VC-DATA-MODEL-2.0. +23. Verifiable Presentations in verifiable presentations MUST use the Enveloped Verifiable Presentation type defined by the VC-DATA-MODEL-2.0. +24. Credentials in verifiable presentations MUST be secured. + +## Additional Requirements + +25. If `kid` is present when the key of the issuer or subject is expressed as a DID URL, it MUST be present. +26. If implementations do not know which media type to use, media types defined in this specification MUST be used. +27. A conforming JWS document MUST conform to all of the "MUST" statements in Section 3.1 With JOSE. +28. A conforming SD-JWT document MUST conform to all of the "MUST" statements in Section 3.2 With SD-JWT. +29. A conforming COSE document MUST conform to all of the "MUST" statements in Section 3.3 With COSE. +30. When the issuer value is a string, iss value, if present, MUST match issuer value. +31. When issuer value is an object with an id value, iss value, if present, MUST match issuer.id value. +32. Additional members may be present as header parameters and claims. If they are not understood, they MUST be ignored. +33. When iss is absent, and the issuer is identified as a URL, the kid MUST be an absolute URL to a verification method listed in a controller document or a DID Document. +34. When the holder is identified as a URL, and iss is absent, the kid MUST be an absolute URL to a verification method listed in a controller document. +35. All claims expected for the typ MUST be present. +36. All claims that are understood MUST be evaluated according the verifier's validation policies. +37. All claims that are not understood MUST be ignored. +38. The verified document returned from verification MUST be a well-formed compact JSON-LD document, as described in Verifiable Credentials Data Model v2.0. +39. If the extension mechanism type is not understood, this property MUST be ignored (for both credentialSchema and credentialStatus). +40. Implementations MUST support the JWS compact serialization. +41. Implementations MUST support the SD-JWT compact serialization (`application/sd-jwt`). + +## Should Statements (to be tested as warnings or recommendations) + +42. The `typ` header parameter SHOULD be `vc+jwt` for VCs and `vp+jwt` for VPs. When present, the `cty` header parameter SHOULD be `vc` for VCs and `vp` for VPs. +43. For COSE, the `typ` header parameter SHOULD be `application/vc+cose` for VCs and `application/vp+cose` for VPs. When present, the `content type (3)` header parameter SHOULD be `application/vc` for VCs and `application/vp` for VPs. +44. When securing verifiable credentials with SD-JWT, implementers SHOULD ensure that properties necessary for the validation and verification of a credential are NOT selectively disclosable (i.e., such properties SHOULD be disclosed). +45. The most specific media type (or subtype) available SHOULD be used, instead of more generic media types (or supertypes). +46. Verifiers SHOULD strive to minimize the processing of untrusted data. +47. After verification has succeeded, additional validation checks SHOULD be performed as described in Section 5.4 Validation. +48. Schema extension mechanisms such as `credentialSchema` SHOULD be checked. +49. Status extension mechanisms such as `credentialStatus` SHOULD be checked. +50. When using URL identifiers, the kid is RECOMMENDED to be an absolute URL that includes a JWK Thumbprint U