SSL natif

native-ssl vous permet de construire la confiance TLS à partir du store de certificats du système d'exploitation, et non uniquement des cacerts embarqués dans votre JRE. Le module lit les racines de confiance connues de l'OS sous macOS, Windows et Linux, les fusionne avec les défauts de la JVM, et expose le résultat sous la forme d'un unique X509TrustManager.

Ajouter la dépendance

dependencies {
    implementation("dev.nucleusframework:nucleus.native-ssl:2.0.7")
}

Construire un trust manager

NativeTrustManager est un objet avec trois propriétés initialisées à la demande. Lisez celle dont votre pile HTTP a besoin :

import dev.nucleusframework.nativessl.NativeTrustManager
import javax.net.ssl.SSLContext
import javax.net.ssl.SSLSocketFactory
import javax.net.ssl.X509TrustManager

val trustManager: X509TrustManager = NativeTrustManager.trustManager
val sslContext: SSLContext = NativeTrustManager.sslContext
val sslSocketFactory: SSLSocketFactory = NativeTrustManager.sslSocketFactory

Fonctionnement

La première lecture de n'importe quelle propriété de NativeTrustManager construit une seule fois un X509TrustManager combiné, à la demande et de façon thread-safe, puis le met en cache. La construction collecte les émetteurs acceptés par défaut de la JVM, y ajoute les certificats signalés par l'OS, et charge les deux ensembles dans un nouveau KeyStore qui alimente le trust manager renvoyé. Si l'OS ne signale aucun certificat, les défauts de la JVM sont utilisés tels quels.

Les certificats de l'OS incluent les racines installées par une politique d'entreprise, un MDM ou un proxy d'inspection TLS — des racines que les cacerts d'un JRE embarqué ne contiennent pas, ce qui fait autrement échouer les handshakes HTTPS vers ces hôtes.

La collecte des certificats dépend de la plateforme. macOS et Windows passent par un bridge JNI livré dans le JAR ; Linux lit des bundles de certificats sur le disque, sans bibliothèque native.

macOS

Le framework Security est appelé via libnucleus_ssl.dylib (embarqué pour arm64 et x86_64), en deux passes :

1. Ancres système — SecTrustCopyAnchorCertificates() renvoie chaque racine livrée par Apple.
2. Domaines user et admin — SecTrustSettingsCopyCertificates() énumère les certificats dotés de trust settings explicites. Chaque candidat est évalué avec une logique qui reprend celle de JetBrains jvm-native-trusted-roots :
   • Les trust settings user sont examinés d'abord, puis ceux d'admin.
   • En l'absence de trust settings, l'évaluation se fait en direct via SecTrustEvaluateWithError.
   • Un tableau de trust settings vide compte comme de confiance, selon la documentation d'Apple.
   • kSecTrustSettingsResult doit valoir TrustRoot, et le certificat doit être auto-signé (égalité de DN et signature vérifiée contre sa propre clé).
   • kSecTrustSettingsPolicy, s'il est présent, doit valoir kSecPolicyAppleSSL.
   • Les clés de contrainte inconnues rejettent le certificat : mieux vaut échouer fermé que relâcher les règles en silence.

Windows

Crypt32 est appelé via nucleus_ssl.dll (embarqué pour x64 et ARM64). Le module scanne deux types de stores sur plusieurs emplacements :

Les emplacements scannés sont CURRENT_USER, LOCAL_MACHINE, CURRENT_USER_GROUP_POLICY, LOCAL_MACHINE_GROUP_POLICY et LOCAL_MACHINE_ENTERPRISE. Les certificats distribués par Group Policy et Active Directory atterrissent dans des stores que SunMSCAPI n'atteint pas.

Dans le bridge natif, la déduplication se fait par empreinte SHA-1 (CERT_HASH_PROP_ID). Si la bibliothèque JNI échoue à se charger, le module retombe sur les keystores Windows-ROOT, Windows-CA et Windows-MY de SunMSCAPI.

Linux

Pur JVM, sans bibliothèque partagée. Le module lit les mêmes chemins que crypto/x509 de Go :

Sous Linux, les certificats sont dédupliqués par contenu DER entre toutes les sources.

Référence de l'API

NativeTrustManager est le seul point d'entrée public. Il expose trois propriétés en lecture seule et aucune méthode.

La collecte des certificats est interne et s'adapte à la plateforme courante. Il n'existe aucun point d'extension public pour fournir une source de certificats personnalisée.

Notes

ProGuard

Les classes du bridge JNI doivent être conservées sous macOS et Windows. Le plugin Gradle Nucleus ajoute ces règles automatiquement ; ajoutez-les vous-même si vous maintenez la config ProGuard à la main :

-keep class dev.nucleusframework.nativessl.mac.NativeSslBridge {
    native <methods>;
}
-keep class dev.nucleusframework.nativessl.windows.WindowsSslBridge {
    native <methods>;
}

Logging

Les logs de debug sont taggés NativeCertificateProvider, NativeSslBridge, WindowsCertificateProvider et LinuxCertificateProvider. Ils sont coupés par défaut. Activez-les avec :

import dev.nucleusframework.core.runtime.tools.allowNucleusRuntimeLogging

allowNucleusRuntimeLogging = true

Et ensuite

• HTTP natif — câble le trust manager natif dans java.net.http, OkHttp et Ktor.
• Modules — la liste complète des modules Nucleus et ce que chacun apporte.