javacardx.security
Class CredentialManager

java.lang.Object
  extended by javacardx.security.CredentialManager

@TransactionType(value=SUPPORTS)
@SensitiveType(sensitivity=INTEGRITY)
public abstract class CredentialManager
extends Object

CredentialManager objects manage the credentials used to establish secure communications with peers. More precisely, CredentialManager objects are responsible both for managing the key material that is used to authenticate with peers and for managing the trust material that is used when making trust decisions, such as when deciding whether credentials presented by a peer should be accepted.

CredentialManager objects allow for:

The determination of the security characteristics that must be required (the security requirements) when establishing secure communications with peers is managed independently of credential managers by the means of CredentialManager.SecurityRequirements objects.

The credentials and the security requirements to be used for establishing a particular secure communication may depend on the type of communication and its mode of operation:

Additionally, for finer granularity of management of credentials and security requirements, the endpoint URI is passed as an additional parameter to the methods of CredentialManager and SecurityRequirements objects so that this information can be used to determine the proper credentials or security requirements to be used depending not only on the mode of operation (WEB, GCF...) but also on the actual connection or access endpoint URI. Endpoint URIs passed as parameters to methods of CredentialManager and SecurityRequirements objects are canonicalized URIs.

CredentialManager and SecurityRequirements objects may be set:

These CredentialManager and SecurityRequirements objects' methods are invoked by the protocol handlers establishing (or accepting) secure communications with (resp. from) peers on behalf of the application. Protocol handlers must in priority use the credential manager and security requirements set by the application for a specified mode of operation or for the default mode of operation; if none is set, they must use the credential manager and security requirements set by the card manager.

The credential manager and the security requirements that must apply for a particular connection being established are looked up independently of each other by the protocol handler.

Only credential managers and security requirements set by applications themselves can be retrieved through this API: credential managers and security requirements set by the card manager are not accessible to applications.

Credential manager setting and getting are subject to permission checks.

See Runtime Environment Specification for the Java Card Platform, Connected Edition, chapters 3, 6 and 8 for details regarding credential management and related descriptor-based configuration.

See Also:
CredentialManager.SecurityRequirements, KeyBuilder, JCRuntimePermission, SecurityInfo, TLSSecurityInfo

Nested Class Summary
static class CredentialManager.SecurityRequirements
          Encapsulates the requirements for a secure connection or access.
 
Field Summary
static byte MODE_DEFAULT
          The default mode of operation.
static byte MODE_GCF_CLIENT
          The mode of operation corresponding to GCF client communications.
static byte MODE_GCF_SERVER
          The mode of operation corresponding to GCF server communications.
static byte MODE_SIO_CLIENT
          The mode of operation corresponding to the client-side of SIO-based inter-application communications.
static byte MODE_SIO_SERVER
          The mode of operation corresponding to the server-side of SIO-based inter-application communications.
static byte MODE_WEB_SERVER
          The mode of operation corresponding to HTTP/HTTPS communications managed by the Web container.
 
Constructor Summary
CredentialManager()
           
 
Method Summary
abstract  void checkTrusted(Certificate[] certificateChain, String authType, String endpointURI, byte mode)
          Checks whether the complete or partial certificate chain provided by the peer is trusted for authentication (based on the authentication type) of a connection/access to the specified endpoint URI.
abstract  Certificate[] chooseCertificateChain(String[] types, String[] issuers, String endpointURI, byte mode)
          Chooses the certificate chain (of one of the specified key types) to be used to authenticate a connection/access to the specified endpoint URI given the public key types and the list of certificate issuer authorities recognized by the peer (if any).
abstract  byte[] choosePreSharedKey(String pskIdentity, String endpointURI, byte mode)
          Chooses the pre-shared key to be used to authenticate a connection/access to the specified endpoint URI given the PSK (Pre-Shared Key) identity designated or hinted at by the peer (if any).
abstract  Certificate[] getAcceptedCertificateIssuers(String endpointURI, byte mode)
          Returns the list of certificate authority certificates which are trusted for authenticating a peer connection/access to the specified endpoint URI.
static CredentialManager getCredentialManager(byte mode)
          Returns the credential manager set by the currently executing application for the specified mode of operation.
abstract  Key[] getCredentials(String[] types, String endpointURI, byte mode)
          Returns the current application's credentials (keys) of the specified types to be used to access the specified endpoint URI.
abstract  PrivateKey getMatchingPrivateKey(Certificate certificate, String endpointURI, byte mode)
          Returns the private key corresponding to the specified certificate used to authenticate a connection/access to the specified endpoint URI.
abstract  String getPSKIdentity(String hint, String endpointURI, byte mode)
          Returns the PSK (Pre-Shared Key) identity to be used to authenticate a connection/access to the specified endpoint URI given the PSK identity hint provided by the peer (the TLS server).
abstract  String getPSKIdentityHint(String endpointURI, byte mode)
          Returns the PSK (Pre-Shared Key) identity hint to be used to authenticate a connection/access to the specified endpoint URI.
static CredentialManager.SecurityRequirements getSecurityRequirements(byte mode)
          Returns the security requirements set by the currently executing application for the specified mode of operation.
abstract  Object[] getTrustedCredentials(String[] aliases, String endpointURI, byte mode)
          Returns the peer application's credential (keys or certificates) associated with the provided aliases and required to access the specified endpoint URI.
static void setCredentialManager(CredentialManager manager, byte mode)
          Sets the credential manager of the currently executing application for the specified mode of operation.
static void setSecurityRequirements(CredentialManager.SecurityRequirements requirements, byte mode)
          Sets the security requirements of the currently executing application for the specified mode of operation.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MODE_DEFAULT

public static final byte MODE_DEFAULT
The default mode of operation.

See Also:
Constant Field Values

MODE_GCF_CLIENT

public static final byte MODE_GCF_CLIENT
The mode of operation corresponding to GCF client communications.

See Also:
Constant Field Values

MODE_GCF_SERVER

public static final byte MODE_GCF_SERVER
The mode of operation corresponding to GCF server communications.

See Also:
Constant Field Values

MODE_SIO_CLIENT

public static final byte MODE_SIO_CLIENT
The mode of operation corresponding to the client-side of SIO-based inter-application communications.

See Also:
Constant Field Values

MODE_SIO_SERVER

public static final byte MODE_SIO_SERVER
The mode of operation corresponding to the server-side of SIO-based inter-application communications.

See Also:
Constant Field Values

MODE_WEB_SERVER

public static final byte MODE_WEB_SERVER
The mode of operation corresponding to HTTP/HTTPS communications managed by the Web container.

See Also:
Constant Field Values
Constructor Detail

CredentialManager

public CredentialManager()
Method Detail

getCredentialManager

public static final CredentialManager getCredentialManager(byte mode)
Returns the credential manager set by the currently executing application for the specified mode of operation.

Note that this method does not return the credential manager which may have been set by the card manager and which applies if no other credential manager instance has been set by the application for the mode.

Parameters:
mode - the mode of operation.
Returns:
the credential manager set for the specified mode, if any; null otherwise.
Throws:
SecurityException - if the permission to get a credential manager is not granted.
IllegalArgumentException - if the mode is invalid.

setCredentialManager

public static final void setCredentialManager(CredentialManager manager,
                                              byte mode)
Sets the credential manager of the currently executing application for the specified mode of operation.

Note that the credential manager will override in that mode the credential manager set by the card manager, if any.

Parameters:
manager - the credential manager.
mode - the mode of operation.
Throws:
SecurityException - if the permission to set a credential manager is not granted.
IllegalArgumentException - if the mode is invalid.

getSecurityRequirements

public static final CredentialManager.SecurityRequirements getSecurityRequirements(byte mode)
Returns the security requirements set by the currently executing application for the specified mode of operation.

Parameters:
mode - the mode of operation.
Returns:
the security requirements set for the specified mode, if any; null otherwise.
Throws:
IllegalArgumentException - if the mode is invalid.

setSecurityRequirements

public static final void setSecurityRequirements(CredentialManager.SecurityRequirements requirements,
                                                 byte mode)
Sets the security requirements of the currently executing application for the specified mode of operation.

Parameters:
requirements - the security requirements.
mode - the mode of operation.
Throws:
IllegalArgumentException - if the mode is invalid.

checkTrusted

public abstract void checkTrusted(Certificate[] certificateChain,
                                  String authType,
                                  String endpointURI,
                                  byte mode)
                           throws CertificateException
Checks whether the complete or partial certificate chain provided by the peer is trusted for authentication (based on the authentication type) of a connection/access to the specified endpoint URI.

The certificate chain is ordered with the peer's subject certificate first and the trusted root certificate last.

Before being passed to this method, the provided certificate chain has been validated by the SSL/TLS protocol handler (for X.509 certificates, RFC 3280 defines a standardized path validation algorithm). This validation includes the checking of the proper chaining and signing of the certificates; checking of the validity period of the certificates and of the revocation status is on a best effort basis.

The authentication type determination depends on the mode of communication:

Client mode (MODE_GCF_CLIENT)
The authentication type is the key exchange algorithm portion of the cipher suite name (as defined in the Key Exchange column of the CipherSuite definitions table in Appendix C of RFC 5246). For example, for the "TLS_RSA_WITH_RC4_128_MD5" cipher suite, the authType should be "RSA". Checking is case-sensitive.
Server mode (MODE_GCF_SERVER or MODE_WEB_SERVER)
The authentication type is the name of the key type (as defined by KeyBuilder) of the certificates provided by the client upon a certificate request by the server. Note that this key type corresponds to the key type of one of the certificates returned by the getAcceptedCertificateIssuers() method and that this key type may not correspond to that of the key exchange algorithm. For example, if RSAPublicKey is used, the authType should be "RSA_PUBLIC". Checking is case-sensitive.

Parameters:
certificateChain - the (previously validated) certificate chain to be checked.
authType - the key exchange algorithm used or the key type of the client's certificate.
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_GCF_CLIENT, MODE_GCF_SERVER or MODE_WEB_SERVER.
Throws:
CertificateException - if the certificate chain is not trusted.

getAcceptedCertificateIssuers

public abstract Certificate[] getAcceptedCertificateIssuers(String endpointURI,
                                                            byte mode)
Returns the list of certificate authority certificates which are trusted for authenticating a peer connection/access to the specified endpoint URI.

Parameters:
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_GCF_SERVER or MODE_WEB_SERVER.
Returns:
the list of accepted CA issuer certificates or null if all are accepted.

chooseCertificateChain

public abstract Certificate[] chooseCertificateChain(String[] types,
                                                     String[] issuers,
                                                     String endpointURI,
                                                     byte mode)
Chooses the certificate chain (of one of the specified key types) to be used to authenticate a connection/access to the specified endpoint URI given the public key types and the list of certificate issuer authorities recognized by the peer (if any).

The certificate chain must be ordered with the subject certificate first and the trusted root certificate last.

This operation may depend on the endpoint URI used for the connection.

Parameters:
types - the accepted key type names as defined by KeyBuilder, ordered with the most-preferred key type first.
issuers - the list of acceptable certificate issuer subject names or null if it does not matter which issuers are used.
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_GCF_CLIENT, MODE_GCF_SERVER or MODE_WEB_SERVER.
Returns:
the certificate chain to be used or null if no suitable certificate chain could be determined.

choosePreSharedKey

public abstract byte[] choosePreSharedKey(String pskIdentity,
                                          String endpointURI,
                                          byte mode)
Chooses the pre-shared key to be used to authenticate a connection/access to the specified endpoint URI given the PSK (Pre-Shared Key) identity designated or hinted at by the peer (if any). This method is invoked during TLS-PSK handshakes.

This operation may depend on the endpoint URI used for the connection.

Parameters:
pskIdentity - the PSK identity designated or hinted at by the peer (may be null).
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_GCF_CLIENT, MODE_GCF_SERVER or MODE_WEB_SERVER.
Returns:
the pre-shared key for the provided PSK identity, or null if no suitable key could be determined.

getPSKIdentityHint

public abstract String getPSKIdentityHint(String endpointURI,
                                          byte mode)
Returns the PSK (Pre-Shared Key) identity hint to be used to authenticate a connection/access to the specified endpoint URI. This method is invoked on the server side of a connection during a TLS-PSK handshake.

Parameters:
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_GCF_SERVER or MODE_WEB_SERVER.
Returns:
the PSK identity hint, or null if none could be determined.

getPSKIdentity

public abstract String getPSKIdentity(String hint,
                                      String endpointURI,
                                      byte mode)
Returns the PSK (Pre-Shared Key) identity to be used to authenticate a connection/access to the specified endpoint URI given the PSK identity hint provided by the peer (the TLS server). This method is invoked on the client side of a connection during a TLS-PSK handshake.

Parameters:
hint - the PSK identity hint provided by the peer.
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_GCF_CLIENT.
Returns:
the PSK identity, or null if none could be determined.

getMatchingPrivateKey

public abstract PrivateKey getMatchingPrivateKey(Certificate certificate,
                                                 String endpointURI,
                                                 byte mode)
Returns the private key corresponding to the specified certificate used to authenticate a connection/access to the specified endpoint URI.

Parameters:
certificate - the public key certificate.
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_GCF_CLIENT, MODE_GCF_SERVER or MODE_WEB_SERVER.
Returns:
the private key object corresponding to the specified public key certificate, or null if no matching key could be determined.

getTrustedCredentials

public abstract Object[] getTrustedCredentials(String[] aliases,
                                               String endpointURI,
                                               byte mode)
Returns the peer application's credential (keys or certificates) associated with the provided aliases and required to access the specified endpoint URI.

This method is invoked by the Java Card RE, for example, when the server application of a protected resource has invoked JCSystem.isClientInRole(String, String), to retrieve the server application's credential to be used for authenticating the client application attempting to access the protected resource. The credential aliases correspond to the aliases the role was mapped to at deployment-time in the Runtime descriptor.

A CredentialManager implementation may use both, only one or none of the parameters aliases and endpointURI to determine the credential(s) to be returned.

Parameters:
aliases - the credential aliases.
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_SIO_SERVER.
Returns:
the credential object instances (keys or certificates) associated with the provided aliases, or null if no suitable credentials could be determined.

getCredentials

public abstract Key[] getCredentials(String[] types,
                                     String endpointURI,
                                     byte mode)
Returns the current application's credentials (keys) of the specified types to be used to access the specified endpoint URI.

This method is invoked by the Java Card RE, for example, when the server application of a protected resource has invoked JCSystem.isClientInRole(String, String), to retrieve the credential to be used for authenticating the client application attempting to access the protected resource.

The types of the credentials (keys) are the types that can be paired with the credentials the peer application provided for authenticating the current application as per a call to getTrustedCredentials(java.lang.String[], java.lang.String, byte). The key types passed are only base key types. If the peer application provided a certificate, the key type passed is the type of the private key that can be paired to the certificate'subject's public key.

For example, if the peer application provided a key of type name DES_TRANSIENT_RESET, the key type passed to this method is the base key type DES. If the peer application provided a key of type name RSA_PUBLIC, the key type passed to this method is the paired key type RSA_PRIVATE.

The current application may be required to use different credentials for the same resource URI depending on the roles defined by the peer application.

Parameters:
types - the key type names as defined by KeyBuilder.
endpointURI - the canonicalized endpoint URI.
mode - the mode of operation: MODE_SIO_CLIENT.
Returns:
the credential object instances (keys) of the requested type, or null if no suitable credentials could be determined.


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