Class ZephyrTls
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 Summary
Modifier and TypeMethodDescriptionstatic voidaddTrustedCertificates(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.static voidAdd the certificates of a PEM stream to the bundle, asaddTrustedCertificates(File).static Fileapply()Apply the configuration now: write the bundle (unlesssetCaFile(File)names a file) and setSSL_CERT_FILEandSSL_CERT_DIRin the process environment.static voidbeforeNativeConnection(String daemonUri) Internal:ZephyrWalletFullcalls this before it hands a daemon URI to the native core.static intdownloadCertificates(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 andnull.static intdownloadCertificates(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.static StringGet the date of the root certificates shipped in this library: the date of Mozilla's list as curl published it.static voidTrust exactly this file and nothing else:SSL_CERT_FILEnames it, and the rules above (system, user, shipped and added certificates) are not used; no bundle is written.static voidsetUseShippedCertificates(boolean use) Include the root certificates shipped in this library (getShippedCertificatesDate()).static voidsetUseSystemCertificates(boolean use) Include the system's root certificates in the bundle: on Android those of the system store ("AndroidCAStore", aliasessystem:), elsewhere the accepted issuers of the Java runtime's default trust manager.static voidsetUseUserCertificates(boolean use) Include the certificates the user installed on the device (Android, aliasesuser:of "AndroidCAStore").
-
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", aliasessystem:), 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, aliasesuser: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
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
Add the certificates of a PEM stream to the bundle, asaddTrustedCertificates(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
Trust exactly this file and nothing else:SSL_CERT_FILEnames 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
Apply the configuration now: write the bundle (unlesssetCaFile(File)names a file) and setSSL_CERT_FILEandSSL_CERT_DIRin 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 underjava.io.tmpdir(the app's cache directory), inzephyr-java-tls; elsewhere in a directory this process creates for itself, deleted when the JVM exits.- Returns:
- the file
SSL_CERT_FILEnames - Throws:
ZephyrError- with the cause if anything fails
-
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
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 andnull.- 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
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 certificatesapply()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. WhenexpectedSha256is given, the body's sha256 must match; every certificate block must parse, and there must be at least 50. Only then istargetwritten (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 filetarget- the file to writeexpectedSha256- 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
Internal:ZephyrWalletFullcalls this before it hands a daemon URI to the native core. Applications do not call it. For anhttps://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 namesSSL_CERT_FILEorSSL_CERT_DIR. Anything else does nothing.- Parameters:
daemonUri- the URI the wallet is about to use, may be null- Throws:
ZephyrError- if applying fails
-