Advanced control over API connection and authentication.

Configuring the JSON-RPC service

To configure the API server, such as changing the port number, you can change these options in jsonrpc.properties.

Option Default Type Description
headless false boolean Set to true to run SparkBit in headless mode without a user interface.
rpcserver false boolean Set to true to activate the JSON-RPC server.
rpcport 38332 integer TCP port number to listen on for API requests.
rpctimeout 30000 (http)
500000 (https)
integer Default timeout for incoming requests in milliseconds.
rpcuser none string Username for client authentication.
rpcpassword none string Password for client authentication. By default HTTP basic authentication is used.
rpcdigest false boolean Set to true to use HTTP digest access authentication, using the MD5(username:realm:password) scheme with realm jsonrpc. Note however that sparkbit-cli does not support digest authentication.
rpcallowip 127.0.0.1 string By default, the server only accepts connections from the same computer, i.e. IP address 127.0.0.1. Use this setting to specify a list of IP addresses the server should accept connections. The list is delimited by the ! character, for example rpcallowip=127.0.0.1!192.168.2.1. You can also specify ranges, e.g. 192.168.1.100-255 or 192.168.1.- or -.-.-.- for any address. More wildcard options are given in the Jetty documentation for IPAccessHandler.
rpcsslkeystorefilename none string Filename of a Java KeyStore file, relative to the SparkBit-Data folder. This keystore should contain the key pair and SSL certificate for your domain, or a self-signed certificate if you are a developer testing locally.
rpcsslkeystorepassword none string A Java KeyStore must have a password. This is set when you create it with the keytool executable in the Java JDK.
rpcsslkeymanagerpassword none string An individual Java key can also have a password. This is set when you create it with the keytool executable in the Java JDK.
rpcsslallowtls11 false boolean By default the JSON-RPC server requires SSL clients to connect with TLS 1.2. Use this setting to enable TLS 1.1 for older clients. This is not recommended for production systems.
rpcsslallowtls10 false boolean You can enable TLS 1.0 for even older clients (see above). Not recommended for production systems.
rpcsslciphers TLS_ECDHE_RSA_.* string Comma-separated list of ciphers the server allows clients to use. Click to see available Java 7 ciphers and Java 8 ciphers.
rpcsendassettimeout 20000 integer Timeout in milliseconds to wait for confirmation that sending bitcoin or an asset has been successful, before the JSON-RPC server responds with the txid. Sending normally takes just a few seconds but can take longer due to network propagation delays. Set this value to 0 for no waiting, meaning the server will respond immediately after completing a send operation. This is useful for single-shot command-line usage, but you should wait between multiple send operations, since the change outputs of an outgoing transaction are temporarily unspendable until that transaction has propagated.

SSL connections on localhost (127.0.0.1)

The supplied keystore file keystore_localhost_sample.jks provides a self-signed certificate for developer testing. You can create your own similar localhost keystore using the keytool command bundled with every Java JDK.

keytool -genkey -keyalg RSA -alias jetty -keystore keystore_localhost_sample.jks -storepass changeit -validity 365 -keysize 2048

You will enter an interactive mode, in which you can leave most fields blank. When asked What is your first and last name? enter localhost. To examine the keystore created, run this command:

keytool -list -v -keystore keystore_localhost_sample.jks

SSL connections over the Internet

The SparkBit JSON-RPC server is an embedded Jetty server, so you can follow the Jetty SSL configuration options to set up SSL for the SparkBit API. For your convenience a summary is provided here.

In production, when clients connect to the JSON-RPC server over SSL, they expect a valid domain name based certificate, signed by a reputable certificate authority rather than a self-signed certificate. An analogy is a driving license, where a server can present one to the client, but the client won’t trust it unless it has been signed and certified by the proper driving authorities.

To run SparkBit and the JSON-RPC server on a website Amazing-Bitcoin-Based-Assets.com (ABBA), you would need to do the following:

  1. Purchase the domain name from a registrar such as NameCheap or Gandi.
  2. Create a local key pair and certificate using the keytool command bundled with the Java JDK. This enters an interactive mode where you enter the domain name when asked What is your first and last name?. This and other information entered will be visible to anyone examining the signed certificate. Be sure to note the password chosen as part of this process:keytool -genkey -keyalg RSA -alias jetty -keystore keystore_ABBA.jks -storepass changeit -validity 365 -keysize 2048
  3. Now create a certificate signing request as follows:keytool -certreq -alias jetty -keystore keystore_ABBA.jks -file ABBA.csr
  4. Take a look at ABBA.csr, the certificate signing request, to see what it contains.
  5. Purchase or obtain a key pair and SSL certificate signed by a certificate authority, uploading the ABBA.csr file as part of the process. There are many providers who can can sign your certificate, including StartSSL who provide free certifications for non-commercial use.
  6. When the process completes, download the signed SSL certicificate. You may need to convert this file into a different format to import it into your keystore, as well as importing the certificate authority root key and any intermediate keys. There are plenty of online tutorials which show how do this. For example if you acquired a free SSL certificate from StartSSL, you would download:
    • The root certificate “StartCom Root CA (DER encoded)” named ca.cer.
    • The intermediate certificate “Class 1 Intermediate Server CA” named sub.class1.server.ca.
    • Your signed certificate, saving it as signed_ABBA.cer.

    Then you would import these three certificates into your keystore as follows: (order is important!)

    • StartSSL root certificate: keytool -import -alias startsslroot -file ca.cer -keystore keystore_ABBA.jks -trustcacerts
    • StartSSL intermediate certificate chain: keytool -import -alias startsslintermediate -file sub.class1.server.ca.crt -keystore keystore_ABBA.jks -trustcacerts
    • Signed ABBA certificate: keytool -import -alias jetty -file signed_ABBA.cer -keystore keystore_ABBA.jks

    Now if you examine your KeyStore file using keytool -list -keystore keystore_ABBA.jks you should see all three certificates.

  7. Copy keystore_ABBA.jks to the SparkBit-Data directory and configure jsonrpc.properties as follows:rpcssl=true
    rpcsslkeystorefilename=keystore_ABBA.jks
    rpcsslkeystorepassword=[your chosen password]
    rpcsslkeymanagerpassword=[your chosen password]
  8. Finally, test your SSL connection by using your browser to get the current time and date from the Sparkbit JSON-RPC server: https://[your rpcuser]:[your rpcpassword]@Amazing-Bitcoin-Based-Assets.com:38332/date