Java Pinning provides support for pinning TLS (and SSL) certificates without any CA validation required. The library runs on Java and Android and is available from Maven Central. It is licensed under the Apache License, Version 2.0. If Java Pinning pins the public key of a certificate, or the hash of such, and produces a SSLContext which will only accept connections to a host in possession of the corresponding private key. There is no additional validation using the system's trust store, i.e. Java Pinning disables PKI (CA validation). This means that as soon as the private key is compromised, an attacker will be able to impersonate the host.
You should only use Java Pinning if you are in control of both ends of the TLS connection, so that you can replace the Pin in case the private key has been compromised. To be absolutely clear: If you need to change the server certificate, you need to change also the PIN in the client. Usually you want to add the new PIN first, before changing the server certificate. If you don't add the new PIN, your clients wont be able to connect to your server! Please inform yourself about the available alternatives to Java Pinning to determine if your use case is a match for Java Pinning. See also the "Alternatives" section in this README.
How to use
If your XMPP service does not provide you the server certificates SHA256 hash or the full certificate over a secure channel, then you could obtain the information for example via
- Go to xmpp.net
- Select "Test a server", enter your service name and make sure "c2s" is selected
- Press "Check!"
- Wait a bit until the information in the "Certificates" section appears
- The first certificate ("#0") is the one of your service. In the "Details" section select SHA-256
- Copy the SHA-256 hash, e.g.
- Java Pinning versions < 1.0.1 require the colons to be removed and the letters to be lowercase. This transformation could be done with the following bash script
$ pin=83:F9:17:1E:06:A3:13:11:88:89:F7:D7:93:02:BD:1B:7A:20:42:EE:0C:FD:02:9A:BF:8D:D0:6F:FA:6C:D9:D3 $ echo $pin | tr '[:upper:]' '[:lower:]' | tr -d :
- Create the Java Pinning Pin String by prefixing
CERTSHA256to the Pin. Thus our example SHA256 value becomes
HTTPS (and other services using TLS right from the start)
X509TrustManager tm = Java7Pinning .trustManagerForPin("SHA256:e3b1812d945da1a2a2c5fa28029d2fe34c7c4142fb098f5cfedff1ff20e98781");
Now you can setup this context.
X509TrustManager tm = Java7Pinning .trustManagerForPin("SHA256:e3b1812d945da1a2a2c5fa28029d2fe34c7c4142fb098f5cfedff1ff20e98781"); XMPPTCPConnectionConfiguration conf = XMPPTCPConnectionConfiguration.builder() .setUsernameAndPassword("user", "pass") .setService("example.org") .setCustomX509TrustManager(tm) .build()
How to add this as dependency
<dependency> <groupId>eu.geekplace.javapinning</groupId> <artifactId>java-pinning-core</artifactId> <version>1.2.0</version> </dependency>
Difference between Public Key Pins and Certificate Pins
Both provide the same security guarantee. If the private key is compromised, both can no longer provide a security guarantee. Using Public Key pinning provides (theoretically) the advantage that the certificate could be replaced with a new one using the same private/public key pair, thus requiring no changes to the used Pins.
Java (and Android)
Pure Certificate Pinning
This technique creates a custom SSLContext that will only accept certificates found or signed by certificates in a key store file.
File keyStoreFile = new File("./myKeyStore"); KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType()); ks.load(new FileInputStream(keyStoreFile), "keyStorePassword".toCharArray()); TrustManagerFactory tmf = TrustManagerFactory.getInstance("X509"); tmf.init(ks); SSLContext sc = SSLContext.getInstance("TLS"); sc.init(null, tmf.getTrustManagers(), new java.security.SecureRandom());
You can read more about it at https://op-co.de/blog/posts/java_sslsocket_mitm/#index10h3
Memorizing Trust Manager
Memorizing Trust Manager (MTM) excels in user scenarios because of its GUI confirmation dialog. MTM does pin the certificate and does also not perform additional validate by the system trust store. It is only available on Android (at the moment).
Android Pinning (AP) does additional validate the pinned certificate by using the system's trust store. It provides probably the best level of security, as it additionally strengthens PKI with pinning. As the name suggests, Android Pinning is only available for Android. The fact that the last commit date is June 2013 makes it questionable if the project is still actively maintained.
Run tests with
- Fix dependency declarations
- Added support for the Java 7
X509ExtendedTrustManagerif your project uses Java 7 please use
- Two new factory methods
JavaPinning.trustManagerforpins()in favor of the correctly named
- Two new factory methods
PlainPin.fromPublicKeythese methods can be used to directly create pins from X509 certificates or X509 public keys.
- Two new getter methods
- Two new factory methods in
PinningTrustManagernow throws a specialized exception when a certificate is not pinned
CertificateNotPinnedExceptionwhich is a sub-type of
CertificateException, this allows you to differentiate pinning exceptions from other certificate related exceptions.
- New class
HexUtilitieswhich contains methods to decode from HEX to bytes and encode bytes to HEX
JavaPinningUtilclass has been deprecated in favor of
HexUtilities, beaware of the fact that the methods in
HexUtilitiesbehave slightly better, but different).
The Pin format requirements have been relaxed. The Pin string may now contain
- Colons (':')
- Uppercase characters