Merge pull request #672 from w3c-ccg/mahmoud_review

cleanup spec text, update links, example, and references
w3c-ccg · Sep 19, 2024 · bb918e9 · bb918e9
2 parents 2ef9298 + 5d2e9d8
commit bb918e9
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 39 deletions.
diff --git a/docs/spec/index.html b/docs/spec/index.html
@@ -236,8 +236,8 @@
     </p>
 
     <p>
-      To contribute to this vocabulary or reference technical details related to
-      the project, please reference the
+      To contribute to this specification or reference technical details related to
+      the project, please refer to the
       primary README located on
       <a href="https://w3id.org/traceability/interoperability/">GitHub</a>.
     </p>
@@ -345,24 +345,26 @@ <h2>Rules for Processing Data</h2>
       informational processing.
     </p>
     <section class="normative">
-      <h2>Identifiers</h2>
-      <p>
-        Identifiers in objects exchanged using this specification are
-        particularly important, not least in that they uniquely identify
-        an object or network transaction, but also, given the
-        asynchronous nature of this mode of data exchange, that they
-        present an area where various attacks could arise by sending
-        data with identifiers already in use with malicious intent to
-        confuse a receiver of the data.
-      </p>
-      <p>
-        Identifiers conformant with this spec <em>MUST</em> be
-        [[rfc3986]] conformant URIs. Unless otherwise noted, an
-        identifier <em>MAY</em> be a DID identifier per [[did-core]], a
-        UUID v4 per [[rfc4122]], or a [[URL]] that identifies a resource
-        directly.
-      </p>
-      <section class="normative">
+        <section class="normative">
+          <h2>Identifiers</h2>
+          <p>
+            Identifiers in objects exchanged using this specification are
+            particularly important, not least in that they uniquely identify
+            an object or network transaction, but also, given the
+            asynchronous nature of this mode of data exchange, in that they
+            present an area where various attacks could be made by sending
+            data with identifiers already in use with malicious intent to
+            confuse a receiver of the data.
+          </p>
+          <p>
+            Identifiers conformant with this specification <em>MUST</em> be
+            [[rfc3986]] conformant URIs. Unless otherwise noted, an
+            identifier <em>MAY</em> be a DID identifier per [[did-core]], a
+            UUID v4 per [[rfc4122]], or a [[URL]] that identifies a resource
+            directly.
+          </p>
+        </section>
+        <section class="normative">
         <h2>Presentations</h2>
         <p>
           Presentations in this spec are
@@ -495,12 +497,12 @@ <h2>General Guidelines</h2>
         As a rule, systems conforming with this specification <em>SHOULD</em>
         leverage and comply with encryption and security guidelines as
         listed in:
-        <a href="https://csrc.nist.gov/publications/detail/fips/186/5/draft"
-          rel="nofollow">FIPS 186-5 (DRAFT)</a>,
+        <a href="https://csrc.nist.gov/pubs/fips/186-5/final"
+          rel="nofollow">FIPS 186-5 Digital Signature Standard (DSS)</a>,
         <a href="https://csrc.nist.gov/publications/detail/fips/180/4/final"
-          rel="nofollow">FIPS 180-4</a>, and
+          rel="nofollow">FIPS 180-4 Secure Hash Standard (SHS)</a>, and
         <a href="https://csrc.nist.gov/publications/detail/fips/197/final"
-          rel="nofollow">FIPS 197</a>. This
+          rel="nofollow">FIPS 197 Advanced Encryption Standard (AES)</a>. This
         effectively means that committers should be thinking along the lines of
         P256 versus other competing
         algorithms.
@@ -530,7 +532,7 @@ <h2>Encryption in Transport</h2>
         interoperability
         <em>MUST</em> utilize TLS and comply with
         <a
-          href="https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-52r2.pdf">
+          href="https://csrc.nist.gov/pubs/sp/800/52/r2/final">
           NIST SP 800-52 rev2</a>
         or superseding publications for configuration and use of TLS in
         transport of data over API or web endpoints.

diff --git a/docs/spec/sections/use-case-requirements.html b/docs/spec/sections/use-case-requirements.html
@@ -67,11 +67,6 @@ <h4>Identifier Discovery</h4>
 necessary to complete integration tests in postman with authentication.
 </p>
 
-<p>
-The current APIs exploit the well known DID configuration,
-which has some limitations, most notably regarding multi-tenant platforms.
-</p>
-
 <section>
 <h5>Integration Considerations</h5>
 <p>
@@ -221,16 +216,18 @@ <h5>verificationMethod</h5>
       "did:web:platform.example:organization:123#key1"
     ],
     "verificationMethod": [
-        {
-            "id": "did:web:platform.example:organization:123#key1",
-            "type": "JsonWebKey2020",
-            "controller": "did:web:platform.example:organization:123",
-            "publicKeyJwk": {
-                "kty": "OKP",
-                "crv": "Ed25519",
-                "x": "rfsiofZ3RcuMWZSoYbvNEZ_8oxeep8uapJDyT0ku8EM"
-            }
+      {
+        "id": "https://university.example/issuers/565049#key-123",
+        "type": "JsonWebKey",
+        "controller": "https://university.example/issuers/565049",
+        "publicKeyJwk": {
+          "kty": "EC",
+          "crv": "P-384",
+          "alg": "ES384",
+          "x": "PxgAmVYOQvSNcMYL2tOzoLwSWn4Ta3tIMPEUKR8pxeb-gmR11-DyKHBoIiY-2LhM",
+          "y": "BZEBTkImVdpwvxR9THIRw16eblnj5-tZa7m-ww5uVd4kyPJNRoWUn2aT9ZuarAe-"
         }
+      }
     ],
     "service": [
       {