Link Search Menu Expand Document
tsrct documentation

Domain Delegated Extensions (DDX)

Before starting this section, ensure that your enterprise setup has been completed by following the enterprise onboarding section.

DDX allows an organization to create facts that are backed by a public-private key pair. The private key of this key pair is always held by the organization and the public key is registered with tsrct along with a description of the fact. This fact can encompass any type of assertion, such as an employee credential, a student degree or transcript, an event ticket, etc.

DDX functionality is provided by a dedicated server that is run by an organization (cls = org). This server software is provided by tsrct but runs in the organization’s cloud tenant environment. This server creates its own data store for managing keys, facts, and other data required by the org.

Each fact registered this way via DDX gets a unique global id, and more importantly, a unique global URL that points to the DDX server hosted by the organization that can be used to cryptographically validate the fact in real time. Here are some examples:

  1. Employee Id: an organization uses their DDX server to create a document whose content body conforms to the DDX schema for identity cards.
    • This document has a tgt (target) field that points to a distinct, existing tsrct id representing a user (usr) or an organization (org)
    • The creation of this document causes the creation of a dedicated keypair within the organization’s DDX installation
    • The uid of this document is used to create a dedicated URL path for this fact based on the DDX server’s host location
    • This document is then submitted to tsrct where it is stored and viewable by the document uid
    • This DDX now shows up as a card in the employee’s tsrct app’s wallet
    • Usage:
      • The employee can present this employee id card and activate its QR code anywhere a scan is required
      • The scanning entity will use their own tsrct app to scan the QR code, which will trigger a verification flow
      • The verification process will send a cryptographic challenge to the employee’s phone
      • The tsrct app on the employee’s phone will receive the challenge and sign it with the employee private key
      • Additionally, the employee phone will reach out to the dedicated URL indicated in the DDX grant to have the signature countersigned by the DDX relationship private key
      • The two signatures (employee private key signature and DDX private key signature) will be embedded in the response to the scan
      • The tsrct app on the scanner’s phone will now show the fully signed response, thus showing that the Employer-Employee relationship is still valid
    • Anytime the employer revokes the DDX for the employee, the DDX card from the employee wallet will disappear and no future validations will be possible
  2. Educational Certificate: Universities and educational institutions can issue a DDX document to a tsrct usr that indicates an academic credential in a process very similar to an employee id:
    • This document indicating an academic credential as a tgt field that contains the 25 digit tsrct id of the awardee
    • The creation of this document causes the creation of a dedicated keypair within the academic institution’s DDX installation
    • The uid of this document is used to create a dedicated URL path for this fact based on the DDX server’s host location
    • This document is then submitted to tsrct where it is stored and viewable by the document uid
    • This DDX now shows up as a card in the awardee’s tsrct app’s wallet
    • Usage:
      • The usage is identical to the employee id use case: the wallet card can be scanned and challenged in real time
      • Additionally (and this applies to the employee id use case as well), the DDX grant can be used to sign documents created by the user
      • Attaching a DDX signature to any document allows the user to assert their credentials; for instance:
        • A user can send a cover letter to a prospective employer signed by the DDX of one or more of their degrees; this will allow the prospective employer to instantly validate the user’s academic credentials

Installing a DDX Node

Installing a DDX Server (or “DDX Node”) is essential to issue and countersign DDX credentials. The DDX Server can be installed on a cloud provider of your choice, such as GCP or AWS.

DDX Server on Google Cloud Platform (GCP)

GCP Project

It is suggested to crete a new, dedicated GCP Project to host the DDX server (for illustrative purposes, we’ll call it tsrct-ddx-project) If you have already created a dedicated project that contains the KMS and keys used for enterprise onboarding, we can just use that project itself. Ideally, if you already have GCP project that hosts your Cloud KMS that was used for enterprise onboarding, we can create a new GCP project (e.g. tsrct-ddx-project) and create a service account that will be able to access the enterprise keys in the KMS project.

DDX Domain Setup

Select a subdomain you’d want to host your DDX Server. For instance, if your organization domain is example.com then you might want to have your DDX Server be accessible via the domain ddx.example.com

  • Obtain a static IP address, either on the premium tier or the standard tier
  • In your DNS entries, map this IP address to the ddx.example.com subdomain

    Create a DDX specific encryption key pair

    To separate DDX functionality from your corporate signing in tsrct, in your KMS, create a new asymmetric encryption/decryption key pair. For this document, we’ll assume the keypair is called ddx-example-com-enc-key. Both the DDX key and the org sig and enc keys created during onboarding should be accessible to the service account that will be used by the Cloud Run servie that will host the DDX Server.

For example, create the encryption key for the DDX node:

gcloud kms keys create ddx-example-com-key-enc \
  --keyring example-com-key-ring \
  --location us-central1 \
  --project t-gcp-project \
  --protection-level "hsm" \
  --purpose "asymmetric-encryption" \
  --default-algorithm "rsa-decrypt-oaep-2048-sha256"

Install the DDX Server

Obtain the DDX Server from the container registry. We will assume here that the installation will be via Cloud Run. Install your DDX Server instance on Cloud Run using the following command (or similar functionality in Terraform):

gcloud run deploy ddx-service \
  --image <image name and version> \
  --project <project name, e.g. tsrct-ddx-project> \
  --region us-central1 \
  --allow-unauthenticated \
  --service-account <cloud run service account name -- must have access to kms key> \
  --platform managed \
  --ingress internal-and-cloud-load-balancing \
  --no-cpu-throttling \
  --cpu-boost \
  --set-env-vars GCP_DDX_ENC_KEY_RESOURCE="projects/<key-project>/locations/<location>/keyRings/<ddx keyrung>>/cryptoKeys/<ddx-example-com-enc-key>/cryptoKeyVersions/1" \
  --set-env-vars GCP_SRC_SIG_KEY_RESOURCE="projects/<key-project>/locations/<location>/keyRings/<tsrct org registration keyring/cryptoKeys/<signatuer key name>/cryptoKeyVersions/1" \
  --set-env-vars GCP_DDX_STORAGE_BUCKET="<name of storage bucket for ddx storage>" \
  --set-env-vars GCP_DDX_PUSH_NOTIFICATION_TOPIC="<pub/sub push topic>" \
  --set-env-vars "^#^spring.profiles.active=gcp,single-tenant" \
  --set-env-vars TSRCT_API_ENDPOINT="https://api.tsrct.io" \
  --set-env-vars TSRCT_DDX_URL_BASE="<base url for the ddx server, e.g. https://ddx.example.com>" \
  --set-env-vars TSRCT_GCP_SINGLE_TENANT_DDX_DOMAIN="<your registered domain, e.g. example.com>" \
  --set-env-vars TSRCT_GCP_SINGLE_TENANT_KEYSET_ID="<your initialization keyset id with tsrct, e.g. 2222222222222222222222222.tsrct-io-init-key>" \
  --set-env-vars TSRCT_GCP_SINGLE_TENANT_SRC_ID="<your org's 25 digit tsrct id, e.g. 2222222222222222222222222>" \
  --set-env-vars TSRCT_GCP_SINGLE_TENANT_DDX_CUSTOM_NAMESPACE="_tsrct_ddx_" \
  --set-env-vars TSRCT_GCP_SINGLE_TENANT_DDX_ICON="<a publicly accessible url for your logo, e.g. https://tsrct.io/favicon.ico>" \
  --memory 2Gi \
  --cpu 2 \
  --min-instances 0 \
  --max-instances 2

provide the appropriate values for the environment variables in the gcloud command above. As indidated, you’ll also have to create the storage bucket and pub/sub topic.

NOTE: The DDX Server will utilize the GCP Cloud Datastore and Cloud Storage in the project where it is hosted. Therefore, please ensure that the DDX Server is installed in a new, clean project so that there is no data interference with any existing data. Also, the cloud storage bucket must be new and have a globally unique name, per GCS guidelines.

An explanation of the above settings is as follows:

image: the container image for the DDX server, to be provided by tsrct

project: your GCP project id

region: your GCP region

allow-unauthenticated: required

service-account: the service account under which the instance will run; this service account must have a role that allows using the org signing key and the ddx encryption key

platform-managed: recommended; if you’re running as a managed cloud run service

ingress: require setting to internal-and-cloud-load-balancing to allow only load balanced requests to connect

no-cpu-throttling: required; since the server uses some background processing

cpu-boost: recommended; for faster cold starts

Traffic Routing to the DDX Server

In the tsrct-ddx-project, create an application load balancer and assign the static IP address obtained earlier to this load balancer. Ensure mode is set to HTTPS and a certificate that can present the DDX domain name (e.g. ddx.example.com) is installed on the load balancer. The routing rules should send all paths with the domain name to the backend service of the Cloud Run DDX Service.

Wait for the certificate and the load balancer to become active. This can take 20-30 minutes in some cases. To check if your DDX Server is live, go to the address of the DDX Server, e.g. https://ddx.example.com For instance, tsrct’s DDX Server is at https://ddx.tsrct.io and provides a liveness message when connected to. You should see a message that looks like this:

{
    "data": {
        "time": "2024-11-30T02:13:07.211Z",
        "build": "1.0.0",
        "message": "ddx node ok"
    },
    "status": "ok",
    "isArray": false,
    "timestamp": "2024-11-30T02:13:07Z"
}

DDX Server on Amazon Web Services (AWS)

This version is in development and will be ready soon.

DDX Server on Microsoft Azure

If you really must have it, write to us at info (at) tsrct dot io, and we’ll be happy to push it up our priority list.

Creating a DDX Credential

Once you have confirmed that your DDX Server is running by hitting your endpoint and getting the ddx node ok message, your DDX Server is ready for use and you can issue a DDX credential.

Also, before creating the DDX credential, ensure you have the tsrct cli installed. The tsrct cli is called tsrct and should be in your classpath.

Also, create a tsrct document that contains the logo of your company or organizations.

All this can be scripted, but is shown here the manual way.

  1. Create a json file that contains the details of the credential you want to issue (say you call it credential.json); the json document should follow the tsrct ddx schema indicated here. Here is the document that was used to create the founder’s ddx credential: 
    {
  "spec": {
 "category": "card",
 "name": "tsrct official person card",
 "design": {
   "logo": "2222222222222222222222222.20240114-01-tsrct-logo",
   "title": "tsrct",
   "subtitle": "Personnel Identification",
   "primaryImage": "2222222222222222222222222.202401150816-sg-profile-pic-small",
   "primaryTitle": "Saurabh Gupta",
   "primarySubtitle": "Founder & CEO, tsrct",
   "backgroundColor": "#fcbc05",
   "foregroundColor": "#303030"
 }
  },
  "data": {
 "startDate": "2023-08-01",
 "jobDescription": [
   "As CEO and Founder of tsrct, Saurabh has the following responsibilities:",
   "* Establish the product and commercial vision for tsrct",
   "* Build the initial prototype to launch the product in the market",
   "* Recruit initial customer base to test and establish product market fit",
   "* Evangelize and write about the various applications and use cases for the technology",
   "* Manage the patent and other IP related to the company",
   "* Seek funding and other means to scale the company"
 ],
 "location": "New York City, NY"
  }
}
  2. Use the tsrct cli to issue the ddx command to your ddx server; your ddx server will complete the key creation, signing and other requirements and submit the ddx to the tsrct api: 
    tsrct domain ddx-create \
  --uid "<uid of the ddx e.g. 202501011532-new-credential>" \
  --url "<your ddx endpoint e.g. https://ddx.example.com>" \
  --src <your org tsrct id, e.g. 2222222222222222222222222> \
  --dom "<your org domain, e.g. tsrct.io>" \
  --tgt "<the target user's tsrct id, e.g. 9000990009900099000990009>" \
  --key "<your org keypair name with tsrct, e.g. 2222222222222222222222222.tsrct-io-init-key>" \
  --scm "2222222222222222222222222.ddx-super-schema-v1" \
  --acl "acl_pub" \
  --lst "true" \
  --dsc "Name and Title assignment" \
  --sub "tsrct:user-id" \
  --nbf "2023-08-01T09:00:00Z" \
  --ref "<optional, attach to any other tsrct documents as reference, e.g. 5210852108521085210852108.9000990009900099000990009.201706230925-ddx-name-saurabh-gupta>" \
  --key-host "gcp" \
  --sig-key-resource "<the fully qualified location of your signing key with GCP, e.g. projects/<projectId>/locations/<us-central1>/keyRings/<keyring name>/cryptoKeys/<signing key name>/cryptoKeyVersions/1>" \
  --ddx-file "credential.json"

DDX’s are issued in the format src.tgt.uid specified above.

The user will now be able to see the DDX card in their wallet and select that card when creating new content to have the DDX be asserted with the content.