mirror of
https://github.com/digital-asset/daml.git
synced 2024-09-20 09:17:43 +03:00
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
This commit is contained in:
parent
7c3d082ca0
commit
b98a3881e5
@ -116,6 +116,7 @@ Daml Documentation
|
|||||||
daml-integration-kit/index
|
daml-integration-kit/index
|
||||||
tools/visual
|
tools/visual
|
||||||
concepts/interoperability
|
concepts/interoperability
|
||||||
|
tools/non-repudiation
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:titlesonly:
|
:titlesonly:
|
||||||
|
81
docs/source/tools/non-repudiation.rst
Normal file
81
docs/source/tools/non-repudiation.rst
Normal file
@ -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 <https://www.digitalasset.com/products/daml-connect>`_ and are currently an
|
||||||
|
:doc:`Early Access Feature in Alpha status </support/status-definitions>`.
|
||||||
|
|
||||||
|
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.
|
Loading…
Reference in New Issue
Block a user