javacardx.spi.security
Class CryptoProvider

java.lang.Object
  extended by javacardx.spi.security.CryptoProvider

@TransactionType(value=NOT_SUPPORTED)
public abstract class CryptoProvider
extends Object

This is the container for all information concerning cryptographic service implementations available from a given provider.

This class maintains the list of all cryptographic service providers. It provides static methods to retrieve cryptographic service implementations based on the name of the cryptographic algorithm and optionally the name of a provider.

When asked for a cryptographic algorithm and a specific provider, this class must lookup the provider and retrieve/determine the name of the class implementing the specified algorithm. It then returns an instance of the retrieved cryptographic algorithm.

When asked for a cryptographic algorithm without specifying a provider, this class must lookup the provider providing the required algorithm which has the higher rank in the preference order. It then returns an instance of the cryptographic algorithm class implemented by that provider.

The cryptographic algorithm name as used by this class must have one of the following formats:

The cryptographic service name for each of the cryptographic service implementation classes is defined by the constant SERVICE_NAME in each of these classes. Each of these classes also defines the constants for each of the algorithms and types these cryptographic service support.

This class is an abstract class. It must be subclassed to provide an implementation of the createAlgorithmImpl(String, boolean) method that retrieves and instantiates the class implementing the requested algorithm.

Java Card RE-owned instances of CryptoProvider are permanent Java Card runtime environment Entry Point Objects.

Since:
Java Card 3.0
See Also:
CryptoServices

Constructor Summary
CryptoProvider(String name, String[] algorithmNames)
          Creates and registers a new provider with the specified name and the list of supported algorithms.
 
Method Summary
protected abstract  Object createAlgorithmImpl(String algorithm, boolean param)
          Returns a cryptographic service implementation object corresponding to the given algorithm.
static Object getAlgorithmImpl(String algorithm)
          Returns a cryptographic service implementation object related to the given algorithm name.
static Object getAlgorithmImpl(String algorithm, boolean param)
          Returns a cryptographic service implementation object related to the given algorithm name.
static Object getAlgorithmImpl(String algorithm, String provider)
          Returns a cryptographic service implementation object related to the given algorithm and provider names.
static Object getAlgorithmImpl(String algorithm, String provider, boolean param)
          Returns a cryptographic service implementation object related to the given algorithm and provider names.
 String[] getAlgorithmNames()
          Returns an array containing the names of all algorithms implemented by this provider.
static String[] getAlgorithms()
          Returns an array containing the names of all available algorithms on the platform.
 String getName()
          Returns the name of this crypto provider.
static String[] getProviders()
          Returns an array containing all the installed providers.
static String[] getProviders(String filter)
          Returns an array containing all installed providers that satisfy the specified selection criteria, or null if no such providers have been installed.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CryptoProvider

public CryptoProvider(String name,
                      String[] algorithmNames)
Creates and registers a new provider with the specified name and the list of supported algorithms. The order in which provider instances are created corresponds to the preference order.

Subclasses of the CryptoProvider class must call this constructor.

Note: Concrete implementations of this class must guarantee the immutability of CryptoProvider objects.

Parameters:
name - the provider name.
algorithmNames - the algorithm names supported by the provider.
Throws:
NullPointerException - if name or algorithmNames is null.
IllegalArgumentException - if a provider with that same name is already registered.
Method Detail

getProviders

public static final String[] getProviders()
Returns an array containing all the installed providers. The order of the providers in the array is their preference order.

Note: this method returns a different array (a defensive copy) for each call in order to guarantee the immutability of the underlying system data structure.

Returns:
an array of all the installed providers, or null if none have been installed.

getAlgorithms

public static final String[] getAlgorithms()
Returns an array containing the names of all available algorithms on the platform. Algorithm names are in the following formats: for example, "keyBuilder.DES.64".

Note: this method returns a different array (a defensive copy) upon each call in order to guarantee the immutability of the underlying system data structure.

Returns:
an array containing the names of all available algorithms on the platform, or null if none have been installed.

getProviders

public static final String[] getProviders(String filter)
Returns an array containing all installed providers that satisfy the specified selection criteria, or null if no such providers have been installed. The returned providers are ordered according to their preference order. The selection criterion must be specified in one of the following formats:

A provider satisfies the specified selection criterion iff the provider implements the specified algorithm or type for the specified cryptographic service.

For example, "keyBuilder.DES.64" would be satisfied by any provider that supplied a KeyBuilder implementation for DES keys.

Note: this method returns a different array (a defensive copy) upon each call in order to guarantee the immutability of the underlying system data structure.

Parameters:
filter - the criterion for selecting providers or null for any provider. The filter is case-insensitive.
Returns:
all the installed providers that satisfy the selection criterion, or null if no such providers have been installed.

getAlgorithmImpl

public static final Object getAlgorithmImpl(String algorithm,
                                            boolean param)
Returns a cryptographic service implementation object related to the given algorithm name. This method returns an instance of the matching cryptographic service implementation that is supported by the provider which has the higher rank in the preference order.

Algorithm names are in the following formats:

for example, "keyBuilder.DES.64".

Parameters:
algorithm - the algorithm name.
param - parameter whose interpretation is crypto service-specific; it must correspond to:
  • the requirement for an instance of the crypto service that can be shared among multiple group contexts and that can be accessed via a Shareable interface,
  • or, the requirement for a key instance that implements the KeyEncryption interface.
Returns:
a cryptographic service implementation object related to the given algorithm name, or null if no such algorithm is installed.
Throws:
NullPointerException - if algorithm is null.
SecurityException - if creating an instance of the requested cryptographic service is not granted.

getAlgorithmImpl

public static final Object getAlgorithmImpl(String algorithm)
Returns a cryptographic service implementation object related to the given algorithm name. Algorithm names are in the following formats: for example, "keyBuilder.DES.64".

Parameters:
algorithm - the algorithm name.
Returns:
a cryptographic service implementation object related to the given algorithm name, or null if no such algorithm is installed.
Throws:
NullPointerException - if algorithm is null.
SecurityException - if creating an instance of the requested cryptographic service is not granted.

getAlgorithmImpl

public static final Object getAlgorithmImpl(String algorithm,
                                            String provider,
                                            boolean param)
Returns a cryptographic service implementation object related to the given algorithm and provider names. Algorithm names are in the following formats: for example, "keyBuilder.DES.64".

Parameters:
algorithm - the algorithm name.
provider - the provider name, or null for any provider.
param - parameter whose interpretation is crypto service-specific; it must correspond to:
  • the requirement for an instance of the crypto service that can be shared among multiple group contexts and that can be accessed via a Shareable interface,
  • or, the requirement for a key instance that implements the KeyEncryption interface.
Returns:
a cryptographic service implementation object related to the given algorithm and provider names, or null if no such provider or algorithm is installed.
Throws:
NullPointerException - if algorithm is null.
SecurityException - if creating an instance of the requested cryptographic service is not granted.

getAlgorithmImpl

public static final Object getAlgorithmImpl(String algorithm,
                                            String provider)
Returns a cryptographic service implementation object related to the given algorithm and provider names. Algorithm names are in the following formats: for example, "keyBuilder.DES.64".

Parameters:
algorithm - the algorithm name.
provider - the provider name, or null for any provider.
Returns:
a cryptographic service implementation object related to the given algorithm and provider names, or null if no such provider or algorithm is installed.
Throws:
NullPointerException - if algorithm is null.
SecurityException - if creating an instance of the requested cryptographic service is not granted.

createAlgorithmImpl

protected abstract Object createAlgorithmImpl(String algorithm,
                                              boolean param)
Returns a cryptographic service implementation object corresponding to the given algorithm. Algorithm names are in the following formats: for example, "keyBuilder.DES.64".

A provider-specific subclass must implement this method to configure the instantiated object before being returned such as with the extra parameter param or with parameters extracted from the algorithm name such as the key length for a KeyBuilder crypto service.

Parameters:
algorithm - the algorithm name.
param - parameter whose interpretation is crypto service-specific; it must correspond to:
  • the requirement for an instance of the crypto service that can be shared among multiple group contexts and that can be accessed via a Shareable interface,
  • or, the requirement for a key instance that implements the KeyEncryption interface.
Returns:
a cryptographic service implementation object related to the given algorithm, or null if no such algorithm is installed or could be created.
Throws:
NullPointerException - if algorithm is null.

getAlgorithmNames

public String[] getAlgorithmNames()
Returns an array containing the names of all algorithms implemented by this provider.

Implementation of this method must guarantee the immutability of CryptoProvider objects, such as by returning a defensive copy of the original array.

Returns:
an array containing the names of all implemented algorithms.

getName

public String getName()
Returns the name of this crypto provider.

Returns:
the name of this crypto provider.


Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.