diff --git a/README.md b/README.md index 659b101..7bf7d11 100644 --- 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