1Conscrypt Implementation Notes 2======================================== 3 4Conscrypt has made some uncommon implementation choices which it's useful to be 5aware of. 6 7## TLS 1.3 Cipher Suites 8 9The supported cipher suites in TLS 1.3 are always enabled. Attempts to disable 10them by omitting them from calls to 11[`setEnabledCipherSuites()`](https://docs.oracle.com/javase/9/docs/api/javax/net/ssl/SSLSocket.html#setEnabledCipherSuites-java.lang.String:A-) 12are ignored. 13 14## Hostname Verification 15 16Prior to version 2.5.0 Conscrypt's hostname verification (enabled by 17[`setEndpointIdentificationAlgorithm("HTTPS")`](https://docs.oracle.com/javase/9/docs/api/javax/net/ssl/SSLParameters.html#setEndpointIdentificationAlgorithm-java.lang.String-)) 18defers entirely to the underlying platform's `HttpsURLConnection` hostname verifier. 19 20The default `HostnameVerifier` on OpenJDK rejects all hostnames, and 21so a `HostnameVerifier` or `ConscryptHostnameVerifier` 22must be set in order to use hostname verification on OpenJDK. On Android, the default 23`HostnameVerifier` performs [RFC 2818](https://tools.ietf.org/html/rfc2818) 24hostname validation, so it will work out of the box. 25 26As of version 2.5.0, Conscrypt ships with its own default `ConscryptHostnameVerifier` 27and this is used on both Android and OpenJDK. It performs RFC 2818 verification 28and is equivalent to the system `HostnameVerifier` on Android 10 and 11. 29 30## AEAD Ciphers 31 32Conscrypt's AEAD ciphers do not support incremental processing (i.e. they will 33always return null from calls to 34[`update()`](https://docs.oracle.com/javase/9/docs/api/javax/crypto/Cipher.html#update-byte:A-)). 35Input is only processed on a call to 36[`doFinal()`](https://docs.oracle.com/javase/9/docs/api/javax/crypto/Cipher.html#doFinal--). 37This ensures that the caller cannot work with output data before the 38authenticator has been processed, but it also means that the input data must be 39buffered completely for each operation. This may necessitate splitting larger 40inputs into chunks; see the [BoringSSL 41docs](https://commondatastorage.googleapis.com/chromium-boringssl-docs/aead.h.html) 42for a discussion of important factors in doing so safely. 43 44## OAEP Digests 45 46Conscrypt's OAEP ciphers (eg, `RSA/ECB/OAEPWithSHA-256AndMGF1Padding`) use the 47named digest for both the main digest and the MGF1 digest. This differs from 48the behavior of some other providers, including the ones bundled with OpenJDK, 49which always use SHA-1 for the MGF1 digest. For maximum compatibility, you 50should use `RSA/ECB/OAEPPadding` and initialize it with an 51[`OAEPParameterSpec`](https://docs.oracle.com/javase/9/docs/api/javax/crypto/spec/OAEPParameterSpec.html). 52