iaik.security.ssl
Class SecurityProvider

java.lang.Object
  |
  +--iaik.security.ssl.SecurityProvider

Direct Known Subclasses:

IaikProvider

public class SecurityProvider

extends java.lang.Object

This interface centralizes all security provider dependend code. If a user of iSaSiLk wants to use another security provider than IAIK (e.g. RSA J/Safe for patent reasons) he only needs to extend this class. This class also contains the settings for the currently active SecurityProvider.

This class provides default implementations for all methods using the JCA/JCE 1.2 APIs except for getPrincipal() and getEncodedPrincipal() because this is not possible in a provider independent way. Therefore, if used with a fully JCA/JCE 1.2 compliant provider no implementation work needs to be done at all and the provider will be used right away.

Note that if no SecurityProvider has been set explicitly, defaults will be used. If the IAIK JCE is available the IaikProvider will be used automatically, otherwise an instance of this class is used.

Note that there are separate documents about the iSaSiLk SecurityProvider model and the use of iSaSiLk with Smartcards.

See Also:

IaikProvider

Field Summary

static java.lang.String	ALG_CIPHER_3DES Constant string DESede/ECB/NoPadding.
static java.lang.String	ALG_CIPHER_DES Constant string DES/ECB/NoPadding.
static java.lang.String	ALG_CIPHER_IDEA Constant string IDEA/ECB/NoPadding.
static java.lang.String	ALG_CIPHER_RC2 Constant string RC2/ECB/NoPadding.
static java.lang.String	ALG_CIPHER_RC4 Constant string RC4/ECB/NoPadding.
static java.lang.String	ALG_CIPHER_RSA Constant string RSA/ECB/PKCS1Padding.
static java.lang.String	ALG_CIPHER_RSA_DECRYPT Constant string RSA/ECB/PKCS1Padding/Decrypt.
static java.lang.String	ALG_CIPHER_RSA_ENCRYPT Constant string RSA/ECB/PKCS1Padding/Encrypt.
static java.lang.String	ALG_CIPHER_RSA_ENCRYPT_SSL2 Constant string RSA/ECB/PKCS1PaddingSSL2.
static java.lang.String	ALG_CIPHER_RSA_SIGN Constant string RSA/ECB/PKCS1Padding/Sign.
static java.lang.String	ALG_CIPHER_RSA_VERIFY Constant string RSA/ECB/PKCS1Padding/Verify.
static java.lang.String	ALG_DIGEST_MD5 Constant string MD5.
static java.lang.String	ALG_DIGEST_SHA Constant string SHA.
static java.lang.String	ALG_HMAC_MD5 Constant string HmacMD5.
static java.lang.String	ALG_HMAC_SHA Constant string HmacSHA1.
static java.lang.String	ALG_KEYEX_DH Constant string DH Used by the library with isImplemented().
static java.lang.String	ALG_KEYEX_DSA Constant string DSA Used by the library with isImplemented().
static java.lang.String	ALG_KEYEX_DSA_CLIENT Constant string DSAClient Used by the library with isImplemented().
static java.lang.String	ALG_KEYEX_RSA Constant string RSA Used by the library with isImplemented().
static java.lang.String	ALG_KEYPAIR_RSA Constant string RSA.
static java.lang.String	ALG_SIGNATURE_MD5RSA Constant string MD5withRSA.
static java.lang.String	ALG_SIGNATURE_RAWDSA Constant string RawDSA.
static java.lang.String	ALG_SIGNATURE_SHADSA Constant string SHA1withDSA.
static int	CIPHER_DECRYPT Constant for a cipher object which is to be initialized for decryption.
static int	CIPHER_ENCRYPT Constant for a cipher object which is to be initialized for encryption.
static int	CIPHER_NONE Constant for a cipher object which is not to be initialized.
protected java.lang.String	providerName
static int	SIGNATURE_NONE Constant for a signature object which is not to be initialized.
static int	SIGNATURE_SIGN Constant for a signature object which is to be initialized for signing.
static int	SIGNATURE_VERIFY Constant for a signature object which is to be initialized for verification.

Constructor Summary

SecurityProvider()
Default constructor.

SecurityProvider(java.lang.String providerName)
Constructor specifying the provider to use.

Method Summary

protected Cipher	getCipher(java.lang.String algorithm, int mode, Key key, AlgorithmParameterSpec param, SecureRandom random) This method returns the desired Cipher object.
protected DHPrivateKey	getDHPrivateKey(java.math.BigInteger x, java.math.BigInteger p, java.math.BigInteger g) This method returns a DHPrivateKey created from the values: x, p and g.
protected DHPublicKey	getDHPublicKey(java.math.BigInteger y, java.math.BigInteger p, java.math.BigInteger g) This method returns a DHPublicKey created from the values: y, p and g.
protected byte[]	getEncodedPrincipal(Principal principal) This method returns a DER encoded Name (Principal).
protected KeyPairGenerator	getKeyPairGenerator(java.lang.String algorithm) Return a KeyPairGenerator for the requested algorithm.
protected Mac	getMac(java.lang.String algorithm, Key key) This method returns the desired HMAC object.
protected MessageDigest	getMessageDigest(java.lang.String algorithm) This method returns the desired MessageDigest object.
protected Principal	getPrincipal(byte[] array) This method returns a Principal created from a DER encoded byte array.
protected RSAPublicKey	getRSAPublicKey(java.math.BigInteger modulus, java.math.BigInteger publicExponent) This method returns a RSAPublicKey created from the values: modulus and publicExponent.
protected SecureRandom	getSecureRandom() Return a new instance of a SecureRandom number generator.
static SecurityProvider	getSecurityProvider() Returns the active SecurityProvider.
protected Signature	getSignature(java.lang.String algorithm, int mode, Key key, SecureRandom random) This method returns the desired Signature object.
protected X509Certificate	getX509Certificate(byte[] array) This method returns a X509Certificate created from a DER encoded byte array.
protected boolean	isImplemented(java.lang.String algorithm) Check if the specified algorithm is implemented by this provider.
static void	setSecurityProvider(SecurityProvider provider) Sets the global SecurityProvider.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

providerName

protected java.lang.String providerName

SIGNATURE_NONE

public static int SIGNATURE_NONE

Constant for a signature object which is not to be initialized.

SIGNATURE_SIGN

public static int SIGNATURE_SIGN

Constant for a signature object which is to be initialized for signing.

SIGNATURE_VERIFY

public static int SIGNATURE_VERIFY

Constant for a signature object which is to be initialized for verification.

CIPHER_NONE

public static int CIPHER_NONE

Constant for a cipher object which is not to be initialized.

CIPHER_ENCRYPT

public static int CIPHER_ENCRYPT

Constant for a cipher object which is to be initialized for encryption.

CIPHER_DECRYPT

public static int CIPHER_DECRYPT

Constant for a cipher object which is to be initialized for decryption.

ALG_DIGEST_MD5

public static final java.lang.String ALG_DIGEST_MD5

Constant string MD5. Used by the library with getMessageDigest().

ALG_DIGEST_SHA

public static final java.lang.String ALG_DIGEST_SHA

Constant string SHA. Used by the library with getMessageDigest().

ALG_HMAC_MD5

public static final java.lang.String ALG_HMAC_MD5

Constant string HmacMD5. Used by the library with getMac().

ALG_HMAC_SHA

public static final java.lang.String ALG_HMAC_SHA

Constant string HmacSHA1. Used by the library with getMac().

ALG_SIGNATURE_SHADSA

public static final java.lang.String ALG_SIGNATURE_SHADSA

Constant string SHA1withDSA. Used by the library with getSignature().

ALG_SIGNATURE_RAWDSA

public static final java.lang.String ALG_SIGNATURE_RAWDSA

Constant string RawDSA. Used by the library with getSignature().

ALG_SIGNATURE_MD5RSA

public static final java.lang.String ALG_SIGNATURE_MD5RSA

Constant string MD5withRSA. Used by the library with getSignature().

ALG_CIPHER_RC4

public static final java.lang.String ALG_CIPHER_RC4

Constant string RC4/ECB/NoPadding. Used by the library with getCipher().

ALG_CIPHER_RC2

public static final java.lang.String ALG_CIPHER_RC2

Constant string RC2/ECB/NoPadding. Used by the library with getCipher().

ALG_CIPHER_DES

public static final java.lang.String ALG_CIPHER_DES

Constant string DES/ECB/NoPadding. Used by the library with getCipher().

ALG_CIPHER_3DES

public static final java.lang.String ALG_CIPHER_3DES

Constant string DESede/ECB/NoPadding. Used by the library with getCipher().

ALG_CIPHER_IDEA

public static final java.lang.String ALG_CIPHER_IDEA

Constant string IDEA/ECB/NoPadding. Used by the library with getCipher().

ALG_KEYPAIR_RSA

public static final java.lang.String ALG_KEYPAIR_RSA

Constant string RSA. Used by the library with getKeyPairGenerator().

ALG_KEYEX_RSA

public static final java.lang.String ALG_KEYEX_RSA

Constant string RSA Used by the library with isImplemented().

ALG_KEYEX_DSA

public static final java.lang.String ALG_KEYEX_DSA

Constant string DSA Used by the library with isImplemented().

ALG_KEYEX_DSA_CLIENT

public static final java.lang.String ALG_KEYEX_DSA_CLIENT

Constant string DSAClient Used by the library with isImplemented().

ALG_KEYEX_DH

public static final java.lang.String ALG_KEYEX_DH

Constant string DH Used by the library with isImplemented().

ALG_CIPHER_RSA

public static final java.lang.String ALG_CIPHER_RSA

Constant string RSA/ECB/PKCS1Padding. This string is NOT used with getCipher(), but it is the prefix of all RSA algorithm identifier strings (see below). The different identifiers were chosen to simplify using a particular RSA implementation just one of these operations. For example, to implement RSA client authentication on a smartcard one will only care about signature creation operations and will want to leave all other operations to the standard implementation. This can easily be done by checking for the String ALG_CIPHER_RSA_SIGN only.

If you write your own security provider that does nothing like this you will typically use code like:

 if( algorithm.startsWith(ALG_CIPHER_RSA) ) {
   algorithm = ALG_CIPHER_RSA;
 }
 return Cipher.getInstance(algorithm, "MyProvider");
 

ALG_CIPHER_RSA_SIGN

public static final java.lang.String ALG_CIPHER_RSA_SIGN

Constant string RSA/ECB/PKCS1Padding/Sign. Used by the library with getCipher() to indicate an RSA signature creation operation (private key encryption).

ALG_CIPHER_RSA_VERIFY

public static final java.lang.String ALG_CIPHER_RSA_VERIFY

Constant string RSA/ECB/PKCS1Padding/Verify. Used by the library with getCipher() to indicate an RSA signature verification operation (public key decryption).

ALG_CIPHER_RSA_ENCRYPT

public static final java.lang.String ALG_CIPHER_RSA_ENCRYPT

Constant string RSA/ECB/PKCS1Padding/Encrypt. Used by the library with getCipher() to indicate an RSA data encryption operation (public key encryption).

ALG_CIPHER_RSA_DECRYPT

public static final java.lang.String ALG_CIPHER_RSA_DECRYPT

Constant string RSA/ECB/PKCS1Padding/Decrypt. Used by the library with getCipher() to indicate an RSA data decryption operation (private key decryption).

ALG_CIPHER_RSA_ENCRYPT_SSL2

public static final java.lang.String ALG_CIPHER_RSA_ENCRYPT_SSL2

Constant string RSA/ECB/PKCS1PaddingSSL2. Used by the library with getCipher() in SSLv2 mode to detect version rollback attacks (see RFC2246 section E.2). If this padding variant is not supported by a particular provider it should treat it the same as ALG_CIPHER_RSA_ENCRYPT.

Constructor Detail

SecurityProvider

public SecurityProvider()

Default constructor.

SecurityProvider

public SecurityProvider(java.lang.String providerName)

Constructor specifying the provider to use. If this constructor is used only the specified provider is searched, no implementations from other providers are used.

Method Detail

getSecurityProvider

public static SecurityProvider getSecurityProvider()

Returns the active SecurityProvider. If no provider has been set explicitly using setSecurityProvider() and the IAIK JCE is available this will be the IaikProvider, otherwise it is an instance of this class.

NOTE that the SecurityProvider setting is global for all SSLContexts.

Returns:

the installed SecurityProvider

setSecurityProvider

public static void setSecurityProvider(SecurityProvider provider)

Sets the global SecurityProvider.

NOTE that the SecurityProvider setting is global for all SSLContexts.

Parameters:

provider - the SecurityProvider which shall be used

isImplemented

protected boolean isImplemented(java.lang.String algorithm)

Check if the specified algorithm is implemented by this provider. The algorithm argument is the ALG_CIPHER_xxx string for symmetric algorithms or ALG_KEYEX_xxx for asymmetric algorithms. The default implementation performs the check by calling the respective get method and checking for exceptions.

It should normally not be necessary to override this method. Note that the library uses a caching mechanism to make sure this method is only called once per algorithm and SecurityProvider.

getDHPublicKey

protected DHPublicKey getDHPublicKey(java.math.BigInteger y,
                                     java.math.BigInteger p,
                                     java.math.BigInteger g)
                              throws java.lang.Exception

This method returns a DHPublicKey created from the values: y, p and g. This method only must be implemented if one wants to use Diffie-Hellman cipher suites.

Parameters:

y - the public value y

p - the prime modulus p

g - the base generator g

Returns:

the new created DHPublicKey

getDHPrivateKey

protected DHPrivateKey getDHPrivateKey(java.math.BigInteger x,
                                       java.math.BigInteger p,
                                       java.math.BigInteger g)
                                throws java.lang.Exception

This method returns a DHPrivateKey created from the values: x, p and g. This method only must be implemented if one wants to use Diffie-Hellman cipher suites.

Parameters:

x - the private value x

p - the prime modulus p

g - the base generator g

Returns:

the new created DHPrivateKey

getRSAPublicKey

protected RSAPublicKey getRSAPublicKey(java.math.BigInteger modulus,
                                       java.math.BigInteger publicExponent)
                                throws java.lang.Exception

This method returns a RSAPublicKey created from the values: modulus and publicExponent. This method only must be implemented if one wants to use exportable RSA cipher suites.

Parameters:

modulus - the modulus

publicExponent - the public exponent

Returns:

the new created RSAPublicKey

getX509Certificate

protected X509Certificate getX509Certificate(byte[] array)
                                      throws java.lang.Exception

This method returns a X509Certificate created from a DER encoded byte array.

Parameters:

array - a X509Certificate as DER encoded byte array

Returns:

the created X509Certificate

getPrincipal

protected Principal getPrincipal(byte[] array)
                          throws java.lang.Exception

This method returns a Principal created from a DER encoded byte array. A Principal in Sun's point of view is the ASN.1 stucture: Name. This method is the opposite of getEncodedPrincipal(Principal).

Parameters:

array - a Name (Principal) as DER encoded byte array

Returns:

the created Name (Principal)

getEncodedPrincipal

protected byte[] getEncodedPrincipal(Principal principal)

This method returns a DER encoded Name (Principal). A Principal in Sun's point of view is the ASN.1 stucture: Name. This method is the oposite of getPrincipal(byte[]).

Parameters:

principal - the Name (Principal) to encode

Returns:

the Name (Principal) as DER encoded byte array

getMessageDigest

protected MessageDigest getMessageDigest(java.lang.String algorithm)
                                  throws java.lang.Exception

This method returns the desired MessageDigest object. iSaSiLk makes use of the following algorithms:

• "SHA"
• "MD5"

Parameters:

algorithm - the name of the algorithm

getMac

protected Mac getMac(java.lang.String algorithm,
                     Key key)
              throws java.lang.Exception

This method returns the desired HMAC object. These are required for TLS. If your provider is never to be used with TLS you can return null here (not recommended though). iSaSiLk makes use of the following algorithms:

• "HmacMD5"
• "HmacSHA1"

Parameters:

algorithm - the name of the algorithm

getSignature

protected Signature getSignature(java.lang.String algorithm,
                                 int mode,
                                 Key key,
                                 SecureRandom random)
                          throws java.lang.Exception

This method returns the desired Signature object. iSaSiLk makes use of the following algorithms:

• "SHA1withDSA"
• "RawDSA" (DSA client authentication only)
• "MD5withRSA" (SSL 2.0 client authentication only)

If the mode parameter is SIGNATURE_SIGN or SIGNATURE_VERIFY the signature object is to be initialized with the provided key in the respective mode.

getCipher

protected Cipher getCipher(java.lang.String algorithm,
                           int mode,
                           Key key,
                           AlgorithmParameterSpec param,
                           SecureRandom random)
                    throws java.lang.Exception

This method returns the desired Cipher object. iSaSiLk makes use of the following algorithms:

• "RSA/ECB/PKCS1Padding/xxx" (see note above)
• "RC4/ECB/NoPadding"
• "RC2/CBC/NoPadding"
• "IDEA/CBC/NoPadding"
• "DES/CBC/NoPadding"
• "DESede/CBC/NoPadding"

The symmetric ciphers shall explain themselves.

RSA/ECB/PKCS1Padding means RSA en/decryption with padding as defined in PKCS#1 1.5 where the padding block type is automatically selected based on the type of key used (block type 1 for signature operations, block type 2 for encryption operations). This cipher will be always used the same way (other methods need not to be implemented!):

 Cipher rsa = provider.getCipher("RSA/ECB/PKCS1Padding/...", ...);
 crypted = rsa.doFinal(plain);
 

If the mode parameter is CIPHER_ENCRYPT or CIPHER_DECRYPT the cipher object is to be initialized with the provided key in the respective mode.

getKeyPairGenerator

protected KeyPairGenerator getKeyPairGenerator(java.lang.String algorithm)
                                        throws java.lang.Exception

Return a KeyPairGenerator for the requested algorithm.

This method is only called to generate temporary RSA keys of 512 or 1024 bit if those are required for an export cipher and you have not set any in the SSLServerContext.

getSecureRandom

protected SecureRandom getSecureRandom()

Return a new instance of a SecureRandom number generator. This can be the original java.security.SecureRandom or a better generator if available (as when using IAIK JCE).