From 7eca7515d6c38681fe4c657d15974cd3e83c51dd Mon Sep 17 00:00:00 2001 From: Joel Dudley Date: Tue, 30 Oct 2018 18:06:01 +0000 Subject: [PATCH] Clarifies that only one serialisation mechanism is required. Clarifies dependencies required for Client RPC. (#4135) * Makes it clear that only one serialisation mechanism is required. Clarifies dependencies required for Client RPC. * Addresses review feedback. --- docs/source/clientrpc.rst | 21 ++++++++++++--------- docs/source/serialization.rst | 27 ++++++++++++++------------- 2 files changed, 26 insertions(+), 22 deletions(-) diff --git a/docs/source/clientrpc.rst b/docs/source/clientrpc.rst index 7390f69a55..dbcee97aeb 100644 --- a/docs/source/clientrpc.rst +++ b/docs/source/clientrpc.rst @@ -11,20 +11,23 @@ Interacting with a node Overview -------- -You should interact with your node using the `CordaRPCClient`_ library. This library that allows you to easily -write clients in a JVM-compatible language to interact with a running node. The library connects to the node using a -message queue protocol and then provides a simple RPC interface to interact with the node. You make calls on a JVM -object as normal, and the marshalling back and forth is handled for you. +To interact with your node, you need to write a client in a JVM-compatible language using the `CordaRPCClient`_ class. +This class allows you to connect to your node via a message queue protocol and provides a simple RPC interface for +interacting with the node. You make calls on a JVM object as normal, and the marshalling back-and-forth is handled for +you. .. warning:: The built-in Corda webserver is deprecated and unsuitable for production use. If you want to interact with - your node via HTTP, you will need to stand up your own webserver, then create an RPC connection between your node - and this webserver using the `CordaRPCClient`_ library. You can find an example of how to do this using the popular - Spring Boot server `here `_. + your node via HTTP, you will need to stand up your own webserver that connects to your node using the + `CordaRPCClient`_ class. You can find an example of how to do this using the popular Spring Boot server + `here `_. Connecting to a node via RPC ---------------------------- -`CordaRPCClient`_ provides a ``start`` method that takes the node's RPC address and returns a `CordaRPCConnection`_. -`CordaRPCConnection`_ provides a ``proxy`` method that takes an RPC username and password and returns a `CordaRPCOps`_ +To use `CordaRPCClient`_, you must add ``net.corda:corda-rpc:$corda_release_version`` as a ``cordaCompile`` dependency +in your client's ``build.gradle`` file. + +`CordaRPCClient`_ has a ``start`` method that takes the node's RPC address and returns a `CordaRPCConnection`_. +`CordaRPCConnection`_ has a ``proxy`` method that takes an RPC username and password and returns a `CordaRPCOps`_ object that you can use to interact with the node. Here is an example of using `CordaRPCClient`_ to connect to a node and log the current time on its internal clock: diff --git a/docs/source/serialization.rst b/docs/source/serialization.rst index 00f4baa07a..b394754147 100644 --- a/docs/source/serialization.rst +++ b/docs/source/serialization.rst @@ -39,22 +39,23 @@ weakly or untyped string-based serialisation schemes like JSON or XML. The prima Whitelisting ------------ -In classic Java serialization, any class on the JVM classpath can be deserialized. This has shown to be a source of exploits -and vulnerabilities by exploiting the large set of 3rd party libraries on the classpath as part of the dependencies of -a JVM application and a carefully crafted stream of bytes to be deserialized. In Corda, we prevent just any class from -being deserialized (and pro-actively during serialization) by insisting that each object's class belongs on a whitelist -of allowed classes. +In classic Java serialization, any class on the JVM classpath can be deserialized. This is a source of exploits and +vulnerabilities that exploit the large set of third-party libraries that are added to the classpath as part of a JVM +application's dependencies and carefully craft a malicious stream of bytes to be deserialized. In Corda, we strictly +control which classes can be deserialized (and, pro-actively, serialized) by insisting that each (de)serializable class +is part of a whitelist of allowed classes. -Classes get onto the whitelist via one of three mechanisms: +To add a class to the whitelist, you must use either of the following mechanisms: -#. Via the ``@CordaSerializable`` annotation. In order to whitelist a class, this annotation can be present on the - class itself, on any of the super classes or on any interface implemented by the class or super classes or any - interface extended by an interface implemented by the class or superclasses. -#. By implementing the ``SerializationWhitelist`` interface and specifying a list of `whitelist` classes. -#. Via the built in Corda whitelist (see the class ``DefaultWhitelist``). Whilst this is not user editable, it does list - common JDK classes that have been whitelisted for your convenience. +#. Add the ``@CordaSerializable`` annotation to the class. This annotation can be present on the + class itself, on any super class of the class, on any interface implemented by the class or its super classes, or any + interface extended by an interface implemented by the class or its super classes. +#. Implement the ``SerializationWhitelist`` interface and specify a list of whitelisted classes. -The annotation is the preferred method for whitelisting. An example is shown in :doc:`tutorial-clientrpc-api`. +There is also a built-in Corda whitelist (see the ``DefaultWhitelist`` class) that whitelists common JDK classes for +convenience. This whitelist is not user-editable. + +The annotation is the preferred method for whitelisting. An example is shown in :doc:`tutorial-clientrpc-api`. It's reproduced here as an example of both ways you can do this for a couple of example classes. .. literalinclude:: example-code/src/main/kotlin/net/corda/docs/kotlin/ClientRpcTutorial.kt