Class SslSession
- java.lang.Object
-
- com.intel.crypto.SslSession
-
- All Implemented Interfaces:
- SecureSession, StreamCipher
public abstract class SslSession extends java.lang.Object implements StreamCipher, SecureSession
This abstract class represents an SSL session This class implements both the
StreamCipher
andSecureSession
interfaces and allows to establish a secure SSL session with a remote SSL server, and passing encrypted data within this session.Establishing a session:
- Call
CertificateStore.create()
to create a new certificate store. This store can be reused by multiple sessions. - Add trusted root CA certificates to the store using
addCertificate()
. - Create a
Calendar
instance and initialize the time to establish the session's notion of time. - Call
SslSession.create()
with the session parameters (time, FQDN and certificate store) to create a new session instance. - Call
performHandshake()
sequentially transferring the handshake messages between the session and the remote SSL server. - Call
isEstablished()
to check if the handshake completed successfully.
encrypt()
anddecrypt()
inside the SSL session.
NOTE: the default protocol version for negotiation is TLS 1.2Verifying CRLs (after handshake):
- Call
getChainInfo()
to retrieve an array ofSslSession.CertificateInfo
instances that represent the certificate chain which was received from the SSL server during the handshake phase, ordered from leaf to root. - Start from the first intermediate certificate (one before the last in the array) and finish with the leaf.
- For each certificate in the chain:
- Retrieve the CRL distribution points from the certificate using
CertificateInfo.getInfo()
and pass it to the host software. - After the host software obtains the CRLs, for each CRL distribution point:
- Call
createCrl()
using the same index of the certificate with the CRL distribution point. - Add the CRL chunk by chunk using
Crl.appendChunk()
. - Call
Crl.verify()
to make sure the CRL is in the correct format and signed. - Call
Crl.getTimeRange()
and verify the CRL in hand is up to date. - Obtain the certificate serial number using
CertificateInfo.getInfo()
. - Search for the serial number using
Crl.findSerialNumber()
to make sure the certificate is not revoked. - Call
Crl.destroy()
to release system resources.
- Call
Closing session:
- Call
generateAlertMessage()
with alertTypeSSL_ALERT_CLOSE_NOTIFY
and send the output buffers to the remote SSL server. - Call
destroy()
to release system resources.
Stop using SSL services:
If SSL services are no longer needed, the user should invokeCertificateStore.destroy()
for each certificate store instance created anddestroy()
for each SslSession instance created to release the system resources.SSL alerts:
Any of the session methods throwingOperationFailedException
stands for an SSL alert that was either received from the server or generated by the DAL firmware during the communication with the SSL server, all alerts are treated as fatal rendering the session unusable. The only methods that are allowed in this state are:destroy()
getFailure()
isServerAlert()
generateAlertMessage()
hasMoreOutput()
- session state getters
OperationFailedException
should be as follows:- Call
isServerAlert()
to understand whether an alert was sent from the server or DAL FW decided that alert should be generated.- if the server sent the alert
- Call
getFailure()
to check thealertType
the server sent
- if
(alertType ==
SSL_ALERT_CLOSE_NOTIFY
)
- requests to close the session gracefully- Call
generateAlertMessage()
with alertTypeSSL_ALERT_CLOSE_NOTIFY
and send the output buffers to the remote SSL server.
- Call
- if DAL FW decided that alert should be generated
- Call
getFailure()
to determine thealertType
that should be generated - Call
generateAlertMessage()
with thealertType
received fromgetFailure()
and send the output buffers to the remote SSL server.
- Call
destroy()
to release system resources.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class and Description static class
SslSession.CertificateInfo
This class represents single certificate in the certificate chain received from the SSL server during the Handshake phasestatic class
SslSession.Crl
This class represents a certificate revocation list object.
-
Field Summary
Fields Modifier and Type Field and Description static int
ASYMMETRIC_KEY_RSA_1024
An RSA key with 1024 bits strengthstatic int
ASYMMETRIC_KEY_RSA_2048
An RSA key with 2048 bits strengthstatic int
ASYMMETRIC_KEY_RSA_4096
An RSA key with 4096 bits strengthstatic short
PROTOCOL_VERSION_SSL_3_0
Deprecated.no longer supported due to existing security vulnerabilities.static short
PROTOCOL_VERSION_TLS_1_0
The TLSv1 protocol versionstatic short
PROTOCOL_VERSION_TLS_1_1
The TLSv1.1 protocol versionstatic short
PROTOCOL_VERSION_TLS_1_2
The TLSv1.2 protocol version.static short
SSL_ALERT_ACCESS_DENIED
static short
SSL_ALERT_BAD_CERTIFICATE
static short
SSL_ALERT_BAD_CERTIFICATE_HASH_VALUE
static short
SSL_ALERT_BAD_CERTIFICATE_STATUS_RESPONSE
static short
SSL_ALERT_BAD_CERTIFICATE_UNKNOWN_PSK
static short
SSL_ALERT_BAD_RECORD_MAC
static short
SSL_ALERT_CERTIFICATE_EXPIRED
static short
SSL_ALERT_CERTIFICATE_REVOKED
static short
SSL_ALERT_CERTIFICATE_UNKNOWN
static short
SSL_ALERT_CERTIFICATE_UNOBTAINABLE
static short
SSL_ALERT_CLOSE_NOTIFY
static short
SSL_ALERT_DECODE_ERROR
static short
SSL_ALERT_DECOMPRESSION_FAILURE
static short
SSL_ALERT_DECRYPT_ERROR
static short
SSL_ALERT_DECRYPTION_FAILED
static short
SSL_ALERT_EXPORT_RESTRICTION
static short
SSL_ALERT_HANDSHAKE_FAILURE
static short
SSL_ALERT_ILLEGAL_PARAMETER
static short
SSL_ALERT_INSUFFICIENT_SECURITY
static short
SSL_ALERT_INTERNAL_ERROR
static short
SSL_ALERT_NO_CERTIFICATE
static short
SSL_ALERT_NO_RENEGOTIATION
static short
SSL_ALERT_NONE
Indicates success status - no alert occurred ; corresponds to JOM_SSL_ALERT_NONEstatic short
SSL_ALERT_PROTOCOL_VERSION
static short
SSL_ALERT_RECORD_OVERFLOW
static short
SSL_ALERT_UNEXPECTED_MESSAGE
static short
SSL_ALERT_UNKNOWN_CA
static short
SSL_ALERT_UNRECOGNIZED_NAME
static short
SSL_ALERT_UNSUPPORTED_CERTIFICATE
static short
SSL_ALERT_UNSUPPORTED_EXTENSION
static short
SSL_ALERT_USER_CANCELED
static short
TLS_RSA_WITH_AES_128_CBC_SHA
A cipher suite using RSA with AES-128 CBC and a SHA-1 hashstatic short
TLS_RSA_WITH_AES_128_GCM_SHA256
A cipher suite using RSA with AES-128 GCM and a SHA256 hashstatic short
TLS_RSA_WITH_AES_256_CBC_SHA
A cipher suite using RSA with AES-256 CBC and a SHA-1 hashstatic short
TLS_RSA_WITH_RC4_128_SHA
Deprecated.no longer supported due to existing security vulnerabilities.
-
Method Summary
Methods Modifier and Type Method and Description static SslSession
create(Calendar.DateTime time, java.lang.String fqdn, CertificateStore certStore)
Factory method for creating a SSL session using a fixed time for validity checks.static SslSession
create(Calendar calendar, byte[] setTimeInfo, short setTimeInfoIndex, java.lang.String fqdn, CertificateStore certStore)
Factory method for creating an SSL session.abstract SslSession.Crl
createCrl(byte chainIndex, int crlLength)
A factory method that creates a new CRL instance with a preallocated size.abstract short
decrypt(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex, short outputLength)
Decrypts the provided input data using the key currently stored by the instance.abstract void
destroy()
Destroys a session cleaning up its system resources.abstract void
enableClientAuthentication(ClientCertificateChain clientCertChain)
Enables the SSL client authentication for this specific SSL session instance.abstract short
encrypt(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex, short outputLength)
Encrypts the provided input data using the key currently stored by the instance.abstract short
generateAlertMessage(short alertType, byte[] output, short outputIndex, short outputLength)
Generates an SSL alert message to be sent the remote server explicitly to close the session cleanly.
This method may be needed to be called more than once, if there is more output to be sent.
Generating an alert message invalidates any instances ofSslSession.Crl
andSslSession.CertificateInfo
associated with this session
but does not destroy them, calling destroy is still required to release system resources when the instances
are no longer required. Note: this method shouldn't be called whenisServerAlert()
returns trueabstract SslSession.CertificateInfo[]
getChainInfo()
Returns an array of instances that represent the certificate chain which was received from the SSL server during the handshake phase.
The array index is zero based and is from leaf to root: 0 index is the leaf, the last certificate is the root.
The first certificate in the array is the leaf and the last is the root CA which is the trust anchor for this certificate chain.abstract short[]
getCipherSuite()
Returns the currently set cipher suite for the sessionabstract int
getFailure()
Returns the last failure of the secure sessionabstract int
getKeySizes()
Returns the currently set of supported asymmetric key sizes for the session.
Note that this method is not supported for the current generationshort
getMaxBufferLength()
Returns the maximum size in bytes allowed for the input buffer toperformHandshake()
,encrypt()
anddecrypt()
abstract short
getMinProtocolVersion()
Returns the currently set minimum protocol version supported for the session.
Note that this method is not supported for the current generation.abstract boolean
isEstablished()
Returns whether the secure session is establishedabstract boolean
isServerAlert()
Returns whether the last SSL alert was generated by the remote server.abstract short
performHandshake(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex, short outputLength)
Performs a handshake in order to establish a secure session with the other endpoint.
The caller should callisEstablished
after this call to see whether the session is established.
This function may be needed to be called more than once, depending on the underlying session type.abstract void
setCipherSuite(short[] ciphers, short index, short length)
Sets the cipher suites that will be negotiated during the handshake.
If not invoked will default to (TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_CBC_SHA
)TLS_RSA_WITH_RC4_128_SHA
is deprecated and no longer supported.abstract void
setKeySizes(int asymmetricKeySizes)
Sets the supported asymmetric key sizes for the session.
If not called will default to all key sizes.
Note that this method is not supported for the current generationabstract void
setMinProtocolVersion(short minProtocolVersion)
Sets the minimum protocol version supported by this session.
Note that this method is not supported for the current generation.-
Methods inherited from interface com.intel.crypto.StreamCipher
hasMoreOutput
-
Methods inherited from interface com.intel.crypto.SecureSession
hasMoreOutput
-
-
-
-
Field Detail
-
TLS_RSA_WITH_AES_128_CBC_SHA
public static final short TLS_RSA_WITH_AES_128_CBC_SHA
A cipher suite using RSA with AES-128 CBC and a SHA-1 hash- See Also:
- Constant Field Values
-
TLS_RSA_WITH_RC4_128_SHA
public static final short TLS_RSA_WITH_RC4_128_SHA
Deprecated. no longer supported due to existing security vulnerabilities.A cipher suite using RSA with RC4-128 and a SHA-1 hash.- See Also:
- Constant Field Values
-
TLS_RSA_WITH_AES_256_CBC_SHA
public static final short TLS_RSA_WITH_AES_256_CBC_SHA
A cipher suite using RSA with AES-256 CBC and a SHA-1 hash- See Also:
- Constant Field Values
-
TLS_RSA_WITH_AES_128_GCM_SHA256
public static final short TLS_RSA_WITH_AES_128_GCM_SHA256
A cipher suite using RSA with AES-128 GCM and a SHA256 hash- See Also:
- Constant Field Values
-
PROTOCOL_VERSION_SSL_3_0
public static final short PROTOCOL_VERSION_SSL_3_0
Deprecated. no longer supported due to existing security vulnerabilities.The SSLv3 protocol version.- See Also:
- Constant Field Values
-
PROTOCOL_VERSION_TLS_1_0
public static final short PROTOCOL_VERSION_TLS_1_0
The TLSv1 protocol version- See Also:
- Constant Field Values
-
PROTOCOL_VERSION_TLS_1_1
public static final short PROTOCOL_VERSION_TLS_1_1
The TLSv1.1 protocol version- See Also:
- Constant Field Values
-
PROTOCOL_VERSION_TLS_1_2
public static final short PROTOCOL_VERSION_TLS_1_2
The TLSv1.2 protocol version. This is the default protocol version for negotiation- See Also:
- Constant Field Values
-
ASYMMETRIC_KEY_RSA_1024
public static final int ASYMMETRIC_KEY_RSA_1024
An RSA key with 1024 bits strength- See Also:
- Constant Field Values
-
ASYMMETRIC_KEY_RSA_2048
public static final int ASYMMETRIC_KEY_RSA_2048
An RSA key with 2048 bits strength- See Also:
- Constant Field Values
-
ASYMMETRIC_KEY_RSA_4096
public static final int ASYMMETRIC_KEY_RSA_4096
An RSA key with 4096 bits strength- See Also:
- Constant Field Values
-
SSL_ALERT_NONE
public static final short SSL_ALERT_NONE
Indicates success status - no alert occurred ; corresponds to JOM_SSL_ALERT_NONE- See Also:
- Constant Field Values
-
SSL_ALERT_CLOSE_NOTIFY
public static final short SSL_ALERT_CLOSE_NOTIFY
- See Also:
- Constant Field Values
-
SSL_ALERT_UNEXPECTED_MESSAGE
public static final short SSL_ALERT_UNEXPECTED_MESSAGE
- See Also:
- Constant Field Values
-
SSL_ALERT_BAD_RECORD_MAC
public static final short SSL_ALERT_BAD_RECORD_MAC
- See Also:
- Constant Field Values
-
SSL_ALERT_DECRYPTION_FAILED
public static final short SSL_ALERT_DECRYPTION_FAILED
- See Also:
- Constant Field Values
-
SSL_ALERT_RECORD_OVERFLOW
public static final short SSL_ALERT_RECORD_OVERFLOW
- See Also:
- Constant Field Values
-
SSL_ALERT_DECOMPRESSION_FAILURE
public static final short SSL_ALERT_DECOMPRESSION_FAILURE
- See Also:
- Constant Field Values
-
SSL_ALERT_HANDSHAKE_FAILURE
public static final short SSL_ALERT_HANDSHAKE_FAILURE
- See Also:
- Constant Field Values
-
SSL_ALERT_NO_CERTIFICATE
public static final short SSL_ALERT_NO_CERTIFICATE
- See Also:
- Constant Field Values
-
SSL_ALERT_BAD_CERTIFICATE
public static final short SSL_ALERT_BAD_CERTIFICATE
- See Also:
- Constant Field Values
-
SSL_ALERT_UNSUPPORTED_CERTIFICATE
public static final short SSL_ALERT_UNSUPPORTED_CERTIFICATE
- See Also:
- Constant Field Values
-
SSL_ALERT_CERTIFICATE_REVOKED
public static final short SSL_ALERT_CERTIFICATE_REVOKED
- See Also:
- Constant Field Values
-
SSL_ALERT_CERTIFICATE_EXPIRED
public static final short SSL_ALERT_CERTIFICATE_EXPIRED
- See Also:
- Constant Field Values
-
SSL_ALERT_CERTIFICATE_UNKNOWN
public static final short SSL_ALERT_CERTIFICATE_UNKNOWN
- See Also:
- Constant Field Values
-
SSL_ALERT_ILLEGAL_PARAMETER
public static final short SSL_ALERT_ILLEGAL_PARAMETER
- See Also:
- Constant Field Values
-
SSL_ALERT_UNKNOWN_CA
public static final short SSL_ALERT_UNKNOWN_CA
- See Also:
- Constant Field Values
-
SSL_ALERT_ACCESS_DENIED
public static final short SSL_ALERT_ACCESS_DENIED
- See Also:
- Constant Field Values
-
SSL_ALERT_DECODE_ERROR
public static final short SSL_ALERT_DECODE_ERROR
- See Also:
- Constant Field Values
-
SSL_ALERT_DECRYPT_ERROR
public static final short SSL_ALERT_DECRYPT_ERROR
- See Also:
- Constant Field Values
-
SSL_ALERT_EXPORT_RESTRICTION
public static final short SSL_ALERT_EXPORT_RESTRICTION
- See Also:
- Constant Field Values
-
SSL_ALERT_PROTOCOL_VERSION
public static final short SSL_ALERT_PROTOCOL_VERSION
- See Also:
- Constant Field Values
-
SSL_ALERT_INSUFFICIENT_SECURITY
public static final short SSL_ALERT_INSUFFICIENT_SECURITY
- See Also:
- Constant Field Values
-
SSL_ALERT_INTERNAL_ERROR
public static final short SSL_ALERT_INTERNAL_ERROR
- See Also:
- Constant Field Values
-
SSL_ALERT_USER_CANCELED
public static final short SSL_ALERT_USER_CANCELED
- See Also:
- Constant Field Values
-
SSL_ALERT_NO_RENEGOTIATION
public static final short SSL_ALERT_NO_RENEGOTIATION
- See Also:
- Constant Field Values
-
SSL_ALERT_UNSUPPORTED_EXTENSION
public static final short SSL_ALERT_UNSUPPORTED_EXTENSION
- See Also:
- Constant Field Values
-
SSL_ALERT_CERTIFICATE_UNOBTAINABLE
public static final short SSL_ALERT_CERTIFICATE_UNOBTAINABLE
- See Also:
- Constant Field Values
-
SSL_ALERT_UNRECOGNIZED_NAME
public static final short SSL_ALERT_UNRECOGNIZED_NAME
- See Also:
- Constant Field Values
-
SSL_ALERT_BAD_CERTIFICATE_STATUS_RESPONSE
public static final short SSL_ALERT_BAD_CERTIFICATE_STATUS_RESPONSE
- See Also:
- Constant Field Values
-
SSL_ALERT_BAD_CERTIFICATE_HASH_VALUE
public static final short SSL_ALERT_BAD_CERTIFICATE_HASH_VALUE
- See Also:
- Constant Field Values
-
SSL_ALERT_BAD_CERTIFICATE_UNKNOWN_PSK
public static final short SSL_ALERT_BAD_CERTIFICATE_UNKNOWN_PSK
- See Also:
- Constant Field Values
-
-
Method Detail
-
createCrl
public abstract SslSession.Crl createCrl(byte chainIndex, int crlLength) throws CryptoException
A factory method that creates a new CRL instance with a preallocated size. The system resources required for a CRL are significant therefore
only a single active CRL instance can exist in all SSL session across all applets.Crl.destroy()
must be called when the CRL instance is no longer needed.- Parameters:
chainIndex
- the location of the certificate in the certificate chain for which the CRL is created. Refers to the certificate containing the CRL distribution point
retrieved bygetChainInfo()
. Can't be the index of the root CA in the chain - the last element in the array.crlLength
- the size preallocated for the CRL, can't exceed the value returned byCrl.getMaxCrlLength()
. Size must match the exact size of the CRL.- Returns:
- a new CRL instance for the specified certificate
- Throws:
IllegalUseException
- if one of the following occursgenerateAlertMessage()
was previously calleddestroy()
was previously calledisEstablished()
returns false- the session previously failed with a protocol level error by throwing an OperationFailedException
IllegalParameterException
- when one or more of the parameters is illegal or if the index of the root CA in the chain is specifiedOutOfResourcesException
- if there's already an active CRL instance in use by any SSL sessionCryptoException
- if an internal error occurred
-
getChainInfo
public abstract SslSession.CertificateInfo[] getChainInfo() throws CryptoException
Returns an array of instances that represent the certificate chain which was received from the SSL server during the handshake phase.
The array index is zero based and is from leaf to root: 0 index is the leaf, the last certificate is the root.
The first certificate in the array is the leaf and the last is the root CA which is the trust anchor for this certificate chain.- Returns:
- An array of the certificate info available in the certificate chain
- Throws:
IllegalUseException
- if one of the following occursgenerateAlertMessage()
was previously calleddestroy()
was previously calledisEstablished()
returns false
CryptoException
- if an internal error occurred
-
create
public static SslSession create(Calendar calendar, byte[] setTimeInfo, short setTimeInfoIndex, java.lang.String fqdn, CertificateStore certStore) throws CryptoException
Factory method for creating an SSL session.- Parameters:
calendar
- ACalendar
instance representing the time for this sessionsetTimeInfo
- the time info returned from theCalendar.setTime()
methodsetTimeInfoIndex
- the offset in the specified setTimeInfo arrayfqdn
- the server FQDN to match during the SSL handshake phasecertStore
- ACertificateStore
instance to associate with this session- Returns:
- A new
SslSession
instance - Throws:
OutOfResourcesException
- in case the maximum allowed number of sessions was exceededNotInitializedException
- if the calendar instance was not initialized correctlyIllegalParameterException
- if one or more of the parameters is illegalNotSupportedException
- in case SSL is not supported on the current platformCryptoException
- if an internal error occurred
-
create
public static SslSession create(Calendar.DateTime time, java.lang.String fqdn, CertificateStore certStore) throws CryptoException
Factory method for creating a SSL session using a fixed time for validity checks.
Note: This method will be only supported on coinless platforms.
In order to query if the platform contains a coin battery usePlatformInfo.isCoinBatteryPresent()
- Parameters:
time
- ACalendar.DateTime
instance representing the time for this sessionfqdn
- the server FQDN to match during the SSL handshake phasecertStore
- ACertificateStore
instance to associate with this session- Returns:
- A new
SslSession
instance - Throws:
OutOfResourcesException
- in case the maximum allowed number of sessions was exceededIllegalParameterException
- if one or more of the parameters is illegalNotSupportedException
- in case the platform contains a coin battery.
in order to indicate if the platform contains a coin cell seePlatformInfo.isCoinBatteryPresent()
.CryptoException
- if an internal error occurred
-
enableClientAuthentication
public abstract void enableClientAuthentication(ClientCertificateChain clientCertChain) throws CryptoException
Enables the SSL client authentication for this specific SSL session instance. The provided certificate chain is used to authenticate the client to the server, if the server request client authentication during the SSL handshake phase.- Parameters:
clientCertChain
- an instance of ClientCertificateChain to be associated with the SSL session- Throws:
IllegalParameterException
- in case the argument is invalidNotInitializedException
- if the certificate chain class wasn't initialized correctly- If the instance doesn't contain client certificates
- If the client private key wasn't set
IllegalUseException
- will be thrown in the following cases:- If the instance was destroyed using the
destroy()
method - If a handshake with the server was started/established
- If the instance was destroyed using the
CryptoException
-
setCipherSuite
public abstract void setCipherSuite(short[] ciphers, short index, short length) throws CryptoException
Sets the cipher suites that will be negotiated during the handshake.
If not invoked will default to (TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_CBC_SHA
)TLS_RSA_WITH_RC4_128_SHA
is deprecated and no longer supported.- Parameters:
ciphers
- a list of cipher suites supported by this session (one of of TLS_RSA_* constants)index
- the offset in the ciphers arraylength
- the length of the ciphers array- Throws:
IllegalUseException
- if one of the following occursperformHandshake()
was previously calleddestroy()
was previously calledgenerateAlertMessage()
was previously called
IllegalParameterException
- if or more of the parameters is illegalCryptoException
- if an internal error occurred
-
getCipherSuite
public abstract short[] getCipherSuite() throws CryptoException
Returns the currently set cipher suite for the session- Returns:
- Returns the currently set cipher suite for the session
- Throws:
IllegalUseException
- if one of the following occursdestroy()
was previously calledgenerateAlertMessage()
was previously called
CryptoException
-
setMinProtocolVersion
public abstract void setMinProtocolVersion(short minProtocolVersion) throws CryptoException
Sets the minimum protocol version supported by this session.
Note that this method is not supported for the current generation.- Parameters:
minProtocolVersion
- the minimum protocol version supported in this session (one of PROTOCOL_VERSION_* constants)- Throws:
NotSupportedException
- alwaysCryptoException
-
getMinProtocolVersion
public abstract short getMinProtocolVersion() throws CryptoException
Returns the currently set minimum protocol version supported for the session.
Note that this method is not supported for the current generation.- Returns:
- Returns the currently set minimum protocol version for the session
- Throws:
NotSupportedException
- alwaysCryptoException
-
setKeySizes
public abstract void setKeySizes(int asymmetricKeySizes) throws CryptoException
Sets the supported asymmetric key sizes for the session.
If not called will default to all key sizes.
Note that this method is not supported for the current generation- Parameters:
asymmetricKeySizes
- a bitmask of the key sizes supported (one or more of ASYMMETRIC_KEY_* constants)- Throws:
IllegalUseException
- if one of the following occursperformHandshake()
was previously calleddestroy()
was previously calledgenerateAlertMessage()
was previously called
NotSupportedException
- alwaysCryptoException
-
getKeySizes
public abstract int getKeySizes()
Returns the currently set of supported asymmetric key sizes for the session.
Note that this method is not supported for the current generation- Returns:
- Returns the currently set asymmetric of supported key sizes for the session
- Throws:
NotSupportedException
- always
-
getFailure
public abstract int getFailure() throws CryptoException
Returns the last failure of the secure session- Specified by:
getFailure
in interfaceSecureSession
- Returns:
- the SSL alert protocol error code of the last failure (one of the SSL_ALERT_* constants) or SSL_ALERT_NONE if no failure occurred
- Throws:
IllegalUseException
- if one of the following occursdestroy()
was previously calledgenerateAlertMessage()
was previously called
CryptoException
- if an internal error occurred
-
isServerAlert
public abstract boolean isServerAlert() throws CryptoException
Returns whether the last SSL alert was generated by the remote server.- Returns:
- True if the last SSL error was generated by the remote server. False otherwise.
- Throws:
IllegalUseException
- if one of the following occursdestroy()
was previously calledOperationFailedException
wasn't thrown from one of the following methods:
CryptoException
- if an internal error occurred
-
generateAlertMessage
public abstract short generateAlertMessage(short alertType, byte[] output, short outputIndex, short outputLength) throws CryptoException
Generates an SSL alert message to be sent the remote server explicitly to close the session cleanly.
This method may be needed to be called more than once, if there is more output to be sent.
Generating an alert message invalidates any instances ofSslSession.Crl
andSslSession.CertificateInfo
associated with this session
but does not destroy them, calling destroy is still required to release system resources when the instances
are no longer required. Note: this method shouldn't be called whenisServerAlert()
returns true- Parameters:
alertType
- the alert type to generate. One of SSL_ALERT_* constants, which is received fromgetFailure()
output
- an array to hold the output dataoutputIndex
- index in the output arrayoutputLength
- output data length- Returns:
- The number of bytes returned in output array
- Throws:
IllegalParameterException
- if alertType 255.IllegalUseException
- if one of the following occursdestroy()
was previously calledperformHandshake()
was never called- invoking before extracting all of the output buffer generated by a previous call to
encrypt()
orperformHandshake()
(i.e. whilehasMoreOutput()
returns true due toencrypt()
orperformHandshake()
) generateAlertMessage(short, byte[], short, short)
was already called for this session with a different alertType- a complete alert message was previously generated
CryptoException
- if an internal error occurred
-
performHandshake
public abstract short performHandshake(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex, short outputLength) throws CryptoException
Performs a handshake in order to establish a secure session with the other endpoint.
The caller should callisEstablished
after this call to see whether the session is established.
This function may be needed to be called more than once, depending on the underlying session type.
Input data should be valid SSL payload received from the SSL server (or null for the first call).
Output data should be transmitted as SSL payload to the SSL server.
A secured session must be established beforeencrypt()
ordecrypt()
can be invoked.- Specified by:
performHandshake
in interfaceSecureSession
- Parameters:
input
- an array that holds the input data containing the session establishment data. Can't be null if inputLength > 0 and inputLength can't exceedgetMaxBufferLength()
bytesinputIndex
- index in the input arrayinputLength
- input data length - must be zero ifhasMoreOutput()
returns trueoutput
- an array to hold the output dataoutputIndex
- index in the output arrayoutputLength
- output data length- Returns:
- The number of bytes returned in the output array
- Throws:
NotInitializedException
- if the certificate store provided tocreate()
for this session does not contain any certificatesIllegalUseException
- if one of the following occursgenerateAlertMessage()
was previously calleddestroy()
was previously calledisEstablished()
returns true- providing input when
hasMoreOutput()
returns true - the session previously failed with a protocol level error by throwing an OperationFailedException
IllegalParameterException
- one or more of the input parameters is illegalOperationFailedException
- if the handshake failed due to protocol level errorCryptoException
- if an internal error occurred
-
isEstablished
public abstract boolean isEstablished() throws CryptoException
Returns whether the secure session is established- Specified by:
isEstablished
in interfaceSecureSession
- Returns:
- Whether the secure session is established
- Throws:
IllegalUseException
- if one of the following occursdestroy()
was previously calledgenerateAlertMessage()
was previously called
CryptoException
-
encrypt
public abstract short encrypt(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex, short outputLength) throws CryptoException
Encrypts the provided input data using the key currently stored by the instance.
Input data is the plain text data to encrypt using the SSL session.
Output data is a SSL payload containing the encrypted plain text that should be transmitted to the SSL server.- Specified by:
encrypt
in interfaceStreamCipher
- Parameters:
input
- the input data to encrypt. Can't be null if inputLength > 0 and inputLength can't exceedgetMaxBufferLength()
bytesinputIndex
- index in the input arrayinputLength
- input data length - must be zero ifhasMoreOutput()
returns trueoutput
- an array to hold the output dataoutputIndex
- index in the output arrayoutputLength
- output data length- Returns:
- The number of bytes returned in output array
- Throws:
IllegalUseException
- if one of the following occursgenerateAlertMessage()
was previously calleddestroy()
was previously calledisEstablished()
returns false- providing input when
hasMoreOutput()
returns true - the session previously failed with a protocol level error by throwing an OperationFailedException
IllegalParameterException
- when one or more of the parameters is illegalNotInitializedException
- if a required encryption parameter is not configured (for example, the key to be used for encryption)CryptoException
- if an internal error occurred
-
decrypt
public abstract short decrypt(byte[] input, short inputIndex, short inputLength, byte[] output, short outputIndex, short outputLength) throws CryptoException
Decrypts the provided input data using the key currently stored by the instance.
Input data is the SSL payload containing encrypted data received from the SSL server.
Output data is the plain text data in the SSL payload.- Specified by:
decrypt
in interfaceStreamCipher
- Parameters:
input
- the input data to decrypt. Can't be null if inputLength > 0 and inputLength can't exceedgetMaxBufferLength()
bytesinputIndex
- index in the input arrayinputLength
- input data length - must be zero ifhasMoreOutput()
returns trueoutput
- an array to hold the output dataoutputIndex
- index in the output arrayoutputLength
- output data length- Returns:
- The number of bytes returned in output array. when decrypting a closeNotify alert the method returns -1 and no data is written to the output array.
- Throws:
OperationFailedException
- if the decryption failed due to protocol level error (the SSL server sent alert)IllegalUseException
- if one of the following occursgenerateAlertMessage()
was previously calleddestroy()
was previously calledisEstablished()
returns false- providing input when
hasMoreOutput()
returns true - the session previously failed with a protocol level error by throwing an OperationFailedException
IllegalParameterException
- when one or more of the parameters are illegalNotInitializedException
- if a required encryption parameter is not configured (for example, the key to be used for encryption)CryptoException
- if an internal error occurred
-
getMaxBufferLength
public short getMaxBufferLength()
Returns the maximum size in bytes allowed for the input buffer toperformHandshake()
,encrypt()
anddecrypt()
- Specified by:
getMaxBufferLength
in interfaceSecureSession
- Specified by:
getMaxBufferLength
in interfaceStreamCipher
- Returns:
- The maximum size in bytes allowed for the input buffer
-
destroy
public abstract void destroy() throws CryptoException
Destroys a session cleaning up its system resources. Must be called when the session is no longer required.
If there is an active instance ofSslSession.Crl
which was created by this session it is destroyed.
Any instance ofSslSession.CertificateInfo
associated with this session is invalidated.- Specified by:
destroy
in interfaceSecureSession
- Throws:
IllegalUseException
- ifdestroy()
was previously calledCryptoException
- if an internal error occurred
-
-