Platform SDK Java 8.5 API Reference

com.genesyslab.platform.commons.connection.tls
Class TrustManagerHelper

java.lang.Object
  extended by com.genesyslab.platform.commons.connection.tls.TrustManagerHelper

public class TrustManagerHelper
extends java.lang.Object

Helper class that provides convenient methods to create TrustManager instances. CRL

Parameter crlFilePath sets path to Certificate Revocation List (CRL) file. Only file-based CRLs in PEM format are supported. This parameter is optional in all methods and can be set to null if CRL validation is not needed. Applicable to all security providers.

Parameter ExpectedHostName is optional in all methods - if set to null host name check will not be performed.
Note: this parameter is not applicable to PKCS#11 provider, since it does not allow customization of certificate validation.
When non-null value is set, it will be used to validate certificates' Subject fields. This value will be matched against certificate's Alternative Subject Name values (ASNs). If any one of these names matches, this check passes. If there are no ASNs specified and user specified DNS name to match against, certificate's Distinguished Name (DN) from Subject field will be used.

IP address can be IPv4 or IPv6 literal address. If IP address is specified for ExpectedHostName value, exact char-to-char match will be used.
Note: X.509 certificates can contain IP addresses only in ASNs, not in general Subject field. If there are no ASNs in the certificate and user has provided IP address to match against, host name check will fail.

DNS name values for ExpectedHostName allow wildcard usage.

Examples:

     // Exact match implied
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "foo.bar.com");

     // Wildcards can be used; "foo.bar.com" will match the following patterns:
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "*.bar.com");
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "foo.*.com");

     // Wildcard can match only one level in domain name.
     // "foo.bar.com" will NOT match the following patterns:
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "*");
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "*.com");

     // IP addresses can be used. They imply exact char-to-char matching:
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "192.168.1.1");
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "127.0.0.1");
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "::");
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "::ffff:192.168.1.1");
     createPEMTrustManager("c:/certificates/ca.pem", "c:/certificates/ca-crl.pem", "2001:DB8::CAFE");
 


Constructor Summary
TrustManagerHelper()
           
 
Method Summary
static javax.net.ssl.X509TrustManager createDefaultTrustManager()
          Creates TrustManager based on Java default key store chain.
static javax.net.ssl.X509TrustManager createJKSTrustManager(java.io.InputStream jksStream, char[] keyStorePassword, java.io.InputStream crlStream, java.lang.String expectedHostName)
          Creates TrustManager based on Java Key Store file, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createJKSTrustManager(java.lang.String jksFilePath, char[] keyStorePassword, java.lang.String crlFilePath, java.lang.String expectedHostName)
          Creates TrustManager based on Java Key Store file, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createMSCAPITrustManager(javax.security.auth.callback.CallbackHandler callbackHandler, java.io.InputStream crlStream, java.lang.String expectedHostName)
          Creates TrustManager based on Windows Certificate Services user trusted root key store, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createMSCAPITrustManager(javax.security.auth.callback.CallbackHandler callbackHandler, java.lang.String crlFilePath, java.lang.String expectedHostName)
          Creates TrustManager based on Windows Certificate Services user trusted root key store, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createPEMTrustManager(java.io.InputStream caCertStream, java.io.InputStream crlStream, java.lang.String expectedHostName)
          Creates TrustManager based on provided CA certificate, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createPEMTrustManager(java.lang.String caCertFilePath, java.lang.String crlFilePath, java.lang.String expectedHostName)
          Creates TrustManager based on provided CA certificate, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createPKCS11TrustManager(javax.security.auth.callback.CallbackHandler callbackHandler, java.io.InputStream crlStream)
          Creates TrustManager based on PKCS#11 provider key store, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createPKCS11TrustManager(javax.security.auth.callback.CallbackHandler callbackHandler, java.lang.String crlFilePath)
          Creates TrustManager based on PKCS#11 provider key store, optional CRL data and optionally adds check for expected hostname.
static javax.net.ssl.X509TrustManager createTrustEveryoneTrustManager()
          Creates a TrustManager instance that will trust any presented certificate regardless of its properties.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TrustManagerHelper

public TrustManagerHelper()
Method Detail

createPEMTrustManager

public static javax.net.ssl.X509TrustManager createPEMTrustManager(java.io.InputStream caCertStream,
                                                                   java.io.InputStream crlStream,
                                                                   java.lang.String expectedHostName)
                                                            throws java.io.IOException,
                                                                   java.security.GeneralSecurityException
Creates TrustManager based on provided CA certificate, optional CRL data and optionally adds check for expected hostname.

Parameters:
caCertStream - Stream to read CA certificate from, X.509 PEM format
crlStream - Stream to read CRL data from, PEM format. Can be null if CRL is not used.
expectedHostName - DNS name/IP to match certificate against.
If it isn't in fully qualified domain name then performance will reduced due trying getting full one. If it dosn't have full form and getting full one fail then it will be interpreted as the ip according to the passed expectedHostname argument
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createPEMTrustManager

public static javax.net.ssl.X509TrustManager createPEMTrustManager(java.lang.String caCertFilePath,
                                                                   java.lang.String crlFilePath,
                                                                   java.lang.String expectedHostName)
                                                            throws java.io.IOException,
                                                                   java.security.GeneralSecurityException
Creates TrustManager based on provided CA certificate, optional CRL data and optionally adds check for expected hostname.

Parameters:
caCertFilePath - Path to file to read CA certificate from, X.509 PEM format
crlFilePath - Path to file to read CRL data from, PEM format. Can be null if CRL is not used.
expectedHostName - DNS name/IP to match certificate against.
If it isn't in fully qualified domain name then performance will reduced due trying getting full one. If it dosn't have full form and getting full one fail then it will be interpreted as the ip according to the passed expectedHostname argument
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createMSCAPITrustManager

public static javax.net.ssl.X509TrustManager createMSCAPITrustManager(javax.security.auth.callback.CallbackHandler callbackHandler,
                                                                      java.io.InputStream crlStream,
                                                                      java.lang.String expectedHostName)
                                                               throws java.io.IOException,
                                                                      java.security.GeneralSecurityException
Creates TrustManager based on Windows Certificate Services user trusted root key store, optional CRL data and optionally adds check for expected hostname.

Parameters:
callbackHandler - CallbackHandler instance used to provide password necessary to access the key store. Must be always provided, can not be null. Use DummyCallbackHandler instance if no password is required.
crlStream - Stream to read CRL data from, PEM format. Can be null if CRL is not used.
expectedHostName - DNS name/IP to match certificate against.
If it isn't in fully qualified domain name then performance will reduced due trying getting full one. If it dosn't have full form and getting full one fail then it will be interpreted as the ip according to the passed expectedHostname argument
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createMSCAPITrustManager

public static javax.net.ssl.X509TrustManager createMSCAPITrustManager(javax.security.auth.callback.CallbackHandler callbackHandler,
                                                                      java.lang.String crlFilePath,
                                                                      java.lang.String expectedHostName)
                                                               throws java.io.IOException,
                                                                      java.security.GeneralSecurityException
Creates TrustManager based on Windows Certificate Services user trusted root key store, optional CRL data and optionally adds check for expected hostname.

Parameters:
callbackHandler - CallbackHandler instance used to provide password necessary to access the key store. Must be always provided, can not be null. Use DummyCallbackHandler instance if no password is required.
crlFilePath - Path to file to read CRL data from, PEM format. Can be null if CRL is not used.
expectedHostName - DNS name/IP to match certificate against.
If it isn't in fully qualified domain name then performance will reduced due trying getting full one. If it dosn't have full form and getting full one fail then it will be interpreted as the ip according to the passed expectedHostname argument
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createPKCS11TrustManager

public static javax.net.ssl.X509TrustManager createPKCS11TrustManager(javax.security.auth.callback.CallbackHandler callbackHandler,
                                                                      java.io.InputStream crlStream)
                                                               throws java.io.IOException,
                                                                      java.security.GeneralSecurityException
Creates TrustManager based on PKCS#11 provider key store, optional CRL data and optionally adds check for expected hostname. Note that Java FIPS-compliant implementation does not allow custom host name matching.

Parameters:
callbackHandler - CallbackHandler instance used to provide password necessary to access the key store. Must be always provided, can not be null. Use DummyCallbackHandler instance if no password is required.
crlStream - Stream to read CRL data from, PEM format. Can be null if CRL is not used.
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createPKCS11TrustManager

public static javax.net.ssl.X509TrustManager createPKCS11TrustManager(javax.security.auth.callback.CallbackHandler callbackHandler,
                                                                      java.lang.String crlFilePath)
                                                               throws java.io.IOException,
                                                                      java.security.GeneralSecurityException
Creates TrustManager based on PKCS#11 provider key store, optional CRL data and optionally adds check for expected hostname. Note that Java FIPS-compliant implementation does not allow custom host name matching.

Parameters:
callbackHandler - CallbackHandler instance used to provide password necessary to access the key store. Must be always provided, can not be null. Use DummyCallbackHandler instance if no password is required.
crlFilePath - Path to file to read CRL data from, PEM format. Can be null if CRL is not used.
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createDefaultTrustManager

public static javax.net.ssl.X509TrustManager createDefaultTrustManager()
                                                                throws java.io.IOException,
                                                                       java.security.GeneralSecurityException
Creates TrustManager based on Java default key store chain.

Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createJKSTrustManager

public static javax.net.ssl.X509TrustManager createJKSTrustManager(java.io.InputStream jksStream,
                                                                   char[] keyStorePassword,
                                                                   java.io.InputStream crlStream,
                                                                   java.lang.String expectedHostName)
                                                            throws java.io.IOException,
                                                                   java.security.GeneralSecurityException
Creates TrustManager based on Java Key Store file, optional CRL data and optionally adds check for expected hostname. Unlike other key store types, JKS needs explicit passwords, Java API does not allow to wrap them in CallbackHandler objects.

Parameters:
jksStream - Stream to read key store from.
keyStorePassword - Password to access key store
crlStream - Stream to read CRL data from, PEM format. Can be null if CRL is not used.
expectedHostName - DNS name/IP to match certificate against.
If it isn't in fully qualified domain name then performance will reduced due trying getting full one. If it dosn't have full form and getting full one fail then it will be interpreted as the ip according to the passed expectedHostname argument
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createJKSTrustManager

public static javax.net.ssl.X509TrustManager createJKSTrustManager(java.lang.String jksFilePath,
                                                                   char[] keyStorePassword,
                                                                   java.lang.String crlFilePath,
                                                                   java.lang.String expectedHostName)
                                                            throws java.io.IOException,
                                                                   java.security.GeneralSecurityException
Creates TrustManager based on Java Key Store file, optional CRL data and optionally adds check for expected hostname. Unlike other key store types, JKS needs explicit passwords, Java API does not allow to wrap them in CallbackHandler objects.

Parameters:
jksFilePath - Path to file to read key store from.
keyStorePassword - Password to access key store
crlFilePath - Path to file to read CRL data from, PEM format. Can be null if CRL is not used.
expectedHostName - DNS name/IP to match certificate against.
If it isn't in fully qualified domain name then performance will reduced due trying getting full one. If it dosn't have full form and getting full one fail then it will be interpreted as the ip according to the passed expectedHostname argument
Returns:
Configured TrustManager
Throws:
java.io.IOException - If there are problems reading any of streams
java.security.GeneralSecurityException - If there are problems with certificate/CRL data/format.

createTrustEveryoneTrustManager

public static javax.net.ssl.X509TrustManager createTrustEveryoneTrustManager()
Creates a TrustManager instance that will trust any presented certificate regardless of its properties. Can be used for server side that does not expect any certificates from clients or for testing purposes.

Returns:
A TrustManager instance that will trust any presented certificate

Platform SDK Java 8.5 API Reference

Send comments on this topicTechpubs.webadmin@genesys.com.
Document version: 8.5.302.00
Copyright © 2006–2017 Genesys Telecommunications Laboratories, Inc. All rights reserved.