Package zephyr.common

Class ZephyrTls

java.lang.Object
zephyr.common.ZephyrTls

public final class ZephyrTls extends Object
The root certificates the native wallet trusts for https:// nodes.

This class decides which root certificates ZephyrWalletFull trusts when its daemon URI is https://. The Java RPC classes (ZephyrDaemonRpc, ZephyrWalletRpc, ZephyrRpcConnection) are not affected: they use the trust store of the Java runtime.

The default is the root certificates shipped in this library and nothing else: Mozilla's list of root certificates as curl publishes it (getShippedCertificatesDate()), the same on every device and renewed with each release. A node whose certificate comes from a private CA, or from a CA only the device knows, needs addTrustedCertificates(File) or setUseSystemCertificates(true). Android 7.0's system store lacks ISRG Root X1 (the root of Let's Encrypt), which the shipped certificates cover.

When it applies. On Android the defaults are applied automatically before the first https:// connection of a wallet, unless the process environment already names SSL_CERT_FILE or SSL_CERT_DIR (then the app has chosen, and nothing is changed). When the app calls any configuration method of this class, the configuration is applied before the next https:// connection of a wallet, on every platform. On a desktop JVM nothing changes unless the application calls this class: OpenSSL's own default (/etc/ssl) and the SSL_CERT_FILE and SSL_CERT_DIR of the environment stay in effect.

How it works. apply() writes one PEM file with the chosen certificates and sets SSL_CERT_FILE to it and SSL_CERT_DIR to an empty directory, in the process environment, where the OpenSSL of the native wallet reads them. The environment belongs to the whole process. The core reads the bundle whenever a wallet sets up its connection, so configure this class before the wallet is created or its connection is set.

What it cannot do. There is no certificate pinning. A certificate whose host name does not match the URI is refused: the core checks the name. The app's Network Security Configuration does not apply to the native wallet.

All members are static. Those that read or change the configuration are synchronized; a download holds the lock only while it reads the configuration, not during the connection.

  • Method Details

    • setUseSystemCertificates

      public static void setUseSystemCertificates(boolean use)
      Include the system's root certificates in the bundle: on Android those of the system store ("AndroidCAStore", aliases system:), elsewhere the accepted issuers of the Java runtime's default trust manager. Off by default.
      Parameters:
      use - true to include the system's root certificates
    • setUseUserCertificates

      public static void setUseUserCertificates(boolean use)
      Include the certificates the user installed on the device (Android, aliases user: of "AndroidCAStore"). Off by default; ignored outside Android.
      Parameters:
      use - true to include the user's certificates (Android)
    • setUseShippedCertificates

      public static void setUseShippedCertificates(boolean use)
      Include the root certificates shipped in this library (getShippedCertificatesDate()). On by default.
      Parameters:
      use - true to include the shipped root certificates
    • addTrustedCertificates

      public static void addTrustedCertificates(File pemFile)
      Add the certificates of a PEM file to the bundle, for example the CA of a private node or a self-signed node certificate whose name matches the node's host name. Every block between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- is read; other text is skipped. A certificate that is already in the list is not added twice.
      Parameters:
      pemFile - the PEM file
      Throws:
      ZephyrError - if the file cannot be read, holds no certificate, or a block is not a certificate; then nothing is added
    • addTrustedCertificates

      public static void addTrustedCertificates(InputStream pem)
      Add the certificates of a PEM stream to the bundle, as addTrustedCertificates(File). The stream is read to its end and not closed.
      Parameters:
      pem - the PEM data
      Throws:
      ZephyrError - if the stream cannot be read, holds no certificate, or a block is not a certificate; then nothing is added
    • setCaFile

      public static void setCaFile(File pemFile)
      Trust exactly this file and nothing else: SSL_CERT_FILE names it, and the rules above (system, user, shipped and added certificates) are not used; no bundle is written.
      Parameters:
      pemFile - the PEM file to trust, or null to go back to the rules above
    • apply

      public static File apply()
      Apply the configuration now: write the bundle (unless setCaFile(File) names a file) and set SSL_CERT_FILE and SSL_CERT_DIR in the process environment. The bundle is written to a temporary name and renamed, so a half-written file is never in use. On Android the files are under java.io.tmpdir (the app's cache directory), in zephyr-java-tls; elsewhere in a directory this process creates for itself, deleted when the JVM exits.
      Returns:
      the file SSL_CERT_FILE names
      Throws:
      ZephyrError - with the cause if anything fails
    • getShippedCertificatesDate

      public static String getShippedCertificatesDate()
      Get the date of the root certificates shipped in this library: the date of Mozilla's list as curl published it.
      Returns:
      the date, for example "2026-11-05", or "unknown"
    • downloadCertificates

      public static int downloadCertificates(File target)
      Download the current root certificates from curl (https://curl.se/ca/cacert.pem, Mozilla's list), without a checksum: downloadCertificates(URL, File, String) with that URL and null.
      Parameters:
      target - the file to write
      Returns:
      the number of certificates in the downloaded file
      Throws:
      ZephyrError - if anything fails; an existing target is then left untouched
    • downloadCertificates

      public static int downloadCertificates(URL source, File target, String expectedSha256)
      Download root certificates newer than those shipped in this library, for an app that wants them before its next zephyr-java release. The library never calls this itself, and it does not change the configuration: the app adds the file at start, when it exists:
       File roots = new File(context.getFilesDir(), "cacert.pem");
       if (roots.isFile()) ZephyrTls.addTrustedCertificates(roots);   // at start, before the wallet
       ...
       ZephyrTls.downloadCertificates(roots);                          // later, on a background thread
       

      Only https. The connection trusts the certificates apply() would write under the current configuration (system, shipped and added certificates), so Android 7.0, whose own store cannot verify curl.se, reaches it through the shipped certificates; the host name is checked as usual. No redirect is followed; connect and read time out after 30 s; the answer must be 200 and at most 2 MiB. When expectedSha256 is given, the body's sha256 must match; every certificate block must parse, and there must be at least 50. Only then is target written (a temporary file in the same directory, then renamed).

      This contacts a third party (curl.se, unless the app names another source) and so shows it the device's address. Call it from a background thread and not more than once a day. The file is trusted because the https connection is: whoever could forge a certificate under the current roots could add a root. An app that can get the checksum from a source of its own should pass it. Apps that do not call this get new roots with each zephyr-java release.

      Parameters:
      source - the https URL of a PEM file
      target - the file to write
      expectedSha256 - the sha256 of the file in hex, or null to skip the check
      Returns:
      the number of certificates in the downloaded file
      Throws:
      ZephyrError - if anything fails; an existing target is then left untouched
    • beforeNativeConnection

      public static void beforeNativeConnection(String daemonUri)
      Internal: ZephyrWalletFull calls this before it hands a daemon URI to the native core. Applications do not call it. For an https:// URI it applies the configuration when the app configured this class and the configuration changed since the last apply, or, on Android without any configuration, the defaults once, unless the environment already names SSL_CERT_FILE or SSL_CERT_DIR. Anything else does nothing.
      Parameters:
      daemonUri - the URI the wallet is about to use, may be null
      Throws:
      ZephyrError - if applying fails