|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavacardx.security.CredentialManager
@TransactionType(value=SUPPORTS) @SensitiveType(sensitivity=INTEGRITY) public abstract class CredentialManager
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:
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:
CredentialManager and SecurityRequirements objects may be set:
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.
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 |
---|
public static final byte MODE_DEFAULT
public static final byte MODE_GCF_CLIENT
public static final byte MODE_GCF_SERVER
public static final byte MODE_SIO_CLIENT
public static final byte MODE_SIO_SERVER
public static final byte MODE_WEB_SERVER
Constructor Detail |
---|
public CredentialManager()
Method Detail |
---|
public static final CredentialManager getCredentialManager(byte mode)
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.
mode
- the mode of operation.
SecurityException
- if the permission to get a credential manager is not granted.
IllegalArgumentException
- if the mode is invalid.public static final void setCredentialManager(CredentialManager manager, byte mode)
Note that the credential manager will override in that mode the credential manager set by the card manager, if any.
manager
- the credential manager.mode
- the mode of operation.
SecurityException
- if the permission to set a credential manager is not granted.
IllegalArgumentException
- if the mode is invalid.public static final CredentialManager.SecurityRequirements getSecurityRequirements(byte mode)
mode
- the mode of operation.
IllegalArgumentException
- if the mode is invalid.public static final void setSecurityRequirements(CredentialManager.SecurityRequirements requirements, byte mode)
requirements
- the security requirements.mode
- the mode of operation.
IllegalArgumentException
- if the mode is invalid.public abstract void checkTrusted(Certificate[] certificateChain, String authType, String endpointURI, byte mode) throws CertificateException
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:
MODE_GCF_CLIENT
)authType
should be "RSA". Checking is case-sensitive.MODE_GCF_SERVER
or MODE_WEB_SERVER
)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.
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
.
CertificateException
- if the certificate chain is not trusted.public abstract Certificate[] getAcceptedCertificateIssuers(String endpointURI, byte mode)
endpointURI
- the canonicalized endpoint URI.mode
- the mode of operation: MODE_GCF_SERVER
or MODE_WEB_SERVER
.
public abstract Certificate[] chooseCertificateChain(String[] types, String[] issuers, String endpointURI, byte mode)
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.
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
.
public abstract byte[] choosePreSharedKey(String pskIdentity, String endpointURI, byte mode)
This operation may depend on the endpoint URI used for the connection.
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
.
public abstract String getPSKIdentityHint(String endpointURI, byte mode)
endpointURI
- the canonicalized endpoint URI.mode
- the mode of operation: MODE_GCF_SERVER
or
MODE_WEB_SERVER
.
public abstract String getPSKIdentity(String hint, String endpointURI, byte mode)
hint
- the PSK identity hint provided by the peer.endpointURI
- the canonicalized endpoint URI.mode
- the mode of operation: MODE_GCF_CLIENT
.
public abstract PrivateKey getMatchingPrivateKey(Certificate certificate, String endpointURI, byte mode)
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
.
public abstract Object[] getTrustedCredentials(String[] aliases, String endpointURI, byte mode)
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.
aliases
- the credential aliases.endpointURI
- the canonicalized endpoint URI.mode
- the mode of operation: MODE_SIO_SERVER
.
public abstract Key[] getCredentials(String[] types, String endpointURI, byte mode)
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.
types
- the key type names as defined by
KeyBuilder
.endpointURI
- the canonicalized endpoint URI.mode
- the mode of operation: MODE_SIO_CLIENT
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |