public interface KeyService extends ResourceService
Provides key management services.
generate(..)
, computePublicKey(..)
and generateKeyPair(..)
methods generate cryptographic keys.derive(..)
method performs Key Derivation Functions (KDF).computeSharedSecret(..)
method provides key agreement between an off-card entity and the CSP.manage(..)
method in mode IMPORT
imports a public key.manage(..)
method in mode EXPORT
exports a public key.getType(..)
and getSize(..)
.
Key derivation functions (KDF) must be pre-configured by the CSP Admin and cannot be selected via the CSP-API.
Supported algorithms are defined in Section 6.7.1 of GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Source | Algorithm | Result | Additional Input Data |
---|---|---|---|
KEY_MASTER_SECRET KEY_DERIVED_SECRET KEY_SHARED_SECRET |
KDF_AES_CMAC |
KEY_AES |
Optional application-specific context information. |
KEY_MASTER_SECRET KEY_DERIVED_SECRET KEY_SHARED_SECRET |
KDF_ECC |
KEY_ECC_PRIVATE |
Not supported. |
KEY_MASTER_SECRET KEY_DERIVED_SECRET KEY_SHARED_SECRET |
KDF_HKDF |
KEY_AES KEY_HMAC KEY_DERIVED_SECRET |
Optional salt and application-specific context information. |
PWD_STRONG |
KDF_PBKDF2 |
KEY_DERIVED_SECRET |
Salt strongly recommended: minimum 64 bits, preferably 128 bits or more. |
Key agreement schemes (KAS) must be pre-configured by the CSP Admin and cannot be selected via the CSP-API.
Supported algorithms are defined in Section 6.7.2 of GlobalPlatform Amendment N [GPC_SPE_230] and may include:
Algorithm | Private Source | Public Source | Result |
---|---|---|---|
KAS_ECKA_DH | Static KEY_ECC_PRIVATE | Remote KEY_ECC_PUBLIC | KEY_SHARED_SECRET |
KAS_ECKA_EG | Static KEY_ECC_PRIVATE | Ephemeral KEY_ECC_PUBLIC | KEY_SHARED_SECRET |
KAS_ECKA_EG | Ephemeral KEY_ECC_PRIVATE | Static KEY_ECC_PUBLIC | KEY_SHARED_SECRET |
The resources required for key management must be configured by the CSP Admin.
The resource identifiers for key resources, assigned during creation, must be used in the methods provided by the KeyService
.
For details on admin commands of the CSP-Protocol, see Chapter 7 of GlobalPlatform Amendment N [GPC_SPE_230].
Below are pseudo admin command examples using CSP-Protocol ASN.1 types.
// Create an static ECC key pair used for key agreement and generate it. CSPCreateResource(STATIC_KEY_ID, KEY_ECC_PRIVATE, CURVE_BRAINPOOL_P256_R1) CSPCreateResource(STATIC_KEY_ID_PUBLIC, KEY_ECC_PUBLIC, CURVE_BRAINPOOL_P256_R1) CSPSetValue(STATIC_ECC_PRIVATE_KEY_ID, data) CSPComputePublicKey(STATIC_KEY_ID, STATIC_KEY_ID_PRIVATE) // Create an ephemeral ECC key pair with CLEAR & SETUP privileges that allows the client application to modify its key values. CSPCreateResource(EPHEMERAL_KEY_ID, KEY_ECC_PRIVATE, CURVE_BRAINPOOL_P256_R1, transient=true) CSPCreateResource(EPHEMERAL_KEY_ID_PUBLIC, KEY_ECC_PUBLIC, CURVE_BRAINPOOL_P256_R1, transient=true) // Create a shared secret that is used for the result of a key agreement operation. CSPCreateResource(SHARED_SECRET_ID, KEY_SHARED_SECRET, 256, transient=true) // Create an AES 256 bit cipher key and set CLEAR & SETUP privileges that allow the client application to modify its key value. CSPCreateResource(CIPHER_KEY_ID, KEY_AES, 256) // Configure access control. CSPConfigureResource(STATIC_KEY_ID, ACR_USE) CSPConfigureResource(STATIC_KEY_ID_PUBLIC, ACR_USE) CSPConfigureResource(EPHEMERAL_KEY_ID, ACR_CLEAR & ACR_SETUP & ACR_USE) CSPConfigureResource(EPHEMERAL_KEY_ID_PUBLIC, ACR_CLEAR & ACR_SETUP & ACR_USE) CSPConfigureResource(SHARED_SECRET_ID, ACR_CLEAR & ACR_SETUP & ACR_USE) CSPConfigureResource(CIPHER_KEY_ID, ACR_CLEAR & ACR_SETUP & ACR_USE) // Configure usage and algorithms. CSPConfigureResource(STATIC_KEY_ID, USAGE_KEY, KAS_ECKA_EG) CSPConfigureResource(STATIC_KEY_ID_PUBLIC, USAGE_KEY, KAS_ECKA_EG) CSPConfigureResource(EPHEMERAL_KEY_ID, USAGE_KEY, KAS_ECKA_EG) CSPConfigureResource(EPHEMERAL_KEY_ID_PUBLIC, USAGE_KEY, KAS_ECKA_EG) CSPConfigureResource(SHARED_SECRET_ID, USAGE_KEY, KDF_AES) CSPConfigureResource(CIPHER_KEY_ID, USAGE_CIPHER, CIPHER_AES_GCM)
Sample code for using the KeyService
:
// Retrieve CSP Shareable Instance. AID cspAID = JCSystem.lookupAID(CSP_AID_DATA, (short) 0, (byte) CSP_AID_DATA.length); GlobalService cspGlobalService = GPSystem.getService(cspAID, CSP.GLOBAL_SERVICE_ID); AID clientAID = JCSystem.getAID(); GPRegistryEntry clientRegistryEntry = GPSystem.getRegistryEntry(clientAID); CSP csp = (CSP) cspGlobalService.getServiceInterface(clientRegistryEntry, CSP.DEFAULT_SERVICE_ID, null, (short) 0, (short) 0); // Init service. KeyService keyService = csp.getKeyService(); switch (ins) { // Key pair generation sample. case GENERATE_KEY_PAIR: if (keyService.getState(EPHEMERAL_KEY_ID) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(EPHEMERAL_KEY_ID); } if (keyService.getState(EPHEMERAL_KEY_ID_PUBLIC) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(EPHEMERAL_KEY_ID_PUBLIC); } keyService.generate(EPHEMERAL_KEY_ID); keyService.computePublicKey(EPHEMERAL_KEY_ID, EPHEMERAL_KEY_ID_PUBLIC); break; // Key generation sample. case RE_GENERATE_CIPHER_KEY_ID: if (keyService.getState(CIPHER_KEY_ID) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(CIPHER_KEY_ID); } keyService.generate(CIPHER_KEY_ID); break; // Key derivation sample. case DERIVE_CIPHER_KEY_ID: if (keyService.getState(CIPHER_KEY_ID) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(CIPHER_KEY_ID); } // The KDF_AES algorithm was configured by the CSP Admin to the SHARED_SECRET_ID. keyService.derive(SHARED_SECRET_ID, CIPHER_KEY_ID, derivationData, (short) 0, (short) derivationData.length); SensitiveArrays.assertIntegrity(derivationData); break; // ECKA-DH key agreement sample. case ECKA_DH_KEY_AGREEMENT: if (keyService.getState(SHARED_SECRET_ID) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(SHARED_SECRET_ID); } keyService.agree(STATIC_KEY_ID, REMOTE_KEY_ID_PUBLIC, SHARED_SECRET_ID, data); break; // ECKA-EG key agreement sample. case ECKA_EG_KEY_AGREEMENT_INITIATION: // Generate new ephemeral ECC key pair. if (keyService.getState(EPHEMERAL_KEY_ID) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(EPHEMERAL_KEY_ID); } if (keyService.getState(EPHEMERAL_KEY_ID_PUBLIC) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(EPHEMERAL_KEY_ID_PUBLIC); } keyService.generateKeyPair(EPHEMERAL_KEY_ID, EPHEMERAL_KEY_ID_PUBLIC); // Initiate the ECKA-EG key agreement. keyService.agree(EPHEMERAL_KEY_ID, STATIC_KEY_ID_PUBLIC, SHARED_SECRET_ID); break; case ECKA_EG_KEY_AGREEMENT_RESPONSE: short publicKeyLength = publicKeyData[0]; // Import remote public key. if (keyService.getState(REMOTE_KEY_ID_PUBLIC) != ResourceService.STATE_UNINITIALIZED) { keyService.clear(REMOTE_KEY_ID_PUBLIC); } keyService.initManage(REMOTE_KEY_ID_PUBLIC, KeyService.MODE_IMPORT_PUBLIC_KEY); keyService.manage(publicKeyData, (short) 1, publicKeyLength); SensitiveArrays.assertIntegrity(publicKeyData); // Create response to an ECKA-EG key agreement. keyService.agree(STATIC_KEY_ID, REMOTE_KEY_ID_PUBLIC, SHARED_SECRET_ID); break; }
CertificateService
,
PasswordService
,
OffloadingService
Modifier and Type | Field and Description |
---|---|
static byte |
KEY_AES
AES symmetric key for encryption, decryption and MAC operations.
|
static byte |
KEY_DERIVED_SECRET
Derived secret result from key derivation, used as input for further key derivation.
|
static byte |
KEY_ECC_PRIVATE
ECC private key for Elliptic Curve Cryptography operations.
|
static byte |
KEY_ECC_PUBLIC
ECC public key for Elliptic Curve Cryptography operations.
|
static byte |
KEY_HMAC
Symmetric key for HMAC signature generation.
|
static byte |
KEY_MASTER_SECRET
Master secret generated within the CSP, used as input for key derivation.
|
static byte |
KEY_RSA_PRIVATE
RSA private key for RSA algorithms.
|
static byte |
KEY_RSA_PUBLIC
RSA public key for RSA algorithms.
|
static byte |
KEY_SHARED_SECRET
Shared secret result from key agreement, used as input for key derivation.
|
static byte |
MANAGE_MODE_PUBLIC_KEY_EXPORT
Sets the service to public key export mode.
|
static byte |
MANAGE_MODE_PUBLIC_KEY_IMPORT
Sets the service to public key import mode.
|
RESOURCE_CERTIFICATE, RESOURCE_COUNTER, RESOURCE_KEY, RESOURCE_PASSWORD, RESOURCE_TIMER, STATE_BLOCKED, STATE_EXHAUSTED, STATE_EXPIRED, STATE_OPERATIONAL, STATE_UNINITIALIZED
RESULT_FALSE, RESULT_TRUE
Modifier and Type | Method and Description |
---|---|
void |
computePublicKey(short srcPrivKeyResourceId,
short destPubKeyResourceId)
Compute a public key from the given private key.
|
void |
computeSharedSecret(short privateKeyResourceId,
short pubKeyResourceId,
short destSharedSecretResourceId)
Perform key agreement.
|
void |
derive(short sourceResourceId,
short destResourceId)
Convenience method that invokes
derive(sourceResourceId, destResourceId, null, (short) 0, (short) 0) . |
void |
derive(short sourceResourceId,
short destResourceId,
byte[] inputData,
short inputOffset,
short inputLength)
Derive a key from a source secret or password.
|
void |
generate(short keyResourceId)
Randomly generate a private or symmetric cryptographic key.
|
void |
generateKeyPair(short privateKeyResourceId,
short pubKeyResourceId)
Generate key values for public/private key pairs.
|
short |
getManagedLength(short publicKeyResourceId)
Retrieve the size, in bytes, of the buffer required for importing or exporting the certificate.
|
short |
getSize(short keyResourceId)
Retrieve the key size in bits.
|
byte |
getType(short keyResourceId)
Retrieve the key type.
|
void |
initManage(short publicKeyResourceId,
byte mode)
Initializes the service for either public key import or export.
|
short |
isTransient(short keyResourceId)
Retrieve whether the key is marked as transient.
|
short |
manage(byte[] buffer,
short offset,
short length)
Import or export a public key, depending on the mode set.
|
short |
updateManage(byte[] buffer,
short offset,
short length)
Multipart public key import or export, depending on the mode set.
|
clear, clearTransient, getResourceType, getState
assertSensitiveResult
static final byte KEY_AES
Encoded as unsigned big-endian byte array: [integer_bytes]
.
Length must match CSP-configured key size.
static final byte KEY_HMAC
Encoded as unsigned big-endian byte array: [integer_bytes]
.
Length must match CSP-configured key size.
static final byte KEY_ECC_PUBLIC
Encoded per [X9.62] Section 3.2.1, including x and y coordinates:
0x04 [X_bytes][Y_bytes]
.
Curve size must match CSP configuration.
KEY_ECC_PRIVATE
,
Constant Field Valuesstatic final byte KEY_ECC_PRIVATE
Encoded as unsigned big-endian byte array: [integer_bytes]
.
Length must match configured curve size.
KEY_ECC_PUBLIC
,
Constant Field Valuesstatic final byte KEY_RSA_PUBLIC
Encoded as unsigned big-endian byte array: [modulus_bytes][exponent_bytes]
.
Modulus length must match the RSA key size (e.g., 256 bytes for a 2048-bit key). Public exponent typically has a fixed size of 3 bytes for the common value 65537.
KEY_RSA_PRIVATE
,
Constant Field Valuesstatic final byte KEY_RSA_PRIVATE
Encoded as unsigned big-endian byte array: [modulus_bytes][exponent_bytes]
.
Lengths must match CSP-configured RSA key size (e.g., 256 bytes for 2048-bit key).
KEY_RSA_PUBLIC
,
Constant Field Valuesstatic final byte KEY_MASTER_SECRET
Encoded as unsigned big-endian byte array: [integer_bytes]
.
Length must match the CSP-configured key size.
static final byte KEY_DERIVED_SECRET
Encoded as unsigned big-endian byte array: [integer_bytes]
.
Length must match the CSP-configured key size.
static final byte KEY_SHARED_SECRET
Encoded as unsigned big-endian byte array: [integer_bytes]
.
Length must match the CSP-configured key size.
static final byte MANAGE_MODE_PUBLIC_KEY_IMPORT
In this mode, the manage(..)
and updateManage(..)
methods are used to export a public key.
initManage(..)
,
Constant Field Valuesstatic final byte MANAGE_MODE_PUBLIC_KEY_EXPORT
In this mode, the manage(..)
and updateManage(..)
methods are used to export a public key.
initManage(..)
,
Constant Field Valuesvoid initManage(short publicKeyResourceId, byte mode)
Method Behavior:
This method initializes the service for subsequent use with the updateManage(..)
and/or manage(..)
methods
to import or export the provided public key.
The method handles access control and events according to Section 6.7.3 of GlobalPlatform Amendment N.
publicKeyResourceId
- Public key resource.mode
- IMPORT
or EXPORT
.CSPException
- with reason:
ILLEGAL_VALUE
: Unknown mode [2074], resource ID does not exist [2001] or not a public key [2073].ILLEGAL_CONFIG
: CSP not activated [3001], resource not initialized for EXPORT
[3003], resource already initialized for IMPORT
[3004] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or
updateManage(..)
,
manage(..)
,
clear(..)
short updateManage(byte[] buffer, short offset, short length)
Method Behavior:
This method processes a data chunk for multipart import or export when the full public key cannot be transported in one array.
Based on the mode from the last initManage(..)
call, it imports or exports the public key without finalizing this process.
The method handles access control and events according to Section 6.7.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data in IMPORT
.CSPSensitiveArrays
for the output buffer in EXPORT
and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
in EXPORT
.initManage(..)
before calling this method.manage(..)
after one or more updateManage(..)
calls.buffer
- Input buffer for IMPORT
or output buffer for EXPORT
.offset
- Start offset in the buffer for reading or writing.length
- Number of bytes to read or write.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1002], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], resource not initialized for EXPORT
[3003] or resource already initialized for IMPORT
[3004].INVALID_INIT
: Service not initialized [4070].ILLEGAL_USE
: Invalid input data [6070] or illegal output buffer [6071].initManage(..)
,
manage(..)
short manage(byte[] buffer, short offset, short length)
Method Behavior:
Imports or exports a public key based on the last initManage(..)
call.
After completion, a new initManage(..)
call is required to prepare the service for the next import or export.
The method handles access control, counters, timers and events according to Section 6.7.3 of GlobalPlatform Amendment N.
Usage Guidelines:
CSPSensitiveArrays
for the input data in IMPORT
.CSPSensitiveArrays
for the output buffer in EXPORT
and invoke assertIntegrity(..)
after processing it.assertSensitiveResult(..)
in EXPORT
.initManage(..)
before calling this method.updateManage(..)
as needed before finalizing with this method.buffer
- Input buffer for IMPORT
or output buffer for EXPORT
.offset
- Start offset in the buffer for reading or writing.length
- Number of bytes to read or write.CSPException
- with reason:
ILLEGAL_BUFFER
: Illegal input or output buffer [1001], [1002], [1004], [1005], [1006], [1007].ILLEGAL_CONFIG
: CSP not activated [3001], missing resource [3002], resource not initialized for EXPORT
[3003] or resource already initialized for IMPORT
[3004].INVALID_INIT
: Service not initialized [4070].ILLEGAL_USE
: Invalid input data [6070] or illegal output buffer [6071].initManage(..)
,
updateManage(..)
short getManagedLength(short publicKeyResourceId)
publicKeyResourceId
- The public key resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or not a public key [2073].ILLEGAL_CONFIG
: CSP not activated [3001] or resource not initialized [3003].NOT_ALLOWED
: Client not authenticated [5006].short isTransient(short keyResourceId)
Transient keys are stored in volatile memory.
keyResourceId
- Key resource.TRUE
if the key is transient; otherwise FALSE
.CSPException
- for:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a KEY
[2070].NOT_ALLOWED
: Client not authenticated [5006].byte getType(short keyResourceId)
Available types:
keyResourceId
- Key resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a KEY
[2070].NOT_ALLOWED
: Client not authenticated [5006].getSize(..)
short getSize(short keyResourceId)
keyResourceId
- Key resource.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or is not a KEY
[2070].NOT_ALLOWED
: Client not authenticated [5006].getType(..)
void generate(short keyResourceId)
Available for
Method Behavior:
This method uses a secure random number generator to generate a key value
and changes its state from STATE_UNINITIALIZED
to STATE_OPERATIONAL
.
The method handles access control, counters, timers and events according to Section 6.7.3 of GlobalPlatform Amendment N.
If an error occurs, all changes are rolled back to the state prior to this method's invocation.
Usage Guidelines:
clear(..)
if not in STATE_UNINITIALIZED
.keyResourceId
- Key to be generated.CSPException
- with reason:
ILLEGAL_VALUE
: Resource ID does not exist [2001] or not a private or symmetric key [2071].ILLEGAL_CONFIG
: Resource already initialized [3004].NOT_ALLOWED
: Client not authenticated [5006] or resource missing ACCESS_SETUP
[5008].clear(..)
,
generateKeyPair(..)
,
computePublicKey(..)
void generateKeyPair(short privateKeyResourceId, short pubKeyResourceId)
Available for:
Method Behavior:
This method uses a secure random number generator to generate the private key and computes the public key from it.
Changes the state of both resources from STATE_UNINITIALIZED
to STATE_OPERATIONAL
.
The method handles access control, counters, timers and events according to Section 6.7.3 of GlobalPlatform Amendment N.
If an error occurs, all changes are rolled back to the state prior to this method's invocation.
Usage Guidelines:
clear(..)
if not in STATE_UNINITIALIZED
.privateKeyResourceId
- Private key to be generated.pubKeyResourceId
- Public key to be generated.CSPException
- with reason:
ILLEGAL_VALUE
: A resource ID does not exist [2001], or first is not a private [2072] or second not a public key [2073].ILLEGAL_CONFIG
: A resource is already initialized [3004] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006] or a resource missing ACCESS_SETUP
[5008] or a policy failed [500B].clear(..)
,
generate(..)
,
computePublicKey(..)
void computePublicKey(short srcPrivKeyResourceId, short destPubKeyResourceId)
Available for:
Method Behavior:
This method computes the public key value from an already initialized private key
and changes the state of the public key resource from ResourceService.STATE_UNINITIALIZED
to ResourceService.STATE_OPERATIONAL
.
The method handles access control, counters, timers and events according to Section 6.7.3 of GlobalPlatform Amendment N.
If an error occurs, all changes are rolled back to the state prior to this method's invocation.
Usage Guidelines:
STATE_OPERATIONAL
.clear(..)
if it is not in STATE_UNINITIALIZED
.srcPrivKeyResourceId
- Private key; will not be modified.destPubKeyResourceId
- Public key to be generated.CSPException
- for:
ILLEGAL_VALUE
: A resource ID does not exist [2001], first is not private [2072] or second is not public [2073].ILLEGAL_CONFIG
: Private key not initialized [3003], public key already initialized [3004] or inconsistent policy config [3009].NOT_ALLOWED
: Client not authenticated [5006], private key missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], public key missing ACCESS_SETUP
[5008] or a policy failed [500B].generate(..)
,
clear(..)
void derive(short sourceResourceId, short destResourceId, byte[] inputData, short inputOffset, short inputLength)
Available for:
Method Behavior:
Derives a new key from the input resource and additional data using the key derivation algorithm configured to the source key
and changes the destination resource from ResourceService.STATE_UNINITIALIZED
to ResourceService.STATE_OPERATIONAL
.
The method handles access control, counters, timers and events according to Section 6.7.3 of GlobalPlatform Amendment N.
If an error occurs, all changes are rolled back to the state prior to this method's invocation.
Usage Guidelines:
CSPSensitiveArrays
for the input data.STATE_OPERATIONAL
.clear(..)
if it is not in STATE_UNINITIALIZED
.sourceResourceId
- Source key (secret or password) for key derivation.destResourceId
- Derived key.inputData
- Input data to be considered during key derivation, can be null
.inputOffset
- Offset in the input buffer to start reading; can be 0
.inputLength
- Length of the input data in bytes; can be 0
.CSPException
- for:
ILLEGAL_BUFFER
: Illegal input buffer [1003], [1004], [1005], [1006], [1007].ILLEGAL_VALUE
: A resource ID does not exist [2001].ILLEGAL_CONFIG
: Source not initialized [3003], destination already initialized [3004] or inconsistent key derivation configuration [3070].NOT_ALLOWED
: Client not authenticated [5006] or source missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_KEY
[5070] or destination missing ACCESS_SETUP
[5008].ILLEGAL_USE
: Illegal input data [6072].NOT_SUPPORTED
: Derivation algorithm [8074] not supported.derive(..)
,
clear(..)
void derive(short sourceResourceId, short destResourceId)
derive(sourceResourceId, destResourceId, null, (short) 0, (short) 0)
.sourceResourceId
- Source key (secret or password) for key derivation.destResourceId
- Derived key.CSPException
- for:
ILLEGAL_VALUE
: A resource ID does not exist [2001].ILLEGAL_CONFIG
: Source not initialized [3003], destination already initialized [3004] or inconsistent key derivation configuration [3070].NOT_ALLOWED
: Client not authenticated [5006] or source missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], not configured for USAGE_KEY
[5070] or destination missing ACCESS_SETUP
[5008].NOT_SUPPORTED
: Derivation algorithm [8074] not supported.derive(..)
void computeSharedSecret(short privateKeyResourceId, short pubKeyResourceId, short destSharedSecretResourceId)
Available for:
KEY_ECC_PRIVATE
, KEY_ECC_PUBLIC
, KEY_SHARED_SECRET
)KEY_RSA_PRIVATE
, KEY_RSA_PUBLIC
, KEY_SHARED_SECRET
)Method Behavior:
This method computes a shared secret using the private and public keys, along with the provided additional data,
and changes the state of the shared secret resource from ResourceService.STATE_UNINITIALIZED
to ResourceService.STATE_OPERATIONAL
.
It uses the key agreement scheme configured to the private key.
The method handles access control, counters, timers and events according to Section 6.7.3 of GlobalPlatform Amendment N.
If an error occurs, all changes are rolled back to the state prior to this method's invocation.
Usage Guidelines:
STATE_OPERATIONAL
.clear(..)
if it is not in STATE_UNINITIALIZED
.privateKeyResourceId
- Private key (local or remote).pubKeyResourceId
- Public key (local or remote).destSharedSecretResourceId
- Shared secret to be computed.CSPException
- for:
ILLEGAL_VALUE
: A resource ID does not exist [2001].ILLEGAL_CONFIG
: Private or public key not initialized [3003], shared secret already initialized [3004] or inconsistent key agreement configuration [3071].NOT_ALLOWED
: Client not authenticated [5006] or private or public key missing ACCESS_USE
[5007], exhausted [50A0], expired [50B1], private key not configured for USAGE_KEY
[5070] or shared secret missing ACCESS_SETUP
[5008].NOT_SUPPORTED
: Key agreement scheme [8075] not supported.clear(..)
Copyright © 2023-2025 GlobalPlatform, Inc. All rights reserved. The technology provided or described in this specification is subject to updates, revisions, and extensions by GlobalPlatform. Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights or other intellectual property rights of which they may be aware which might be necessarily infringed by the implementation of the specification or other work product set forth in this document, and to provide supporting documentation.
THIS SPECIFICATION OR OTHER WORK PRODUCT IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NON-INFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE COMPANY, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER DIRECTLY OR INDIRECTLY ARISING FROM THE IMPLEMENTATION OF THIS SPECIFICATION OR OTHER WORK PRODUCT.