Destinations

A destination is a programmatically targetable URI for the secure submission of signed-and-encrypted messages.  Destinations are underpinned with their own unique digital certificate, which is used for the encryption of any messages targeting the destination.  This ensures that only the possessor of the destination's private key is able to decrypt the payload. This also allows the message recipient to authoritatively verify the identity of the sender.

NOTE: The Document Store service is reliant on the On-Chain Registry service. The certificate associated with each destination is stored in the On-Chain Registry membership profile. This makes it possible to query the destinations of all members in an environment through a convenient address book, while also providing access to all certificates for the encryption of messages and verification of signatures.

The console will guide you through the deployment of the On-Chain Registry Service and confirmation of an identity.  Note that the simplest approach is to allow Kaleido to register your membership identity on chain with a self-signed identity certificate. This will allow you to create the destination immediately through the Kaleido console.  If you prefer to use an externally-signed certificate for your organizational identity, you will be responsible for using the Kaleido SDK to upload the destination certificate in order to prove ownership of the Ethereum account associated with your profile.  No matter the approach, Kaleido will handle generation of the destination certificate.

Destinations for Kaleido self-signed identities

  • Access your Document Store service by clicking its name or selecting the View Dashboard option from the service dropdown.
  • Click the DESTINATIONS tab and select SETUP DESTINATION.
  • Kaleido will check for an instance of the On-Chain Registry and that your organization has been established within it.  If either of these actions have not occurred, their absence will be reflected in the console.
  • Click the large blue button to let Kaleido take care of the heavy lifting.  If you prefer to use an externally-signed cert, skip down to the next section.

Docstore Prerequisites

  • Once the Registry is successfully deployed and your organization has been established on-chain, you'll see a success panel.  Go ahead and click NEXT in the bottom right.
  • Create your destination by providing a compliant name (allowed characters are listed in the console) and clicking FINISH.
  • It will take a few seconds to generate the crypto materials and build the certificate.  Once complete, you will be exited out of the destination generation modal and see your newly created destination.

Docstore Destination Created

  • Proceed with this process to create additional destinations.  Multiple destinations may be desired for different business segments or asset classes.

Destinations for Externally-Signed Identities

  • An organization with an externally-signed identity will display a blue ribbon next to its name on the home screen for your consortium.  If you have not yet established your identity and do NOT wish to use a Kaleido self-signed certificate, follow the instructions to confirm your identity and generate a Kaleido-compliant x509 certificate.
  • Once you have generated and uploaded your certificate, refer to the On-Chain Registry documentation for instructions on programmatically establishing your identity on-chain.  This step requires usage of the Kaleido SDK (written in Go).  You will use this same utility to upload the destination certificate to the On-Chain Registry.  The procedure for uploading a destination certificate is identical to that of any profile call to the On-Chain Registry.  You will supply a key value pair and prove ownership of the Ethereum account bound to your organization.

All subsequent documentation requires your externally-signed certificate to have been programmatically uploaded to the On-Chain Registry.

  • Within your Document Store service, click the DESTINATIONS tab and select SETUP DESTINATION.  You should be greeted with the success panel shown below.  If you see an incomplete step, go back and ensure that your externally-signed certificate has been successfully uploaded.

Docstore External Signing

  • Click NEXT and supply a compliant name for your destination.  Click FINISH.
  • This will take you to a new screen displaying your destination certificate and targetable URI.  As an admin you are responsible for copying the certificate and subsequently uploading it to the On-Chain Registry.  To reiterate, this process is necessary because Kaleido does not have the private key for the corresponding Ethereum address bound to your organization's profile.  As a cryptographic security mechanism, you are required to demonstrate ownership/possession of this key for any calls targeting the profile.
  • This screen will look similar to the following:

Docstore External Signing Complete

  • Take note of the comments in the screen shot.  The URI is the "key" for your upcoming call.  The raw certificate file is the associated "value."
  • Once you have copied the URI and destination certificate, click the I'LL TAKE IT FROM HERE button at the bottom of the screen.  If for any reason you need the URI and/or certificate to be redisplayed, simply click the DESTINATIONS tab within the service.  This screen will display your destination along with an orange status icon indicating that the destination procedure is still incomplete.  Click the RETRY button next to the destination to redisplay your data.

Docstore External Destination in List

  • You will see your URI and destination certificate redisplayed in a new modal.
  • For ease of use on the command line, we recommend saving the certificate as a .pem or .txt file and providing the explicit path in the upcoming CLI call.  The semantics of this call are identical to that of App 2 App messaging and any profile call to the On-Chain Registry.  Those instructions are documented, along with example payloads, at the bottom of Registry Interaction via CLI.
  • This call is ultimately an invocation of the Profiles smart contract.  It requires the URI and certificate to be supplied as a key value pair, as well as the enumeration of the organization's owning Ethereum address and the path to the corresponding private key.
  • Use the ./kld profile set key command to execute this call.  For enhanced readability of the utility, you can provide the -h flag to see the available flags for this call.
>MacBook-Pro:kaleido-sdk-go johndoe$ ./kld profile set key -h
Set the key to a particular value

Usage:
kld profile set key [flags]

Flags:
-h, --help help for key
-k, --keystore string Keystore path so accounts can be used to sign tx
-o, --owner ethereum-address Account of the profile owner
-n, --revision string Revision for the key (default "1568157024")
-v, --value string Value for the key

Global Flags:
--api-key string Kaleido API KEY (optional)
--api-url string Kaleido API URL (optional)
--config string Config file that captures re-usable settings such as API URl, API Key, etc. (default is $HOME/.kld.yaml)
-i, --service-id string Service ID (optional if config is setup properly)
--verbose int Verbosity level of output (0 or 1)
  • The three required flags are -v for value, -o for Ethereum account owner and -k for the path to the account's private key.  The URI is passed as an extension to the initial command.
  • A proper call might resemble the following:
./kld profile set key kld://documentstore/m/zzhzotsgrm/e/zzi1iia4w2/s/zztncfmg86/d/abc_123 -v "$(cat ~/tmp/destination.pem)" -o 0xb5dac389b1520c7c419244389548fe868742c984 -k /Users/johndoe/Library/Ethereum/keystore
  • If the call is successful (namely, the URI, certificate, Ethereum account and private key have all been properly passed to the interface) then your destination's status will change from orange to green.
  • Repeat this process to create additional destinations within your service.