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. | ||
| secure.hmacUpdate() | Adds a data stream for HMAC operation. | ||
| secure.hmacDigest() | Outputs the HMAC value. | ||
| secure.freeHmac() | Releases HMAC operation resources. | ||
| secure.startSha256() | Starts SHA-256 hash operation. | ||
| secure.updateSha256() | Adds a data stream for SHA-256 hash operation. | ||
| secure.finishSha256() | Outputs the SHA-256 hash value. | ||
| secure.base64Encode() | Performs Base64 encoding on the given data. | ||
| secure.base64Decode() | Performs Base64 decoding on the given data. | ||
| secure.genKey() | Creates a key pair for asymmetric encryption. | ||
| secure.encPK() | Encrypts data using the specified public key. | ||
| secure.decPK() | Decrypts data using the specified private key. | ||
| secure.setSign() | Sets up Signature operation/verification. | ||
| secure.signUpdate() | Adds a data stream for signature operation/verification. | ||
| secure.signDigest() | Outputs the signature value. | ||
| secure.verifyDigest() | Outputs the result of signature verification. | ||
| secure.freeSign() | Releases signature operation/verification resources. |
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);