CredentialManager (Java Card API, 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.security
Class CredentialManager

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

- retrieving and handling the application-private credentials securely within the application's context.
- retrieving credentials in any required application-specific/dependent way.
- retrieving and handling credentials that may be protocol dependent, such as public key certificates and private keys, when asymmetric cryptography is used for SSL/TLS handshake, or shared secret keys, when symmetric cryptography is used for SSL/TLS handshake.

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:

- HTTPS connections managed by the Web container,
- SSL/TLS server secure socket GCF connections managed by the application itself,
- SSL/TLS and HTTPS client secure socket GCF connections managed by the application itself,
- and inter-application communications thru SIO-based services or events.

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:

- in an application's group context by the card manager at instantiation-time,
- in an application's owner context by the application itself throughout its lifetime.

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.

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.