Since: API level 20
public class

SecureChannelManager

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.ucm.core.SecureChannelManager

Class Overview

This class provides ability to use secure channel.

Since
API level 20
KNOX 2.7

Summary

Constants
String BUNDLE_EXTRA_SCP_ENCRYPTION This constant defines Bundle Extra for key usage, encryption is enabled.
String BUNDLE_EXTRA_SCP_KEY_ID This constant defines Bundle Extra for key id.
String BUNDLE_EXTRA_SCP_KEY_LENGTH This constant defines Bundle Extra for key length of AES/MAC key for message encryption and C-MAC generation.
String BUNDLE_EXTRA_SCP_KEY_PARAM_DH_G This constant defines Bundle Extra for Byte array of Diffie-Hellman generator for key agreement.
String BUNDLE_EXTRA_SCP_KEY_PARAM_DH_P This constant defines Bundle Extra for prime number needed for key agreement (Diffie-Hellman).
String BUNDLE_EXTRA_SCP_KEY_PARAM_ECC This constant defines Bundle Extra for ECC curve id for key agreement
Note: SCP11A/B only.
String BUNDLE_EXTRA_SCP_KEY_VERSION This constant defines Bundle Extra for key version.
String BUNDLE_EXTRA_SCP_MAC This constant defines Bundle Extra for key usage, MAC for message authentication.
String BUNDLE_EXTRA_SCP_PROTOCOL This constant defines Bundle Extra for secure channel protocol id.
int BUNDLE_SCP_KEY_PARAM_ECC_FRP_P256 This constant defines value for ECC curve spec FRP-P256.
int BUNDLE_SCP_KEY_PARAM_ECC_NIST_P256 This constant defines value for ECC curve spec NIST-P256.
int ERROR_APDU_PARSING This error constant is returned due to APDU parsing error.
int ERROR_CA_CERT_NOT_FOUND This error constant is returned due to no CA cert found.
int ERROR_CHANNEL_NOT_FOUND This error constant is returned when Secure Channel is not found.
int ERROR_DEVICE_COMPROMISED This error constant is returned due to Device compromised.
int ERROR_INTERNAL This error constant is returned due to internal processing error.
int ERROR_INTERNAL_CRYPTO_FAILED This error constant is returned due to Crypto operation failed.
int ERROR_INVALID_MESSAGE_TYPE This error constant is returned due to invalid message type.
int ERROR_INVALID_PERMISSION This error constant is returned due to invalid permission.
int ERROR_INVALID_PROTOCOL This error constant is returned due to invalid protocol.
int ERROR_INVALID_SD_CERT This error constant is returned due to invalid SD cert.
int ERROR_INVALID_SD_MAC This error constant is returned due to invalid SD MAC.
int ERROR_INVALID_SD_RECEIPT This error constant is returned due to invalid SD receipt.
int ERROR_NOT_SUPPORTED_CURVE This error constant is returned due to no supported curve.
int ERROR_NO_INTERNAL_MEMORY This error constant is returned due to No internal memory.
int ERROR_SD_CERT_NOT_FOUND This error constant is returned due to no SD cert found.
int ERROR_TLV_PARSING This error constant is returned due to TLC parsing error.
int ERROR_TZ_APP_CONNECTION_FAILED This error constant is returned due to TZ APP connection failed.
int MESSAGE_TYPE_COMMAND processMessage(int, byte[]) API message type - "Command" for SCP communication.
int MESSAGE_TYPE_FORWARD_TO_SD ApduMessage message type - "Forward to SD" for SCP communication.
int MESSAGE_TYPE_PROCESSING_COMPLETED ApduMessage message type - "Completed" for SCP communication.
int MESSAGE_TYPE_RESPONSE processMessage(int, byte[]) API message type - "Response" for SCP communication.
int MESSAGE_TYPE_SECURE_CHANNEL processMessage(int, byte[]) API message type - "Channel" for SCP communication.
int PROTOCOL_TYPE_SCP11A createSecureChannel(int, Bundle) API protocol type - "SCP11A" for SCP communication.
int PROTOCOL_TYPE_SCP11B createSecureChannel(int, Bundle) API protocol type - "SCP11B" for SCP communication.
int PROTOCOL_TYPE_SCP_CUSTOM createSecureChannel(int, Bundle) API protocol type - "SCP custom" for SCP communication.
int PROTOCOL_TYPE_SCP_OTHER createSecureChannel(int, Bundle) API protocol type - "SCP other" for SCP communication.
int STATUS_FAILURE ApduMessage Status - Failure
int STATUS_SC_CONSTRUCTED ApduMessage Status - Secure Channel constructed.
int STATUS_SC_REQUIRED ApduMessage Status - Secure Channel required.
int STATUS_SUCCESS ApduMessage Status - Success
Public Methods
ApduMessage createSecureChannel(int protocolType, Bundle bundle)
API to Create secure channel via SCP11.
int destroySecureChannel()
API to destroy secure channel.
static SecureChannelManager getInstance()
Retrieve SecureChannelManager Instance which can interact with KNOX Credential Storage.
ApduMessage processMessage(int type, byte[] msg)
API to Process message via SCP11.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String BUNDLE_EXTRA_SCP_ENCRYPTION

Since: API level 20

This constant defines Bundle Extra for key usage, encryption is enabled.
Note: Encryption is by default enabled, not allowed to be disabled.

Since
API level 20
KNOX 2.7
Constant Value: "scp_encryption"

public static final String BUNDLE_EXTRA_SCP_KEY_ID

Since: API level 20

This constant defines Bundle Extra for key id.

Since
API level 20
KNOX 2.7
Constant Value: "scp_key_id"

public static final String BUNDLE_EXTRA_SCP_KEY_LENGTH

Since: API level 20

This constant defines Bundle Extra for key length of AES/MAC key for message encryption and C-MAC generation.
Note: Key length is fixed as 256bit, not allowed to be changed.

Since
API level 20
KNOX 2.7
Constant Value: "scp_key_length"

public static final String BUNDLE_EXTRA_SCP_KEY_PARAM_DH_G

Since: API level 20

This constant defines Bundle Extra for Byte array of Diffie-Hellman generator for key agreement.
Note: SCP11B_CUSTOM only. SCP11A and B uses ECC, will ignore DH-P/G.

Since
API level 20
KNOX 2.7
Constant Value: "scp_key_agreement_param_dh_g"

public static final String BUNDLE_EXTRA_SCP_KEY_PARAM_DH_P

Since: API level 20

This constant defines Bundle Extra for prime number needed for key agreement (Diffie-Hellman).
Note: SCP11B_CUSTOM only. SCP11A and B uses ECC, will ignore DH-P/G.

Since
API level 20
KNOX 2.7
Constant Value: "scp_key_agreement_param_dh_p"

public static final String BUNDLE_EXTRA_SCP_KEY_PARAM_ECC

Since: API level 20

This constant defines Bundle Extra for ECC curve id for key agreement
Note: SCP11A/B only.

Since
API level 20
KNOX 2.7
Constant Value: "scp_key_agreement_param_ecc"

public static final String BUNDLE_EXTRA_SCP_KEY_VERSION

Since: API level 20

This constant defines Bundle Extra for key version.

Since
API level 20
KNOX 2.7
Constant Value: "scp_key_version"

public static final String BUNDLE_EXTRA_SCP_MAC

Since: API level 20

This constant defines Bundle Extra for key usage, MAC for message authentication.
Note: MAC is by default enabled, not allowed to be disabled.

Since
API level 20
KNOX 2.7
Constant Value: "scp_mac"

public static final String BUNDLE_EXTRA_SCP_PROTOCOL

Since: API level 20

This constant defines Bundle Extra for secure channel protocol id.

Since
API level 20
KNOX 2.7
Constant Value: "scp_protocol"

public static final int BUNDLE_SCP_KEY_PARAM_ECC_FRP_P256

Since: API level 20

This constant defines value for ECC curve spec FRP-P256.

Since
API level 20
KNOX 2.7
Constant Value: 64 (0x00000040)

public static final int BUNDLE_SCP_KEY_PARAM_ECC_NIST_P256

Since: API level 20

This constant defines value for ECC curve spec NIST-P256.

Since
API level 20
KNOX 2.7
Constant Value: 0 (0x00000000)

public static final int ERROR_APDU_PARSING

Since: API level 20

This error constant is returned due to APDU parsing error.

Since
API level 20
KNOX 2.7
Constant Value: 52 (0x00000034)

public static final int ERROR_CA_CERT_NOT_FOUND

Since: API level 20

This error constant is returned due to no CA cert found.

Since
API level 20
KNOX 2.7
Constant Value: 55 (0x00000037)

public static final int ERROR_CHANNEL_NOT_FOUND

Since: API level 20

This error constant is returned when Secure Channel is not found.

Since
API level 20
KNOX 2.7
Constant Value: 53 (0x00000035)

public static final int ERROR_DEVICE_COMPROMISED

Since: API level 20

This error constant is returned due to Device compromised.

Since
API level 20
KNOX 2.7
Constant Value: 62 (0x0000003e)

public static final int ERROR_INTERNAL

Since: API level 20

This error constant is returned due to internal processing error.

Since
API level 20
KNOX 2.7
Constant Value: 50 (0x00000032)

public static final int ERROR_INTERNAL_CRYPTO_FAILED

Since: API level 20

This error constant is returned due to Crypto operation failed.

Since
API level 20
KNOX 2.7
Constant Value: 57 (0x00000039)

public static final int ERROR_INVALID_MESSAGE_TYPE

Since: API level 20

This error constant is returned due to invalid message type.

Since
API level 20
KNOX 2.7
Constant Value: 64 (0x00000040)

public static final int ERROR_INVALID_PERMISSION

Since: API level 20

This error constant is returned due to invalid permission.

Since
API level 20
KNOX 2.7
Constant Value: 65 (0x00000041)

public static final int ERROR_INVALID_PROTOCOL

Since: API level 20

This error constant is returned due to invalid protocol.

Since
API level 20
KNOX 2.7
Constant Value: 63 (0x0000003f)

public static final int ERROR_INVALID_SD_CERT

Since: API level 20

This error constant is returned due to invalid SD cert.

Since
API level 20
KNOX 2.7
Constant Value: 59 (0x0000003b)

public static final int ERROR_INVALID_SD_MAC

Since: API level 20

This error constant is returned due to invalid SD MAC.

Since
API level 20
KNOX 2.7
Constant Value: 61 (0x0000003d)

public static final int ERROR_INVALID_SD_RECEIPT

Since: API level 20

This error constant is returned due to invalid SD receipt.

Since
API level 20
KNOX 2.7
Constant Value: 60 (0x0000003c)

public static final int ERROR_NOT_SUPPORTED_CURVE

Since: API level 20

This error constant is returned due to no supported curve.

Since
API level 20
KNOX 2.7
Constant Value: 58 (0x0000003a)

public static final int ERROR_NO_INTERNAL_MEMORY

Since: API level 20

This error constant is returned due to No internal memory.

Since
API level 20
KNOX 2.7
Constant Value: 54 (0x00000036)

public static final int ERROR_SD_CERT_NOT_FOUND

Since: API level 20

This error constant is returned due to no SD cert found.

Since
API level 20
KNOX 2.7
Constant Value: 56 (0x00000038)

public static final int ERROR_TLV_PARSING

Since: API level 20

This error constant is returned due to TLC parsing error.

Since
API level 20
KNOX 2.7
Constant Value: 51 (0x00000033)

public static final int ERROR_TZ_APP_CONNECTION_FAILED

Since: API level 20

This error constant is returned due to TZ APP connection failed.

Since
API level 20
KNOX 2.7
Constant Value: 66 (0x00000042)

public static final int MESSAGE_TYPE_COMMAND

Since: API level 20

processMessage(int, byte[]) API message type - "Command" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 200 (0x000000c8)

public static final int MESSAGE_TYPE_FORWARD_TO_SD

Since: API level 20

ApduMessage message type - "Forward to SD" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 400 (0x00000190)

public static final int MESSAGE_TYPE_PROCESSING_COMPLETED

Since: API level 20

ApduMessage message type - "Completed" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 401 (0x00000191)

public static final int MESSAGE_TYPE_RESPONSE

Since: API level 20

processMessage(int, byte[]) API message type - "Response" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 201 (0x000000c9)

public static final int MESSAGE_TYPE_SECURE_CHANNEL

Since: API level 20

processMessage(int, byte[]) API message type - "Channel" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 202 (0x000000ca)

public static final int PROTOCOL_TYPE_SCP11A

Since: API level 20

createSecureChannel(int, Bundle) API protocol type - "SCP11A" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 100 (0x00000064)

public static final int PROTOCOL_TYPE_SCP11B

Since: API level 20

createSecureChannel(int, Bundle) API protocol type - "SCP11B" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 101 (0x00000065)

public static final int PROTOCOL_TYPE_SCP_CUSTOM

Since: API level 20

createSecureChannel(int, Bundle) API protocol type - "SCP custom" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 102 (0x00000066)

public static final int PROTOCOL_TYPE_SCP_OTHER

Since: API level 20

createSecureChannel(int, Bundle) API protocol type - "SCP other" for SCP communication.

Since
API level 20
KNOX 2.7
Constant Value: 103 (0x00000067)

public static final int STATUS_FAILURE

Since: API level 20

ApduMessage Status - Failure

Since
API level 20
KNOX 2.7
Constant Value: 1 (0x00000001)

public static final int STATUS_SC_CONSTRUCTED

Since: API level 20

ApduMessage Status - Secure Channel constructed.

Since
API level 20
KNOX 2.7
Constant Value: 300 (0x0000012c)

public static final int STATUS_SC_REQUIRED

Since: API level 20

ApduMessage Status - Secure Channel required.

Since
API level 20
KNOX 2.7
Constant Value: 301 (0x0000012d)

public static final int STATUS_SUCCESS

Since: API level 20

ApduMessage Status - Success

Since
API level 20
KNOX 2.7
Constant Value: 0 (0x00000000)

Public Methods

public ApduMessage createSecureChannel (int protocolType, Bundle bundle)

Since: API level 20

API to Create secure channel via SCP11.

Returns
  • ApduMessage
Usage

An application can use this API to Create secure channel via SCP11.

 try {
   Bundle bundle = new Bundle();
   bundle.putInt(SecureChannelManager.BUNDLE_EXTRA_SCP_PROTOCOL, SecureChannelManager.PROTOCOL_TYPE_SCP11B);
   bundle.putInt(SecureChannelManager.BUNDLE_EXTRA_SCP_KEY_ID, 0);
   bundle.putInt(SecureChannelManager.BUNDLE_EXTRA_SCP_KEY_ID, 1);
   bundle.putInt(SecureChannelManager.BUNDLE_EXTRA_SCP_KEY_LENGTH, keyLength); // must be 0x20 : AES256
   bundle.putBoolean(SecureChannelManager.BUNDLE_EXTRA_SCP_ENCRYPTION, encEnabled); // must be true : enabled
   bundle.putBoolean(SecureChannelManager.BUNDLE_EXTRA_SCP_MAC, macEnabled); // must be true : enabled
   bundle.putInt(SecureChannelManager.BUNDLE_EXTRA_SCP_KEY_PARAM_ECC, SecureChannelManager.BUNDLE_SCP_KEY_PARAM_ECC_NIST_P256); // ECC curve : NIST-P256
 
   SecureChannelManager credentialUtil = SecureChannelManager.getInstance();
   ApduMessage resp = credentialUtil.createSecureChannel(protocol, bundle);
   if(resp.status == SecureChannelManager.STATUS_FAILURE) {
     Log.e(TAG, "Channel construction failed");
     return;
   }

   while (resp.messageType == SecureChannelManager.MESSAGE_TYPE_FORWARD_TO_SD) {
     Log.e(TAG, "FORWARDING : " + Hex.toHexString(resp.message));
     // forward APDU to your SD
     byte[] sdResp = transmitData(resp.message);
     if(sdResp == null || sdResp.length < 2) {
       Log.e(TAG, "sdResp == null");
       return;
     }

     resp = credentialUtil.processMessage(SecureChannelManager.MESSAGE_TYPE_SECURE_CHANNEL, sdResp);
     switch(resp.status) {
       case SecureChannelManager.STATUS_SUCCESS:
         if(resp.messageType == SecureChannelManager.MESSAGE_TYPE_FORWARD_TO_SD)
           continue;
       case SecureChannelManager.STATUS_SC_CONSTRUCTED:
         Log.e(TAG, "Channel constructed!");
         break;
       default:
         mSecureChannelExists = false;
         Log.e(TAG, "Channel construction failed");
         break;
       }
    }
 } catch (SecurityException e) {
   Log.w(TAG, "SecurityException: " + e);
 }
 

Since
API level 20
KNOX 2.7

public int destroySecureChannel ()

Since: API level 20

API to destroy secure channel.

Returns
Usage

An application can use this API to destroy secure channel.

 SecureChannelManager credManager = SecureChannelManager.getInstance();
 
 try {
   int result = credManager.destroySecureChannel();
 } catch (SecurityException e) {
   Log.w(TAG, "SecurityException: " + e);
 }
 

Since
API level 20
KNOX 2.7

public static SecureChannelManager getInstance ()

Since: API level 20

Retrieve SecureChannelManager Instance which can interact with KNOX Credential Storage.

Returns
  • SecureChannelManager instance.
Since
API level 20
KNOX 2.7

public ApduMessage processMessage (int type, byte[] msg)

Since: API level 20

API to Process message via SCP11.

Parameters
type message type, MESSAGE_TYPE_COMMAND, MESSAGE_TYPE_RESPONSE, MESSAGE_TYPE_SECURE_CHANNEL
msg input data
Returns
  • ApduMessage
Usage

An application can use this API to Process message via SCP11.

 try {
   SecureChannelManager credentialUtil = SecureChannelManager.getInstance();

   // Encrypt response
   resp = credentialUtil.processMessage(SecureChannelManager.MESSAGE_TYPE_COMMAND, data);
   if (resp.status != SecureChannelManager.STATUS_SUCCESS) {
     Log.e(TAG, "Command encryption failed");
   } else {
     Log.e(TAG, "encrypted length : " + resp.message.length);
   }

   // forward APDU to your SD
   byte[] sdResp = transmitData(resp.message);

   // Decrypt response
   resp = credentialUtil.processMessage(SecureChannelManager.MESSAGE_TYPE_RESPONSE, data);
   if (resp == null || resp.status != SecureChannelManager.STATUS_SUCCESS) {
     Log.e(TAG, "Response decryption failed");
     break;
   } else {
     Log.d(TAG,"decrypt success." + new String(resp.message));
   }
 } catch (SecurityException e) {
   Log.w(TAG, "SecurityException: " + e);
 }
 

Since
API level 20
KNOX 2.7