mirror of
https://github.com/corda/corda.git
synced 2025-04-07 19:34:41 +00:00
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.
This commit is contained in:
parent
ab1deaac99
commit
7eca7515d6
@ -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 <https://github.com/corda/spring-webserver>`_.
|
||||
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 <https://github.com/corda/spring-webserver>`_.
|
||||
|
||||
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:
|
||||
|
@ -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
|
||||
|
Loading…
x
Reference in New Issue
Block a user