Link Search Menu Expand Document
tsrct documentation

Getting Started for Enterprises (org)

NOTE: this section is for enterprise admins. If you’re a user using the mobile app, go to mobile app

Organizations (such as companies, governments, etc.) are called orgs in tsrct.

Organizations bootstrap themselves with their domain name. Domains are fully qualified, so example.com, finance.example.com, smb.finance.example.com, and api.example.com can each be different organizations.

It is very simple to bootstrap an organization. There are four broad steps:

  1. Create a key pair
  2. Create a corporate UID
  3. Update the domain’s DNS entry
  4. Send a registration request to tsrct

Each of the above is detailed below; for simplicity, assume that the domain being registered is example.com:

0. Preparation

You’ll need to download the tsrct cli and make it part of your classpath. You can download the version appropriate for your os here

More information about the tsrct cli is given in the cli page in this documentation.

The tsrct cli is invoked by calling tsrct, for example: tsrct --help

GCP Preparation

If you’re using GCP, ensure that your gcloud utility is installed and logged into the correct project. If new to gcloud, please review the instructions on installing and initializing your gcloud environment. Also please review the instructions for using gcloud with GCP KMS here.

AWS Preparation

If you’re using AWS, the appropriate documentation is coming soon; you can also infer equivalent commands from the provided GCP commands.

If you really need this, contact info at tsrct dot io

Azure Preparation

If you really need this, contact info at tsrct dot io

1. Create a key pair

GCP usage

Assume that the GCP project id is t-gcp-project and region is us-central1

Using the command line, create a key ring (e.g. example-com-key-ring):

gcloud kms keyrings create example-com-key-ring --location us-central1

now when you list the keyrings, you’ll be able to see the keyring just created:

gcloud kms keyrings list --project t-gcp-project --location us-central1

You’ll see output like:

NAME
projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring

More details about keyring creation on GCP are given here

Now create the signing key of type ASYMMETRIC_SIGN called example-com-key-sig in the above key ring:

gcloud kms keys create example-com-key-sig \
  --keyring example-com-key-ring \
  --location us-central1 \
  --project t-gcp-project \
  --protection-level "hsm" \
  --purpose "asymmetric-signing" \
  --default-algorithm "rsa-sign-pkcs1-2048-sha256" \

The default algorithm is required to be rsa-sign-pkcs1-2048-sha256; support for other key types is not available at this time.

Similarly, create the encryption key for the org:

gcloud kms keys create 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" \

The default algorithm is required to be rsa-decrypt-oaep-2048-sha256; support for other key types is not available at this time.

It is recommended that the hsm protection level be chosen for both keys since this will be the root key for all operations on tsrct for the org.

More information on asymmetric key creation is available here

For later steps, you’ll need the fully qualified name of each key with the version number. To get the version numbers, use the following commands:

Initially, get the names of all the keys you’ve just created:

gcloud kms keys list \
  --project t-gcp-project \
  --location us-central1 \
  --keyring projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring

in the above, the values for --project and --keyring will be adjusted appropriately. You will get output like:

NAME                                                                                            PURPOSE             ALGORITHM                     PROTECTION_LEVEL  LABELS  PRIMARY_ID  PRIMARY_STATE
projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-enc  ASYMMETRIC_DECRYPT  RSA_DECRYPT_OAEP_2048_SHA256  HSM
projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-sig  ASYMMETRIC_SIGN     RSA_SIGN_PKCS1_2048_SHA256    HSM

again, the above is an example only, your actual values will vary

You will need the exact key version to specify which key should be used for signing and registration, so the following command to get the cryptoKeyVersion for each key: for the encryption key, provide the encryption key name:

gcloud kms keys versions list \
  --project tsrct-key \
  --location global \
  --key projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-enc

which will produce output similar to the following (with your specific key version):

NAME                                                                                                                           STATE
projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-enc/cryptoKeyVersions/1  ENABLED

for the signing key, provide the signing key name:

gcloud kms keys versions list \
  --project tsrct-key \
  --location global \
  --key projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-sig

which will produce output similar to the following (with your specific key version):

NAME                                                                                                                           STATE
projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-sig/cryptoKeyVersions/1  ENABLED

AWS key creation

This content is being developed

2. Select a Corporate UID

All tsrct actors (organizations or users) are identified by a globally unique, 25 digit identifier called a uid.

The uid can be selected by the actor, but is subject to the following constraints:

  1. it cannot begin with a 0 or a 1
  2. it must be 25 digits long where the last digit is a calculated Verhoeff checksum, so the actor is only able to specify the first 24 digits

For instance the tsrct uid for tsrct itself is 2222222222222222222222222 (that’s 25 2’s) and it’s a special uid since the checksum matches the overall pattern. There are many such uid’s and with a bit of effort, you can find them. Keep in mind, trading uids is forbidden under tsrct’s terms of service.

You can check available uids using the tsrct cli (You’ll need the tsrct cli, which you can download here):

tsrct uid avail <24 digit uid stem>

so, typing in tsrct uid avail 222222222222222222222222 (that’s using 24 2’s) will give the following output:

uid with checksum: 2222222222222222222222222
Sorry! Your selected uid 2222222222222222222222222 is not available!

You can invoke the above endpoint multiple times to determine if a desired uid is available. Once you’ve determined that your desired uid is available, make a note of it and proceed to the next step: the actual registration of your domain.

3. Update the DNS entry

Now that the sig and enc keys exist in the cloud, you’ll have to generate the DNS entries that will point to your ownership of the domain.

Using the tsrct cli, generate the entries required for DNS:

tsrct domain dns \
  --key-set-id <key-set-id-name> \
  --uid <organization-uid> \
  --key-host gcp \
  --sig-key-resource projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-sig/cryptoKeyVersions/1 \
  --enc-key-resource projects/t-gcp-project/locations/us-central1/keyRings/example-com-key-ring/cryptoKeys/example-com-key-enc/cryptoKeyVersions/1

items in the above command are:

  • --key-set-id: this is the common key set id that tsrct will use. You can choose it to be whatever you want, for instance tsrct’s own keys are initialized by the key set name tsrct-io-init-key
  • --uid: this is the available uid you’ve determined earlier in the process
  • --key-host: the cloud platform code where the KMS is located, in this case gcp
  • --sig-key-resource: the fully qualified name and version of the signing key in the KMS; this name will depend on the key host cloud provider.
  • --enc-key-resource: the fully qualified name and version of the encryption key in the KMS; this name will depend on the key host cloud provider.

This will output the items that are to be added to your DNS TXT records for the domain you want to register. Since this is a long TXT record, it is broken into 4 discrete items labelled 0-3.

update domain dns entry with the following TXT records:
tsrct-domain-verification[0]=sig:UOeX...BVAitG
tsrct-domain-verification[1]=cRySthgX...lpnsYz
tsrct-domain-verification[2]=7k5onYXZ...pC4WFO
tsrct-domain-verification[3]=OFZg1CPK...x0GEdg

you can see how these records have been added to tsrct’s own DNS entries here.

Now that your DNS has been updated, make sure that the changes have propagated by running a command like dig or using a web based tool like dns.google

For instance, for the domain example.com, the dig command will be:

dig example.com TXT

Once you’re able to see the tsrct-domain-verification records, you can proceed to the last step of registering your domain with tsrct.

4. Send a registration request

To register your domain (in this example, example.com), run the following command from the tsrct cli:

tsrct domain init \
  --dom example.com \
  --key-set-id <key-set-id-name> \
  --uid <organization-uid> \
  --key-host gcp \
  --sig-key-resource <fully qualified signing key crypto key version name from earlier steps> \
  --enc-key-resource <fully qualified encryption key crypto key version name from earlier steps>

items in the above command are:

  • --dom: the domain to register; this example uses example.com but of course your domain will be your actual organization domain name
  • --key-set-id: the key set id that was input in the prior task of getting the dns entries
  • --uid: the uid chosen for the organization
  • --key-host: the cloud platform code where the KMS is located, in this case gcp
  • --sig-key-resource: the fully qualified name and version of the signing key in the KMS; this name will depend on the key host cloud provider.
  • --enc-key-resource: the fully qualified name and version of the encryption key in the KMS; this name will depend on the key host cloud provider.

you will receive a response indicating that your domain has been registered. If there is an error, it will say so.

NOTE: sometimes, due to the timing sensitivities, you might get an error even if you’ve done everything correctly. In that case, just re-run the above command.

Once your registration succeeds, you can go to tsrct.io and enter the registered domain in the search box and hit submit to view the online entry for your domain. For instance, the registered entry for tsrct.io itself is available at https://tsrct.io/tsrct.io.

Congrats, you’re now on tsrct!!