CryptoProvider (Java Card SPI, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacardx.spi.security
Class CryptoProvider

    java.lang.Object
      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:

- <crypto_service>.<algorithm_or_type>
- <crypto_service>.<key_algorithm_or_type>.<key_length>

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:
  - <crypto_service>.<algorithm_or_type>
  - <crypto_service>.<key_algorithm_or_type>.<key_length>
  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:
  - <crypto_service>.<algorithm_or_type>
  - <crypto_service>.<key_algorithm_or_type>.<key_length>

  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:

  - <crypto_service>.<algorithm_or_type>
  - <crypto_service>.<key_algorithm_or_type>.<key_length>
  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:
  - <crypto_service>.<algorithm_or_type>
  - <crypto_service>.<key_algorithm_or_type>.<key_length>
  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:
  - <crypto_service>.<algorithm_or_type>
  - <crypto_service>.<key_algorithm_or_type>.<key_length>
  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:
  - <crypto_service>.<algorithm_or_type>
  - <crypto_service>.<key_algorithm_or_type>.<key_length>
  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:
  - <crypto_service>.<algorithm_or_type>
  - <crypto_service>.<key_algorithm_or_type>.<key_length>
  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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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