Self-Description-Signer

How To Use
How it Works
Environment variables for self-issued certificates (This is for test-setups only)

How To Use

Update the self description in self-description.json, replace it with your own. See details in the Architecture Document
Create a new .env file in the /config directory with PRIVATE_KEY, CERTIFICATE, CONTROLLER, VERIFICATION_METHOD and X5U_URL as properties. Feel free to use the example file example.env located in the /config directory. You could quickly copy the file with the following command:
```
cp config/example.env config/.env
```
Make sure to provide your own values for the above mentioned properties in the newly created .env file.

IMPORTANT: You need to create your own CERTIFICATE and PRIVATE_KEY and put it into the created /config/.env file. This certificate needs to be issued by a Gaia-X endorsed trust anchor. You can find the list of endorsed trust anchors here: https://gaia-x.gitlab.io/policy-rules-committee/trust-framework/trust_anchors/

NOTE: It is not sufficient to simply create create a new local key pair which is not issued by a trust anchor because verification will fail and the trust servcie won't sign your Self Description!
You can find more information on setting up your own certificate here:
- https://gitlab.com/gaia-x/lab/compliance/gx-compliance#how-to-setup-certificates
X5U_URL - You need to generate a .pem file with the certificate chain of your certificate and upload it to your server (make it accessible via URI). You can find an example here: https://www.delta-dao.com/.well-known/x509CertificateChain.pem

You can use whatsmychaincert.com as a helper tool to generate your certificate chain using metadata from your certificate. Make sure to check "Include Root Certificate" checkbox.

VERIFICATION_METHOD - The did:web has to resolve to the path of your did.json. It defaults to your-domain.com/.well-known/did.json if you enter did:web:your-domain.com. You can also specify a specific path, check the did:web specifications for this.

More info on x5u: https://www.rfc-editor.org/rfc/rfc7517#section-4.6
Install dependencies npm i and execute the script node index.js (node@16 or higher required).
- Alternatively, the script can be run with docker
  1. Build the container with docker build -t self-description-signer .
  2. Run the script with docker run -it --mount src="$(pwd)/config",target=/usr/src/app/config,type=bind self-description-signer

The given self description will be locally signed and a new file containing self description + proof called {timestamp}_self-signed_{gx-type}.json will be created.

Example self-signed Self Description:

{
  "selfDescriptionCredential": {
     "@context": [
         "https://www.w3.org/2018/credentials/v1",
         "https://registry.gaia-x.eu/v2206/api/shape"
     ],
     "type": [
         "VerifiableCredential",
         "LegalPerson"
     ],
     "id": "https://compliance.gaia-x.eu/.well-known/participant.json",
     "issuer": "did:web:compliance.gaia-x.eu",
     "issuanceDate": "2022-09-23T23:23:23.235Z",
     "credentialSubject": {
         "id": "did:web:compliance.gaia-x.eu",
         "gx-participant:name": "Gaia-X AISBL",
         "gx-participant:legalName": "Gaia-X European Association for Data and Cloud AISBL",
         "gx-participant:registrationNumber": {
             "gx-participant:registrationNumberType": "local",
             "gx-participant:registrationNumberNumber": "0762747721"
         },
         "gx-participant:headquarterAddress": {
             "gx-participant:addressCountryCode": "BE",
             "gx-participant:addressCode": "BE-BRU",
             "gx-participant:streetAddress": "Avenue des Arts 6-9",
             "gx-participant:postalCode": "1210"
         },
         "gx-participant:legalAddress": {
             "gx-participant:addressCountryCode": "BE",
             "gx-participant:addressCode": "BE-BRU",
             "gx-participant:streetAddress": "Avenue des Arts 6-9",
             "gx-participant:postalCode": "1210"
         },
         "gx-participant:termsAndConditions": "70c1d713215f95191a11d38fe2341faed27d19e083917bc8732ca4fea4976700"
     },
     "proof": {
         "type": "JsonWebSignature2020",
         "created": "2022-10-01T13:02:09.771Z",
         "proofPurpose": "assertionMethod",
         "verificationMethod": "did:web:compliance.gaia-x.eu",
         "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..XQqRvvuxW1xHUy_eRzOk4LwyjwlRofg0JBiO0nrWGHAjwMA87OVJ37mB6GylgEttEaUjXQV-QmbGfEnE-YQf5S7B-id9Lld-CC-vW8M-2EvXh3oQp3l5W35mvvdVQXBj16LLskQZpfZGRHM0hn7zGEw24fDc_tLaGoNR9LQ6UzmSrHMwFFVWz6XH3RoG-UY0aZDpnAxjpWxUWaa_Jzf65bfNlx2EdSv3kIKKYJLUlQTk0meuFDD23VrkGStQTGQ8GijY3BNo6QWw889tt5YKWtiSZjbDYYHsVCwMzPoKT0hVJ1wy2ve6pJ4MSYfhiMxoDq6YBOm-oYKYfBeN22fjqQ"
     }
}

In addition, a did.json will be created based on the provided CERTIFICATE and VERIFICATION_METHOD

Example did.json:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:compliance.gaia-x.eu",
  "verificationMethod": [
    {
      "@context": "https://w3c-ccg.github.io/lds-jws2020/contexts/v1/",
      "id": "did:web:compliance.gaia-x.eu",
      "type": "JsonWebKey2020",
      "controller": "did:web:compliance.gaia-x.eu#JWK2020-RSA",
      "publicKeyJwk": {
        "kty": "RSA",
        "n": "ulmXEa0nehbR338h6QaWLjMqfXE7mKA9PXoC_6_8d26xKQuBKAXa5k0uHhzQfNlAlxO-IpCDgf9cVzxIP-tkkefsjrXc8uvkdKNK6TY9kUxgUnOviiOLpHe88FB5dMTH6KUUGkjiPfq3P0F9fXHDEoQkGSpWui7eD897qSEdXFre_086ns3I8hSVCxoxlW9guXa_sRISIawCKT4UA3ZUKYyjtu0xRy7mRxNFh2wH0iSTQfqf4DWUUThX3S-jeRCRxqOGQdQlZoHym2pynJ1IYiiIOMO9L2IQrQl35kx94LGHiF8r8CRpLrgYXTVd9U17-nglrUmJmryECxW-555ppQ",
        "e": "AQAB",
        "alg": "PS256",
        "x5u": "https://compliance.gaia-x.eu/.well-known/x509CertificateChain.pem"
      }
    }
  ],
  "assertionMethod": ["did:web:compliance.gaia-x.eu#JWK2020-RSA"]
}

Upload this did.json to your domain (e.g. https://your_domain.com/.well-known/did.json).

After uploading the did.json(important) re-run the script and finally, the compliance service compliance service is used to sign the locally signed self description. It signs it if the final result is successfully verified against the compliance service. The result is stored in a new file called {timestamp}_complete_{gx-type}.json

Complete Self-Description signed by the Compliance Service:

{
  "selfDescriptionCredential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://registry.gaia-x.eu/v2206/api/shape"
    ],
    "type": ["VerifiableCredential", "LegalPerson"],
    "id": "https://compliance.gaia-x.eu/.well-known/participant.json",
    "issuer": "did:web:compliance.gaia-x.eu",
    "issuanceDate": "2022-09-23T23:23:23.235Z",
    "credentialSubject": {
      "id": "did:web:compliance.gaia-x.eu",
      "gx-participant:name": "Gaia-X AISBL",
      "gx-participant:legalName": "Gaia-X European Association for Data and Cloud AISBL",
      "gx-participant:registrationNumber": {
        "gx-participant:registrationNumberType": "local",
        "gx-participant:registrationNumberNumber": "0762747721"
      },
      "gx-participant:headquarterAddress": {
        "gx-participant:addressCountryCode": "BE",
        "gx-participant:addressCode": "BE-BRU",
        "gx-participant:streetAddress": "Avenue des Arts 6-9",
        "gx-participant:postalCode": "1210"
      },
      "gx-participant:legalAddress": {
        "gx-participant:addressCountryCode": "BE",
        "gx-participant:addressCode": "BE-BRU",
        "gx-participant:streetAddress": "Avenue des Arts 6-9",
        "gx-participant:postalCode": "1210"
      },
      "gx-participant:termsAndConditions": "70c1d713215f95191a11d38fe2341faed27d19e083917bc8732ca4fea4976700"
    },
    "proof": {
      "type": "JsonWebSignature2020",
      "created": "2022-10-01T13:02:09.771Z",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:web:compliance.gaia-x.eu",
      "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..XQqRvvuxW1xHUy_eRzOk4LwyjwlRofg0JBiO0nrWGHAjwMA87OVJ37mB6GylgEttEaUjXQV-QmbGfEnE-YQf5S7B-id9Lld-CC-vW8M-2EvXh3oQp3l5W35mvvdVQXBj16LLskQZpfZGRHM0hn7zGEw24fDc_tLaGoNR9LQ6UzmSrHMwFFVWz6XH3RoG-UY0aZDpnAxjpWxUWaa_Jzf65bfNlx2EdSv3kIKKYJLUlQTk0meuFDD23VrkGStQTGQ8GijY3BNo6QWw889tt5YKWtiSZjbDYYHsVCwMzPoKT0hVJ1wy2ve6pJ4MSYfhiMxoDq6YBOm-oYKYfBeN22fjqQ"
    }
  },
  "complianceCredential": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "type": ["VerifiableCredential", "ParticipantCredential"],
    "id": "https://catalogue.gaia-x.eu/credentials/ParticipantCredential/1664629337488",
    "issuer": "did:web:compliance.gaia-x.eu",
    "issuanceDate": "2022-10-01T13:02:17.489Z",
    "credentialSubject": {
      "id": "did:web:compliance.gaia-x.eu",
      "hash": "3280866b1b8509ce287850fb113dc76d1334959c759f82a57415164d7a3a4026"
    },
    "proof": {
      "type": "JsonWebSignature2020",
      "created": "2022-10-01T13:02:17.489Z",
      "proofPurpose": "assertionMethod",
      "jws": "eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..YQAIjkqX6OL4U3efV0zumn8-l8c4wQo98SOSlzt53HOR8qlLu5L5lmwZJnAsR7gKW-6jv5GBT0X4ORQ1ozLvihFj6eaxxJNgzLFPoH5w9UEaEIO8mMGyeQ-YQYWBbET3IK1mcHm2VskEsvpLvQGnk6kYJCXJzmaHMRSF3WOjNq_JWN8g-SldiGhgfKsJvIkjCeRm3kCt_UVeHMX6SoLMFDjI8JVxD9d5AG-kbK-xb13mTMdtbcyBtBJ_ahQcbNaxH-CfSDTSN51szLJBG-Ok-OlMagHY_1dqViXAKl4T5ShoS9fjxQItJvFPGA14axkY6s00xKVCUusi31se6rxC9g",
      "verificationMethod": "did:web:compliance.gaia-x.eu"
    }
  }
}

How it Works

The given Self Description is canonized with URDNA2015
Next the canonized output is hashed with SHA256.
That hash is then signed with the given private key and the proof is created using JsonWebKey2020.

Environment variables for self-issued certificates (This is for test-setups only)

This section is part of a bigger guide and describes environment variables needed to sign self-issued certificates. If you want to use the https://compliance.gaia-x.eu follow the instructions above and ignore this section. Here you can find the full guide for a local test-setup: Using self-issued certificates for local testing

How to set signer tool environment variables:

PRIVATE_KEY = copy pk8key.pem content
CERTIFICATE = copy cert.pem content
VERIFICATION_METHOD = did:web:localhost%3A3000 (assuming port 3000 for the compliance service, you have to encode : as %3A)
X5U_URL = https://localhost:3000/.well-known/x509CertificateChain.pem
BASE_URL = https://localhost:3000

More information about environment variables can be found in the How To Use section.

For now you can ignore the generated did.json since we are using for simplicity reasons the did.json of the compliance service also for the self-description. Usually you would host it under your own domain together with the x509CertificateChain.pem in the .well-known/ directory.

If everything worked you should have 3 files generated. You can now head back to "Step 4: Verify your signed self-description" of the guide.

deltaDAO/self-description-signer

Self-Description-Signer

How To Use

How it Works

Environment variables for self-issued certificates (This is for test-setups only)