update documentation (#9)

* update documentation Signed-off-by: Anja Strunk <[email protected]> * Fix markdown lint Signed-off-by: Anja Strunk <[email protected]> * Fix markdown lint Signed-off-by: Anja Strunk <[email protected]> * Fix markdown lint Signed-off-by: Anja Strunk <[email protected]> * Fix markdown lint Signed-off-by: Anja Strunk <[email protected]> * Fix markdown lint Signed-off-by: Anja Strunk <[email protected]> * Fix markdown lint Signed-off-by: Anja Strunk <[email protected]> * Add instructions for Gaia-X Signed-off-by: Anja Strunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> * Update README.md Signed-off-by: anjastrunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> * Add changes requested by reviewers Signed-off-by: Anja Strunk <[email protected]> * Fix markdown linter Signed-off-by: Anja Strunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> * Update README.md Co-authored-by: Markus Hentsch <[email protected]> Signed-off-by: anjastrunk <[email protected]> --------- Signed-off-by: Anja Strunk <[email protected]> Signed-off-by: anjastrunk <[email protected]> Co-authored-by: Markus Hentsch <[email protected]>
SovereignCloudStack · Aug 9, 2024 · c561946 · c561946
1 parent dc934a7
commit c561946
Showing 1 changed file with 87 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # scs-did-creator
 
-Tools for managing creation of [DID](https://www.w3.org/TR/did-core/) documents for SCS conformant clouds. Currently, scs-did-creator supports [did:web](https://w3c-ccg.github.io/did-method-web/) only.
+Tools for managing creation of [DID](https://www.w3.org/TR/did-core/) documents for SCS conformant clouds. Currently, scs-did-creator supports [did:web](https://w3c-ccg.github.io/did-method-web/) method only.
 
 ## Quick Start
 
@@ -18,11 +18,19 @@ pip install -r requirements.txt
 
 Bases on [DID specification](https://www.w3.org/TR/did-core/#dfn-did-documents): "...DID documents contain information associated with a DID. They typically express verification methods, such as cryptographic public keys, and services relevant to interactions with the DID subject..."
 
-In context of Gaia-X, DID document contains at least one verification method to verify authorship of Gaia-X Credentials. scs-did-creator supports [RSA keys](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) and [EC keys](https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) as verification methods, only. If not already exist, create a public-private key pair with [OpenSSL](https://developers.yubico.com/PIV/Guides/Generating_keys_using_OpenSSL.html)
+There a several types of verification methods, such as [JsonWebKey2020](https://w3c-ccg.github.io/lds-jws2020/#json-web-key-2020) (JWK) or [EcdsaSecp256k1VerificationKey2019](https://w3c-ccg.github.io/lds-ecdsa-secp256k1-2019/). A complete list of supported types can be found in [DID Spec Registry](https://www.w3.org/TR/did-spec-registries/).
+
+**Note**: scs-did-creator supports JWK, only.
+
+Public-Private JWK key pairs can be generated by different cryptographic algorithms.
+
+**Note**: scs-did-creator supports [RSA keys](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) and [EC keys](https://en.wikipedia.org/wiki/Elliptic-curve_cryptography), only.
+
+You need at least one private-public key pair to generate a DID document. If you do not have one, create a public-private key pair with [OpenSSL](https://developers.yubico.com/PIV/Guides/Generating_keys_using_OpenSSL.html).
 
 ### Configure scs-did-creator
 
-Mandatory content for DID document such as issuer and verification methods are taken from `config.yaml`.
+Mandatory content for the DID document is taken from `config.yaml`.
 
 ```yaml
 issuer: "did:web:example.com"
@@ -35,19 +43,88 @@ verification-methods:
     - "https://www.example.com/cert2.pem" 
 ```
 
-Attribute `issuer` defines issuer of DID document, which is the DID itself. scs-did-creator does support did:web only.
-Attribute `verification-methods` refers to a list of public key files or x509 certificates, set as verification method in generated DID document. A public key file must be set as absolute path, an x509 certificate can be an URL or an absolute file path.
-Currently, all verification methods are set as `assertionMethod`, i.e. used to verify [Verifiable Credentials](https://www.w3.org/TR/vc-data-model-2.0/) issued by `issuer`.
+The following attributes MUST be set:
+
+- `issuer`: Issuer of DID document, which is the DID itself.
+- `verification-methods`: List of public keys used as verification methods in DID document to be generated. scs-did-creator sets JWK as verification method. JWK is formatted according to [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517#section-4) as verification method only. At least one verification method MUST be set:
+
+  - `keys` entry: Absolute file path to private key file. Using this setting adds JWK as verification method expressed by parameters `n` and `e`, only
+  - `x509s` entry: Either file path or URL to X.509 certificate chain. The generator uses the public key represented by the first certificate in the chain as verification method. Specifying a certificate via file path adds the [`x5c`](https://datatracker.ietf.org/doc/html/rfc7517#section-4.7), using an URL adds the [`x5u`](https://datatracker.ietf.org/doc/html/rfc7517#section-4.6) parameter to the JWK format.
+
+**Note**: To produce a DID document compatible with the Compliance API of the Gaia-X Digital Clearing House (GXDCH), specify a single `x509s` entry using a publicly accessible URL pointing to a valid certificate chain and omit any `keys` entries.
+
+**Note**: Each entry in `verification-method` will add an additional verification method to the DID document. E.g., the following configuration file will result in a DID document with two verification methods.
+
+```yaml
+issuer: "did:web:example.com"
+verification-methods:
+  keys:
+    - "/example1.pem.pub"
+  x509s:
+    - "https://www.example.com/cert2.pem" 
+```
+
+```json
+
+{
+  "@context": [
+    "https://www.w3.org/ns/did/v1",
+    "https://w3id.org/security/suites/jws-2020/v1"
+  ],
+  "id": "did:web:example.com",
+  "verificationMethod": [
+    {
+      "@context": "https://w3c-ccg.github.io/lds-jws2020/contexts/v1/",
+      "id": "did:did:web:example.com#JWK2020-RSA-0",
+      "type": "JsonWebKey2020",
+      "controller": "did:did:web:example.com",
+      "publicKeyJwk": {
+        "kty": "RSA",
+        "kid": "q7Br89MDU0pbnBELpEwMHuy8KmOZXoZLIVb3gVGN9So",
+        "n": "l2p0GOipSrw8CPOxPfRUohkB_ritC4wwNsH1A8eilZ1ntEfjCFsuxGutoEFXq8ge5dyvmmeZu5Ezt2crTJbS55_OFAeepsPIyO_O3JHJNtp5aNOv-0bJUVc5_6xLC5ucLUYtj5tzRimiaP5AM-uZCqIpG5VV8ELT1-HTaW9Bj-Ruajwm0MplGK3lZlpt1FAM7Rp4OAHyMiHDimw8X4qwgFIaj28YZqyIkB04Yc-jhl7_lHB0WRfVN---Lj9J-vCgKIfvCYlKWIwGgIr5FuElDnGv3uNFnTlcruWtBG0JzV8PLWJ0AGeWZWYsSca41Df9BvqVY24qi9JUH89FNqMnc_mNlX-G-49ap0c4L-kEQ6jCO3_tsqYsIMRWiuPeZ49d8o7kYZasXPuAvqLXCJK4BBGnXcBiqvfyrazWe0Yz_jC9MxdqXyakEf2RWmaPtna9JVH-Lx8eSHcvrX5FOSz2fPEwC_FCfM9gpO8TnUTq93gcXWuJtswChCryAtlmF3lC4DFdgzJxnqesrS1x0J2rqOl2anpQRCUa5m3om3y0gqQ3_XYqK1ezDbP3pRkeuwSS2e4HEPEZM6-euAK0G6TKA-EIO1Igb1F_EqeV_cOw5Jjxljj9IGzKrCZ4qXZX30sG0aMeCgGvreU2jGIDJzNrY7lM1SgXOFKffluI7nrvOzk",
+        "e": "AQAB"
+      }
+    },
+    {
+      "@context": "https://w3c-ccg.github.io/lds-jws2020/contexts/v1/",
+      "id": "did:did:web:example.com#JWK2020-X509-1",
+      "type": "JsonWebKey2020",
+      "controller": "did:web:example.com",
+      "publicKeyJwk": {
+        "kty": "RSA",
+        "kid": "q7Br89MDU0pbnBELpEwMHuy8KmOZXoZLIVb3gVGN9So",
+        "n": "l2p0GOipSrw8CPOxPfRUohkB_ritC4wwNsH1A8eilZ1ntEfjCFsuxGutoEFXq8ge5dyvmmeZu5Ezt2crTJbS55_OFAeepsPIyO_O3JHJNtp5aNOv-0bJUVc5_6xLC5ucLUYtj5tzRimiaP5AM-uZCqIpG5VV8ELT1-HTaW9Bj-Ruajwm0MplGK3lZlpt1FAM7Rp4OAHyMiHDimw8X4qwgFIaj28YZqyIkB04Yc-jhl7_lHB0WRfVN---Lj9J-vCgKIfvCYlKWIwGgIr5FuElDnGv3uNFnTlcruWtBG0JzV8PLWJ0AGeWZWYsSca41Df9BvqVY24qi9JUH89FNqMnc_mNlX-G-49ap0c4L-kEQ6jCO3_tsqYsIMRWiuPeZ49d8o7kYZasXPuAvqLXCJK4BBGnXcBiqvfyrazWe0Yz_jC9MxdqXyakEf2RWmaPtna9JVH-Lx8eSHcvrX5FOSz2fPEwC_FCfM9gpO8TnUTq93gcXWuJtswChCryAtlmF3lC4DFdgzJxnqesrS1x0J2rqOl2anpQRCUa5m3om3y0gqQ3_XYqK1ezDbP3pRkeuwSS2e4HEPEZM6-euAK0G6TKA-EIO1Igb1F_EqeV_cOw5Jjxljj9IGzKrCZ4qXZX30sG0aMeCgGvreU2jGIDJzNrY7lM1SgXOFKffluI7nrvOzk",
+        "e": "AQAB",
+        "alg": "RS256",
+        "x5u": "https://www.example.com/cert2.pem" 
+      }
+    }
+  ],
+  "assertionMethod": [
+    "did:web:gaia-x.cloudandheat.com#JWK2020-RSA-0",
+    "did:web:gaia-x.cloudandheat.com#JWK2020-X509-1"
+  ]
+}
+```
+
+Gaia-X requires JWK as x.509 certificate. If you use scs-did-generator to create Gaia-X compliant DID documents, you have to use the parameter `x509s` with a single x.509 certificate entry referenced by URL.
+
+```yaml
+issuer: "did:web:example.com"
+verification-methods:
+  x509s:
+    - "https://www.example.com/cert2.pem" 
+```
 
 ### Run scs-did-creator
 
-Run scs-did-creator with configuration file, implicitly.
+Running the scs-did-creator without specifying a configuration file. This implies the default path at `/etc/scs-did-gen/config.yaml`, which must exist:
 
 ```shell
 python3 -m creator.cli
 ```
 
-Run scs-did-creator with own configuration file
+Running the scs-did-creator with a specified configuration file path:
 
 ```shell
 python3 -m creator.cli --config=my-config.template.yaml
@@ -61,17 +138,15 @@ python3 -m creator.cli --output-file=my-did-document.json
 
 ## Developers Guide
 
-scs-did-creator uses [jinja templates](https://jinja.palletsprojects.com/en/3.1.x/) to generate DID documents.
-
 ### Running unit tests
 
-First, install the test dependencies in addition to the main dependencies into your virtualenv as described above under "Quick Start Guide":
+Install test dependencies in addition to the main dependencies into your virtualenv as described above under "Quick Start Guide":
 
 ```shell
 pip install -r test-requirements.txt
 ```
 
-Then, tests can be run with:
+Run tests:
 
 ```shell
 python3 -m pytest