Keymanager3

Service URI - luna://com.webos.service.keymanager3

Provides methods for generation and deletion of keys, encryption and decryption, generation and verification of signature, etc.
These crypto operations are performed by the keymaster trusted application (TA) running under the trusted execution environment (TEE). It is a similar concept to Android's HW keymaster, demonstrating the high-standard key protection technology.

From webOS TV 24, you can use this API for data protection (confidentiality, integrity).

The following is the list of encryption algorithms provided by keymanager3 and their key sizes.

Encryption (Key type)	Purpose	Key size	Remarks
AES	encrypt, decrypt	128, 192, 256
RSA	sign, verify, encrypt, decrypt	1024, 2048, 3072, 4096	Generating RSA keys in the TEE has significant impact on the TV's performance. The size of a key generated using keymanager3 will be 1024 only. To generate keys of other sizes, generate a key in the app first, and import it to keymanager3 to use crypto operations.
ED	sign, verify	224(P224), 256(P256), 384(P384), 521(P521)	The key size is determined by the curve algorithm.
HMAC	sign, verify	64 or bigger	The recommended size is 256 (32 bytes).

Methods

Method	Description	Supported in Emulator
generateKey	Requests generation of a key for the encryption algorithm supported by keymanager3. The length and type of the key should be specified.	No
importKey	Delivers a key generated outside to the keymanager3 service. The key is encrypted by keymanager3 and stored and, later, is used for crypto operations supported by keymanager3.	No
exportKey	Gets the public key, which is the pair of the requested key.	No
removeKey	Requests deletion of a key generated or stored by keymanager3.	No
begin	Specifies the crypto operation of keymanager3 to use using the key name and gets a unique handle id required to call the update/finish method later.	No
update	Delivers the unique handle id and data acquired by calling the begin method.	No
finish	Delivers the unique handle id and data acquired by calling the begin method, completes the crypto operation with the data delivered by the update method, and receives the result.	No
abort	After getting the unique handle id by calling the begin method, requests abortion of the corresponding crypto operation. You MUST call this abort method to stop the operation after calling the begin method. By doing so, you can prevent a critical error on a TV device due to insufficient resource.	No

generateKey

Description

Enables an app to generate a new key or keypair and store it in the database.
The key generated by this method can be used only by the owner of the key. For example, if app A creates a key using this method, that key can be used only by this app A.
The key name must be unique, which means you cannot generate a key with the existing key name. To generate a key with the existing name, remove that existing key using the removeKey method first.

Parameters

Name	Required	Type	Description
name	Required	String	Name of a key to generate.
params	Required	Object::ParamSet	Specifies the key-associated authorization parameter set.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-10001, -10002, -10003, -10004, -10005, -10006, -10007, -10008, -10009, -10010, -10011, -10012, -10016, -10017, -10018	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

Generate an AES key using the generateKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "generateKey",
  parameters: {
    name: "AES256",
    params: {
      type: "AES",
      size: 256,
      mode: ["ECB", "CBC"],
      purpose: ["encrypt", "decrypt"],
      padding: ["PKCS7"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Generate an RSA key using the generateKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "generateKey",
  parameters: {
    name: "RSA1024",
    params: {
      type: "RSA",
      size: 1024,
      purpose: ["sign", "verify"],
      padding: ["PKCS1"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Generate an HMAC key using the generateKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "generateKey",
  parameters: {
    name: "HMAC256",
    params: {
      type: "HMAC",
      size: 256,
      purpose: ["sign", "verify"],
      digest: ["SHA2_256"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Generate an EC key using the generateKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "generateKey",
  parameters: {
    name: "EC256",
    params: {
      type: "EC",
      size: 256,
      purpose: ["sign", "verify"],
      padding: "PKCS1",
      digest: ["SHA2_256"],
      curve: "P256",
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return when the key already exists

{
  "returnValue": false,
  "errorCode": -10002,
  "errorText": "Key already exists"
}

Failure return when the key size is invalid

{
  "returnValue": false,
  "errorCode": -10003,
  "errorText": "Invalid key size"
}

Failure return when the purpose is invalid

{
  "returnValue": false,
  "errorCode": -10004,
  "errorText": "Invalid purpose"
}

Failure return when the padding is not supported

{
  "returnValue": false,
  "errorCode": -10006,
  "errorText": "Invalid padding"
}

importKey

Description

Enables an app to import a key or key pair and store it in the database.
To import a key pair, just import the private key, then keymanager3 will derive its public key.

Parameters

Name	Required	Type	Description
name	Required	String	Name of the key to import.
data	Required	String	Base64-encoded key data that the app wants to import. For AES and HMAC: Base64-encoded binary format For RAS and EC: Base64-encoded PKCS#8 DER format
params	Required	Object::ParamSet	Specifies the key associated authorization parameter set.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-10001, -10002, -10003, -10004, -10005, -10006, -10007, -10008, -10009, -10010, -10011, -10012, -10016, -10017, -10018	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

Store the existing AES key in the keymanager3 database using the importKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "importKey",
  parameters: {
    name: "AES256",
    data: "JFWOIEJFOIJQOIEJFOIJQOIEJFOQIJFOIQJEFOQIJFE",
    params: {
      type: "AES",
      size: 256,
      mode: ["ECB", "CBC"],
      purpose: ["encrypt", "decrypt"],
      padding: ["PKCS7"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Store the existing RSA key in the keymanager3 database using the importKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "importKey",
  parameters: {
    name: "RSA2048",
    data: base64data,
    params: {
      type: "RSA",
      size: 2048,
      purpose: ["sign", "verify"],
      padding: ["PKCS1"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Store the existing HMAC key in the keymanager3 database using the importKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "importKey",
  parameters: {
    name: "HMAC192",
    data: "AAECAwQFBgcICQoLDA0OD/Dg0MCwoJCA",
    params: {
      type: "HMAC",
      size: 192,
      purpose: ["sign", "verify"],
      digest: ["SHA2_256"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Store the existing EC key in the keymanager3 database using the importKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "importKey",
  data: "MHgCAQAwEAYHKoZIzj0CAQYFK4EEACEEYTBfAgEBBBzdKeUoBI95MlFJ0fJf7Ny0j2KeaTGWueZpkD1boTwDOgAEwB3KS89AOv+OTGRzshsXPX4CpYJcPIrD6A+z2K0pTBJV/DcefaLag3fhNcFH96jEKcDZxHYNWUA=",
  parameters: {
    name: "EC224",
    params: {
      type: "EC",
      size: 224,
      purpose: ["sign", "verify"],
      padding: "PKCS1",
      digest: ["SHA2_256"],
      curve: "P224",
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return when the key already exists

{
  "returnValue": false,
  "errorCode": -10002,
  "errorText": "Key already exists"
}

Failure return when the key type is invalid

{
  "returnValue": false,
  "errorCode": -10010,
  "errorText": "Invalid key type"
}

Failure return when the key size is invalid

{
  "returnValue": false,
  "errorCode": -10003,
  "errorText": "Invalid key size"
}

Failure return when the purpose is invalid

{
  "returnValue": false,
  "errorCode": -10004,
  "errorText": "Invalid purpose"
}

Failure return when the padding is not supported

{
  "returnValue": false,
  "errorCode": -10006,
  "errorText": "Invalid padding"
}

exportKey

Description

Enables an app to export a public key from the existing keypair by the key name.

Parameters

Name	Required	Type	Description
name	Required	String	Name of the key from which the app wants to export the public key. Note Therefore, only RSA and EC keys can be exported.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
pubkey	Optional	String	Base64-encoded DER format of public key.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-10001, -20017	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

Get the public key of the existing RSA key using the exportKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "exportKey",
  parameters: {
    name: "RSA1024",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Get the public key of the existing EC key using the exportKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "exportKey",
  parameters: {
    name: "EC224",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
    "returnValue": true,
    "pubkey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwfSdrRlE50jwRsj/WJ8rDpGPaFcMn/1XlKRsRqYUKM/cI4x8DXZjBFtedxJwVRHGzODpyCL7LqyaUU4M9W5seNdnZXtQ2Kfyiq7Bx9QIy5Z1G7eif6ZnG2AN4SruJ+P4vfWBlzu9RyufhwybRoCS08oOS9H
yb+uhrFoh7TiQQRx8zGM2j04pNGuuvyjV0MQNuBL8RjCnoBnQX5PnYonQh4NReIcGH/J3C3XdlnrpuhArYb8wMxzQkOAM91wtMPwU2VX8sYLmdnqDrW+LameghtacuAZUUdJnG4ccanmDj1mPAxpWFx8Q3bxm+OStqt1LnQT5vLc7kgoMyfH70h2dTwIDAQAB"
}

Failure return when the key name does not exist

{
    "returnValue": false,
    "errorCode": -10001,
    "errorText": "Key not found"
}

Failure return when the key type is neither RSA nor EC

{
    "returnValue": false,
    "errorCode": -20017,
    "errorText": "Get error from keymaster"
}

removeKey

Description

Removes a key from the device by key name.

Parameters

Name	Required	Type	Description
name	Required	String	Name of the key to remove.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-10000, -10001, -10009	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

Remove a key using the removeKey method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "removeKey",
  parameters: {
    name: "AES256",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return when the key name does not exist

{
    "returnValue": false,
    "errorCode": -10001,
    "errorText": "Key not found"
}

begin

Description

Parameters

Name	Required	Type	Description
name	Required	String	Name of the key to operate the cryptography.
params	Required	Object::ParamSet	Specifies the operation-associated authorization parameter set. As it is not possible to use a key in any way inconsistent with the authorizations specified at the time of generation, the key owner should list every authorization parameter set that will be used afterward. AES To use AES, "mode" must be set. The default padding is None. PKCS7 is available only for mode ECB or CBC. Except for AES-ECB, if you want to decrypt cipher, the iv value returned from the encrypt operation must be set. (Base64 encoded value, plain length is CBC, CTR -16byte, GCM-12byte) If None is selected as "padding" for AES-ECB or CBC, the size of the input data must be a multiple of the block size. RSA The default padding is PKCS1. The default digest is SHA2_256. Note If "padding" is set to PKCS1_OAEP, "digest" cannot be set as None. If "padding" is set to None, "digest" must be set as None explicitly. EC In the case of the EC algorithm, "curve" is a required param. The default digest is SHA2_256 for EcDsa curve (P224/P256/P384/P521). HMAC The default MAC length is 32 bytes.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
handle	Optional	String	Handle that is used with the update and finish methods to complete the operation. This handle is the context for the crypto operation. Note The actual data type of the handle is uint64, but it returns a handle value as a string.
iv	Optional	String	For AES-CBC/GCM/CTR encryption, if the user does not set the iv value, a unique iv is automatically generated and returned.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-10001, -10002, -10003, -10004, -10005, -10006, -10007, -10008, -10009, -10010, -10011, -10012, -10016, -10017, -10018, -20033, -20052	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

Call the begin method for encryption using the AES key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "begin",
  parameters: {
    name: "AES256",
    params: {
      type: "AES",
      mode: ["CBC"],
      purpose: ["encrypt"],
      padding: ["PKCS7"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
    // Should parse "iv" param
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the begin method for decryption using the AES key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "begin",
  parameters: {
    name: "AES256",
    params: {
      type: "AES",
      size: 256,
      mode: ["CBC"],
      purpose: ["decrypt"],
      padding: ["PKCS7"],
      iv: "tipAtFblvLXf/iLR8t5dGw==",
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the begin method for signing using the RSA key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "begin",
  parameters: {
    name: "RSA1024",
    params: {
      type: "RSA",
      purpose: ["sign"],
      padding: ["PKCS1"],
      digest: ["SHA2_256"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the begin method for verification using the RSA key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "begin",
  parameters: {
    name: "RSA1024",
    params: {
      type: "RSA",
      purpose: ["verify"],
      padding: ["PKCS1"],
      digest: ["SHA2_256"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the begin method for signing using the HMAC key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "begin",
  parameters: {
    name: "HMAC256",
    params: {
      type: "HMAC",
      purpose: ["sign"],
      digest: ["SHA2_256"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the begin method for verification using the HMAC key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "begin",
  parameters: {
    name: "HMAC256",
    params: {
      type: "HMAC",
      purpose: ["verify"],
      digest: ["SHA2_256"],
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the begin method for signing using the EC key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "generateKey",
  parameters: {
    name: "EC256",
    params: {
      type: "EC",
      purpose: ["sign"],
      padding: "PKCS1",
      digest: ["SHA2_512"],
      curve: "P256",
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the begin method for verification using the EC key

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "generateKey",
  parameters: {
    name: "EC256",
    params: {
      type: "EC",
      purpose: ["verify"],
      padding: "PKCS1",
      digest: ["SHA2_512"],
      curve: "P256",
    },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true,
  "handle": "10699227874884526357"
}

Success return with the iv value

{
  "returnValue": true,
  "handle": "10699227874884526357",
  "iv": "tpoUOY8ca/Fd46JGSDKmtw=="
}

Failure return

{
  "returnValue": false,
  "errorCode": -10002,
  "errorText": "Key already exists"
}

Failure return when the key size is invalid

{
  "returnValue": false,
  "errorCode": -10003,
  "errorText": "Invalid key size"
}

Failure return when the purpose is invalid

{
  "returnValue": false,
  "errorCode": -10004,
  "errorText": "Invalid purpose"
}

Failure return when the padding is not supported

{
  "returnValue": false,
  "errorCode": -10006,
  "errorText": "Invalid padding"
}

Failure return when the key type is invalid

{
  "returnValue": false,
  "errorCode": -10010,
  "errorText": "Invalid key type"
}

update

Description

Provides data to process the ongoing operation started by the begin method. If the returned consumed_size is not matched to the full length of the input data, you should call the update method again with the remaining data starting after the data's consumed_size.
Do not process a large amount of data at once. If the data size exceeds 1M, split the data and use theupdate method multiple times with the spilt data sets.

Parameters

Name	Required	Type	Description
handle	Required	String	Operation handle that is returned by the begin method. Note The actual datatype of the handle is uint64, but it is input as a string.
data	Required	String	Input data to operate. It must be base64-encoded.
aad	Optional	String	aad that is authenticated but not encrypted. It is only for the AES-GCM block mode, and it must be base64 encoded.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
consumed_size	Optional	String	Returns the consumed size upon the success of the method. Note If it is equal to the size of the input, it means all input is delivered. But if not, the app has to call the update method again to deliver the remaining input.
output	Optional	String	Returns the base64-encoded output upon the success of the method. Note It could be cipher, plaintext or signature.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-10003, -10008, -10009, -10010, -10016, -10017, -20028	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

Call the update method using the handle acquired by calling the begin method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "update",
  parameters: {
    handle: "10699227874884526357",
    data: "dGVzdCB1cGRhdGUgZGF0YQ==",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true,
  "consumed_size": 16,
  "output": "uvFYV8bL3EByEcswuUOYUg=="
}

Success return

{
  "returnValue": true
}

Failure return when the handle is invalid

{
  "errorCode": -20028,
  "errorText": "Get error from keymaster",
  "returnValue": false
}

finish

Description

Begins a cryptographic operation, using the specified key, for the specified purpose with the specified parameters (as appropriate), and returns an operation handle that is used with update and finish to complete the operation.
Do not process a large amount of data at once. If the data size exceeds 1M, split the data and use thefinish method multiple times with the spilt data sets.

Parameters

Name	Required	Type	Description
name	Required	String	Name of the key to operate the cryptography.
data	Optional	String	Input data to operate. It must be base64 encoded.
signature	Optional	String	Base64-encoded signature of the message. Note Signature is used for the verification purpose only.
aad	Optional	String	aad that is authenticated but not encrypted. It is only for the AES-GCM block mode, and it must be base64 encoded.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
output	Optional	String	Base64-encoded output upon the success of the method. Note It could be cipher, plaintext or signature.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-10008, -10016, -10017, -20030	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

Call the finish method using the handle acquired by calling the begin method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "finish",
  parameters: {
    handle: "13123551428131904409",
    data: "dGVzdCBmaW5pc2ggZGF0YQ==",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Call the finish method using the handle acquired by calling the begin method

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "finish",
  parameters: {
    handle: "13123551428131904409",
    data: "dGVzdCBmaW5pc2ggZGF0YQ==",
    signature:
"jUZPi2UrptakGiThbBFQzOKXRGpRP2Jp3v1HJZPE5Y0s+zexj+i8d57rGQ/EoBCwDtJNCgK8wPa9tF7jWjp3mL41P5xszxXzkvOufZ3nME9zj4SbknBNP2Pw16mjOolp1FF0xau5Zpyotm+7D60nu2tJl9tW1j+7Ck+r1OxmDdMdFNbMBJiClwbk3hFU/wtEF1kbN0Z6+XPfkSu5NAs8O83rMWsoJ4iDmeFoF+T2YZlWQLZM6IvN8KNKnkhkVR86RlBeh7Yu8BF3UpA2poVReRuIOLwz8+MLt00+bgiIAPSIBCDg6En0AKZPTLT1gx7PTHwkB05ReyDEJmGNMbslDA==",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return when the purpose is encryption/decryption

{
  "returnValue": true,
  "output": "rXXAt28n9kGyNGBK8Ur2fd6eM2FJoPcROwuBMC6l4Cc="
}

Success return when the purpose is signing

{
  "returnValue": true,
  "output": "jUZPi2UrptakGiThbBFQzOKXRGpRP2Jp3v1HJZPE5Y0s+zexj+i8d57rGQ/EoBCwDtJNCgK8wPa9tF7jWjp3mL41P5xszxXzkvOufZ3nME9zj4SbknBNP2Pw16mjOolp1FF0xau5Zpyotm+7D60nu2tJl9tW1j+7Ck+r1OxmDdMdFNbMBJiClwbk3hFU/
wtEF1kbN0Z6+XPfkSu5NAs8O83rMWsoJ4iDmeFoF+T2YZlWQLZM6IvN8KNKnkhkVR86RlBeh7Yu8BF3UpA2poVReRuIOLwz8+MLt00+bgiIAPSIBCDg6En0AKZPTLT1gx7PTHwkB05ReyDEJmGNMbslDA=="
}

Success return when the purpose is verification

{
  "returnValue": true
}

Failure return when verification failed

{
  "errorCode": -20030,
  "errorText": "Get error from keymaster",
  "returnValue": false
}

abort

Description

Aborts the in-progress operation.
Once you call abort with a handle, the handle value is no longer available for cryptographic operation.

Parameters

Name	Required	Type	Description
handle	Required	String	Context to abort the in-progress operation. Note The actual datatype of the handle is uint64, but it is input as a string.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the result of the operation. true: The operation was successful. false: The operation failed.
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method returns errorCode only if it fails.
errorText	Optional	String	errorText contains the error code if the method fails. The method returns errorText only if it fails.

Error reference

Error code	Error text	Error description
-20028	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

If the handle acquired by calling the begin method is no longer needed

var request = webOS.service.request("luna://com.webos.service.keymanager3", {
  method: "abort",
  parameters: {
    handle: "3901299957133494448",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return when the handle is not valid

{
  "returnValue": false,
  "errorCode": -20028,
  "errorText": "Get error from keymaster"
}

Objects

ParamSet

Description

Contains the information about the key or operation parameter values.
As it is not possible to use a key in any way inconsistent with the authorizations specified at the time of generation, the key owner should list every authorization parameter set that will be used afterward.

Properties

Name	Required	Type	Description
type	Required	String	Type of a key. Possible values are: AES RSA EC HMAC
size	Optional	Number	Size of a key. Possible values for each key type are: AES: 128, 192, 256 RSA: 1024, 2048, 3072, 4096 Only 1024 size can be generated by keymanager3. Apps can import generated RSA-2048/RSA-3072/RSA-4096 key data to keymanager3. EC 224, 256, 384, 521 The key size is determined by the curve algorithm. So it is not necessary to specify the size to generate/import EC keys. Supported matching key sizes are: P224(224), P256(256), P384(384), P521(521). HMAC: The minimum size changes according to the digit algorithm. However, the recommended size is at least 256 (32 bytes).
purpose	Optional	String array	Purpose of the operation. Possible values for each key type are: AES: encrypt, decrypt RSA: sign, verify, encrypt, decrypt EC: sign, verify HMAC: sign, verify
mode	Optional	String array	Note It is applicable only for AES keys. This is required to generate/import/begin with AES keys. Mode of the operation. Possible values are: ECB CBC CTR GCM
padding	Optional	String array	Note It is applicable only for AES keys. This is required to generate/import/begin with AES keys. Padding mode for the keys. Possible values are: AES None PKCS7 (Default if "padding" is not specified) (PKCS7 is only for the ECB and CBC modes.) RSA (private key) None PKCS1 PKCS1_OAEP (Default if "padding" is not specified)
digest	Optional	String array	Digest of the signing/verification operation. Possible values for supported key types are: RSA: SHA2_224, SHA2_256, SHA2_384, SHA2_512 EC: SHA2_224, SHA2_256, SHA2_384, SHA2_512 HMAC: SHA2_256
mac_length	Optional	String	MAC length for operations that need MAC (HMAC, AES-GCM). By default, the minimum mac length is as follows: HMAC: 64 RSA: 128 You can update the value to a larger value.
iv	Optional	String	Note It is applicable only for AES-CBC, AES-GCM, and AES-CTR keys. If it is required to use a specific iv value, use this parameter. If not, when using an algorithm that requires an iv value, keymanager3 automatically generates and returns it. The client service that calls the keymanager3 API must manage it. For encryption, if the iv parameter is not set, a unique iv value is automatically generated and returned. (It will be a base64-encoded value, and the plain iv length is CBC, CTR -16byte, or GCM-12byte). For decryption, the iv value used for encryption must be set.
curve	Optional	String	Note It is applicable only for EC keys. Specify the Elliptic Curve algorithm. This is required to generate/import/begin with EC keys. Possible values are: P224 P256 P384 P521

Error code reference

Error code	Error text	Error description
-10000	not implemented	This feature is not supported.
-10001	key not found	The key could not be found.
-10002	key already exists	A key with the same name already exists.
-10003	invalid key size	The selected key size is not supported.
-10004	invalid purpose	The selected purpose is not supported.
-10005	invalid mode	The selected mode is not supported.
-10006	invalid padding	The selected padding is not supported.
-10007	invalid digest	The selected digest is not supported.
-10008	invalid data size	The data size is too large.
-10009	not supported parameter	The data size is too large or does not match the selected algorithm.
-10010	Invalid key type	The selected key type is not supported.
-10011	Failed to encrypt key	Encryption of key failed.
-10012	Failed to decrypt key	Decryption of key failed.
-10016	Base64 encoding is failed	Base64 encoding of data failed.
-10017	Base64 decoding is failed	Base64 decoding of data failed.
-10018	Invalid EC curve	The selected EC curve is not supported.
-20009	Get error from keymaster	The selected mac length is not supported.
-20010	Get error from keymaster	The selected padding mode is not supported.
-20011	Get error from keymaster	The selected padding mode is not compatible.
-20012	Get error from keymaster	The selected digest mode is not supported.
-20013	Get error from keymaster	The selected digest mode is not compatible.
-20017	Get error from keymaster	Unsupported key type.
-20019	Get error from keymaster	The selected key type does not support encryption.
-20020	Get error from keymaster	The selected key type does not support verification.
-20021	Get error from keymaster	The data size inputted is not valid.
-20028	Get error from keymaster	The handle is not valid.
-20030	Get error from keymaster	Verification failed.
-20033	Get error from keymaster	Key data is corrupted or invalid.
-20052	Get error from keymaster	IV value is not set.

No Headings

webOS News

LG Electronics Announces Call for Participants for the LG webOS Hackathon 2024

LG Smart TVs Unlock Limitless Entertainment and Personal Growth With New Apps

Keymanager3

generateKey

importKey

exportKey

removeKey

begin

update

finish

abort

Objects

ParamSet

Description

Properties

Error code reference