From b98a3881e5c2d0dbcd6dd0c0c7f3133350c09b2d Mon Sep 17 00:00:00 2001 From: Stefano Baghino <43749967+stefanobaghino-da@users.noreply.github.com> Date: Wed, 31 Mar 2021 13:30:54 +0200 Subject: [PATCH] Non-repudiation: documentation (#9288) * Non-repudiation: documentation changelog_begin [Runtime Components] New feature: the non-repudiation middleware is now available as an early access feature, please have a look at its page in the early access section of the documentation to learn more changelog_end Closes #8659 * Remove exceprt from Wikipedia * Fix typo * Fix naming * Address https://github.com/digital-asset/daml/pull/9288#discussion_r604647664 * Address https://github.com/digital-asset/daml/pull/9288#discussion_r604651195 * Address https://github.com/digital-asset/daml/pull/9288#discussion_r604792871 --- docs/source/index.rst | 1 + docs/source/tools/non-repudiation.rst | 81 +++++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/source/tools/non-repudiation.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index e4dd711b97..34e4e4c894 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -116,6 +116,7 @@ Daml Documentation daml-integration-kit/index tools/visual concepts/interoperability + tools/non-repudiation .. toctree:: :titlesonly: diff --git a/docs/source/tools/non-repudiation.rst b/docs/source/tools/non-repudiation.rst new file mode 100644 index 0000000000..9e79cfb458 --- /dev/null +++ b/docs/source/tools/non-repudiation.rst @@ -0,0 +1,81 @@ +.. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +Non-repudiation +############### + +The non-repudiation middleware, API and client library are only available in the +`Daml Connect Enterprise Edition `_ and are currently an +:doc:`Early Access Feature in Alpha status `. + +When you are issuing a command over the Ledger API, there is an implicit trust assumption between the issuer of the command and the operator of the participant +that the latter will not issue commands on behalf of the former. + +The non-repudiation middleware and its client library are a Daml Connect Enterprise Edition exclusive feature that allows ledger operators to run +participant nodes that will require each command to come with a verifiable cryptographic signature, which will persisted by the operator. As the +sole owner of the private key used to sign the command, the authenticity of the command is thus verified and preserved, ensuring that an operator +cannot issue a command on behalf of the user and that the user cannot repudiate the command. + +Note that this is an early access feature: its status is currently under development and further feedback can change how certain details might work +once the feature is declared a stable part of Daml Connect Enterprise Edition. If you are interested in this feature, you are welcome to use it and +give us feedback that will shape how this feature will ultimately come to be. + +Architecture +~~~~~~~~~~~~ + +The non-repudiation system consists of three components: + +- the non-repudiation middleware is a reverse proxy that sits in front of the Ledger API that verifies command signatures and forwards the signed command to the actual participant node +- the non-repudiation API is a web server used by the operator to upload new certificates and verify repudiation claims +- the non-repudiation client is a gRPC interceptor that can be used alongside any gRPC client on the JVM, including the official Java bindings, that will ensure that commands are signed with a given private key + +Running the server-side components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The server-side components are the middleware and the API. Both can be run as a single process by running the non-repudiation fat JAR provided as part of Daml Connect Enterprise Edition. + +Note that at the current stage you need to also have a PostgreSQL server running where signed commands will be persisted. + +The following example shows how to run the non-repudiation server components by connecting to a participant at localhost:6865 and proxying it to the 6866 port, using the given PostgreSQL instance to persist signed commands and certificates. + +.. code-block:: sh + + java -jar /path/to/the/non-repudiation.jar --ledger-host localhost --ledger-port 6865 --proxy-port 6866 --jdbc url=jdbc:postgresql:nr,user=nr,password=nr + +For details on how to run them, please run the fat JAR with the ``--help`` command line option. + +Using the client +~~~~~~~~~~~~~~~~ + +The client is a gRPC interceptor which is available to Daml Connect Enterprise Edition users (hence, it's not available on Maven Central). + +The Maven coordinates for the library are `com.daml:non-repudiation-client`. + +The following example shows how to use this interceptor with the official Java bindings + +.. code-block:: java + + PrivateKey key = readYourPrivateKey(); + X509Certificate certificate = readYourX509Certificate(); + NettyChannelBuilder builder = NettyChannelBuilder.forAddress(hostname, port); + builder.intercept(SigningInterceptor.signCommands(key, certificate)); + DamlLedgerClient client = DamlLedgerClient.newBuilder(builder).build(); + client.connect(); + +Non-repudiation over the HTTP JSON API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The non-repudiation middleware acts *exclusively* as a reverse proxy in front of the Ledger API server: if you want to use the HTTP JSON API you will need to +run your own HTTP JSON API server and start it with a certificate that will be used to sign every command issued by the HTTP JSON API to the participant. + +The HTTP JSON API bundled with the Daml Connect Enterprise Edition has the following extra command line options that *must* be used to run an HTTP JSON API +server against the non-repudiation middleware: + +- `--non-repudiation-certificate-path`: the path to the X.509 certificate containing the public counterpart to the private key that will be used to sign the commands +- `--non-repudiation-private-key-path`: the path to the file containing the private key that will be used to sign the commands +- `--non-repudiation-private-key-algorithm`: the name of the cryptographic algorithm of the private key (for a list of names supported in the OpenJDK: https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyFactory) + +TLS support +~~~~~~~~~~~ + +At the current stage the non-repudiation feature does not support running against secure Ledger API servers. This will be added as part of stabilizing this feature.