AmazonKMS Class

Properties   Methods   Events   Config Settings   Errors  

The AmazonKMS class provides an easy-to-use interface for Amazon's Key Management Service.

Syntax

cloudkeys.amazonkms()

Remarks

The AmazonKMS class makes it easy to work with the Amazon Key Management Service (KMS) in a secure manner using TLS. Amazon KMS allows you to create, manage, and use KMS keys for cryptographic operations. You can also work with aliases, and generate data keys and data key pairs.

To begin, register for an AWS account and obtain an AccessKey and SecretKey to use for authentication. Once one or more KMS keys have been created, either via the AWS console (recommended) or this API, you'll be ready to start using the class to manage and use the KMS keys.

Resource Terminology

As implied above, there are three kinds of resources associated with Amazon KMS. The primary resource type is the AWS KMS key, or "KMS key". KMS keys can be symmetric or asymmetric, and can be used either for encryption and decryption, or signing and verification. KMS keys themselves can never leave the Amazon cloud, they are used for server-side cryptographic operations only. This is a security feature, but it does mean that the amount of data that can be processed in a KMS key-based cryptographic operation is relatively small.

To work around the small server-side cryptographic operation data limit, Amazon KMS also supports the generation of data keys (symmetric) and data key pairs (asymmetric), which can then be used outside of Amazon KMS in order to encrypt/decrypt and sign/verify larger amounts data. KMS itself only generates these keys, it does not track them or make use of them for cryptographic operations. However, it does encrypt the data key (or, for data key pairs, the private key) using a KMS key when it is generated, which means that the key must be decrypted using a KMS key each time it needs to be used. For more information, refer to Amazon's Envelope Encryption description, which details the many security benefits of this strategy.

The last resource is called an alias. Aliases provide friendly names for KMS keys, which can otherwise only be identified by their Id or Amazon resource name (ARN). Since an alias is a standalone resource, it can be created and deleted without affecting the KMS key it refers to. It can also be updated to refer to a different KMS key at any time.

Note: KMS keys and aliases are region-specific resources. That is, KMS keys and aliases cannot be accessed or used outside of the region that they reside in.

Using the Class

KMS keys can be created using the CreateKey method. A KMS key's key spec (i.e., whether it is symmetric or asymmetric, and in the latter case, what kind of asymmetric) and usage (i.e., whether it is for encryption/decryption or signing/verification) must be set at the time of creation, and they cannot be changed later. A description of the KMS key can also be provided when it is created, and can be changed at any time using the UpdateKeyDescription method.

When a KMS key will no longer be used, it can be scheduled for deletion using the ScheduleKeyDeletion method. AWS requires that KMS keys remain in a "pending deletion" state for at least seven days to help ensure that they are truly no longer needed. If at any time during the waiting period it is discovered that the KMS key is still needed, the deletion can be canceled using the CancelKeyDeletion method (KMS keys cannot be used while they are pending deletion). // The CreateKey method returns the Amazon resource name of the newly-created KMS key. string keyArn = kms.CreateKey("SYMMETRIC_DEFAULT", false, "Test key"); // ... Some time later ... // Schedules the KMS key for deletion in 15 days. kms.ScheduleKeyDeletion(keyArn, 15);

Aliases can be created and deleted using the CreateAlias and DeleteAlias methods. Also, while aliases can be updated to refer to a different KMS key at any time during their lifetime. Note that all alias names must begin with the prefix alias/ (but cannot begin with alias/aws/, which is a reserved prefix). kms.CreateAlias("alias/MyTestKey", keyArn); kms.UpdateAlias("alias/MyTestKey", otherKeyArn); kms.DeleteAlias("alias/MyTestKey"); // Only deletes the alias; the KMS key it refers to is unaffected.

To list KMS keys or aliases, use the ListKeys and ListAliases methods. For the former, the IncludeKeyDetails property can optionally be enabled to have the class attempt to retrieve the full information for each KMS key (Amazon only returns the KMS key's ARN and Id while listing). // If there are many KMS keys to list, there may be multiple pages of results. This will // cause all pages of results to be accumulated into the Keys collection property. do { kms.ListKeys(); } while (!string.IsNullOrEmpty(kms.KeyMarker)); foreach (AWSKey key in kms.Keys) { Console.WriteLine(key.ARN); }

Depending on a KMS key's usage, it can be used to perform different cryptographic operations. KMS keys with encryption/decryption usage can be used in Encrypt, Decrypt, and ReEncrypt operations. KMS keys with sign/verify usage can be used in Sign and Verify operations. To perform a cryptographic operation, use InputData or InputFile to supply the input data that should be processed. All operations will output the result data to OutputData or OutputFile (except Verify; refer to its documentation for more information). // Create an asymmetric KMS key with encrypt/decrypt usage. string keyArn = kms.CreateKey("RSA_4096", false, "Encryption Key #237"); // Encrypt the string "Test123" and write the encrypted data to an output file. kms.InputData = "Test123"; kms.OutputFile = "C:/temp/enc.dat"; kms.Encrypt(keyArn, "RSAES_OAEP_SHA_256"); // ...Later, decrypt the data again. kms.InputFile = "C:/temp/enc.dat"; kms.OutputFile = ""; // So that the data will be output to the OutputData property. kms.Decrypt(keyArn, "RSAES_OAEP_SHA_256");

It's important to note that the amount of data that can be processed in server-side cryptographic operations is very small. For signing operations, it is limited to 4096 bytes; for encryption operations, the limit varies based on the selected KMS key's key spec and the selected encryption algorithm (see the Encrypt method's documentation for more information).

To work around this issue, Amazon KMS supports the generation of data keys and data key pairs (described above) which can be used locally to encrypt/decrypt or sign/verify large amounts of data. To generate a data key or a data key pair, call the GenerateDataKey and GenerateDataKeyPair methods. // Generates a data key, including a plaintext copy. // The encrypted copy is encrypted by the specified KMS key. kms.GenerateDataKey("AES_256", keyArn, true); // The resulting information is stored in the following properties: // kms.KeyData.ARN: The ARN of the KMS key used to encrypt the data key. // kms.KeyData.EncryptedKey: The encrypted copy of the data key. // kms.KeyData.KeySpec: The spec of the generated data key. // kms.KeyData.PlaintextKey: The plaintext copy of the data key (if it was requested). // Generates a data key pair, including plaintext copy. // The encrypted copy of the private key is encrypted by the specified KMS key. kms.GenerateDataKeyPair("ECC_NIST_P384", keyArn, true); // The resulting information is stored in the following properties: // kms.KeyData.ARN: The ARN of the KMS key used to encrypt the data key pair's private key. // kms.KeyData.EncryptedKey: The encrypted copy of the private key. // kms.KeyData.KeySpec: The spec of the generated data key pair. // kms.KeyData.PlaintextKey: The plaintext copy of the private key (if it was requested). // kms.KeyData.PublicKey: The data key pair's public key.

The class also supports a variety of other functionality, including:

• Retrieval of an asymmetric KMS key's public key with GetPublicKey.
• Enabling and disabling KMS keys with SetKeyEnabled.
• Automatic rotation of KMS keys with GetKeyRotationStatus and SetKeyRotationStatus.
• Encryption contexts for Encrypt, Decrypt, and ReEncrypt.
• And more!

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

AmazonKMS.AccessKey Property

The access key to use for authentication.

Syntax

getAccessKey(): string;
setAccessKey(accessKey: string): void;

Default Value

""

Remarks

This property specifies the access key that should be used for authentication. Both this property and SecretKey must be set before attempting any operations which connect to the server.

AmazonKMS.Aliases Property

A collection of aliases.

Syntax

getAliases(): AWSAliasList;

Default Value

Remarks

This collection holds a list of AWSAlias items.

Calling ListAliases will populate this collection.

This property is read-only and not available at design time.

AmazonKMS.AliasMarker Property

A marker indicating what page of aliases to return next.

Syntax

getAliasMarker(): string;
setAliasMarker(aliasMarker: string): void;

Default Value

""

Remarks

This property will be populated when ListAliases is called if the results are pages and there are more pages. To list all aliases, continue to call ListAliases until this property returns empty string.

Refer to ListAliases for more information.

This property is not available at design time.

AmazonKMS.EncryptionContext Property

A collection of encryption context items.

Syntax

getEncryptionContext(): AWSContextItemList;
setEncryptionContext(encryptionContext: AWSContextItemList): void;

Default Value

Remarks

This collection holds a list of AWSContextItem items.

Calling AddEncryptionContextItem will populate this collection. The items in this collection are used when Encrypt, Decrypt, GenerateDataKey, or GenerateDataKeyPair is called.

This property is not available at design time.

AmazonKMS.Firewall Property

A set of properties related to firewall access.

Syntax

getFirewall(): Firewall;
setFirewall(firewall: Firewall): void;

Default Value

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the class will attempt to connect.

AmazonKMS.Idle Property

The current status of the class.

Syntax

isIdle(): boolean;

Default Value

TRUE

Remarks

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

This property is read-only.

AmazonKMS.IncludeKeyDetails Property

Whether to attempt to retrieve full details when listing KMS keys.

Syntax

isIncludeKeyDetails(): boolean;
setIncludeKeyDetails(includeKeyDetails: boolean): void;

Default Value

FALSE

Remarks

This property specifies whether the class should make additional requests when ListKeys is called in order to retrieve full information for each KMS key. By default, Amazon will only return the KeysARN and KeysId of each KMS key.

If this property is enabled, then after the initial listing is returned, the class will call GetKeyInfo internally for each KMS key returned. For all KMS keys for which this call is successful, the additional information will be used to populate the Key* properties. Any KMS keys for which the GetKeyInfo call fails will only have their KeysARN and KeysId properties populated, as usual.

This property is not available at design time.

AmazonKMS.InputData Property

The data to process.

Syntax

getInputData(): Uint8Array;
setInputData(inputData: Uint8Array): void;

Default Value

""

Remarks

This property specifies the data that should be processed in a cryptographic operation.

Input Sources & Output Destinations

The class automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. The InputFile property
2. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. The OutputFile property
2. The OutputData property

This property is not available at design time.

AmazonKMS.InputFile Property

The file whose data should be processed.

Syntax

getInputFile(): string;
setInputFile(inputFile: string): void;

Default Value

""

Remarks

This property specifies the file whose data should be processed in a cryptographic operation. It accepts both absolute and relative file paths.

Input Sources & Output Destinations

The class automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. The InputFile property
2. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. The OutputFile property
2. The OutputData property

AmazonKMS.KeyData Property

The downloaded key information.

Syntax

getKeyData(): AWSKeyData;

Default Value

Remarks

This property holds an AWSKeyData object. It may represent any of the following, depending on which method was called:

• When GetPublicKey is called, it will contain the specified KMS key's public key, plus additional information about it.
• When GenerateDataKey is called, it will contain the data key and information about it.
• When GenerateDataKeyPair is called, it will contain the data key pair and information about it.

This property is read-only and not available at design time.

AmazonKMS.KeyMarker Property

A marker indicating what page of KMS keys to return next.

Syntax

getKeyMarker(): string;
setKeyMarker(keyMarker: string): void;

Default Value

""

Remarks

This property will be populated when ListKeys is called if the results are paged and there are more pages. To list all KMS keys, continue to call ListKeys until this property returns empty string.

Refer to ListKeys for more information.

This property is not available at design time.

AmazonKMS.Keys Property

A collection of keys.

Syntax

getKeys(): AWSKeyList;

Default Value

Remarks

This collection holds a list of AWSKey items.

Calling ListKeys will populate this collection.

This property is read-only and not available at design time.

AmazonKMS.LocalHost Property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

getLocalHost(): string;
setLocalHost(localHost: string): void;

Default Value

""

Remarks

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

AmazonKMS.OtherHeaders Property

This property includes other headers as determined by the user (optional).

Syntax

getOtherHeaders(): string;
setOtherHeaders(otherHeaders: string): void;

Default Value

""

Remarks

This property can be set to a string of headers to be appended to the HTTP request headers created from other properties like ContentType and From.

The headers must follow the format Header: Value as described in the HTTP specifications. Header lines should be separated by .

Use this property with caution. If this property contains invalid headers, HTTP requests may fail.

This property is useful for extending the functionality of the class beyond what is provided.

This property is not available at design time.

AmazonKMS.OutputData Property

The output data.

Syntax

getOutputData(): Uint8Array;
setOutputData(outputData: Uint8Array): void;

Default Value

""

Remarks

This property is populated with the data that was output from a successful cryptographic operation.

Note: For the Verify operation, this property functions as a secondary input property instead (along with InputData); refer to the Verify method for more information.

Input Sources & Output Destinations

The class automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. The InputFile property
2. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. The OutputFile property
2. The OutputData property

This property is not available at design time.

AmazonKMS.OutputFile Property

The file to which output data should be written.

Syntax

getOutputFile(): string;
setOutputFile(outputFile: string): void;

Default Value

""

Remarks

This property specifies the file to which data output from a successful cryptographic operation should be written.

Note: For the Verify operation, the specified file functions as a secondary input file instead (along with InputFile); refer to the Verify method for more information.

Input Sources & Output Destinations

The class automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. The InputFile property
2. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. The OutputFile property
2. The OutputData property

AmazonKMS.Overwrite Property

Whether the output file should be overwritten if necessary.

Syntax

isOverwrite(): boolean;
setOverwrite(overwrite: boolean): void;

Default Value

FALSE

Remarks

This property controls whether the specified OutputFile should be overwritten if it already exists.

AmazonKMS.ParsedHeaders Property

This property includes a collection of headers returned from the last request.

Syntax

getParsedHeaders(): HeaderList;

Default Value

Remarks

This property contains a collection of headers returned from the last request. Whenever headers are returned from the server, the headers are parsed into a collection of headers. Each Header in this collection contains information describing that header.

MaxHeaders can be used to control the maximum number of headers saved.

This property is read-only and not available at design time.

AmazonKMS.Proxy Property

This property includes a set of properties related to proxy access.

Syntax

getProxy(): Proxy;
setProxy(proxy: Proxy): void;

Default Value

Remarks

This property contains fields describing the proxy through which the class will attempt to connect.

AmazonKMS.QueryParams Property

Additional query parameters to be included in the request.

Syntax

getQueryParams(): QueryParamList;
setQueryParams(queryParams: QueryParamList): void;

Default Value

Remarks

This is a collection of query parameters that will be added to the request. Parameters can be added via the AddQueryParam method.

AmazonKMS.Region Property

The region that the class will make requests against.

Syntax

getRegion(): string;
setRegion(region: string): void;

Default Value

"us-east-1"

Remarks

This property controls which region the class will make requests against. By default the class uses us-east-1, the US East (N. Virginia) region. This property should be changed in order to create or access resources in other regions, as KMS keys and aliases are region-specific resources.

Regions:

The class will always convert this property's value to lowercase. If this property is cleared, the class will reset it to the default value.

AmazonKMS.SecretKey Property

The secret key to use for authentication.

Syntax

getSecretKey(): string;
setSecretKey(secretKey: string): void;

Default Value

""

Remarks

This property specifies the secret key that should be used for authentication. Both this property and AccessKey must be set before attempting any operations which connect to the server.

AmazonKMS.SSLAcceptServerCert Property

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

getSSLAcceptServerCert(): Certificate;
setSSLAcceptServerCert(SSLAcceptServerCert: Certificate): void;

Default Value

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

AmazonKMS.SSLCert Property

The certificate to be used during SSL negotiation.

Syntax

getSSLCert(): Certificate;
setSSLCert(SSLCert: Certificate): void;

Default Value

Remarks

The digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the field to the encoded certificate. To select a certificate, use the store and subject fields.

AmazonKMS.SSLProvider Property

This specifies the SSL/TLS implementation to use.

Syntax

getSSLProvider(): AmazonkmsSSLProviders;
setSSLProvider(SSLProvider: AmazonkmsSSLProviders): void;

enum AmazonkmsSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected the platform implementation will be used by default in all cases in the JavaScript edition.

Note: The Internal provider is not support at this time.

AmazonKMS.SSLServerCert Property

The server certificate for the last established connection.

Syntax

getSSLServerCert(): Certificate;

Default Value

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

AmazonKMS.Timeout Property

A timeout for the class.

Syntax

getTimeout(): number;
setTimeout(timeout: number): void;

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the class .

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

AmazonKMS.addEncryptionContextItem Method

Adds an item to the EncryptionContext properties.

Syntax

async amazonkms.addEncryptionContextItem(name : string, value : string): Promise<void>

Remarks

This method adds an item to the EncryptionContext* properties. Name specifies the name of the item, and Value specifies the value of the item.

AmazonKMS.addQueryParam Method

Adds a query parameter to the QueryParams properties.

Syntax

async amazonkms.addQueryParam(name : string, value : string): Promise<void>

Remarks

This method is used to add a query parameter to the QueryaParam* properties. Name specifies the name of the parameter, and Value specifies the value of the parameter.

All specified Values will be URL encoded by the class automatically. Consult the service documentation for details on the available parameters.

AmazonKMS.cancelKeyDeletion Method

Cancels the deletion of the specified KMS key.

Syntax

async amazonkms.cancelKeyDeletion(keyId : string): Promise<void>

Remarks

This method cancels the deletion of the KMS key specified by KeyId. Refer to the ScheduleKeyDeletion method for more information.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key in the current account and Region.

AmazonKMS.clearKeyData Method

Clears information stored in the KeyData properties.

Syntax

async amazonkms.clearKeyData(plaintextOnly : boolean): Promise<void>

Remarks

This method clears the information stored in the KeyData* properties, removing it from memory. If the PlaintextOnly parameter is true, only the KeyDataPlaintextKey property is cleared.

AmazonKMS.config Method

Sets or retrieves a configuration setting.

Syntax

async amazonkms.config(configurationString : string): Promise<string>

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

AmazonKMS.createAlias Method

Creates a new alias.

Syntax

async amazonkms.createAlias(name : string, keyId : string): Promise<void>

Remarks

This method creates a new alias with the given Name and associates it with the KMS key specified by KeyId.

The value passed for Name must begin with alias/, and must consist solely of alphanumeric characters, forward slashes /, underscores _, and hyphens -. The final name must not begin with alias/aws/, which is a reserved prefix.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key in the current account and Region.

AmazonKMS.createKey Method

Creates a new KMS key.

Syntax

async amazonkms.createKey(keySpec : string, forSigning : boolean, description : string): Promise<string>

Remarks

This method creates a new KMS key of the specified KeySpec, and returns its Amazon resource name (ARN). The new KMS key's Id is the last part of the returned ARN; for example, if the ARN is arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab, then the KMS key's Id is 1234abcd-12ab-34cd-56ef-1234567890ab.

The KeySpec parameter specifies the type of KMS key that should be created. To create a symmetric key, pass SYMMETRIC_DEFAULT (or empty string); this will create a key using a symmetric algorithm based on AES-256-GCM. To create an asymmetric key, pass one of the following strings instead:

• RSA_2048
• RSA_3072
• RSA_4096
• ECC_NIST_P256 (secp256r1)
• ECC_NIST_P384 (secp384r1)
• ECC_NIST_P521 (secp521r1)
• ECC_SECG_P256K1 (secp256k1)

The ForSigning parameter specifies whether the new KMS key should be for encryption and decryption (false) or signing and verification (true). However, this is only applicable for RSA key specs; symmetric keys are always for encryption/decryption, and elliptic curve key specs are always for signing/verification, so this parameter is ignored if one of those specs is passed for KeySpec.

The Description parameter specifies the KMS key's description. This description can be changed at any time using the UpdateKeyDescription method.

To create the KMS key in a custom key store, set the CustomKeyStoreId configuration setting before calling this method. To set the KMS key's key policy, set the CreateKeyPolicy configuration setting before calling this method. Refer to these configuration settings for more information.

AmazonKMS.decrypt Method

Decrypts data using a KMS key.

Syntax

async amazonkms.decrypt(keyId : string, algorithm : string): Promise<void>

Remarks

This method decrypts data using the KMS key specified by KeyId and the given Algorithm. The data to decrypt is taken from the the specified InputFile or the InputData property. The decrypted data is output to the the specified OutputFile or the OutputData property.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. If an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place.

The Algorithm parameter specifies which algorithm to use to decrypt the data; it must match the algorithm used to encrypt the data previously. Possible values vary depending on the specified KMS key's key spec:

If Algorithm is SYMMETRIC_DEFAULT, the encryption context items in the EncryptionContext* properties will be included in the request. Keep in mind that in order to successfully decrypt the data, the exact same encryption context items that were present when the data was encrypted must be supplied again. Encryption context items are case-sensitive, but not order-sensitive.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is for signing/verification instead of encryption/decryption (see KeysForSigning).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.deleteAlias Method

Deletes an alias.

Syntax

async amazonkms.deleteAlias(aliasName : string): Promise<void>

Remarks

This method deletes the alias with the given AliasName.

The value passed for the AliasName parameter must include the alias/ prefix, and must be the name of an alias in the current account and Region

AmazonKMS.doEvents Method

Processes events from the internal message queue.

Syntax

async amazonkms.doEvents(): Promise<void>

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

AmazonKMS.encrypt Method

Encrypts data using a KMS key.

Syntax

async amazonkms.encrypt(keyId : string, algorithm : string): Promise<void>

Remarks

This method encrypts data using the KMS key specified by KeyId and the given Algorithm. The data to encrypt is taken from the the specified InputFile or the InputData property. The encrypted data is output to the the specified OutputFile or the OutputData property.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. If an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place.

The Algorithm parameter specifies which algorithm to use to encrypt the data. Possible values vary depending on the specified KMS key's key spec. The KMS key's key spec and the selected algorithm together dictate the maximum size of the input data.

If Algorithm is SYMMETRIC_DEFAULT, the encryption context items in the EncryptionContext* properties will be included in the request. Including an encryption context when encrypting data means that the exact same encryption context must be supplied again in order to decrypt the data. Encryption context items are case-sensitive, but not order-sensitive.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is for signing/verification instead of encryption/decryption (see KeysForSigning).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.generateDataKey Method

Generates a data key that can be used outside of Amazon KMS.

Syntax

async amazonkms.generateDataKey(keySpec : string, keyId : string, includePlaintext : boolean): Promise<void>

Remarks

This method generates a data key that can be used outside of Amazon KMS for encryption and decryption. The generated data key will be encrypted using the KMS key specified by KeyId before it is returned. The key and its related information will be downloaded to the following KeyData* properties, refer to their documentation for more information:

• KeyDataARN
• KeyDataEncryptedKey
• KeyDataKeySpec
• KeyDataPlaintextKey (if true is passed for IncludePlaintext)

The KeySpec parameter specifies either the spec of the data key, or the size of the data key in bytes. Valid values are:

• AES_128
• AES_256
• Some number of bytes in the range 1 to 1024 (e.g., 64)

The value passed for the KeyId parameter must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. If an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place. The specified KMS key must be symmetric. Any encryption context items present in the EncryptionContext* properties will be included in the request and used when encrypting the data key; they must be supplied again in order to decrypt it.

The IncludePlaintext parameter specifies whether the server should return a plaintext (i.e., unencrypted) copy of the data key in addition to the encrypted copy. This can be useful if the data key will be used immediately.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is asymmetric (see KeysKeySpec).
• It is for signing/verification instead of encryption/decryption (see KeysForSigning).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.generateDataKeyPair Method

Generates a data key pair that can be used outside of Amazon KMS.

Syntax

async amazonkms.generateDataKeyPair(keyPairSpec : string, keyId : string, includePlaintext : boolean): Promise<void>

Remarks

This method generates a data key pair that can be used outside of Amazon KMS for encryption and decryption, or signing and verification. The private key of the generated key pair will be encrypted using the KMS key specified by KeyId before it is returned. The key and its related information will be downloaded to the following KeyData* properties, refer to their documentation for more information:

• KeyDataARN
• KeyDataEncryptedKey
• KeyDataKeySpec
• KeyDataPlaintextKey (if true is passed for IncludePlaintext)
• KeyDataPublicKey

The KeySpec parameter specifies the spec of the data key pair. Valid values are:

• RSA_2048
• RSA_3072
• RSA_4096
• ECC_NIST_P256 (secp256r1)
• ECC_NIST_P384 (secp384r1)
• ECC_NIST_P521 (secp521r1)
• ECC_SECG_P256K1 (secp256k1)

The value passed for the KeyId parameter must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. If an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place. The specified KMS key must be symmetric. Any encryption context items present in the EncryptionContext* properties will be included in the request and used when encrypting the private key; they must be supplied again in order to decrypt it.

The IncludePlaintext parameter specifies whether the server should return a plaintext (i.e., unencrypted) copy of the data key pair's private key in addition to the encrypted copy. This can be useful if the private key will be used immediately.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is asymmetric (see KeysKeySpec).
• It is for signing/verification instead of encryption/decryption (see KeysForSigning).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.generateRandomBytes Method

Generates a cryptographically-secure random byte string.

Syntax

async amazonkms.generateRandomBytes(numBytes : number): Promise<void>

Remarks

This method uses Amazon KMS to generate a cryptographically-secure random byte string of the specified length (measured in bytes). The random bytes are output to the the OutputFile or the OutputData property.

The value passed for NumBytes must be in the range 1 to 1024.

AmazonKMS.getKeyInfo Method

Gets information about a KMS key.

Syntax

async amazonkms.getKeyInfo(keyId : string): Promise<void>

Remarks

This method gets information about the KMS key specified by KeyId. When the information is returned, the class clears the Key* properties and repopulates them with a single item that contains the KMS key's information. The KeyList event is also fired.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. If an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place.

AmazonKMS.getKeyRotationStatus Method

Retrieves the key rotation status for a KMS key.

Syntax

async amazonkms.getKeyRotationStatus(keyId : string): Promise<boolean>

Remarks

This method retrieves the key rotation status for the KMS key specified by KeyId; it will return true if the KMS key's key material is set to be automatically rotated, or false if not.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key in the current Region. If an ARN is provided, it can be for a KMS key in another account so long as the appropriate permissions are in place.

This method will always return false for asymmetric KMS keys, KMS keys with imported key material, and KMS keys that reside in a custom key store, as such KMS keys do not support automatic key rotation. This method will also return false if the server returns an error for any other reason.

AmazonKMS.getPublicKey Method

Retrieves the public key of an asymmetric KMS key.

Syntax

async amazonkms.getPublicKey(keyId : string): Promise<void>

Remarks

This method retrieves the public key of the asymmetric KMS key specified by KeyId. The public key and its related information will be downloaded to the following KeyData* properties, refer to their documentation for more information:

• KeyDataAlgorithms
• KeyDataARN
• KeyDataForSigning
• KeyDataKeySpec
• KeyDataPublicKey

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is symmetric (see KeysKeySpec).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.listAliases Method

Lists aliases in the current account and region.

Syntax

async amazonkms.listAliases(forKeyId : string): Promise<void>

Remarks

This method lists the aliases in the current account and Region. Optionally, aliases for a specific KMS key (in the current account and Region) can be listed by passing its Id or ARN for the ForKeyId parameter.

Calling this method will fire the AliasList event once for each alias, and will also populate the Alias* properties.

If there are still more aliases available to list when this method returns, the AliasMarker property will be populated. Continue to call this method until AliasMarker is empty to accumulate all pages of results in the Alias* properties.

The MaxAliases configuration setting can be used to control the maximum number of results to return at once.

AmazonKMS.listKeys Method

Lists KMS keys in the current account and region.

Syntax

async amazonkms.listKeys(): Promise<void>

Remarks

This method lists the KMS keys in the current account and Region.

Calling this method will fire the KeyList event once for each KMS key, and will also populate the Key* properties. However, note that by default only the KeysARN and KeysId properties will be populated, since the server does not return full information for KMS keys when listing them. The IncludeKeyDetails property can be enabled to have the class attempt to retrieve full information for each KMS key; refer to its documentation for more information.

If there are still more KMS keys available to list when this method returns, the KeyMarker property will be populated. Continue to call this method until KeyMarker is empty to accumulate all pages of results in the Key* properties.

The MaxKeys configuration setting can be used to control the maximum number of results to return at once.

AmazonKMS.reEncrypt Method

Decrypts data using one KMS key and re-encrypts it using another KMS key.

Syntax

async amazonkms.reEncrypt(oldKeyId : string, oldAlgorithm : string, newKeyId : string, newAlgorithm : string): Promise<void>

Remarks

This method decrypts data using the KMS key specified by OldKeyId and re-encrypts it using the KMS key specified by NewKeyId. This process happens completely on the server; at no point is the unencrypted data transferred over the wire.

The encrypted data is taken from the the specified InputFile or the InputData property. The re-encrypted data is output to the the specified OutputFile or the OutputData property.

The values passed for the OldKeyId and NewKeyId parameters must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. For either or both parameters, if an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place.

The OldAlgorithm and NewAlgorithm parameters specify the encryption algorithm currently in use, and the new encryption algorithm, respectively. Valid values vary depending on the old and new KMS keys key specs:

If OldAlgorithm is SYMMETRIC_DEFAULT, the encryption context items in the EncryptionContext* properties will be included in the request for use with decryption. Keep in mind that in order to successfully decrypt the data, the exact same encryption context items that were present when the data was encrypted must be supplied again. Encryption context items are case-sensitive, but not order-sensitive.

If NewAlgorithm is SYMMETRIC_DEFAULT, the encryption context items in the EncryptionContext* properties will also be included in the request for use with re-encryption, effectively causing the encryption context to be transferred to the re-encrypted data. Alternatively, the NewEncryptionContext configuration setting can be set before calling this method in order to supply a new encryption context (or, if set to {}, to "remove" the existing one).

This method will fail if any of the following are true regarding either of the specified KMS keys:

• Its KeysState is anything other than aksEnabled (0).
• It is for signing/verification instead of encryption/decryption (see KeysForSigning).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.reset Method

Resets the class to its initial state.

Syntax

async amazonkms.reset(): Promise<void>

Remarks

This method resets the class to its initial state.

AmazonKMS.scheduleKeyDeletion Method

Schedules the deletion of a KMS key.

Syntax

async amazonkms.scheduleKeyDeletion(keyId : string, daysToWait : number): Promise<void>

Remarks

This method schedules the deletion of the KMS key specified by KeyId. The DaysToWait parameter specifies the length of the waiting period; it must be a value between 7 and 30.

When a KMS key is scheduled for deletion, it cannot be used. This is a safety feature designed to help identify any code that still relies on the KMS key.

AmazonKMS.sendCustomRequest Method

Sends a custom request to the server.

Syntax

async amazonkms.sendCustomRequest(action : string): Promise<void>

Remarks

This method can be used to send arbitrary requests to the server. The value passed for the Action parameter must be one of the actions described in the Amazon KMS documentation.

When this method is called, the class does the following:

1. Builds a request URL, including query parameters, based on the following:
   • Region
   • QueryParam*
2. Adds request headers from OtherHeaders.
3. Adds any request body supplied via the specified InputFile or InputData.
4. Signs the request.
5. Sends the request to the server.
6. Stores the response headers in the ParsedHeader* properties; and the response body in the specified OutputFile or OutputData.

If the response body is JSON data, the XPath, XText, and other X* configuration settings can then be used to navigate and extract information from it.

AmazonKMS.setKeyEnabled Method

Enables or disables a KMS key.

Syntax

async amazonkms.setKeyEnabled(keyId : string, enabled : boolean): Promise<void>

Remarks

This method enables or disables the KMS key specified by KeyId.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key in the current account and Region.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is aksPendingDeletion (2) or aksPendingImport (3).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.setKeyRotationStatus Method

Enables or disables automatic key rotation for a KMS key.

Syntax

async amazonkms.setKeyRotationStatus(keyId : string, enabled : boolean): Promise<void>

Remarks

This method enables or disables automatic key material rotation for the KMS key specified by KeyId.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key in the current account and Region.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is asymmetric (see KeysKeySpec).
• It has imported key material (see KeysOrigin).
• It resides in a custom key store (see KeysCustomKeyStoreId).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.sign Method

Signs a message using a KMS key.

Syntax

async amazonkms.sign(keyId : string, algorithm : string, isDigest : boolean): Promise<void>

Remarks

This method signs a message using the KMS key specified by KeyId and the given Algorithm. The message data to sign is taken from the the specified InputFile or the InputData property. The signature data is output to the the specified OutputFile or the OutputData property.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. If an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place.

The Algorithm parameter specifies which algorithm to use to sign the data. Possible values are:

• RSASSA_PSS_SHA_256
• RSASSA_PSS_SHA_384
• RSASSA_PSS_SHA_512
• RSASSA_PKCS1_V1_5_SHA_256
• RSASSA_PKCS1_V1_5_SHA_384
• RSASSA_PKCS1_V1_5_SHA_512
• ECDSA_SHA_256
• ECDSA_SHA_384
• ECDSA_SHA_512

The IsDigest parameter specifies whether the message data is the original message (false) or a message digest (true). When supplying a message digest, keep in mind that the same digest will need to be provided in order to Verify the signature later.

Note that a maximum of 4096 bytes of message data can be sent to the server. If IsDigest is false, and more than 4096 bytes of message data are provided, the class will automatically compute an appropriate message digest and send it instead. In such cases, the computed digest is made available via the MessageDigest configuration setting.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is symmetric (see KeysKeySpec).
• It is for encryption/decryption instead of signing/verification (see KeysForSigning).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.updateAlias Method

Updates an alias to refer to a different KMS key.

Syntax

async amazonkms.updateAlias(aliasName : string, newKeyId : string): Promise<void>

Remarks

This method updates the alias named AliasName, changing it so that it refers to the KMS key specified by NewKeyId.

The value passed for the AliasName parameter must include the alias/ prefix, and must be the name of an alias in the current account and Region

The value passed for the NewKeyId parameter must be the Id or ARN of a KMS key in the current account and Region. The specified KMS key must be of the same type (i.e., symmetric or asymmetric) and have the same usage (i.e., encryption/decryption or signing/verification) as the KMS key that the alias currently refers to.

This method will fail if the specified alias is AWS-managed (i.e., its name begins with alias/aws/). This method will also fail if the specified KMS key's state is aksPendingDeletion (2), or if it is AWS-managed (see KeysAWSManaged).

AmazonKMS.updateKeyDescription Method

Updates a KMS key's description.

Syntax

async amazonkms.updateKeyDescription(keyId : string, newDescription : string): Promise<void>

Remarks

This method updates the description of the KMS key specified by KeyId.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key in the current account and Region.

This method will fail if the specified KMS key's state is aksPendingDeletion (2), or if it is AWS-managed (see KeysAWSManaged).

AmazonKMS.verify Method

Verifies a digital signature using a KMS key.

Syntax

async amazonkms.verify(keyId : string, algorithm : string, isDigest : boolean): Promise<boolean>

Remarks

This method verifies a digital signature using the KMS key specified by KeyId and the given Algorithm. The message data is taken from the the specified InputFile or the InputData property. The digital signature data is taken from the specified OutputFile or the OutputData property. If the signature is successfully verified, this method returns true, otherwise it returns false.

The value passed for the KeyId parameter must be the Id or ARN of a KMS key, or the name or ARN of an alias, in the current Region. If an ARN is provided, it can be for a KMS key or alias in another account so long as the appropriate permissions are in place.

The Algorithm parameter specifies which algorithm was used to sign the data. Possible values are:

• RSASSA_PSS_SHA_256
• RSASSA_PSS_SHA_384
• RSASSA_PSS_SHA_512
• RSASSA_PKCS1_V1_5_SHA_256
• RSASSA_PKCS1_V1_5_SHA_384
• RSASSA_PKCS1_V1_5_SHA_512
• ECDSA_SHA_256
• ECDSA_SHA_384
• ECDSA_SHA_512

The IsDigest parameter specifies whether the data whose signature is being verified is the original message (false) or a message digest (true). When a message digest is supplied, keep in mind that it must be the exact same digest that was used at signing time, regardless of whether it has been recomputed.

Note that, as with the Sign method, a maximum of 4096 bytes of message data can be sent to the server. If IsDigest is false, and more than 4096 bytes of message data are provided, the class will automatically compute an appropriate message digest and send it instead. In such cases, the computed digest is made available via the MessageDigest configuration setting.

This method will fail if any of the following are true regarding the specified KMS key:

• Its KeysState is anything other than aksEnabled (0).
• It is symmetric (see KeysKeySpec).
• It is for encryption/decryption instead of signing/verification (see KeysForSigning).
• It is an AWS-managed KMS key (see KeysAWSManaged).

AmazonKMS.AliasList Event

Fires once for each alias when listing aliases.

Syntax

amazonkms.on('AliasList', listener: (e: {readonly ARN: string, readonly name: string, readonly keyId: string}) => void )

Remarks

This event fires once for each alias returned when ListAliases is called.

ARN reflects the Amazon resource name of the alias.

Name reflects the name of the alias, including the alias/ prefix.

KeyId reflects the Id of the KMS key that the alias refers to.

AmazonKMS.EndTransfer Event

This event fires when a document finishes transferring.

Syntax

amazonkms.on('EndTransfer', listener: (e: {readonly direction: number}) => void )

Remarks

The EndTransfer event is fired when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

AmazonKMS.Error Event

Information about errors during data delivery.

Syntax

amazonkms.on('Error', listener: (e: {readonly errorCode: number, readonly description: string}) => void )

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class .

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

AmazonKMS.Header Event

This event is fired every time a header line comes in.

Syntax

amazonkms.on('Header', listener: (e: {readonly field: string, readonly value: string}) => void )

Remarks

The Field parameter contains the name of the HTTP header (which is the same as it is delivered). The Value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the Field parameter contains "" (empty string).

AmazonKMS.KeyList Event

Fires once for each KMS key when listing KMS keys.

Syntax

amazonkms.on('KeyList', listener: (e: {readonly ARN: string, readonly id: string, readonly accountId: string, readonly description: string, readonly enabled: boolean, readonly AWSManaged: boolean, readonly forSigning: boolean, readonly keySpec: string, readonly algorithms: string, readonly state: number, readonly creationDate: string, readonly deletionDate: string}) => void )

Remarks

This event fires once for each KMS key returned when ListKeys or GetKeyInfo is called. However, note that only ARN and Id are populated when ListKeys is called (unless the IncludeKeyDetails property is enabled; refer to its documentation for more information).

ARN reflects the Amazon resource name of the KMS key.

Id reflects the Id of the KMS key.

AccountId reflects the Id of the AWS account that owns the KMS key.

Description reflects the KMS key's description.

Enabled reflects whether the KMS key is currently enabled.

AWSManaged reflects whether the KMS key is AWS-managed (true) or customer-managed (false).

ForSigning reflects whether the KMS key's usage is signing/verification (true) or encryption/decryption (false).

KeySpec reflects the key spec of the KMS key. For symmetric KMS keys, the only possible value is SYMMETRIC_DEFAULT which, according to the Amazon KMS documentation, is based on AES-256-GCM. For asymmetric KMS keys, possible values are:

• RSA_2048
• RSA_3072
• RSA_4096
• ECC_NIST_P256 (secp256r1)
• ECC_NIST_P384 (secp384r1)
• ECC_NIST_P521 (secp521r1)
• ECC_SECG_P256K1 (secp256k1)

Algorithms reflects a comma-separated list of algorithms that the KMS key supports. If KeysForSigning is false, possible values are:

• SYMMETRIC_DEFAULT
• RSAES_OAEP_SHA_1
• RSAES_OAEP_SHA_256

If KeysForSigning is true, possible values are:

• RSASSA_PSS_SHA_256
• RSASSA_PSS_SHA_384
• RSASSA_PSS_SHA_512
• RSASSA_PKCS1_V1_5_SHA_256
• RSASSA_PKCS1_V1_5_SHA_384
• RSASSA_PKCS1_V1_5_SHA_512
• ECDSA_SHA_256
• ECDSA_SHA_384
• ECDSA_SHA_512

State reflects the KMS key's state. Possible values are:

• aksEnabled (0): The KMS key is enabled and ready for use. (Also the default value used when ListKeys is called.)
• aksDisabled (1): The KMS key is disabled and cannot be used until it is enabled again.
• aksPendingDeletion (2): The KMS key is pending deletion and cannot be used unless the deletion is canceled.
• aksPendingImport (3): The KMS key has been created, but external key material has not yet been imported into it, so it cannot be used.
• aksUnavailable (4): The KMS key is currently unavailable because the CloudHSM cluster that contains its key material has been disconnected from Amazon KMS.

CreationDate reflects the creation date of the KMS key, in seconds since the Unix epoch (including fractional seconds).

If the KMS key's state is aksPendingDeletion (2), DeletionDate reflects the deletion date, in seconds since the Unix epoch (including fractional seconds)

AmazonKMS.Log Event

This event fires once for each log message.

Syntax

amazonkms.on('Log', listener: (e: {readonly logLevel: number, readonly message: string, readonly logType: string}) => void )

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

AmazonKMS.SSLServerAuthentication Event

Fired after the server presents its certificate to the client.

Syntax

amazonkms.on('SSLServerAuthentication', listener: (e: {readonly certEncoded: string, readonly certEncodedB: Uint8Array, readonly certSubject: string, readonly certIssuer: string, readonly status: string, accept: boolean}) => void )

Remarks

This event fires with information about the server certificate. The Status property shows why verification failed (otherwise, Status contains the string OK). To manually accept an untrusted certificate, the SSLAcceptAnyServerCert setting must be set to True before initiating the connection.

AmazonKMS.SSLStatus Event

Shows the progress of the secure connection.

Syntax

amazonkms.on('SSLStatus', listener: (e: {readonly message: string}) => void )

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

AmazonKMS.StartTransfer Event

This event fires when a document starts transferring (after the headers).

Syntax

amazonkms.on('StartTransfer', listener: (e: {readonly direction: number}) => void )

Remarks

The StartTransfer event is fired when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

AmazonKMS.Transfer Event

This event is fired while a document transfers (delivers document).

Syntax

amazonkms.on('Transfer', listener: (e: {readonly direction: number, readonly bytesTransferred: number, readonly percentDone: number, readonly text: string, readonly textB: Uint8Array}) => void )

Remarks

The Text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The BytesTransferred parameter contains the number of bytes transferred in this Direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

Note: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

AWSAlias Type

An Amazon KMS alias.

Remarks

This type represents an Amazon KMS alias.

Fields

AWSContextItem Type

An Amazon KMS encryption context item.

Remarks

This type represents an Amazon KMS encryption context item.

Fields

Constructors

public AWSContextItem();

public AWSContextItem(String name, String value);

AWSKey Type

An AWS KMS key.

Remarks

This type represents an AWS KMS key.

Fields

AWSKeyData Type

Key information downloaded from Amazon KMS.

Remarks

This type represents a KMS key's public key, a data key, or a data key pair downloaded from Amazon KMS.

Fields

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

public Certificate();

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

public Certificate(String certificateFile);

Opens CertificateFile and reads out the contents as an X509 public key.

public Certificate(byte[] certificateData);

Parses CertificateData as an X509 public key.

public Certificate(int certStoreType, String store, String storePassword, String subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, String store, String storePassword, String subject, String configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, String store, String storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject, String configurationString);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

Firewall Type

This is the firewall the class will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall and the .

Fields

Constructors

public Firewall();

Header Type

This is an HTTP header as it is received from the server.

Remarks

When a header is received through a Header event, it is parsed into a Header type. This type contains a , and its corresponding .

Fields

Constructors

public Header();

public Header(String field, String value);

Proxy Type

This is the proxy the class will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the and the .

Fields

Constructors

public Proxy();

public Proxy(String server, int port);

public Proxy(String server, int port, String user, String password);

QueryParam Type

A query parameter to send in the request.

Remarks

This type represents a query parameter to send in the request.

Fields

Constructors

public QueryParam();

public QueryParam(String name, String value);

Config Settings (class cloudkeys.amazonkms)

AmazonKMS Config Settings

<firstlevel>
  <one>value</one>
  <two>
    <item>first</item>
    <item>second</item>
  </two>
  <three>value three</three>
</firstlevel>

{
  "firstlevel": {
    "one": "value",
    "two": ["first", "second"],
    "three": "value three"
  }
}

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

Trappable Errors (class cloudkeys.amazonkms)

Common Errors

HTTP Errors

TCPClient Errors

SSL Errors

TCP/IP Errors