07. Secure

The secure object is a built-in object that provides security-related operations and data encryption/decryption functionality.

Functional overview:

• Supports HMAC operation.
• Supports SHA-256 hash operation.
• Supports Base64 encoding/decoding.
• Supports data encryption/decryption.
• Supports signature operation/verification.

---

secure Global Object

Methods()/Properties	Summary	Version	Note
secure.setHmac()	Sets up HMAC operation.	01.00.00+
secure.hmacUpdate()	Adds a data stream for HMAC operation.	01.00.00+
secure.hmacDigest()	Outputs the HMAC value.	01.00.00+
secure.freeHmac()	Releases HMAC operation resources.	01.00.00+
secure.startSha256()	Starts SHA-256 hash operation.	01.00.00+
secure.updateSha256()	Adds a data stream for SHA-256 hash operation.	01.00.00+
secure.finishSha256()	Outputs the SHA-256 hash value.	01.00.00+
secure.base64Encode()	Performs Base64 encoding on the given data.	01.00.00+
secure.base64Decode()	Performs Base64 decoding on the given data.	01.00.00+
secure.genKey()	Creates a key pair for asymmetric encryption.	01.00.00+
secure.encPK()	Encrypts data using the specified public key.	01.00.00+
secure.decPK()	Decrypts data using the specified private key.	01.00.00+
secure.setSign()	Sets up Signature operation/verification.	01.00.00+
secure.signUpdate()	Adds a data stream for signature operation/verification.	01.00.00+
secure.signDigest()	Outputs the signature value.	01.00.00+
secure.verifyDigest()	Outputs the result of signature verification.	01.00.00+
secure.freeSign()	Releases signature operation/verification resources.	01.00.00+

---

Details

secure.setHmac(algo,key)

Sets up HMAC operation.
HMAC operation resources are allocated and methods related to HMAC operations are allowed.
Note that it is not possible to have multiple operation resources at the same time.
When setting up again, execute secure.hmacDigest() or secure.freeHmac() to release the operation resources once.

Name	Type	M/O	Summary	Note
algo	string	mandatory	Algorithm name Specify the name of the algorithm to be used. The following hash algorithms are supported: 'sha256'
key	string, ArrayBuffer	mandatory	Private key This argument can be specified as a string or binary.
return	undefined	-	-	When an error occurs, an exception is raised.

secure.hmacUpdate(message)

Adds the data stream for HMAC operation.
This method can be called continuously.

Name	Type	M/O	Summary	Note
message	string	mandatory	The data stream to operate on This argument can only be specified string.
return	undefined	-	-	When an error occurs, an exception is raised.

secure.hmacDigest()

Outputs the HMAC value in binary.
At the same time, HMAC operation resources are released.

Name	Type	M/O	Summary	Note
return	ArrayBuffer	-	HMAC value	When an error occurs, an exception is raised.

secure.freeHmac()

Releases HMAC operation resources.
This method is used to abort the HMAC operation before calling secure.hmacDigest().

Name	Type	M/O	Summary	Note
return	undefined	-	-

secure.startSha256(data)

Starts SHA-256 hash operation.
Hash operation resources are allocated and methods related to Hash operations are allowed.
Note that it is not possible to have multiple operation resources at the same time.
When restarting, execute secure.finishSha256() to release the operation resources once.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	optional	The data stream to operate on This argument can be specified as a string or binary.
return	undefined	-	-	When an error occurs, an exception is raised.

secure.updateSha256(data)

Adds a data stream for SHA-256 hash operation.
This method can be called continuously.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	optional	The data stream to operate on This argument can be specified as a string or binary.
return	undefined	-	-	When an error occurs, an exception is raised.

secure.finishSha256(data)

Outputs the SHA-256 hash value in binary.
At the same time, hash operation resources are released.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	optional	The data stream to operate on This argument can be specified as a string or binary.
return	ArrayBuffer	-	SHA-256 hash value	When an error occurs, an exception is raised.

secure.base64Encode(data)

Performs Base64 encoding on the given data.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	The data to encode This argument can be specified as a string or binary.
return	string	-	Encoded data	When an error occurs, an exception is raised. If you run out of dynamic memory, reduce the amount of data.

secure.base64Decode(data)

Performs Base64 decoding on the given data. The output is in binary.

Name	Type	M/O	Summary	Note
data	string	mandatory	Encoded data This argument can only be specified string.
return	ArrayBuffer	-	Decoded data	When an error occurs, an exception is raised. If you run out of dynamic memory, reduce the amount of data.

secure.genKey(type[,length])

Creates a key pair for asymmetric encryption.
The created private key is stored in a temporary internal RAM and updated each time this method is executed.
This private key is retained while the script is running, but is destroyed when the script is reloaded, when the system is reset, or when the system enters standby mode.

Name	Type	M/O	Summary	Note
type	string	mandatory	Encryption method name Specify the name of the encryption method to be used. The following encryption methods are supported: 'rsa'
length	number	optional	Key length Range: 1024 - 2048 The default value is 1024.
return	string	-	Public key (PEM format)	When an error occurs, an exception is raised.

secure.encPK(pubKey,data)

Encrypts data using the specified public key.

Name	Type	M/O	Summary	Note
pubKey	string	mandatory	Specified public key (PEM format)	Only RSA (PKCS #1 v2.1 RSAES-OAEP SHA-256) is supported.
data	string	mandatory	Plain data This argument can only be specified string. Range: Key length/8-64-2 (*1)	*1: When key length = 1024, 1024 / 8 - 64 - 2 = 62
return	ArrayBuffer	-	Encrypted data	When an error occurs, an exception is raised.

secure.decPK(encData)

Uses the private key generated with secure.genKey() to decrypt the data.

Name	Type	M/O	Summary	Note
encData	ArrayBuffer	mandatory	Encrypted data	Only RSA (PKCS #1 v2.1 RSAES-OAEP SHA-256) is supported.
return	string	-	Decrypted data	When an error occurs, an exception is raised.

secure.setSign(algo)

Sets up signature operation/verification.
Signature operation/verification resources are allocated and methods related to signature operation/verification are allowed.
Note that it is not possible to have multiple operation resources at the same time.
When setting up again, execute secure.signDigest(), secure.verifyDigest() or secure.freeSign() to release the operation resources once.

Name	Type	M/O	Summary	Note
algo	string	mandatory	Algorithm name Specify the name of the algorithm to be used. The following hash algorithms are supported: 'sha256'
return	undefined	-	-	When an error occurs, an exception is raised.

secure.signUpdate(message)

Adds the data stream for signature operation/verification.
This method can be called continuously.

Name	Type	M/O	Summary	Note
message	string	mandatory	The data stream to operate/verify on This argument can only be specified string.
return	undefined	-	-	When an error occurs, an exception is raised.

secure.signDigest([priKey])

Outputs the signature value in binary.
At the same time, signature operation resources are released.

Name	Type	M/O	Summary	Note
priKey	string	optional	Specified private key (PEM format) If omitted, the private key generated by secure.genKey() is used.	Only RSA (Key length: within 2048) is supported.
return	ArrayBuffer	-	Signature value	When an error occurs, an exception is raised.

secure.verifyDigest(pubKey,signature)

Outputs the result of signature verification.
At the same time, signature verification resources are released.

Name	Type	M/O	Summary	Note
pubKey	string	mandatory	Specified public key (PEM format)	Only RSA (Key length: within 2048) is supported.
signature	ArrayBuffer	mandatory	Signature value This argument can only be specified binary.
return	boolean	-	Result of signature verification True if successful.	When an error occurs, an exception is raised.

secure.freeSign()

Releases signature operation/verification resources.
This method is used to abort the signature operation/verification before calling secure.signDigest() or secure.verifyDigest().

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

Object Usage Examples

Sample 1

This is a sample HMAC operation.

var private_key = '12345';
secure.setHmac('sha256', private_key);
var payload = 'Hello World!';
secure.hmacUpdate(payload);
var digest_bin = secure.hmacDigest();

Sample 2

This is a sample of the Sha-256 hash operation.

var inputData = ['abcde', 'fghijk', 'lmnopqr', 'stuvwxyz' ];
secure.startSha256();
for (var i = 0; i < inputData.length; i++){
  secure.updateSha256(inputData[i]);
}
var hashBin = secure.finishSha256();

Sample 3

This is a sample of Base64 encoding and decoding.

var orgStr = 'abcde';
var b64Str;

ab2string = function(ab) {
  var str = String.fromCharCode.apply(null, new Uint8Array(ab));
  return str;
}

b64Str = secure.base64Encode(orgStr);
print('base64 encode:' + b64Str);

var dec_bin;
decBin = secure.base64Decode(b64Str);
print(ab2string(decBin));

Sample 4

This is a sample of Base64URL encoding.

var b64Str = secure.base64Encode(targetData).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");

Sample 5

This is a sample RSA key pair creation, encryption and decryption.

var key_size = 1024;
var public_key;
public_key = secure.genKey('rsa', key_size);
print('public_key:' + public_key);

var plan_data = '......';//<=1024/8 - 64 -2
var enc_data = secure.encPK(public_key, plan_data);
var dec_data = secure.decPK(enc_data);
print('dec_data:' + dec_data);

Sample 6

This is a sample RSA key pair creation, signature operation and verification.

var message = 'Hello World!!!';
var key_size = 1024;
var public_key;
var signature;
//key-pair
public_key = secure.genKey('rsa', key_size);
//sign
secure.setSign('sha256');
secure.signUpdate(message);
signature = secure.signDigest();//->genKey()
//verify
var verify_result;
secure.setSign('sha256');
secure.signUpdate(message);
verify_result = secure.verifyDigest(public_key, signature);

print('result:' + verify_result);

---

Updated: 2020-06-04