* CORDA-1343 Make the RPCClient ssl constructors public. Clean up broker authentication logic * CORDA-1343 small fix * CORDA-1343 cleanup * CORDA-1343 fixed api changes script * CORDA-1343 fixed merge * CORDA-1343 removed unused property * CORDA-1343 add separate p2p and rpc node users * CORDA-1343 remove test configuration * CORDA-1343 fix tests * CORDA-1343 address core review comments * CORDA-1343 some documentation and adding createWithSsl method for a haAddressPool * CORDA-1343 clean up the CordaRPCClient interface * CORDA-1343 add internal shell test * CORDA-1343 address code review comments * CORDA-1343 split the internalShell user from the System Rpc user * CORDA-1343 fix test * CORDA-1343 Add warning when certificateChainCheckPolicies is being configured * CORDA-1343 Address code review changes * CORDA-1343 fix merge * CORDA-1343 added test, docs, clarify comments * CORDA-1343 clean up docs * CORDA-1343 fix api * CORDA-1343 fix merge * CORDA-1343 fix merge * CORDA-1343 fix merge * CORDA-1343 fix merge
14 KiB
Client RPC
Overview
Corda provides a client 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 Java object as normal, and the marshalling back and forth is handled for you.
The starting point for the client library is the CordaRPCClient class. CordaRPCClient provides a start
method that returns a CordaRPCConnection. A CordaRPCConnection allows you to access an implementation of the CordaRPCOps interface with proxy
in Kotlin or getProxy()
in Java. The observables that are returned by RPC operations can be subscribed to in order to receive an ongoing stream of updates from the node. More detail on this functionality is provided in the docs for the proxy
method.
Warning
The returned CordaRPCConnection is somewhat expensive to create and consumes a small amount of server side resources. When you're done with it, call close
on it. Alternatively you may use the use
method on CordaRPCClient which cleans up automatically after the passed in lambda finishes. Don't create a new proxy for every call you make - reuse an existing one.
For a brief tutorial on using the RPC API, see tutorial-clientrpc-api
.
RPC permissions
For a node's owner to interact with their node via RPC, they must define one or more RPC users. Each user is authenticated with a username and password, and is assigned a set of permissions that control which RPC operations they can perform. Permissions are not required to interact with the node via the shell, unless the shell is being accessed via SSH.
RPC users are created by adding them to the rpcUsers
list in the node's node.conf
file:
rpcUsers=[
{
username=exampleUser
password=examplePass
permissions=[]
}
...
]
By default, RPC users are not permissioned to perform any RPC operations.
Granting flow permissions
You provide an RPC user with the permission to start a specific flow using the syntax StartFlow.<fully qualified flow name>
:
rpcUsers=[
{
username=exampleUser
password=examplePass
permissions=[
"StartFlow.net.corda.flows.ExampleFlow1",
"StartFlow.net.corda.flows.ExampleFlow2"
]
}
...
]
You can also provide an RPC user with the permission to start any flow using the syntax InvokeRpc.startFlow
:
rpcUsers=[
{
username=exampleUser
password=examplePass
permissions=[
"InvokeRpc.startFlow"
]
}
...
]
Granting other RPC permissions
You provide an RPC user with the permission to perform a specific RPC operation using the syntax InvokeRpc.<rpc method name>
:
rpcUsers=[
{
username=exampleUser
password=examplePass
permissions=[
"InvokeRpc.nodeInfo",
"InvokeRpc.networkMapSnapshot"
]
}
...
]
Granting all permissions
You can provide an RPC user with the permission to perform any RPC operation (including starting any flow) using the ALL
permission:
rpcUsers=[
{
username=exampleUser
password=examplePass
permissions=[
"ALL"
]
}
...
]
RPC security management
Setting rpcUsers
provides a simple way of granting RPC permissions to a fixed set of users, but has some obvious shortcomings. To support use cases aiming for higher security and flexibility, Corda offers additional security features such as:
- Fetching users credentials and permissions from an external data source (e.g.: a remote RDBMS), with optional in-memory caching. In particular, this allows credentials and permissions to be updated externally without requiring nodes to be restarted.
- Password stored in hash-encrypted form. This is regarded as must-have when security is a concern. Corda currently supports a flexible password hash format conforming to the Modular Crypt Format provided by the Apache Shiro framework
These features are controlled by a set of options nested in the security
field of node.conf
. The following example shows how to configure retrieval of users credentials and permissions from a remote database with passwords in hash-encrypted format and enable in-memory caching of users data:
security = {
authService = {
dataSource = {
type = "DB",
passwordEncryption = "SHIRO_1_CRYPT",
connection = {
jdbcUrl = "<jdbc connection string>"
username = "<db username>"
password = "<db user password>"
driverClassName = "<JDBC driver>"
}
}
options = {
cache = {
expireAfterSecs = 120
maxEntries = 10000
}
}
}
}
It is also possible to have a static list of users embedded in the security
structure by specifying a dataSource
of INMEMORY
type:
security = {
authService = {
dataSource = {
type = "INMEMORY",
users = [
{
username = "<username>",
password = "<password>",
permissions = ["<permission 1>", "<permission 2>", ...]
},
...
]
}
}
}
Warning
A valid configuration cannot specify both the rpcUsers
and security
fields. Doing so will trigger an exception at node startup.
Authentication/authorisation data
The dataSource
structure defines the data provider supplying credentials and permissions for users. There exist two supported types of such data source, identified by the dataSource.type
field:
- INMEMORY
A static list of user credentials and permissions specified by the
users
field.- DB
An external RDBMS accessed via the JDBC connection described by
connection
. Note that, unlike theINMEMORY
case, in a user database permissions are assigned to roles rather than individual users. The current implementation expects the database to store data according to the following schema:
- Table
users
containing columnsusername
andpassword
. Theusername
column must have unique values.- Table
user_roles
containing columnsusername
androle_name
associating a user to a set of roles.- Table
roles_permissions
containing columnsrole_name
andpermission
associating a role to a set of permission strings.Note
There is no prescription on the SQL type of each column (although our tests were conducted on
username
androle_name
declared of SQL typeVARCHAR
andpassword
ofTEXT
type). It is also possible to have extra columns in each table alongside the expected ones.
Password encryption
Storing passwords in plain text is discouraged in applications where security is critical. Passwords are assumed to be in plain format by default, unless a different format is specified by the passwordEncryption
field, like:
passwordEncryption = SHIRO_1_CRYPT
SHIRO_1_CRYPT
identifies the Apache Shiro fully reversible Modular Crypt Format, it is currently the only non-plain password hash-encryption format supported. Hash-encrypted passwords in this format can be produced by using the Apache Shiro Hasher command line tool.
Caching user accounts data
A cache layer on top of the external data source of users credentials and permissions can significantly improve performances in some cases, with the disadvantage of causing a (controllable) delay in picking up updates to the underlying data. Caching is disabled by default, it can be enabled by defining the options.cache
field in security.authService
, for example:
options = {
cache = {
expireAfterSecs = 120
maxEntries = 10000
}
}
This will enable a non-persistent cache contained in the node's memory with maximum number of entries set to maxEntries
where entries are expired and refreshed after expireAfterSecs
seconds.
Observables
The RPC system handles observables in a special way. When a method returns an observable, whether directly or as a sub-object of the response object graph, an observable is created on the client to match the one on the server. Objects emitted by the server-side observable are pushed onto a queue which is then drained by the client. The returned observable may even emit object graphs with even more observables in them, and it all works as you would expect.
This feature comes with a cost: the server must queue up objects emitted by the server-side observable until you download them. Note that the server side observation buffer is bounded, once it fills up the client is considered slow and kicked. You are expected to subscribe to all the observables returned, otherwise client-side memory starts filling up as observations come in. If you don't want an observable then subscribe then unsubscribe immediately to clear the client-side buffers and to stop the server from streaming. If your app quits then server side resources will be freed automatically.
Warning
If you leak an observable on the client side and it gets garbage collected, you will get a warning printed to the logs and the observable will be unsubscribed for you. But don't rely on this, as garbage collection is non-deterministic.
Futures
A method can also return a ListenableFuture
in its object graph and it will be treated in a similar manner to observables. Calling the cancel
method on the future will unsubscribe it from any future value and release any resources.
Versioning
The client RPC protocol is versioned using the node's Platform Version (see versioning
). When a proxy is created the server is queried for its version, and you can specify your minimum requirement. Methods added in later versions are tagged with the @RPCSinceVersion
annotation. If you try to use a method that the server isn't advertising support of, an UnsupportedOperationException
is thrown. If you want to know the version of the server, just use the protocolVersion
property (i.e. getProtocolVersion
in Java).
Thread safety
A proxy is thread safe, blocking, and allows multiple RPCs to be in flight at once. Any observables that are returned and you subscribe to will have objects emitted in order on a background thread pool. Each Observable stream is tied to a single thread, however note that two separate Observables may invoke their respective callbacks on different threads.
Error handling
If something goes wrong with the RPC infrastructure itself, an RPCException
is thrown. If you call a method that requires a higher version of the protocol than the server supports, UnsupportedOperationException
is thrown. Otherwise, if the server implementation throws an exception, that exception is serialised and rethrown on the client side as if it was thrown from inside the called RPC method. These exceptions can be caught as normal.
Wire protocol
The client RPC wire protocol is defined and documented in net/corda/client/rpc/RPCApi.kt
.
Wire security
CordaRPCClient
has an optional constructor parameter of type ClientRpcSslOptions
, defaulted to null
, which allows communication with the node using SSL. Default null
value means no SSL used in the context of RPC.
To use this feature, the CordaRPCClient
object provides a static factory method createWithSsl
.
In order for this to work, the client needs to provide a truststore containing a certificate received from the node admin. (The Node does not expect the RPC client to present a certificate, as the client already authenticates using the mechanism described above.)
For the communication to be secure, we recommend using the standard SSL best practices for key management.
Whitelisting classes with the Corda node
CorDapps must whitelist any classes used over RPC with Corda's serialization framework, unless they are whitelisted by default in DefaultWhitelist
. The whitelisting is done either via the plugin architecture or by using the @CordaSerializable
annotation. See serialization
. An example is shown in tutorial-clientrpc-api
.