Connection

This document describes the information needed by a client to be able to establish a connection to a Volt, how that information is persisted in a configuration file by the tdx Volt client libraries, and how to use a client configuration file to establish a connection to a tdx Volt using the tdx Volt CLI.

Client connection information

Two pieces of information are required for a client to be able to connect to a tdx Volt to access resources or services:

The client credentials. The client credentials identify the client. As far as the target tdx Volt is concerned, this is primarily made up of the client’s public key. However, in order to be able to prove possession of the key to the target Volt, the private key will be required by the client library to initiate the TLS handshake or sign a JWT. The client credentials are stored in the credential property, described below.
The target tdx Volt configuration. The tdx Volt configuration identifies the target Volt. It includes a unique identitifier, address and public key. See the Volt configuration reference section for a full description and details of how to obtain a tdx Volt configuration. The Volt configuration is stored in the volt property, described below.

Note that only the public portion of the client key is sent to the Volt, the private key is never seen by the Volt.

The basic structure of a client configuration is shown below:

{
  "client_name": "Alice",
  "credential": {
    "key": "<PEM-encoded private key>"
  },
  "volt": {
    <paste a Volt configuration object here>
  }
}

Client configuration file

All the current tdx Volt client libraries support using a file to store a client configuration in the JSON format described here.

It is not obligatory for clients or applications to use this format. The configuration details can be specified as a plain object and stored in whatever method suits.

Obtain a client configuration

If you have a connection to the target tdx Volt configured in the fusebox, you can use this to quickly obtain a client configuration file.

Select the identity you want to use for the client in the Explorer pane on the left side of the fusebox. Then use the ‘copy to clipboard’ button next to the ‘client configuration’ detail in the right-hand panel, as highlighted in the image below:

client-configuration-copy

Alternatively, you can use the ‘copy client configuration’ button on the ‘metadata’ dialog of the identity.

Populating the client key

Note that unless the full client key is stored in the tdx Volt, it will be necessary to manually populate the key property of the JSON that is copied to the clipboard using the method described above.

The example below shows the configuration copied from an identity that doesn’t have the key stored in the tdx Volt. As you can see, the key property has a placeholder (<**** INSERT PEM-FORMAT KEY HERE ****>) that must be replaced with the actual PEM-format private key corresponding to this client.

{
  "client_name": "Local",
  "credential": {
    "client_id": "65b8a083-554e-442e-a62b-c9cefbe208a4",
    "key": "<**** INSERT PEM-FORMAT KEY HERE ****>"
  },
  "volt": {
    "id": "1947660b-fbc0-4345-aec7-03b147d4e417",
    "display_name": "macBook (intel)",
    "address": "192.168.1.69:50908",
    "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA435moWiFRnDK/uUQcLuw\nCv+uPILgwy+MPOUmgoQUNsZgeH2RjFZqWv4JAr+1V67EDcLwIgxjd9pdYfdeHFoG\n5Z4t7qvpbJ0GPpj4SpQiN+XufZ4h+xe5C77pxukHKdzg4KlcE1UavxkRn/hQe/jI\n3tQDl99/iy0zdrClfcGDecTJT9th563ggVGuXi+GJ8iZMc6sNsYR5vMZcL3qJgx+\nUYe9RMqY4wDkbs8BppXLfy9WH41JREN1f9ypEHDKom+Yisbpcx4X9GSllz5Q67BA\nMrpwzzl7Q1F5Dj8oQQcBHvVq7ja33/OpK09iH1Wi6hv+nnd3Pv/8NM3QhoMWFjos\ncwIDAQAB\n-----END PUBLIC KEY-----\n",
    "fingerprint": "EPhBiNvb5RAvM1FjzrrrKYP7ggMBaJ5wM7KMTJjBfPaM",
    "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIDojCCAoqgAwIBAgIEBoqCUTANBgkqhkiG9w0BAQsFADBxMQswCQYDVQQGEwJH\nQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWluZHMg\nTHRkMTAwLgYDVQQDDCdjYS4xOTQ3NjYwYi1mYmMwLTQzNDUtYWVjNy0wM2IxNDdk\nNGU0MTcwHhcNMjIxMDI5MTcwNDIxWhcNMjMxMDI5MTcwNDIyWjBxMQswCQYDVQQG\nEwJHQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWlu\nZHMgTHRkMTAwLgYDVQQDDCdjYS4xOTQ3NjYwYi1mYmMwLTQzNDUtYWVjNy0wM2Ix\nNDdkNGU0MTcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDjfmahaIVG\ncMr+5RBwu7AK/648guDDL4w85SaChBQ2xmB4fZGMVmpa/gkCv7VXrsQNwvAiDGN3\n2l1h914cWgblni3uq+lsnQY+mPhKlCI35e59niH7F7kLvunG6Qcp3ODgqVwTVRq/\nGRGf+FB7+Mje1AOX33+LLTN2sKV9wYN5xMlP22HnreCBUa5eL4YnyJkxzqw2xhHm\n8xlwveomDH5Rh71EypjjAORuzwGmlct/L1YfjUlEQ3V/3KkQcMqib5iKxulzHhf0\nZKWXPlDrsEAyunDPOXtDUXkOPyhBBwEe9WruNrff86krT2IfVaLqG/6ed3c+//w0\nzdCGgxYWOixzAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQD\nAgEGMB0GA1UdDgQWBBSucRk3SzUBcmL5QaqMhyfbGTXCXTANBgkqhkiG9w0BAQsF\nAAOCAQEAsmk8vUGJjoy5ZAibthGUt5qYWwpdkWK1cARZQJY4Kpn/lSTZcPlTdEpi\nxEbUZ74IV/YENQaJAT6fV3DAi3xlwsTxnvJRX94orkh/hJxai1FvWq/CaNs6rz1d\nFji4t5iMmkF+77ZOD1mmnDnvlPW2yp3SuQ26+I8XxgMGnVeNo4aIbHpJoAwXh7l9\n6uUHPfNiIQxne2x0gK9uCAIfTbWLv4XkymSrbrEIicQHgTdWNg7r82lX+DC7zghW\nWYtmx/0v4cioBkBLmMVcqsUt29wWIkl/B6ATYIzPb/ibCtKF8NWvSbr5LxRWm52D\nIJEbj3HsC7sGSQKdGAEvg91nwh8fUw==\n-----END CERTIFICATE-----\n",
    "challenge_code": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI="
  }
}

Create client configuration

If you want to create a new client on a tdx Volt you can manually create one using the CLI.

The first step in creating a client configuration file is to obtain the configuration details of the tdx Volt you wish to connect to.

Get the Volt configuration details

In general, the details of how to go about this are given in the Volt configuration section.

The client libraries support a couple of other methods that attempt to automatically resolve or discover the Volt configuration.

The first of these methods is the use of Volt DID, or decentralised identifier, which is registered on any Volt cloud portal. A full description of decentralised identifiers is out of scope for this document, but more information can be found here.

The Volt DID can be specified in the client configuration in one of two ways, the first of which is a shortcut using the volt property as a string:

{
  "client_name": "Alice",
  "credentials": { ... }
  "volt" : "did:tdx:349970a5-9f3a-4ac6-aef3-75881e7b87e7"
}

The second is to add a did property to the volt object:

{
  "client_name": "Alice",
  "credentials": { ... }
  "volt" : {
    "did": "did:tdx:349970a5-9f3a-4ac6-aef3-75881e7b87e7"
  }
}

Another method of automatically acquiring the Volt configuration is using a discovery URL.

Similar to the DID examples above, the Volt discovery URL can be specified in the client configuration in one of two ways, the first of which is a shortcut using the volt property as a string:

{
  "client_name": "Alice",
  "credentials": { ... }
  "volt" : "https://tdxvolt.com"
}

Or using a http_address property on the volt object:

{
  "client_name": "Alice",
  "credentials": { ... }
  "volt" : {
    "http_address": "https://tdxvolt.com"
  }
}

Note that the target Volt will need to have its HTTP server enabled for the `http_address` resolution to work.

Creating the configuration file

Once you have obtained the target tdx Volt configuration, the next step is to create the client configuration file to store the tdx Volt configuration alongside your client credentials.

Use your favourite text editor to create the configuration file, e.g.

# If using nano, specify the `-w` switch to prevent wrapping as this can corrupt PEM encoded data.
nano -w my.config.json

Create a minimal configuration using the following:

{
  "client_name": "<enter a friendly name for this client>",
  "volt": <paste the Volt configuration obtained above here>
}

An example of a tdx Volt configuration for connection to a local (P2P) tdx Volt is shown below.

{
  "client_name": "connection demo",
  "volt": {
    "id": "449a3385-f380-41f7-bd0a-e60caaa403cb",
    "address": "192.168.1.194:58913",
    "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIDojCCAoqgAwIBAgIEJdz3cjANBgkqhkiG9w0BAQsFADBxMQswCQYDVQQGEwJH\nQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWluZHMg\nTHRkMTAwLgYDVQQDDCdjYS40NDlhMzM4NS1mMzgwLTQxZjctYmQwYS1lNjBjYWFh\nNDAzY2IwHhcNMjIwODI0MTIzNTM1WhcNMjMwODI0MTIzNTM2WjBxMQswCQYDVQQG\nEwJHQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWlu\nZHMgTHRkMTAwLgYDVQQDDCdjYS40NDlhMzM4NS1mMzgwLTQxZjctYmQwYS1lNjBj\nYWFhNDAzY2IwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDASh4j1XKy\nEhMcwzwx00wIywM3pC9JzywpFR1kc20ZxOXBZnOxY/Lm3eOZx9/ml1yk5CnMPx68\nZE3abyZ7/6VhPk110GhpxZO2fyQ+Zgx87Cu1mKSoIXbY6fnLJqsL7vTKOAk6jlw/\nfD/IGoR9DDskAaMq/Wm4lBJG3YdnOMnvwfgNGXWmjsrzYJP92HcPwwdEWf2qG/VF\nU3mP/yAq1DVshPldJqZnWMbPY8FR+9ZAkJCp5v/+tvjNupiduVt3uH9XytdMbOIk\n4ktZa8X3onW0VVcD5YQ9ue9AJRnVhju51Et24ykLG+FgPpbrIjPzsfyTBPJ8qOnB\nzWBEFANMkLVVAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQD\nAgEGMB0GA1UdDgQWBBQlUXr/lsH2y1PKI4cHBKEq7xs1UDANBgkqhkiG9w0BAQsF\nAAOCAQEANigh6q5OURhzQ/VV2LkyuL2GEkCh/aQ8LEO3Dwr+SD8cgNhJ9QrRe325\nYcssyBVf5aXvUccuA8tgF07JfuATtNt8CDPSC6g9FBw5xco1P6a7h9bM1dTdXxRJ\nke168Ys3wgBTnogYOKx75zZEMwZsHFxHEfC3q5DA6V+ZVO3pcv7j2YCv+Eh6eD/U\n4DAUKMY4ZWRPgrL8H32CgjaHgP+tV3GbNgyGeVA4gplmLFj06kfk283dVku4gJ2Y\nx2rY/4Kfv/zFgAOy7b4jnx3DtPUR3ddxJwm49tJkzBs14toukHeOPsGVmBPy9naf\ndBl4q9vffIKV/xDqqIOz7GsByZdyUw==\n-----END CERTIFICATE-----\n",
    "challenge_code": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI="
  }
}

Note that in the example above the credential section has not been specified, and therefore will be auto-generated by the client library and a key will be created and stored in the file. If you already have a key that you wish to use for the connection you should place it in the key property of the credential section.

You can now use the tdx Volt CLI to help complete the configuration file:

./volt list . -c my.config.json

Chances are that the above command will result in errors along the lines of failure binding to Volt: policy decision pending. This means that the owner of the Volt you are trying to connect to needs to approve your request to connect to the Volt. However, if you examine the my.config.json file you should see that the credential section has been created along with an auto-generated key:

cat my.config.json

{
  "client_name": "connection demo",
  "credential": {
    "cert": "",
    "client_id": "",
    "key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDwHswi1C8hISle\nFMbB8tM3//zqp/t/9LC3CjQ5XtcpX6Hv/cASiGOg6qI7DaqLKQxqgxS+7oBNcjkF\na/h/HNPH4Mat1oe8O5H1LcrO7YfJnrNj+BL67r3IrRBrhWfJ6eJ750NRR0Y7+F24\nnC/VlL6DvNWAntW1jH0WURsoK3t43RMFruXefUzjHp/hYCoBUaN+S0KVSWHDADUv\nqB/T8AXkAcJki9HAz9owU4rgkkbrQq4ov53rinKHB66ss5P4OXS6YQ0HPEgmtBIK\nYXuz9h/Jder2cvjET8S/FGTnNNq3cJvlMHHDdhTa3Yc64mmLwfhJfa7agnKT86mX\nC1ON0PNdAgMBAAECggEAUbKIzgjXiDQaORJklbSivNjyGnzRCzYbsgtcvXBRUJhj\nJp51bVjOXP+39tOthO+Qc+TpeBT5vl/wmrGjuMv8GnOV5auqPxcdkAfmiwUyQB0o\n+Ah9nLcCB3cqsQqQx5g2IOYMd2kCsoDMknVBqS+UqonjMoHYQI7uOFucG8y/k90r\nSydtppWsyRaS4sweWgpnjzIQACniD3I1cwaIn1RgiqPexqEI8MMRzwBIV/dF0Ky2\nFcmpDy0A0GKfvsFERJ/JZouKiyv8RL253Kk395sIsggxui9CaHAq09bG00gCIH2y\nlfxCeD+ZTXEtsY7izTp5Ieb01ooIvIVghgwPlizlmQKBgQD9zcVAPrytci++hg2V\nUYCWF4iFfSpHsFPjuMaXwohuZ6u6BJiOrE/LxKT4wFE+91WWONITFfITPQ0ZkABS\nOI5A9F9c+WHyenSl6LJU0KgpndBp0u6yQkW+3i+IFcbqT3EDULX+W5LSrpL5G8Qd\nrGhHDcDa+eS4eYDneTa5f9d2LwKBgQDyMrcNmC7M36OLEumttpTltIlMNj+i0UxO\nGQllpmRDhqoCps/tzXrEwjk4mHCiGGf/rxZEQ3F5p/HPQh29z+EMEaGx/2dlEmGm\nv5RTTzCotVxOKM89Ev1hJrO9Z+NNmiA2VJy0Ve5O56FWXLHpu5t5M9Z3pWNMOabk\nbYv6ZjAYMwKBgQDzThGsFvh1JaPTd1sKK8mjGQhNP8IKW2TwRzBKR7jWbhfYCZPe\nIh2U7/xeYq8AN8cabXolxcH842fte3hzWbg1WI8a6A8XjoDIk5xxZl3vF1S2PfmJ\ndbK62PCj+oxoDqP+U59EKbFEuwo2OIH3GFIW235n7Wtv1TrXrAHkLkP1DQKBgEQE\ndB4QQAxvPfmfrRqI7RX5dpl9nq92Aezo4Re3++5u0i3+dOR+0VySgwle3jrXidVn\ncWRoYGTfAmzHT5zv1W7TQMrBRGNBH0V6BgjDc5HdpPeaRGENhTUUbmPh2hcAEs3P\nQ1btzwg/yrJ7Q8e1VTtbkH53ZwSQKEt8bFQ9AIK7AoGBAOr2hVU++mvM2/iovoZC\ntHf4dn/sJxfdCZbRxIJYde6fM4NZQS5T2YhPS1GiCCTKhiAFlv5DYSPkYofFA3+D\nQmHlihp1Pgo+DWQhufC3k4wP/jZmIatAEQ94QD13oUB5UfE10ZofkanQJCHRHe1M\npQ+3ty7Cg1mUGWf8BeFNpVAb\n-----END PRIVATE KEY-----\n"
  },
  "volt": {
    "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIDojCCAoqgAwIBAgIEBoqCUTANBgkqhkiG9w0BAQsFADBxMQswCQYDVQQGEwJH\nQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWluZHMg\nTHRkMTAwLgYDVQQDDCdjYS4xOTQ3NjYwYi1mYmMwLTQzNDUtYWVjNy0wM2IxNDdk\nNGU0MTcwHhcNMjIxMDI5MTcwNDIxWhcNMjMxMDI5MTcwNDIyWjBxMQswCQYDVQQG\nEwJHQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWlu\nZHMgTHRkMTAwLgYDVQQDDCdjYS4xOTQ3NjYwYi1mYmMwLTQzNDUtYWVjNy0wM2Ix\nNDdkNGU0MTcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDjfmahaIVG\ncMr+5RBwu7AK/648guDDL4w85SaChBQ2xmB4fZGMVmpa/gkCv7VXrsQNwvAiDGN3\n2l1h914cWgblni3uq+lsnQY+mPhKlCI35e59niH7F7kLvunG6Qcp3ODgqVwTVRq/\nGRGf+FB7+Mje1AOX33+LLTN2sKV9wYN5xMlP22HnreCBUa5eL4YnyJkxzqw2xhHm\n8xlwveomDH5Rh71EypjjAORuzwGmlct/L1YfjUlEQ3V/3KkQcMqib5iKxulzHhf0\nZKWXPlDrsEAyunDPOXtDUXkOPyhBBwEe9WruNrff86krT2IfVaLqG/6ed3c+//w0\nzdCGgxYWOixzAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQD\nAgEGMB0GA1UdDgQWBBSucRk3SzUBcmL5QaqMhyfbGTXCXTANBgkqhkiG9w0BAQsF\nAAOCAQEAsmk8vUGJjoy5ZAibthGUt5qYWwpdkWK1cARZQJY4Kpn/lSTZcPlTdEpi\nxEbUZ74IV/YENQaJAT6fV3DAi3xlwsTxnvJRX94orkh/hJxai1FvWq/CaNs6rz1d\nFji4t5iMmkF+77ZOD1mmnDnvlPW2yp3SuQ26+I8XxgMGnVeNo4aIbHpJoAwXh7l9\n6uUHPfNiIQxne2x0gK9uCAIfTbWLv4XkymSrbrEIicQHgTdWNg7r82lX+DC7zghW\nWYtmx/0v4cioBkBLmMVcqsUt29wWIkl/B6ATYIzPb/ibCtKF8NWvSbr5LxRWm52D\nIJEbj3HsC7sGSQKdGAEvg91nwh8fUw==\n-----END CERTIFICATE-----\n",
    "challenge_code": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI=",
    "id": "1947660b-fbc0-4345-aec7-03b147d4e417",
    "address": "192.168.1.69:50908"
  }
}

In the output above, the client_id and cert properties of the credential object are blank. These will be populated once the Volt owner approves the binding request.

Test the connection

Assuming you have created a client configuration file, you can now use it to connect to a Volt.

For example, an initial client configuration file named client.config.json is show below.

This file indicates that the target tdx Volt has id 449a3385-f380-41f7-bd0a-e60caaa403cb and is running locally at the address 192.168.1.194:58913.

{
  "client_name": "connection demo",
  "volt": {
    "id": "449a3385-f380-41f7-bd0a-e60caaa403cb",
    "address": "192.168.1.194:58913",
    "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIDojCCAoqgAwIBAgIEJdz3cjANBgkqhkiG9w0BAQsFADBxMQswCQYDVQQGEwJH\nQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWluZHMg\nTHRkMTAwLgYDVQQDDCdjYS40NDlhMzM4NS1mMzgwLTQxZjctYmQwYS1lNjBjYWFh\nNDAzY2IwHhcNMjIwODI0MTIzNTM1WhcNMjMwODI0MTIzNTM2WjBxMQswCQYDVQQG\nEwJHQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWlu\nZHMgTHRkMTAwLgYDVQQDDCdjYS40NDlhMzM4NS1mMzgwLTQxZjctYmQwYS1lNjBj\nYWFhNDAzY2IwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDASh4j1XKy\nEhMcwzwx00wIywM3pC9JzywpFR1kc20ZxOXBZnOxY/Lm3eOZx9/ml1yk5CnMPx68\nZE3abyZ7/6VhPk110GhpxZO2fyQ+Zgx87Cu1mKSoIXbY6fnLJqsL7vTKOAk6jlw/\nfD/IGoR9DDskAaMq/Wm4lBJG3YdnOMnvwfgNGXWmjsrzYJP92HcPwwdEWf2qG/VF\nU3mP/yAq1DVshPldJqZnWMbPY8FR+9ZAkJCp5v/+tvjNupiduVt3uH9XytdMbOIk\n4ktZa8X3onW0VVcD5YQ9ue9AJRnVhju51Et24ykLG+FgPpbrIjPzsfyTBPJ8qOnB\nzWBEFANMkLVVAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQD\nAgEGMB0GA1UdDgQWBBQlUXr/lsH2y1PKI4cHBKEq7xs1UDANBgkqhkiG9w0BAQsF\nAAOCAQEANigh6q5OURhzQ/VV2LkyuL2GEkCh/aQ8LEO3Dwr+SD8cgNhJ9QrRe325\nYcssyBVf5aXvUccuA8tgF07JfuATtNt8CDPSC6g9FBw5xco1P6a7h9bM1dTdXxRJ\nke168Ys3wgBTnogYOKx75zZEMwZsHFxHEfC3q5DA6V+ZVO3pcv7j2YCv+Eh6eD/U\n4DAUKMY4ZWRPgrL8H32CgjaHgP+tV3GbNgyGeVA4gplmLFj06kfk283dVku4gJ2Y\nx2rY/4Kfv/zFgAOy7b4jnx3DtPUR3ddxJwm49tJkzBs14toukHeOPsGVmBPy9naf\ndBl4q9vffIKV/xDqqIOz7GsByZdyUw==\n-----END CERTIFICATE-----\n",
    "challenge_code": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI="
  }
}

We can use the Volt CLI to issue a request to the Volt. Here we ask the tdx Volt to list all the resources in the clients ‘Home’ folder (indicated by ’.’). This may yield no results if you have only just bound to the Volt.

./volt list . -c client.config.json

Now try uploading a file to the home folder.

./volt upload path/to/some/file . -c client.config.json

And then list the resources again:

./volt list . -c client.config.json

The tdx Volt CLI will look for a client configuration file named `volt.config.json` if none is specified on the command line. So if you use this name to store your configuration details there is no need to specify the `-c client.config.json` parameter.

Relay connections

The discussion so far has related to peer-to-peer connections. However in many scenarios it will be necessary to connect to a Volt that is not on the same local network as the client, and may not be accessible via the wider internet because it is behind a firewall.

In order to be able to connect to remote Volts in these scenarios you can utilise the concept of a Relay Volt, which is described in more detail here.

The first step is to establish the configuration of the Relay Volt you would like to use.

It is then a case of adding another Volt configuration object describing the Relay Volt as a sub-property of the target volt configuration. This relay property takes the same format as the standard Volt configuration:

{
  "client_name": "your friendly name",
  "volt": {
    "id": "<volt id>",
    "ca_pem": "<volt CA certificate>",
    "challenge_code": "<volt challenge code>",
    "relay": {
      "id": "<Relay volt id>",
      "ca_pem": "<Relay volt CA certificate>",
    }
  }
}

You can use the same discovery options as described above for obtaining a Volt configuration, for example, via a DID lookup or a HTTP discovery:

{
  "client_name": "your friendly name",
  "volt": {
    ...
    "relay": "did:tdx:349970a5-9f3a-4ac6-aef3-75881e7b87e7"
  }
}

{
  "client_name": "your friendly name",
  "volt": {
    ...
    "relay": "https://cloud.tdxvolt.com"
  },
}

The addition of the `relay` property is the only addition that is required to a standard client configuration to force the client libraries to connect via a Relay Volt. However if the configuration has previously been used to bind locally, it may be necessary to delete the `credential.cert` property to force the client library to initialise the Relay parameters correctly.

Appendix

Client configuration definition

The JSONSchema definition of the Volt client configuration object is shown below.

Note that the client_name and crytpo properties describe the client and its credentials, and the remainder of the document (the volt property) is simply an instance of a tdx Volt configuration object.

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "https://tdxvolt.com/schemas/volt-client-connection",
  "type": "object",
  "title": "Volt client connection schema",
  "required": ["client_name", "credential", "volt"],
  "properties": {
    "client_name": {
      "type": "string",
      "title": "A human-readable name of the client.",
      "examples": ["Alice"]
    },
    "credential": {
      "type": "object",
      "title": "The cryptographic credentials identifying the client.",
      "required": ["client_id", "key"],
      "properties": {
        "client_id": {
          "type": "string",
          "title": "The UUID assigned to the client by the Volt during the binding phase.",
          "examples": ["c65ab887-35d2-4955-b777-cbc9fba32dd1"]
        },
        "key": {
          "type": "string",
          "title": "The PEM-encoded key of the client. This can be encrypted.",
          "examples": [
            "-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFHDBOBgkqhkiG9w0BBQ0wQTApBgkqhkiG9w0BBQwwHAQInAzvld0a3a4CAggA\nMAwGCCqGSIb3DQIJBQAwFAYIKoZIhvcNAwcECKXsm0+tgmFHBIIEyD+ka/hmH18r\nUfMz8iBPAyD1brAIo5ePF9RYGC95doK6hsKG2wHkXrVPZD8Qj/xTBTpvmTIzLUPb\n4sDUK/mP3CRB2wAFC0UvD4nn0DL/MnRm6C9SzoQ/nP/vN6l1g2cgc+6UpvDhS8r/\nTiXitwO5UoflZyUHCROBdqvN8fsA+J6AjkwBgI//IKxnMTNGRlwhATjbcPRbjowy\nx1lvmMhxTmSxOwNzD5xiHw/aHx7ElFGLCNsXQteGvxN0EEh1HhKpN8i0U2kouzcw\n3FU5RodlpbVvE64SYBqFwlH9p4Sog2qWTpWHgavytyMDxrl+K/q/QJVftMk5kCv8\nr78G/4s9TrOZ3rBk0fZQ+c+EGB/zSQArEhOuFKoN3ANWeGeAZB6euNqaMmMTgk+A\n37n1sNKf56hRQMfTk/28/ZCIDhdQjI6de2DH20RHwOQv+iQSI8D/8vbNRaaDcrkP\nwBa+4c8rocBJS5+bAaydXSf3ymH5Dz4Qi1Ha1rzK27VeZyOoAdKqjj5mhYSs/zsl\n5A63XpSf00mXcRyPIVm3jXEWEK01mqJYxmfR8vFrr08U8zA+pZPiz24hSRIWflT9\n3ZKMpKfo2rUuBERHgTs1TMZ/bfl1vY8NQ7VN4SyLXXBLDGLP7XfNpQIBUs0IFk2T\nyESHa7A0kZDL9+5TZcUtpSeoTYYy1MOB8TJXPVKtvKgrLLpECYRetRIpcK4cXmTP\nhlytaZdUd0yqw+mU4Nhcu602W96U0GwQjmRhF+hBdShX1PkRMvwO7DO2H3mm/iQd\nwc1j3ZpVGFfZZXHq8oAf1LyV76vX33ah8p7k9qLAXFJKlujFadzMw4J/drC42Bva\nN1nLU1FQ3ScAgdg3POOYqLGgoLskS/spiOz/VNMlMt1oGttD+UMF7dNNO70YIqNG\n/a40IxuYX2qYaZGxWfPmh+EU6NLcWQxRWb/zQTdsnlw9YMnIyXBofNbGMOqD3VzE\nE/n1G6ejuXMBfkb7/3YuLVvHPmxi7IDyiIaAvMqyr4zYKe2eAhj0VnhwOYFz7egg\nSdvgdDID4dcgjgCZdvyDBq4eL/E5Xwzu3u3G5qA+xEJAOBBfB7p/wcJ9Eni5DW/4\nisbLVEnkKxs5Hig1M8FKeDMgHbA4lHFQEy6XqczkOpxDqcx1qJMKFTSg9tVP3xJe\nq8yNspDpNt6wtg3e8K+OD2Vr2uvJjobnelYTMlN4hDGmTzVw0uwl2n/6QF5Oc88c\nXDrAviAzEBH0KiXn3RzZ4X+SHe2jVht1l0eqxNmfObekLOOL0sYdb+fYVDzQxiqM\n2ANV+ZG53mwVvhtQneFQ2j4vyn+FEBm0eTuBRfz5MuR1x8c8/5xisBXL19rhd793\njg86IW7YJ39vs6wBh5XvOSk314DxhLK+zbJrIk9mfNuZjdwNLdfBN4bdmI83RU+W\nwYlR2pjy1nax70opXOrvq2GwLdKaX/AwJqRWvFUbp6vBln/ukSe+W/bbOjm7vHk6\neUGW1HkTqTcU5H8UsnIvkAYWaPJzFqd2A6xbO+B1SvhcrZWI+XVHmm1RVmAvuq90\nR4k1/1tt+yGqjOv+9/4R+P9tSaFpDFI3y1VSH3jMZ/tQ23A8jj78EGqvynN/cCMI\nl+TGCtIBH2kefKK/ASE0BQ==\n-----END ENCRYPTED PRIVATE KEY-----\n"
          ]
        }
      }
    },
    "volt": {
      "type": "object",
      "title": "The Volt configuration information.",
      "properties": {
        "$ref": "https://tdxvolt.com/schemas/volt-configuration"
      }
    }
  },
  "examples": [
    {
      "client_name": "CLI",
      "credential": {
        "client_id": "c65ab887-35d2-4955-b777-cbc9fba32dd1",
        "key": "-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFHDBOBgkqhkiG9w0BBQ0wQTApBgkqhkiG9w0BBQwwHAQInAzvld0a3a4CAggA\nMAwGCCqGSIb3DQIJBQAwFAYIKoZIhvcNAwcECKXsm0+tgmFHBIIEyD+ka/hmH18r\nUfMz8iBPAyD1brAIo5ePF9RYGC95doK6hsKG2wHkXrVPZD8Qj/xTBTpvmTIzLUPb\n4sDUK/mP3CRB2wAFC0UvD4nn0DL/MnRm6C9SzoQ/nP/vN6l1g2cgc+6UpvDhS8r/\nTiXitwO5UoflZyUHCROBdqvN8fsA+J6AjkwBgI//IKxnMTNGRlwhATjbcPRbjowy\nx1lvmMhxTmSxOwNzD5xiHw/aHx7ElFGLCNsXQteGvxN0EEh1HhKpN8i0U2kouzcw\n3FU5RodlpbVvE64SYBqFwlH9p4Sog2qWTpWHgavytyMDxrl+K/q/QJVftMk5kCv8\nr78G/4s9TrOZ3rBk0fZQ+c+EGB/zSQArEhOuFKoN3ANWeGeAZB6euNqaMmMTgk+A\n37n1sNKf56hRQMfTk/28/ZCIDhdQjI6de2DH20RHwOQv+iQSI8D/8vbNRaaDcrkP\nwBa+4c8rocBJS5+bAaydXSf3ymH5Dz4Qi1Ha1rzK27VeZyOoAdKqjj5mhYSs/zsl\n5A63XpSf00mXcRyPIVm3jXEWEK01mqJYxmfR8vFrr08U8zA+pZPiz24hSRIWflT9\n3ZKMpKfo2rUuBERHgTs1TMZ/bfl1vY8NQ7VN4SyLXXBLDGLP7XfNpQIBUs0IFk2T\nyESHa7A0kZDL9+5TZcUtpSeoTYYy1MOB8TJXPVKtvKgrLLpECYRetRIpcK4cXmTP\nhlytaZdUd0yqw+mU4Nhcu602W96U0GwQjmRhF+hBdShX1PkRMvwO7DO2H3mm/iQd\nwc1j3ZpVGFfZZXHq8oAf1LyV76vX33ah8p7k9qLAXFJKlujFadzMw4J/drC42Bva\nN1nLU1FQ3ScAgdg3POOYqLGgoLskS/spiOz/VNMlMt1oGttD+UMF7dNNO70YIqNG\n/a40IxuYX2qYaZGxWfPmh+EU6NLcWQxRWb/zQTdsnlw9YMnIyXBofNbGMOqD3VzE\nE/n1G6ejuXMBfkb7/3YuLVvHPmxi7IDyiIaAvMqyr4zYKe2eAhj0VnhwOYFz7egg\nSdvgdDID4dcgjgCZdvyDBq4eL/E5Xwzu3u3G5qA+xEJAOBBfB7p/wcJ9Eni5DW/4\nisbLVEnkKxs5Hig1M8FKeDMgHbA4lHFQEy6XqczkOpxDqcx1qJMKFTSg9tVP3xJe\nq8yNspDpNt6wtg3e8K+OD2Vr2uvJjobnelYTMlN4hDGmTzVw0uwl2n/6QF5Oc88c\nXDrAviAzEBH0KiXn3RzZ4X+SHe2jVht1l0eqxNmfObekLOOL0sYdb+fYVDzQxiqM\n2ANV+ZG53mwVvhtQneFQ2j4vyn+FEBm0eTuBRfz5MuR1x8c8/5xisBXL19rhd793\njg86IW7YJ39vs6wBh5XvOSk314DxhLK+zbJrIk9mfNuZjdwNLdfBN4bdmI83RU+W\nwYlR2pjy1nax70opXOrvq2GwLdKaX/AwJqRWvFUbp6vBln/ukSe+W/bbOjm7vHk6\neUGW1HkTqTcU5H8UsnIvkAYWaPJzFqd2A6xbO+B1SvhcrZWI+XVHmm1RVmAvuq90\nR4k1/1tt+yGqjOv+9/4R+P9tSaFpDFI3y1VSH3jMZ/tQ23A8jj78EGqvynN/cCMI\nl+TGCtIBH2kefKK/ASE0BQ==\n-----END ENCRYPTED PRIVATE KEY-----\n"
      },
      "volt": {
        "id": "1947660b-fbc0-4345-aec7-03b147d4e417",
        "display_name": "macBook (intel)",
        "address": "192.168.1.69:50908",
        "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA435moWiFRnDK/uUQcLuw\nCv+uPILgwy+MPOUmgoQUNsZgeH2RjFZqWv4JAr+1V67EDcLwIgxjd9pdYfdeHFoG\n5Z4t7qvpbJ0GPpj4SpQiN+XufZ4h+xe5C77pxukHKdzg4KlcE1UavxkRn/hQe/jI\n3tQDl99/iy0zdrClfcGDecTJT9th563ggVGuXi+GJ8iZMc6sNsYR5vMZcL3qJgx+\nUYe9RMqY4wDkbs8BppXLfy9WH41JREN1f9ypEHDKom+Yisbpcx4X9GSllz5Q67BA\nMrpwzzl7Q1F5Dj8oQQcBHvVq7ja33/OpK09iH1Wi6hv+nnd3Pv/8NM3QhoMWFjos\ncwIDAQAB\n-----END PUBLIC KEY-----\n",
        "fingerprint": "EPhBiNvb5RAvM1FjzrrrKYP7ggMBaJ5wM7KMTJjBfPaM",
        "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIDojCCAoqgAwIBAgIEBoqCUTANBgkqhkiG9w0BAQsFADBxMQswCQYDVQQGEwJH\nQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWluZHMg\nTHRkMTAwLgYDVQQDDCdjYS4xOTQ3NjYwYi1mYmMwLTQzNDUtYWVjNy0wM2IxNDdk\nNGU0MTcwHhcNMjIxMDI5MTcwNDIxWhcNMjMxMDI5MTcwNDIyWjBxMQswCQYDVQQG\nEwJHQjEUMBIGA1UEBwwLU291dGhhbXB0b24xGjAYBgNVBAoMEW5xdWlyaW5nTWlu\nZHMgTHRkMTAwLgYDVQQDDCdjYS4xOTQ3NjYwYi1mYmMwLTQzNDUtYWVjNy0wM2Ix\nNDdkNGU0MTcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDjfmahaIVG\ncMr+5RBwu7AK/648guDDL4w85SaChBQ2xmB4fZGMVmpa/gkCv7VXrsQNwvAiDGN3\n2l1h914cWgblni3uq+lsnQY+mPhKlCI35e59niH7F7kLvunG6Qcp3ODgqVwTVRq/\nGRGf+FB7+Mje1AOX33+LLTN2sKV9wYN5xMlP22HnreCBUa5eL4YnyJkxzqw2xhHm\n8xlwveomDH5Rh71EypjjAORuzwGmlct/L1YfjUlEQ3V/3KkQcMqib5iKxulzHhf0\nZKWXPlDrsEAyunDPOXtDUXkOPyhBBwEe9WruNrff86krT2IfVaLqG/6ed3c+//w0\nzdCGgxYWOixzAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQD\nAgEGMB0GA1UdDgQWBBSucRk3SzUBcmL5QaqMhyfbGTXCXTANBgkqhkiG9w0BAQsF\nAAOCAQEAsmk8vUGJjoy5ZAibthGUt5qYWwpdkWK1cARZQJY4Kpn/lSTZcPlTdEpi\nxEbUZ74IV/YENQaJAT6fV3DAi3xlwsTxnvJRX94orkh/hJxai1FvWq/CaNs6rz1d\nFji4t5iMmkF+77ZOD1mmnDnvlPW2yp3SuQ26+I8XxgMGnVeNo4aIbHpJoAwXh7l9\n6uUHPfNiIQxne2x0gK9uCAIfTbWLv4XkymSrbrEIicQHgTdWNg7r82lX+DC7zghW\nWYtmx/0v4cioBkBLmMVcqsUt29wWIkl/B6ATYIzPb/ibCtKF8NWvSbr5LxRWm52D\nIJEbj3HsC7sGSQKdGAEvg91nwh8fUw==\n-----END CERTIFICATE-----\n",
        "challenge_code": "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI="
      }
    }
  ]
}