AmazonKMS Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

nsoftware.CloudKeys.AmazonKMS

Remarks

The AmazonKMS component 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 component 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 Component

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 component 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, InputFile, or SetInputStream to supply the input data that should be processed. All operations will output the result data to OutputData, OutputFile, or SetOutputStream (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 component 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 component with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

AccessKey Property (AmazonKMS Component)

The access key to use for authentication.

Syntax

• C#
• VB.NET

public string AccessKey { get; set; }

Public Property AccessKey As String

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.

Aliases Property (AmazonKMS Component)

A collection of aliases.

Syntax

• C#
• VB.NET

public AWSAliasList Aliases { get; }

Public ReadOnly Property Aliases As AWSAliasList

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.

AliasMarker Property (AmazonKMS Component)

A marker indicating what page of aliases to return next.

Syntax

• C#
• VB.NET

public string AliasMarker { get; set; }

Public Property AliasMarker As String

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.

EncryptionContext Property (AmazonKMS Component)

A collection of encryption context items.

Syntax

• C#
• VB.NET

public AWSContextItemList EncryptionContext { get; }

Public Property EncryptionContext As AWSContextItemList

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.

Firewall Property (AmazonKMS Component)

A set of properties related to firewall access.

Syntax

• C#
• VB.NET

public Firewall Firewall { get; set; }

Public Property Firewall As Firewall

Remarks

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

Idle Property (AmazonKMS Component)

The current status of the component.

Syntax

• C#
• VB.NET

public bool Idle { get; }

Public ReadOnly Property Idle As Boolean

Default Value

True

Remarks

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

This property is read-only.

IncludeKeyDetails Property (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public bool IncludeKeyDetails { get; set; }

Public Property IncludeKeyDetails As Boolean

Default Value

False

Remarks

This property specifies whether the component 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 ARN and Id of each KMS key.

If this property is enabled, then after the initial listing is returned, the component 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 Keys collection. Any KMS keys for which the GetKeyInfo call fails will only have their ARN and Id fields populated, as usual.

This property is not available at design time.

InputData Property (AmazonKMS Component)

The data to process.

Syntax

• C#
• VB.NET

public string InputData { get; set; }
public byte[] InputDataB { get; set; }

Public Property InputData As String
Public Property InputDataB As Byte()

Default Value

""

Remarks

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

Input Sources & Output Destinations

The component 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. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

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

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

This property is not available at design time.

InputFile Property (AmazonKMS Component)

The file whose data should be processed.

Syntax

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

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.

Setting this property to a non-empty value will discard any stream set using the SetInputStream method. Similarly, passing a non-null value to the aforementioned method will clear this property.

Input Sources & Output Destinations

The component 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. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

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

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

KeyData Property (AmazonKMS Component)

The downloaded key information.

Syntax

• C#
• VB.NET

public AWSKeyData KeyData { get; }

Public ReadOnly Property KeyData As AWSKeyData

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.

KeyMarker Property (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public string KeyMarker { get; set; }

Public Property KeyMarker As String

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.

Keys Property (AmazonKMS Component)

A collection of keys.

Syntax

• C#
• VB.NET

public AWSKeyList Keys { get; }

Public ReadOnly Property Keys As AWSKeyList

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.

LocalHost Property (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public string LocalHost { get; set; }

Public Property LocalHost As String

Default Value

""

Remarks

This 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 multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the component initiate connections (or accept in the case of server components) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the component 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 multihomed 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.

OtherHeaders Property (AmazonKMS Component)

Other headers as determined by the user (optional).

Syntax

• C#
• VB.NET

public string OtherHeaders { get; set; }

Public Property OtherHeaders As String

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 CRLF ("\r\n") .

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 component beyond what is provided.

This property is not available at design time.

OutputData Property (AmazonKMS Component)

The output data.

Syntax

• C#
• VB.NET

public string OutputData { get; set; }
public byte[] OutputDataB { get; set; }

Public Property OutputData As String
Public Property OutputDataB As Byte()

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 component 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. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

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

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

This property is not available at design time.

OutputFile Property (AmazonKMS Component)

The file to which output data should be written.

Syntax

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

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

Setting this property to a non-empty value will discard any stream set using the SetOutputStream method. Similarly, passing a non-null value to the aforementioned method will clear this property.

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 component 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. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

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

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

Overwrite Property (AmazonKMS Component)

Whether the output file should be overwritten if necessary.

Syntax

• C#
• VB.NET

public bool Overwrite { get; set; }

Public Property Overwrite As Boolean

Default Value

False

Remarks

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

ParsedHeaders Property (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public HeaderList ParsedHeaders { get; }

Public ReadOnly Property ParsedHeaders As HeaderList

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 collection is indexed from 0 to count -1.

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

Proxy Property (AmazonKMS Component)

A set of properties related to proxy access.

Syntax

• C#
• VB.NET

public Proxy Proxy { get; set; }

Public Property Proxy As Proxy

Remarks

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

QueryParams Property (AmazonKMS Component)

Additional query parameters to be included in the request.

Syntax

• C#
• VB.NET

public QueryParamList QueryParams { get; }

Public Property QueryParams As QueryParamList

Remarks

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

Region Property (AmazonKMS Component)

The region that the component will make requests against.

Syntax

• C#
• VB.NET

public string Region { get; set; }

Public Property Region As String

Default Value

"us-east-1"

Remarks

This property controls which region the component will make requests against. By default the component 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 component will always convert this property's value to lowercase. If this property is cleared, the component will reset it to the default value.

SecretKey Property (AmazonKMS Component)

The secret key to use for authentication.

Syntax

• C#
• VB.NET

public string SecretKey { get; set; }

Public Property SecretKey As String

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.

SSLAcceptServerCert Property (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public Certificate SSLAcceptServerCert { get; set; }

Public Property SSLAcceptServerCert As Certificate

Remarks

If it finds any issues with the certificate presented by the server, the component 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.

Note: This functionality is provided only for cases in which 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.

SSLCert Property (AmazonKMS Component)

The certificate to be used during Secure Sockets Layer (SSL) negotiation.

Syntax

• C#
• VB.NET

public Certificate SSLCert { get; set; }

Public Property SSLCert As Certificate

Remarks

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

SSLProvider Property (AmazonKMS Component)

The Secure Sockets Layer/Transport Layer Security (SSL/TLS) implementation to use.

Syntax

• C#
• VB.NET

public AmazonKMSSSLProviders SSLProvider { get; set; }

enum AmazonKMSSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Public Property SSLProvider As AmazonkmsSSLProviders

Enum AmazonKMSSSLProviders
  sslpAutomatic
  sslpPlatform
  sslpInternal
End Enum

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 component 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 as follows:

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

When Automatic is selected, on Windows, the component will use the platform implementation. On Linux/macOS, the component will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used on all platforms.

The .NET Standard library will always use the internal implementation on all platforms.

SSLServerCert Property (AmazonKMS Component)

The server certificate for the last established connection.

Syntax

• C#
• VB.NET

public Certificate SSLServerCert { get; }

Public ReadOnly Property SSLServerCert As Certificate

Remarks

This property contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Timeout Property (AmazonKMS Component)

The timeout for the component.

Syntax

• C#
• VB.NET

public int Timeout { get; set; }

Public Property Timeout As Integer

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 component will wait for the operation to complete before returning control.

The component 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 component throws an exception.

Note: By default, all timeouts are inactivity timeouts, that is, 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.

AddEncryptionContextItem Method (AmazonKMS Component)

Adds an item to the EncryptionContext properties.

Syntax

• C#
• VB.NET

public void AddEncryptionContextItem(string name, string value);

Async Version
public async Task AddEncryptionContextItem(string name, string value);
public async Task AddEncryptionContextItem(string name, string value, CancellationToken cancellationToken);

Public Sub AddEncryptionContextItem(ByVal Name As String, ByVal Value As String)

Async Version
Public Sub AddEncryptionContextItem(ByVal Name As String, ByVal Value As String) As Task
Public Sub AddEncryptionContextItem(ByVal Name As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

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

AddQueryParam Method (AmazonKMS Component)

Adds a query parameter to the QueryParams properties.

Syntax

• C#
• VB.NET

public void AddQueryParam(string name, string value);

Async Version
public async Task AddQueryParam(string name, string value);
public async Task AddQueryParam(string name, string value, CancellationToken cancellationToken);

Public Sub AddQueryParam(ByVal Name As String, ByVal Value As String)

Async Version
Public Sub AddQueryParam(ByVal Name As String, ByVal Value As String) As Task
Public Sub AddQueryParam(ByVal Name As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add a query parameter to the QueryParams collection. Name specifies the name of the parameter, and Value specifies the value of the parameter.

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

CancelKeyDeletion Method (AmazonKMS Component)

Cancels the deletion of the specified KMS key.

Syntax

• C#
• VB.NET

public void CancelKeyDeletion(string keyId);

Async Version
public async Task CancelKeyDeletion(string keyId);
public async Task CancelKeyDeletion(string keyId, CancellationToken cancellationToken);

Public Sub CancelKeyDeletion(ByVal KeyId As String)

Async Version
Public Sub CancelKeyDeletion(ByVal KeyId As String) As Task
Public Sub CancelKeyDeletion(ByVal KeyId As String, cancellationToken As CancellationToken) As Task

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.

ClearKeyData Method (AmazonKMS Component)

Clears information stored in the KeyData properties.

Syntax

• C#
• VB.NET

public void ClearKeyData(bool plaintextOnly);

Async Version
public async Task ClearKeyData(bool plaintextOnly);
public async Task ClearKeyData(bool plaintextOnly, CancellationToken cancellationToken);

Public Sub ClearKeyData(ByVal PlaintextOnly As Boolean)

Async Version
Public Sub ClearKeyData(ByVal PlaintextOnly As Boolean) As Task
Public Sub ClearKeyData(ByVal PlaintextOnly As Boolean, cancellationToken As CancellationToken) As Task

Remarks

This method clears the information stored in the KeyData fields, removing it from memory. If the PlaintextOnly parameter is true, only the PlaintextKey field is cleared.

Config Method (AmazonKMS Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.

CreateAlias Method (AmazonKMS Component)

Creates a new alias.

Syntax

• C#
• VB.NET

public void CreateAlias(string name, string keyId);

Async Version
public async Task CreateAlias(string name, string keyId);
public async Task CreateAlias(string name, string keyId, CancellationToken cancellationToken);

Public Sub CreateAlias(ByVal Name As String, ByVal KeyId As String)

Async Version
Public Sub CreateAlias(ByVal Name As String, ByVal KeyId As String) As Task
Public Sub CreateAlias(ByVal Name As String, ByVal KeyId As String, cancellationToken As CancellationToken) As Task

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.

CreateKey Method (AmazonKMS Component)

Creates a new KMS key.

Syntax

• C#
• VB.NET

public string CreateKey(string keySpec, bool forSigning, string description);

Async Version
public async Task<string> CreateKey(string keySpec, bool forSigning, string description);
public async Task<string> CreateKey(string keySpec, bool forSigning, string description, CancellationToken cancellationToken);

Public Function CreateKey(ByVal KeySpec As String, ByVal ForSigning As Boolean, ByVal Description As String) As String

Async Version
Public Function CreateKey(ByVal KeySpec As String, ByVal ForSigning As Boolean, ByVal Description As String) As Task(Of String)
Public Function CreateKey(ByVal KeySpec As String, ByVal ForSigning As Boolean, ByVal Description As String, cancellationToken As CancellationToken) As Task(Of 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.

Decrypt Method (AmazonKMS Component)

Decrypts data using a KMS key.

Syntax

• C#
• VB.NET

public void Decrypt(string keyId, string algorithm);

Async Version
public async Task Decrypt(string keyId, string algorithm);
public async Task Decrypt(string keyId, string algorithm, CancellationToken cancellationToken);

Public Sub Decrypt(ByVal KeyId As String, ByVal Algorithm As String)

Async Version
Public Sub Decrypt(ByVal KeyId As String, ByVal Algorithm As String) As Task
Public Sub Decrypt(ByVal KeyId As String, ByVal Algorithm As String, cancellationToken As CancellationToken) As Task

Remarks

This method decrypts data using the KMS key specified by KeyId and the given Algorithm. The data to decrypt is taken from the input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The decrypted data is output to the output stream supplied via the SetOutputStream method, 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 collection 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 State is anything other than aksEnabled (0).
• It is for signing/verification instead of encryption/decryption (see ForSigning).
• It is an AWS-managed KMS key (see AWSManaged).

DeleteAlias Method (AmazonKMS Component)

Deletes an alias.

Syntax

• C#
• VB.NET

public void DeleteAlias(string aliasName);

Async Version
public async Task DeleteAlias(string aliasName);
public async Task DeleteAlias(string aliasName, CancellationToken cancellationToken);

Public Sub DeleteAlias(ByVal AliasName As String)

Async Version
Public Sub DeleteAlias(ByVal AliasName As String) As Task
Public Sub DeleteAlias(ByVal AliasName As String, cancellationToken As CancellationToken) As Task

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

DoEvents Method (AmazonKMS Component)

This method processes events from the internal message queue.

Syntax

• C#
• VB.NET

public void DoEvents();

Async Version
public async Task DoEvents();
public async Task DoEvents(CancellationToken cancellationToken);

Public Sub DoEvents()

Async Version
Public Sub DoEvents() As Task
Public Sub DoEvents(cancellationToken As CancellationToken) As Task

Remarks

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

Encrypt Method (AmazonKMS Component)

Encrypts data using a KMS key.

Syntax

• C#
• VB.NET

public void Encrypt(string keyId, string algorithm);

Async Version
public async Task Encrypt(string keyId, string algorithm);
public async Task Encrypt(string keyId, string algorithm, CancellationToken cancellationToken);

Public Sub Encrypt(ByVal KeyId As String, ByVal Algorithm As String)

Async Version
Public Sub Encrypt(ByVal KeyId As String, ByVal Algorithm As String) As Task
Public Sub Encrypt(ByVal KeyId As String, ByVal Algorithm As String, cancellationToken As CancellationToken) As Task

Remarks

This method encrypts data using the KMS key specified by KeyId and the given Algorithm. The data to encrypt is taken from the input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The encrypted data is output to the output stream supplied via the SetOutputStream method, 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 collection 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 State is anything other than aksEnabled (0).
• It is for signing/verification instead of encryption/decryption (see ForSigning).
• It is an AWS-managed KMS key (see AWSManaged).

GenerateDataKey Method (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public void GenerateDataKey(string keySpec, string keyId, bool includePlaintext);

Async Version
public async Task GenerateDataKey(string keySpec, string keyId, bool includePlaintext);
public async Task GenerateDataKey(string keySpec, string keyId, bool includePlaintext, CancellationToken cancellationToken);

Public Sub GenerateDataKey(ByVal KeySpec As String, ByVal KeyId As String, ByVal IncludePlaintext As Boolean)

Async Version
Public Sub GenerateDataKey(ByVal KeySpec As String, ByVal KeyId As String, ByVal IncludePlaintext As Boolean) As Task
Public Sub GenerateDataKey(ByVal KeySpec As String, ByVal KeyId As String, ByVal IncludePlaintext As Boolean, cancellationToken As CancellationToken) As Task

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 fields, refer to their documentation for more information:

• ARN
• EncryptedKey
• KeySpec
• PlaintextKey (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 collection 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 State is anything other than aksEnabled (0).
• It is asymmetric (see KeySpec).
• It is for signing/verification instead of encryption/decryption (see ForSigning).
• It is an AWS-managed KMS key (see AWSManaged).

GenerateDataKeyPair Method (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public void GenerateDataKeyPair(string keyPairSpec, string keyId, bool includePlaintext);

Async Version
public async Task GenerateDataKeyPair(string keyPairSpec, string keyId, bool includePlaintext);
public async Task GenerateDataKeyPair(string keyPairSpec, string keyId, bool includePlaintext, CancellationToken cancellationToken);

Public Sub GenerateDataKeyPair(ByVal KeyPairSpec As String, ByVal KeyId As String, ByVal IncludePlaintext As Boolean)

Async Version
Public Sub GenerateDataKeyPair(ByVal KeyPairSpec As String, ByVal KeyId As String, ByVal IncludePlaintext As Boolean) As Task
Public Sub GenerateDataKeyPair(ByVal KeyPairSpec As String, ByVal KeyId As String, ByVal IncludePlaintext As Boolean, cancellationToken As CancellationToken) As Task

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 fields, refer to their documentation for more information:

• ARN
• EncryptedKey
• KeySpec
• PlaintextKey (if true is passed for IncludePlaintext)
• PublicKey

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 collection 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 State is anything other than aksEnabled (0).
• It is asymmetric (see KeySpec).
• It is for signing/verification instead of encryption/decryption (see ForSigning).
• It is an AWS-managed KMS key (see AWSManaged).

GenerateRandomBytes Method (AmazonKMS Component)

Generates a cryptographically-secure random byte string.

Syntax

• C#
• VB.NET

public void GenerateRandomBytes(int numBytes);

Async Version
public async Task GenerateRandomBytes(int numBytes);
public async Task GenerateRandomBytes(int numBytes, CancellationToken cancellationToken);

Public Sub GenerateRandomBytes(ByVal NumBytes As Integer)

Async Version
Public Sub GenerateRandomBytes(ByVal NumBytes As Integer) As Task
Public Sub GenerateRandomBytes(ByVal NumBytes As Integer, cancellationToken As CancellationToken) As Task

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 output stream supplied via the SetOutputStream method, the OutputFile, or the OutputData property.

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

GetKeyInfo Method (AmazonKMS Component)

Gets information about a KMS key.

Syntax

• C#
• VB.NET

public void GetKeyInfo(string keyId);

Async Version
public async Task GetKeyInfo(string keyId);
public async Task GetKeyInfo(string keyId, CancellationToken cancellationToken);

Public Sub GetKeyInfo(ByVal KeyId As String)

Async Version
Public Sub GetKeyInfo(ByVal KeyId As String) As Task
Public Sub GetKeyInfo(ByVal KeyId As String, cancellationToken As CancellationToken) As Task

Remarks

This method gets information about the KMS key specified by KeyId. When the information is returned, the component clears the Keys collection and repopulates it 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.

GetKeyRotationStatus Method (AmazonKMS Component)

Retrieves the key rotation status for a KMS key.

Syntax

• C#
• VB.NET

public bool GetKeyRotationStatus(string keyId);

Async Version
public async Task<bool> GetKeyRotationStatus(string keyId);
public async Task<bool> GetKeyRotationStatus(string keyId, CancellationToken cancellationToken);

Public Function GetKeyRotationStatus(ByVal KeyId As String) As Boolean

Async Version
Public Function GetKeyRotationStatus(ByVal KeyId As String) As Task(Of Boolean)
Public Function GetKeyRotationStatus(ByVal KeyId As String, cancellationToken As CancellationToken) As Task(Of 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.

GetPublicKey Method (AmazonKMS Component)

Retrieves the public key of an asymmetric KMS key.

Syntax

• C#
• VB.NET

public void GetPublicKey(string keyId);

Async Version
public async Task GetPublicKey(string keyId);
public async Task GetPublicKey(string keyId, CancellationToken cancellationToken);

Public Sub GetPublicKey(ByVal KeyId As String)

Async Version
Public Sub GetPublicKey(ByVal KeyId As String) As Task
Public Sub GetPublicKey(ByVal KeyId As String, cancellationToken As CancellationToken) As Task

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 fields, refer to their documentation for more information:

• Algorithms
• ARN
• ForSigning
• KeySpec
• PublicKey

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

• Its State is anything other than aksEnabled (0).
• It is symmetric (see KeySpec).
• It is an AWS-managed KMS key (see AWSManaged).

ListAliases Method (AmazonKMS Component)

Lists aliases in the current account and region.

Syntax

• C#
• VB.NET

public void ListAliases(string forKeyId);

Async Version
public async Task ListAliases(string forKeyId);
public async Task ListAliases(string forKeyId, CancellationToken cancellationToken);

Public Sub ListAliases(ByVal ForKeyId As String)

Async Version
Public Sub ListAliases(ByVal ForKeyId As String) As Task
Public Sub ListAliases(ByVal ForKeyId As String, cancellationToken As CancellationToken) As Task

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 Aliases collection.

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 Aliases collection.

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

ListKeys Method (AmazonKMS Component)

Lists KMS keys in the current account and region.

Syntax

• C#
• VB.NET

public void ListKeys();

Async Version
public async Task ListKeys();
public async Task ListKeys(CancellationToken cancellationToken);

Public Sub ListKeys()

Async Version
Public Sub ListKeys() As Task
Public Sub ListKeys(cancellationToken As CancellationToken) As Task

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 Keys collection. However, note that by default only the ARN and Id fields 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 component 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 Keys collection.

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

ReEncrypt Method (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public void ReEncrypt(string oldKeyId, string oldAlgorithm, string newKeyId, string newAlgorithm);

Async Version
public async Task ReEncrypt(string oldKeyId, string oldAlgorithm, string newKeyId, string newAlgorithm);
public async Task ReEncrypt(string oldKeyId, string oldAlgorithm, string newKeyId, string newAlgorithm, CancellationToken cancellationToken);

Public Sub ReEncrypt(ByVal OldKeyId As String, ByVal OldAlgorithm As String, ByVal NewKeyId As String, ByVal NewAlgorithm As String)

Async Version
Public Sub ReEncrypt(ByVal OldKeyId As String, ByVal OldAlgorithm As String, ByVal NewKeyId As String, ByVal NewAlgorithm As String) As Task
Public Sub ReEncrypt(ByVal OldKeyId As String, ByVal OldAlgorithm As String, ByVal NewKeyId As String, ByVal NewAlgorithm As String, cancellationToken As CancellationToken) As Task

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 input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The re-encrypted data is output to the output stream supplied via the SetOutputStream method, 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 collection 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 collection 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 State is anything other than aksEnabled (0).
• It is for signing/verification instead of encryption/decryption (see ForSigning).
• It is an AWS-managed KMS key (see AWSManaged).

Reset Method (AmazonKMS Component)

Resets the component to its initial state.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method resets the component to its initial state.

ScheduleKeyDeletion Method (AmazonKMS Component)

Schedules the deletion of a KMS key.

Syntax

• C#
• VB.NET

public void ScheduleKeyDeletion(string keyId, int daysToWait);

Async Version
public async Task ScheduleKeyDeletion(string keyId, int daysToWait);
public async Task ScheduleKeyDeletion(string keyId, int daysToWait, CancellationToken cancellationToken);

Public Sub ScheduleKeyDeletion(ByVal KeyId As String, ByVal DaysToWait As Integer)

Async Version
Public Sub ScheduleKeyDeletion(ByVal KeyId As String, ByVal DaysToWait As Integer) As Task
Public Sub ScheduleKeyDeletion(ByVal KeyId As String, ByVal DaysToWait As Integer, cancellationToken As CancellationToken) As Task

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.

SendCustomRequest Method (AmazonKMS Component)

Sends a custom request to the server.

Syntax

• C#
• VB.NET

public void SendCustomRequest(string action);

Async Version
public async Task SendCustomRequest(string action);
public async Task SendCustomRequest(string action, CancellationToken cancellationToken);

Public Sub SendCustomRequest(ByVal Action As String)

Async Version
Public Sub SendCustomRequest(ByVal Action As String) As Task
Public Sub SendCustomRequest(ByVal Action As String, cancellationToken As CancellationToken) As Task

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 component does the following:

1. Builds a request URL, including query parameters, based on the following:
   • Region
   • QueryParams
2. Adds request headers from OtherHeaders.
3. Adds any request body supplied via the stream specified using SetInputStream, the specified InputFile, or InputData.
4. Signs the request.
5. Sends the request to the server.
6. Stores the response headers in the ParsedHeaders collection; and the response body in the stream specified using SetOutputStream, 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.

SetInputStream Method (AmazonKMS Component)

Sets the stream whose data should be processed.

Syntax

• C#
• VB.NET

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the stream whose data should be processed in a cryptographic operation.

Passing a non-null value for InputStream will cause the InputFile property to be cleared. Similarly, setting InputFile to a non-empty value will discard any stream set using this method.

Input Sources & Output Destinations

The component 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. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

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

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

SetKeyEnabled Method (AmazonKMS Component)

Enables or disables a KMS key.

Syntax

• C#
• VB.NET

public void SetKeyEnabled(string keyId, bool enabled);

Async Version
public async Task SetKeyEnabled(string keyId, bool enabled);
public async Task SetKeyEnabled(string keyId, bool enabled, CancellationToken cancellationToken);

Public Sub SetKeyEnabled(ByVal KeyId As String, ByVal Enabled As Boolean)

Async Version
Public Sub SetKeyEnabled(ByVal KeyId As String, ByVal Enabled As Boolean) As Task
Public Sub SetKeyEnabled(ByVal KeyId As String, ByVal Enabled As Boolean, cancellationToken As CancellationToken) As Task

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 State is aksPendingDeletion (2) or aksPendingImport (3).
• It is an AWS-managed KMS key (see AWSManaged).

SetKeyRotationStatus Method (AmazonKMS Component)

Enables or disables automatic key rotation for a KMS key.

Syntax

• C#
• VB.NET

public void SetKeyRotationStatus(string keyId, bool enabled);

Async Version
public async Task SetKeyRotationStatus(string keyId, bool enabled);
public async Task SetKeyRotationStatus(string keyId, bool enabled, CancellationToken cancellationToken);

Public Sub SetKeyRotationStatus(ByVal KeyId As String, ByVal Enabled As Boolean)

Async Version
Public Sub SetKeyRotationStatus(ByVal KeyId As String, ByVal Enabled As Boolean) As Task
Public Sub SetKeyRotationStatus(ByVal KeyId As String, ByVal Enabled As Boolean, cancellationToken As CancellationToken) As Task

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 State is anything other than aksEnabled (0).
• It is asymmetric (see KeySpec).
• It has imported key material (see Origin).
• It resides in a custom key store (see CustomKeyStoreId).
• It is an AWS-managed KMS key (see AWSManaged).

SetOutputStream Method (AmazonKMS Component)

Sets the stream to which output data should be written.

Syntax

• C#
• VB.NET

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the stream to which data output from a successful cryptographic operation should be written.

Passing a non-null value for OutputStream will cause the OutputFile property to be cleared. Similarly, setting OutputFile to a non-empty value will discard any stream set using this method.

Input Sources & Output Destinations

The component 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. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

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

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

Sign Method (AmazonKMS Component)

Signs a message using a KMS key.

Syntax

• C#
• VB.NET

public void Sign(string keyId, string algorithm, bool isDigest);

Async Version
public async Task Sign(string keyId, string algorithm, bool isDigest);
public async Task Sign(string keyId, string algorithm, bool isDigest, CancellationToken cancellationToken);

Public Sub Sign(ByVal KeyId As String, ByVal Algorithm As String, ByVal IsDigest As Boolean)

Async Version
Public Sub Sign(ByVal KeyId As String, ByVal Algorithm As String, ByVal IsDigest As Boolean) As Task
Public Sub Sign(ByVal KeyId As String, ByVal Algorithm As String, ByVal IsDigest As Boolean, cancellationToken As CancellationToken) As Task

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 input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The signature data is output to the output stream supplied via the SetOutputStream method, 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 component 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 State is anything other than aksEnabled (0).
• It is symmetric (see KeySpec).
• It is for encryption/decryption instead of signing/verification (see ForSigning).
• It is an AWS-managed KMS key (see AWSManaged).

UpdateAlias Method (AmazonKMS Component)

Updates an alias to refer to a different KMS key.

Syntax

• C#
• VB.NET

public void UpdateAlias(string aliasName, string newKeyId);

Async Version
public async Task UpdateAlias(string aliasName, string newKeyId);
public async Task UpdateAlias(string aliasName, string newKeyId, CancellationToken cancellationToken);

Public Sub UpdateAlias(ByVal AliasName As String, ByVal NewKeyId As String)

Async Version
Public Sub UpdateAlias(ByVal AliasName As String, ByVal NewKeyId As String) As Task
Public Sub UpdateAlias(ByVal AliasName As String, ByVal NewKeyId As String, cancellationToken As CancellationToken) As Task

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 AWSManaged).

UpdateKeyDescription Method (AmazonKMS Component)

Updates a KMS key's description.

Syntax

• C#
• VB.NET

public void UpdateKeyDescription(string keyId, string newDescription);

Async Version
public async Task UpdateKeyDescription(string keyId, string newDescription);
public async Task UpdateKeyDescription(string keyId, string newDescription, CancellationToken cancellationToken);

Public Sub UpdateKeyDescription(ByVal KeyId As String, ByVal NewDescription As String)

Async Version
Public Sub UpdateKeyDescription(ByVal KeyId As String, ByVal NewDescription As String) As Task
Public Sub UpdateKeyDescription(ByVal KeyId As String, ByVal NewDescription As String, cancellationToken As CancellationToken) As Task

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 AWSManaged).

Verify Method (AmazonKMS Component)

Verifies a digital signature using a KMS key.

Syntax

• C#
• VB.NET

public bool Verify(string keyId, string algorithm, bool isDigest);

Async Version
public async Task<bool> Verify(string keyId, string algorithm, bool isDigest);
public async Task<bool> Verify(string keyId, string algorithm, bool isDigest, CancellationToken cancellationToken);

Public Function Verify(ByVal KeyId As String, ByVal Algorithm As String, ByVal IsDigest As Boolean) As Boolean

Async Version
Public Function Verify(ByVal KeyId As String, ByVal Algorithm As String, ByVal IsDigest As Boolean) As Task(Of Boolean)
Public Function Verify(ByVal KeyId As String, ByVal Algorithm As String, ByVal IsDigest As Boolean, cancellationToken As CancellationToken) As Task(Of 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 input stream supplied via the SetInputStream method, 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 component 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 State is anything other than aksEnabled (0).
• It is symmetric (see KeySpec).
• It is for encryption/decryption instead of signing/verification (see ForSigning).
• It is an AWS-managed KMS key (see AWSManaged).

AliasList Event (AmazonKMS Component)

Fires once for each alias when listing aliases.

Syntax

• C#
• VB.NET

public event OnAliasListHandler OnAliasList;

public delegate void OnAliasListHandler(object sender, AmazonKMSAliasListEventArgs e);

public class AmazonKMSAliasListEventArgs : EventArgs {
  public string ARN { get; }
  public string Name { get; }
  public string KeyId { get; }
}

Public Event OnAliasList As OnAliasListHandler

Public Delegate Sub OnAliasListHandler(sender As Object, e As AmazonKMSAliasListEventArgs)

Public Class AmazonKMSAliasListEventArgs Inherits EventArgs
  Public ReadOnly Property ARN As String
  Public ReadOnly Property Name As String
  Public ReadOnly Property KeyId As String
End Class

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.

EndTransfer Event (AmazonKMS Component)

This event fires when a document finishes transferring.

Syntax

• C#
• VB.NET

public event OnEndTransferHandler OnEndTransfer;

public delegate void OnEndTransferHandler(object sender, AmazonKMSEndTransferEventArgs e);

public class AmazonKMSEndTransferEventArgs : EventArgs {
  public int Direction { get; }
}

Public Event OnEndTransfer As OnEndTransferHandler

Public Delegate Sub OnEndTransferHandler(sender As Object, e As AmazonKMSEndTransferEventArgs)

Public Class AmazonKMSEndTransferEventArgs Inherits EventArgs
  Public ReadOnly Property Direction As Integer
End Class

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.

Error Event (AmazonKMS Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, AmazonKMSErrorEventArgs e);

public class AmazonKMSErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As AmazonKMSErrorEventArgs)

Public Class AmazonKMSErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

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.

Header Event (AmazonKMS Component)

Fired every time a header line comes in.

Syntax

• C#
• VB.NET

public event OnHeaderHandler OnHeader;

public delegate void OnHeaderHandler(object sender, AmazonKMSHeaderEventArgs e);

public class AmazonKMSHeaderEventArgs : EventArgs {
  public string Field { get; }
  public string Value { get; }
}

Public Event OnHeader As OnHeaderHandler

Public Delegate Sub OnHeaderHandler(sender As Object, e As AmazonKMSHeaderEventArgs)

Public Class AmazonKMSHeaderEventArgs Inherits EventArgs
  Public ReadOnly Property Field As String
  Public ReadOnly Property Value As String
End Class

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).

KeyList Event (AmazonKMS Component)

Fires once for each KMS key when listing KMS keys.

Syntax

• C#
• VB.NET

public event OnKeyListHandler OnKeyList;

public delegate void OnKeyListHandler(object sender, AmazonKMSKeyListEventArgs e);

public class AmazonKMSKeyListEventArgs : EventArgs {
  public string ARN { get; }
  public string Id { get; }
  public string AccountId { get; }
  public string Description { get; }
  public bool Enabled { get; }
  public bool AWSManaged { get; }
  public bool ForSigning { get; }
  public string KeySpec { get; }
  public string Algorithms { get; }
  public int State { get; }
  public string CreationDate { get; }
  public string DeletionDate { get; }
}

Public Event OnKeyList As OnKeyListHandler

Public Delegate Sub OnKeyListHandler(sender As Object, e As AmazonKMSKeyListEventArgs)

Public Class AmazonKMSKeyListEventArgs Inherits EventArgs
  Public ReadOnly Property ARN As String
  Public ReadOnly Property Id As String
  Public ReadOnly Property AccountId As String
  Public ReadOnly Property Description As String
  Public ReadOnly Property Enabled As Boolean
  Public ReadOnly Property AWSManaged As Boolean
  Public ReadOnly Property ForSigning As Boolean
  Public ReadOnly Property KeySpec As String
  Public ReadOnly Property Algorithms As String
  Public ReadOnly Property State As Integer
  Public ReadOnly Property CreationDate As String
  Public ReadOnly Property DeletionDate As String
End Class

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 ForSigning is false, possible values are:

• SYMMETRIC_DEFAULT
• RSAES_OAEP_SHA_1
• RSAES_OAEP_SHA_256

If ForSigning 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)

Log Event (AmazonKMS Component)

Fired once for each log message.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, AmazonKMSLogEventArgs e);

public class AmazonKMSLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As AmazonKMSLogEventArgs)

Public Class AmazonKMSLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event is fired once for each log message generated by the component. 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"

SSLServerAuthentication Event (AmazonKMS Component)

Fired after the server presents its certificate to the client.

Syntax

• C#
• VB.NET

public event OnSSLServerAuthenticationHandler OnSSLServerAuthentication;

public delegate void OnSSLServerAuthenticationHandler(object sender, AmazonKMSSSLServerAuthenticationEventArgs e);

public class AmazonKMSSSLServerAuthenticationEventArgs : EventArgs {
  public string CertEncoded { get; }
  public byte[] CertEncodedB { get; }
  public string CertSubject { get; }
  public string CertIssuer { get; }
  public string Status { get; }
  public bool Accept { get; set; }
}

Public Event OnSSLServerAuthentication As OnSSLServerAuthenticationHandler

Public Delegate Sub OnSSLServerAuthenticationHandler(sender As Object, e As AmazonKMSSSLServerAuthenticationEventArgs)

Public Class AmazonKMSSSLServerAuthenticationEventArgs Inherits EventArgs
  Public ReadOnly Property CertEncoded As String
  Public ReadOnly Property CertEncodedB As Byte()
  Public ReadOnly Property CertSubject As String
  Public ReadOnly Property CertIssuer As String
  Public ReadOnly Property Status As String
  Public Property Accept As Boolean
End Class

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (AmazonKMS Component)

Fired when secure connection progress messages are available.

Syntax

• C#
• VB.NET

public event OnSSLStatusHandler OnSSLStatus;

public delegate void OnSSLStatusHandler(object sender, AmazonKMSSSLStatusEventArgs e);

public class AmazonKMSSSLStatusEventArgs : EventArgs {
  public string Message { get; }
}

Public Event OnSSLStatus As OnSSLStatusHandler

Public Delegate Sub OnSSLStatusHandler(sender As Object, e As AmazonKMSSSLStatusEventArgs)

Public Class AmazonKMSSSLStatusEventArgs Inherits EventArgs
  Public ReadOnly Property Message As String
End Class

Remarks

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

StartTransfer Event (AmazonKMS Component)

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

Syntax

• C#
• VB.NET

public event OnStartTransferHandler OnStartTransfer;

public delegate void OnStartTransferHandler(object sender, AmazonKMSStartTransferEventArgs e);

public class AmazonKMSStartTransferEventArgs : EventArgs {
  public int Direction { get; }
}

Public Event OnStartTransfer As OnStartTransferHandler

Public Delegate Sub OnStartTransferHandler(sender As Object, e As AmazonKMSStartTransferEventArgs)

Public Class AmazonKMSStartTransferEventArgs Inherits EventArgs
  Public ReadOnly Property Direction As Integer
End Class

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.

Transfer Event (AmazonKMS Component)

Fired while a document transfers (delivers document).

Syntax

• C#
• VB.NET

public event OnTransferHandler OnTransfer;

public delegate void OnTransferHandler(object sender, AmazonKMSTransferEventArgs e);

public class AmazonKMSTransferEventArgs : EventArgs {
  public int Direction { get; }
  public long BytesTransferred { get; }
  public int PercentDone { get; }
  public string Text { get; }
  public byte[] TextB { get; }
}

Public Event OnTransfer As OnTransferHandler

Public Delegate Sub OnTransferHandler(sender As Object, e As AmazonKMSTransferEventArgs)

Public Class AmazonKMSTransferEventArgs Inherits EventArgs
  Public ReadOnly Property Direction As Integer
  Public ReadOnly Property BytesTransferred As Long
  Public ReadOnly Property PercentDone As Integer
  Public ReadOnly Property Text As String
  Public ReadOnly Property TextB As Byte()
End Class

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

• C#
• VB.NET

public AWSContextItem();

Public AWSContextItem()

• C#
• VB.NET

public AWSContextItem(string name, string value);

Public AWSContextItem(ByVal Name As String, ByVal Value As String)

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

• C#
• VB.NET

public Certificate();

Public Certificate()

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

• C#
• VB.NET

public Certificate(byte[] encoded);

Public Certificate(ByVal Encoded As Byte())

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, byte[] encoded);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

Firewall Type

The firewall the component will connect through.

Remarks

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

Fields

Constructors

• C#
• VB.NET

public Firewall();

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 Field, and its corresponding Value.

Fields

Constructors

• C#
• VB.NET

public Header();

Public Header()

• C#
• VB.NET

public Header(string field, string value);

Public Header(ByVal Field As String, ByVal Value As String)

Proxy Type

The proxy the component will connect to.

Remarks

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

Fields

Constructors

• C#
• VB.NET

public Proxy();

Public Proxy()

• C#
• VB.NET

public Proxy(string server, int port);

Public Proxy(ByVal Server As String, ByVal Port As Integer)

• C#
• VB.NET

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

Public Proxy(ByVal Server As String, ByVal Port As Integer, ByVal User As String, ByVal Password As String)

QueryParam Type

A query parameter to send in the request.

Remarks

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

Fields

Constructors

• C#
• VB.NET

public QueryParam();

Public QueryParam()

• C#
• VB.NET

public QueryParam(string name, string value);

Public QueryParam(ByVal Name As String, ByVal Value As String)

Config Settings (AmazonKMS Component)

AmazonKMS Config Settings