Intel

Developer Zone

SslSession

com.intel.crypto

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 and SecureSession interfaces and allows to establish a secure SSL session with a remote SSL server, and passing encrypted data within this session.

    Establishing a session:

    1. Call CertificateStore.create() to create a new certificate store. This store can be reused by multiple sessions.
    2. Add trusted root CA certificates to the store using addCertificate().
    3. Create a Calendar instance and initialize the time to establish the session's notion of time.
    4. Call SslSession.create() with the session parameters (time, FQDN and certificate store) to create a new session instance.
    5. Call performHandshake() sequentially transferring the handshake messages between the session and the remote SSL server.
    6. Call isEstablished() to check if the handshake completed successfully.
    Once the session is established the caller can continue to use encrypt() and decrypt() inside the SSL session.

    Verifying CRLs (after handshake):

    1. Call getChainInfo() to retrieve an array of SslSession.CertificateInfo instances that represent the certificate chain which was received from the SSL server during the handshake phase, ordered from leaf to root.
    2. Start from the first intermediate certificate (one before the last in the array) and finish with the leaf.
    3. For each certificate in the chain:
    4. Retrieve the CRL distribution points from the certificate using CertificateInfo.getInfo() and pass it to the host software.
    5. After the host software obtains the CRLs, for each CRL distribution point:
      1. Call createCrl() using the same index of the certificate with the CRL distribution point.
      2. Add the CRL chunk by chunk using Crl.appendChunk().
      3. Call Crl.verify() to make sure the CRL is in the correct format and signed.
      4. Call Crl.getTimeRange() and verify the CRL in hand is up to date.
      5. Obtain the certificate serial number using CertificateInfo.getInfo().
      6. Search for the serial number using Crl.findSerialNumber() to make sure the certificate is not revoked.
      7. Call Crl.destroy() to release system resources.

    Closing session:

    1. Call generateAlertMessage() with alertType SSL_ALERT_CLOSE_NOTIFY and send the output buffers to the remote SSL server.
    2. Call destroy() to release system resources.
    After closing or destroying the session the instance can't be reused and a new session must be created.

    Stop using SSL services:
    If SSL services are no longer needed, the user should invoke CertificateStore.destroy() for each certificate store instance created and destroy() for each SslSession instance created to release the system resources.

    SSL alerts:
    Any of the session methods throwing OperationFailedException 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:

    Handling OperationFailedException should be as follows:
    1. 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
      1. Call getFailure() to check the alertType the server sent
  • if DAL FW decided that alert should be generated
    1. Call getFailure() to determine the alertType that should be generated
    2. Call generateAlertMessage() with the alertType received from getFailure() and send the output buffers to the remote SSL server.
  • Call destroy() to release system resources.
    • 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
        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
      • PROTOCOL_VERSION_SSL_3_0

        public static final short PROTOCOL_VERSION_SSL_3_0
        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
      • 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_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_ACCESS_DENIED

        public static final short SSL_ALERT_ACCESS_DENIED
        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 by getChainInfo(). 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 by Crl.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 occurs
        IllegalParameterException - when one or more of the parameters is illegal or if the index of the root CA in the chain is specified
        OutOfResourcesException - if there's already an active CRL instance in use by any SSL session
        CryptoException - 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 occurs
        CryptoException - if an internal error occurred
      • 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 - always
        CryptoException
      • 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 - always
        CryptoException
      • 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 occurs
        NotSupportedException - always
        CryptoException
      • 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
      • 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's more output to be sent.
        Generating an alert message invalidates any instances of SslSession.Crl and SslSession.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 when isServerAlert() returns true
        Parameters:
        alertType - the alert type to generate. One of SSL_ALERT_* constants, which is received from getFailure()
        output - an array to hold the output data
        outputIndex - index in the output array
        outputLength - output data length
        Returns:
        The number of bytes returned in output array
        Throws:
        IllegalParameterException - if alertType 255.
        IllegalUseException - if one of the following occurs
        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 call isEstablished 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 before encrypt() or decrypt() can be invoked.
        Specified by:
        performHandshake in interface SecureSession
        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 exceed getMaxBufferLength() bytes
        inputIndex - index in the input array
        inputLength - input data length - must be zero if hasMoreOutput() returns true
        output - an array to hold the output data
        outputIndex - index in the output array
        outputLength - output data length
        Returns:
        The number of bytes returned in the output array
        Throws:
        NotInitializedException - if the certificate store provided to create() for this session does not contain any certificates
        IllegalUseException - if one of the following occurs
        IllegalParameterException - one or more of the input parameters is illegal
        OperationFailedException - if the handshake failed due to protocol level error
        CryptoException - if an internal error occurred
      • 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 interface StreamCipher
        Parameters:
        input - the input data to encrypt. Can't be null if inputLength > 0 and inputLength can't exceed getMaxBufferLength() bytes
        inputIndex - index in the input array
        inputLength - input data length - must be zero if hasMoreOutput() returns true
        output - an array to hold the output data
        outputIndex - index in the output array
        outputLength - output data length
        Returns:
        The number of bytes returned in output array
        Throws:
        IllegalUseException - if one of the following occurs
        IllegalParameterException - when one or more of the parameters is illegal
        NotInitializedException - 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 interface StreamCipher
        Parameters:
        input - the input data to decrypt. Can't be null if inputLength > 0 and inputLength can't exceed getMaxBufferLength() bytes
        inputIndex - index in the input array
        inputLength - input data length - must be zero if hasMoreOutput() returns true
        output - an array to hold the output data
        outputIndex - index in the output array
        outputLength - 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 occurs
        IllegalParameterException - when one or more of the parameters are illegal
        NotInitializedException - if a required encryption parameter is not configured (for example, the key to be used for encryption)
        CryptoException - if an internal error occurred