AmazonKMS Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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

AccessKey Property (AmazonKMS Class)

The access key to use for authentication.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccessKey();
int SetAccessKey(const char* lpszAccessKey);

Unicode (Windows)
LPWSTR GetAccessKey();
INT SetAccessKey(LPCWSTR lpszAccessKey);

char* cloudkeys_amazonkms_getaccesskey(void* lpObj);
int cloudkeys_amazonkms_setaccesskey(void* lpObj, const char* lpszAccessKey);

QString GetAccessKey();
int SetAccessKey(QString qsAccessKey);

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.

Data Type

String

Aliases Property (AmazonKMS Class)

A collection of aliases.

Syntax

• C++
• C
• Qt

CloudKeysList<CloudKeysAWSAlias>* GetAliases();

int cloudkeys_amazonkms_getaliascount(void* lpObj);

char* cloudkeys_amazonkms_getaliasarn(void* lpObj, int aliasindex);

char* cloudkeys_amazonkms_getaliaskeyid(void* lpObj, int aliasindex);

char* cloudkeys_amazonkms_getaliasname(void* lpObj, int aliasindex);

int GetAliasCount();

QString GetAliasARN(int iAliasIndex);

QString GetAliasKeyId(int iAliasIndex);

QString GetAliasName(int iAliasIndex);

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.

Data Type

CloudKeysAWSAlias

AliasMarker Property (AmazonKMS Class)

A marker indicating what page of aliases to return next.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAliasMarker();
int SetAliasMarker(const char* lpszAliasMarker);

Unicode (Windows)
LPWSTR GetAliasMarker();
INT SetAliasMarker(LPCWSTR lpszAliasMarker);

char* cloudkeys_amazonkms_getaliasmarker(void* lpObj);
int cloudkeys_amazonkms_setaliasmarker(void* lpObj, const char* lpszAliasMarker);

QString GetAliasMarker();
int SetAliasMarker(QString qsAliasMarker);

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.

Data Type

String

EncryptionContext Property (AmazonKMS Class)

A collection of encryption context items.

Syntax

• C++
• C
• Qt

CloudKeysList<CloudKeysAWSContextItem>* GetEncryptionContext();
int SetEncryptionContext(CloudKeysList<CloudKeysAWSContextItem>* val);

int cloudkeys_amazonkms_getencryptioncontextcount(void* lpObj);
int cloudkeys_amazonkms_setencryptioncontextcount(void* lpObj, int iEncryptionContextCount);

char* cloudkeys_amazonkms_getencryptioncontextname(void* lpObj, int encryptioncontextindex);
int cloudkeys_amazonkms_setencryptioncontextname(void* lpObj, int encryptioncontextindex, const char* lpszEncryptionContextName);

char* cloudkeys_amazonkms_getencryptioncontextvalue(void* lpObj, int encryptioncontextindex);
int cloudkeys_amazonkms_setencryptioncontextvalue(void* lpObj, int encryptioncontextindex, const char* lpszEncryptionContextValue);

int GetEncryptionContextCount();
int SetEncryptionContextCount(int iEncryptionContextCount);

QString GetEncryptionContextName(int iEncryptionContextIndex);
int SetEncryptionContextName(int iEncryptionContextIndex, QString qsEncryptionContextName);

QString GetEncryptionContextValue(int iEncryptionContextIndex);
int SetEncryptionContextValue(int iEncryptionContextIndex, QString qsEncryptionContextValue);

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.

Data Type

CloudKeysAWSContextItem

Firewall Property (AmazonKMS Class)

A set of properties related to firewall access.

Syntax

• C++
• C
• Qt

CloudKeysFirewall* GetFirewall();
int SetFirewall(CloudKeysFirewall* val);

int cloudkeys_amazonkms_getfirewallautodetect(void* lpObj);
int cloudkeys_amazonkms_setfirewallautodetect(void* lpObj, int bFirewallAutoDetect);

int cloudkeys_amazonkms_getfirewalltype(void* lpObj);
int cloudkeys_amazonkms_setfirewalltype(void* lpObj, int iFirewallType);

char* cloudkeys_amazonkms_getfirewallhost(void* lpObj);
int cloudkeys_amazonkms_setfirewallhost(void* lpObj, const char* lpszFirewallHost);

char* cloudkeys_amazonkms_getfirewallpassword(void* lpObj);
int cloudkeys_amazonkms_setfirewallpassword(void* lpObj, const char* lpszFirewallPassword);

int cloudkeys_amazonkms_getfirewallport(void* lpObj);
int cloudkeys_amazonkms_setfirewallport(void* lpObj, int iFirewallPort);

char* cloudkeys_amazonkms_getfirewalluser(void* lpObj);
int cloudkeys_amazonkms_setfirewalluser(void* lpObj, const char* lpszFirewallUser);

bool GetFirewallAutoDetect();
int SetFirewallAutoDetect(bool bFirewallAutoDetect);

int GetFirewallType();
int SetFirewallType(int iFirewallType);

QString GetFirewallHost();
int SetFirewallHost(QString qsFirewallHost);

QString GetFirewallPassword();
int SetFirewallPassword(QString qsFirewallPassword);

int GetFirewallPort();
int SetFirewallPort(int iFirewallPort);

QString GetFirewallUser();
int SetFirewallUser(QString qsFirewallUser);

Remarks

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

Data Type

CloudKeysFirewall

Idle Property (AmazonKMS Class)

The current status of the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIdle();

Unicode (Windows)
BOOL GetIdle();

int cloudkeys_amazonkms_getidle(void* lpObj);

bool GetIdle();

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.

Data Type

Boolean

IncludeKeyDetails Property (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIncludeKeyDetails();
int SetIncludeKeyDetails(int bIncludeKeyDetails);

Unicode (Windows)
BOOL GetIncludeKeyDetails();
INT SetIncludeKeyDetails(BOOL bIncludeKeyDetails);

int cloudkeys_amazonkms_getincludekeydetails(void* lpObj);
int cloudkeys_amazonkms_setincludekeydetails(void* lpObj, int bIncludeKeyDetails);

bool GetIncludeKeyDetails();
int SetIncludeKeyDetails(bool bIncludeKeyDetails);

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 ARN and Id 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 Keys properties. 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.

Data Type

Boolean

InputData Property (AmazonKMS Class)

The data to process.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetInputData(char* &lpInputData, int &lenInputData);
int SetInputData(const char* lpInputData, int lenInputData);

Unicode (Windows)
INT GetInputData(LPSTR &lpInputData, INT &lenInputData);
INT SetInputData(LPCSTR lpInputData, INT lenInputData);

int cloudkeys_amazonkms_getinputdata(void* lpObj, char** lpInputData, int* lenInputData);
int cloudkeys_amazonkms_setinputdata(void* lpObj, const char* lpInputData, int lenInputData);

QByteArray GetInputData();
int SetInputData(QByteArray qbaInputData);

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

Data Type

Binary String

InputFile Property (AmazonKMS Class)

The file whose data should be processed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetInputFile();
wchar_t* GetInputFile_W(); // Windows only
int SetInputFile(const char* lpszInputFile);
int SetInputFile(const wchar_t* lpszInputFile); // Windows only

Unicode (Windows)
LPWSTR GetInputFile();
INT SetInputFile(LPCWSTR lpszInputFile);

char* cloudkeys_amazonkms_getinputfile(void* lpObj);
wchar_t* cloudkeys_amazonkms_getinputfile_W(void* lpObj); // Windows only
int cloudkeys_amazonkms_setinputfile(void* lpObj, const char* lpszInputFile);
int cloudkeys_amazonkms_setinputfile(void* lpObj, const wchar_t* lpszInputFile); // Windows only

QString GetInputFile();
int SetInputFile(QString qsInputFile);

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

Data Type

String

KeyData Property (AmazonKMS Class)

The downloaded key information.

Syntax

• C++
• C
• Qt

CloudKeysAWSKeyData* GetKeyData();

char* cloudkeys_amazonkms_getkeydataalgorithms(void* lpObj);

char* cloudkeys_amazonkms_getkeydataarn(void* lpObj);

int cloudkeys_amazonkms_getkeydataencryptedkey(void* lpObj, char** lpKeyDataEncryptedKey, int* lenKeyDataEncryptedKey);

int cloudkeys_amazonkms_getkeydataforsigning(void* lpObj);

char* cloudkeys_amazonkms_getkeydatakeyspec(void* lpObj);

int cloudkeys_amazonkms_getkeydataplaintextkey(void* lpObj, char** lpKeyDataPlaintextKey, int* lenKeyDataPlaintextKey);

char* cloudkeys_amazonkms_getkeydatapublickey(void* lpObj);

QString GetKeyDataAlgorithms();

QString GetKeyDataARN();

QByteArray GetKeyDataEncryptedKey();

bool GetKeyDataForSigning();

QString GetKeyDataKeySpec();

QByteArray GetKeyDataPlaintextKey();

QString GetKeyDataPublicKey();

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.

Data Type

CloudKeysAWSKeyData

KeyMarker Property (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetKeyMarker();
int SetKeyMarker(const char* lpszKeyMarker);

Unicode (Windows)
LPWSTR GetKeyMarker();
INT SetKeyMarker(LPCWSTR lpszKeyMarker);

char* cloudkeys_amazonkms_getkeymarker(void* lpObj);
int cloudkeys_amazonkms_setkeymarker(void* lpObj, const char* lpszKeyMarker);

QString GetKeyMarker();
int SetKeyMarker(QString qsKeyMarker);

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.

Data Type

String

Keys Property (AmazonKMS Class)

A collection of keys.

Syntax

• C++
• C
• Qt

CloudKeysList<CloudKeysAWSKey>* GetKeys();

int cloudkeys_amazonkms_getkeycount(void* lpObj);

char* cloudkeys_amazonkms_getkeyaccountid(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeyalgorithms(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeyarn(void* lpObj, int keyindex);

int cloudkeys_amazonkms_getkeyawsmanaged(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeycloudhsmclusterid(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeycreationdate(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeycustomkeystoreid(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeydeletiondate(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeydescription(void* lpObj, int keyindex);

int cloudkeys_amazonkms_getkeyenabled(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeyexpirationdate(void* lpObj, int keyindex);

int cloudkeys_amazonkms_getkeyforsigning(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeyid(void* lpObj, int keyindex);

char* cloudkeys_amazonkms_getkeykeyspec(void* lpObj, int keyindex);

int cloudkeys_amazonkms_getkeyorigin(void* lpObj, int keyindex);

int cloudkeys_amazonkms_getkeystate(void* lpObj, int keyindex);

int GetKeyCount();

QString GetKeyAccountId(int iKeyIndex);

QString GetKeyAlgorithms(int iKeyIndex);

QString GetKeyARN(int iKeyIndex);

bool GetKeyAWSManaged(int iKeyIndex);

QString GetKeyCloudHSMClusterId(int iKeyIndex);

QString GetKeyCreationDate(int iKeyIndex);

QString GetKeyCustomKeyStoreId(int iKeyIndex);

QString GetKeyDeletionDate(int iKeyIndex);

QString GetKeyDescription(int iKeyIndex);

bool GetKeyEnabled(int iKeyIndex);

QString GetKeyExpirationDate(int iKeyIndex);

bool GetKeyForSigning(int iKeyIndex);

QString GetKeyId(int iKeyIndex);

QString GetKeyKeySpec(int iKeyIndex);

int GetKeyOrigin(int iKeyIndex);

int GetKeyState(int iKeyIndex);

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.

Data Type

CloudKeysAWSKey

LocalHost Property (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetLocalHost();
int SetLocalHost(const char* lpszLocalHost);

Unicode (Windows)
LPWSTR GetLocalHost();
INT SetLocalHost(LPCWSTR lpszLocalHost);

char* cloudkeys_amazonkms_getlocalhost(void* lpObj);
int cloudkeys_amazonkms_setlocalhost(void* lpObj, const char* lpszLocalHost);

QString GetLocalHost();
int SetLocalHost(QString qsLocalHost);

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 class initiate connections (or accept in the case of server classs) 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 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 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.

Data Type

String

OtherHeaders Property (AmazonKMS Class)

Other headers as determined by the user (optional).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOtherHeaders();
int SetOtherHeaders(const char* lpszOtherHeaders);

Unicode (Windows)
LPWSTR GetOtherHeaders();
INT SetOtherHeaders(LPCWSTR lpszOtherHeaders);

char* cloudkeys_amazonkms_getotherheaders(void* lpObj);
int cloudkeys_amazonkms_setotherheaders(void* lpObj, const char* lpszOtherHeaders);

QString GetOtherHeaders();
int SetOtherHeaders(QString qsOtherHeaders);

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

This property is not available at design time.

Data Type

String

OutputData Property (AmazonKMS Class)

The output data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutputData(char* &lpOutputData, int &lenOutputData);
int SetOutputData(const char* lpOutputData, int lenOutputData);

Unicode (Windows)
INT GetOutputData(LPSTR &lpOutputData, INT &lenOutputData);
INT SetOutputData(LPCSTR lpOutputData, INT lenOutputData);

int cloudkeys_amazonkms_getoutputdata(void* lpObj, char** lpOutputData, int* lenOutputData);
int cloudkeys_amazonkms_setoutputdata(void* lpObj, const char* lpOutputData, int lenOutputData);

QByteArray GetOutputData();
int SetOutputData(QByteArray qbaOutputData);

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

Data Type

Binary String

OutputFile Property (AmazonKMS Class)

The file to which output data should be written.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutputFile();
wchar_t* GetOutputFile_W(); // Windows only
int SetOutputFile(const char* lpszOutputFile);
int SetOutputFile(const wchar_t* lpszOutputFile); // Windows only

Unicode (Windows)
LPWSTR GetOutputFile();
INT SetOutputFile(LPCWSTR lpszOutputFile);

char* cloudkeys_amazonkms_getoutputfile(void* lpObj);
wchar_t* cloudkeys_amazonkms_getoutputfile_W(void* lpObj); // Windows only
int cloudkeys_amazonkms_setoutputfile(void* lpObj, const char* lpszOutputFile);
int cloudkeys_amazonkms_setoutputfile(void* lpObj, const wchar_t* lpszOutputFile); // Windows only

QString GetOutputFile();
int SetOutputFile(QString qsOutputFile);

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

Data Type

String

Overwrite Property (AmazonKMS Class)

Whether the output file should be overwritten if necessary.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOverwrite();
int SetOverwrite(int bOverwrite);

Unicode (Windows)
BOOL GetOverwrite();
INT SetOverwrite(BOOL bOverwrite);

int cloudkeys_amazonkms_getoverwrite(void* lpObj);
int cloudkeys_amazonkms_setoverwrite(void* lpObj, int bOverwrite);

bool GetOverwrite();
int SetOverwrite(bool bOverwrite);

Default Value

FALSE

Remarks

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

Data Type

Boolean

ParsedHeaders Property (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

CloudKeysList<CloudKeysHeader>* GetParsedHeaders();

int cloudkeys_amazonkms_getparsedheadercount(void* lpObj);

char* cloudkeys_amazonkms_getparsedheaderfield(void* lpObj, int parsedheaderindex);

char* cloudkeys_amazonkms_getparsedheadervalue(void* lpObj, int parsedheaderindex);

int GetParsedHeaderCount();

QString GetParsedHeaderField(int iParsedHeaderIndex);

QString GetParsedHeaderValue(int iParsedHeaderIndex);

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.

Data Type

CloudKeysHeader

Proxy Property (AmazonKMS Class)

A set of properties related to proxy access.

Syntax

• C++
• C
• Qt

CloudKeysProxy* GetProxy();
int SetProxy(CloudKeysProxy* val);

int cloudkeys_amazonkms_getproxyauthscheme(void* lpObj);
int cloudkeys_amazonkms_setproxyauthscheme(void* lpObj, int iProxyAuthScheme);

int cloudkeys_amazonkms_getproxyautodetect(void* lpObj);
int cloudkeys_amazonkms_setproxyautodetect(void* lpObj, int bProxyAutoDetect);

char* cloudkeys_amazonkms_getproxypassword(void* lpObj);
int cloudkeys_amazonkms_setproxypassword(void* lpObj, const char* lpszProxyPassword);

int cloudkeys_amazonkms_getproxyport(void* lpObj);
int cloudkeys_amazonkms_setproxyport(void* lpObj, int iProxyPort);

char* cloudkeys_amazonkms_getproxyserver(void* lpObj);
int cloudkeys_amazonkms_setproxyserver(void* lpObj, const char* lpszProxyServer);

int cloudkeys_amazonkms_getproxyssl(void* lpObj);
int cloudkeys_amazonkms_setproxyssl(void* lpObj, int iProxySSL);

char* cloudkeys_amazonkms_getproxyuser(void* lpObj);
int cloudkeys_amazonkms_setproxyuser(void* lpObj, const char* lpszProxyUser);

int GetProxyAuthScheme();
int SetProxyAuthScheme(int iProxyAuthScheme);

bool GetProxyAutoDetect();
int SetProxyAutoDetect(bool bProxyAutoDetect);

QString GetProxyPassword();
int SetProxyPassword(QString qsProxyPassword);

int GetProxyPort();
int SetProxyPort(int iProxyPort);

QString GetProxyServer();
int SetProxyServer(QString qsProxyServer);

int GetProxySSL();
int SetProxySSL(int iProxySSL);

QString GetProxyUser();
int SetProxyUser(QString qsProxyUser);

Remarks

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

Data Type

CloudKeysProxy

QueryParams Property (AmazonKMS Class)

Additional query parameters to be included in the request.

Syntax

• C++
• C
• Qt

CloudKeysList<CloudKeysQueryParam>* GetQueryParams();
int SetQueryParams(CloudKeysList<CloudKeysQueryParam>* val);

int cloudkeys_amazonkms_getqueryparamcount(void* lpObj);
int cloudkeys_amazonkms_setqueryparamcount(void* lpObj, int iQueryParamCount);

char* cloudkeys_amazonkms_getqueryparamname(void* lpObj, int queryparamindex);
int cloudkeys_amazonkms_setqueryparamname(void* lpObj, int queryparamindex, const char* lpszQueryParamName);

char* cloudkeys_amazonkms_getqueryparamvalue(void* lpObj, int queryparamindex);
int cloudkeys_amazonkms_setqueryparamvalue(void* lpObj, int queryparamindex, const char* lpszQueryParamValue);

int GetQueryParamCount();
int SetQueryParamCount(int iQueryParamCount);

QString GetQueryParamName(int iQueryParamIndex);
int SetQueryParamName(int iQueryParamIndex, QString qsQueryParamName);

QString GetQueryParamValue(int iQueryParamIndex);
int SetQueryParamValue(int iQueryParamIndex, QString qsQueryParamValue);

Remarks

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

Data Type

CloudKeysQueryParam

Region Property (AmazonKMS Class)

The region that the class will make requests against.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetRegion();
int SetRegion(const char* lpszRegion);

Unicode (Windows)
LPWSTR GetRegion();
INT SetRegion(LPCWSTR lpszRegion);

char* cloudkeys_amazonkms_getregion(void* lpObj);
int cloudkeys_amazonkms_setregion(void* lpObj, const char* lpszRegion);

QString GetRegion();
int SetRegion(QString qsRegion);

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.

Data Type

String

SecretKey Property (AmazonKMS Class)

The secret key to use for authentication.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSecretKey();
int SetSecretKey(const char* lpszSecretKey);

Unicode (Windows)
LPWSTR GetSecretKey();
INT SetSecretKey(LPCWSTR lpszSecretKey);

char* cloudkeys_amazonkms_getsecretkey(void* lpObj);
int cloudkeys_amazonkms_setsecretkey(void* lpObj, const char* lpszSecretKey);

QString GetSecretKey();
int SetSecretKey(QString qsSecretKey);

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.

Data Type

String

SSLAcceptServerCert Property (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

CloudKeysCertificate* GetSSLAcceptServerCert();
int SetSSLAcceptServerCert(CloudKeysCertificate* val);

char* cloudkeys_amazonkms_getsslacceptservercerteffectivedate(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertexpirationdate(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertextendedkeyusage(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertfingerprint(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertfingerprintsha1(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertfingerprintsha256(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertissuer(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertprivatekey(void* lpObj);

int cloudkeys_amazonkms_getsslacceptservercertprivatekeyavailable(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertprivatekeycontainer(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertpublickey(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertpublickeyalgorithm(void* lpObj);

int cloudkeys_amazonkms_getsslacceptservercertpublickeylength(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertserialnumber(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertsignaturealgorithm(void* lpObj);

int cloudkeys_amazonkms_getsslacceptservercertstore(void* lpObj, char** lpSSLAcceptServerCertStore, int* lenSSLAcceptServerCertStore);
int cloudkeys_amazonkms_setsslacceptservercertstore(void* lpObj, const char* lpSSLAcceptServerCertStore, int lenSSLAcceptServerCertStore);

char* cloudkeys_amazonkms_getsslacceptservercertstorepassword(void* lpObj);
int cloudkeys_amazonkms_setsslacceptservercertstorepassword(void* lpObj, const char* lpszSSLAcceptServerCertStorePassword);

int cloudkeys_amazonkms_getsslacceptservercertstoretype(void* lpObj);
int cloudkeys_amazonkms_setsslacceptservercertstoretype(void* lpObj, int iSSLAcceptServerCertStoreType);

char* cloudkeys_amazonkms_getsslacceptservercertsubjectaltnames(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertthumbprintmd5(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertthumbprintsha1(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertthumbprintsha256(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertusage(void* lpObj);

int cloudkeys_amazonkms_getsslacceptservercertusageflags(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertversion(void* lpObj);

char* cloudkeys_amazonkms_getsslacceptservercertsubject(void* lpObj);
int cloudkeys_amazonkms_setsslacceptservercertsubject(void* lpObj, const char* lpszSSLAcceptServerCertSubject);

int cloudkeys_amazonkms_getsslacceptservercertencoded(void* lpObj, char** lpSSLAcceptServerCertEncoded, int* lenSSLAcceptServerCertEncoded);
int cloudkeys_amazonkms_setsslacceptservercertencoded(void* lpObj, const char* lpSSLAcceptServerCertEncoded, int lenSSLAcceptServerCertEncoded);

QString GetSSLAcceptServerCertEffectiveDate();

QString GetSSLAcceptServerCertExpirationDate();

QString GetSSLAcceptServerCertExtendedKeyUsage();

QString GetSSLAcceptServerCertFingerprint();

QString GetSSLAcceptServerCertFingerprintSHA1();

QString GetSSLAcceptServerCertFingerprintSHA256();

QString GetSSLAcceptServerCertIssuer();

QString GetSSLAcceptServerCertPrivateKey();

bool GetSSLAcceptServerCertPrivateKeyAvailable();

QString GetSSLAcceptServerCertPrivateKeyContainer();

QString GetSSLAcceptServerCertPublicKey();

QString GetSSLAcceptServerCertPublicKeyAlgorithm();

int GetSSLAcceptServerCertPublicKeyLength();

QString GetSSLAcceptServerCertSerialNumber();

QString GetSSLAcceptServerCertSignatureAlgorithm();

QByteArray GetSSLAcceptServerCertStore();
int SetSSLAcceptServerCertStore(QByteArray qbaSSLAcceptServerCertStore);

QString GetSSLAcceptServerCertStorePassword();
int SetSSLAcceptServerCertStorePassword(QString qsSSLAcceptServerCertStorePassword);

int GetSSLAcceptServerCertStoreType();
int SetSSLAcceptServerCertStoreType(int iSSLAcceptServerCertStoreType);

QString GetSSLAcceptServerCertSubjectAltNames();

QString GetSSLAcceptServerCertThumbprintMD5();

QString GetSSLAcceptServerCertThumbprintSHA1();

QString GetSSLAcceptServerCertThumbprintSHA256();

QString GetSSLAcceptServerCertUsage();

int GetSSLAcceptServerCertUsageFlags();

QString GetSSLAcceptServerCertVersion();

QString GetSSLAcceptServerCertSubject();
int SetSSLAcceptServerCertSubject(QString qsSSLAcceptServerCertSubject);

QByteArray GetSSLAcceptServerCertEncoded();
int SetSSLAcceptServerCertEncoded(QByteArray qbaSSLAcceptServerCertEncoded);

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.

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.

Data Type

CloudKeysCertificate

SSLCert Property (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

CloudKeysCertificate* GetSSLCert();
int SetSSLCert(CloudKeysCertificate* val);

char* cloudkeys_amazonkms_getsslcerteffectivedate(void* lpObj);

char* cloudkeys_amazonkms_getsslcertexpirationdate(void* lpObj);

char* cloudkeys_amazonkms_getsslcertextendedkeyusage(void* lpObj);

char* cloudkeys_amazonkms_getsslcertfingerprint(void* lpObj);

char* cloudkeys_amazonkms_getsslcertfingerprintsha1(void* lpObj);

char* cloudkeys_amazonkms_getsslcertfingerprintsha256(void* lpObj);

char* cloudkeys_amazonkms_getsslcertissuer(void* lpObj);

char* cloudkeys_amazonkms_getsslcertprivatekey(void* lpObj);

int cloudkeys_amazonkms_getsslcertprivatekeyavailable(void* lpObj);

char* cloudkeys_amazonkms_getsslcertprivatekeycontainer(void* lpObj);

char* cloudkeys_amazonkms_getsslcertpublickey(void* lpObj);

char* cloudkeys_amazonkms_getsslcertpublickeyalgorithm(void* lpObj);

int cloudkeys_amazonkms_getsslcertpublickeylength(void* lpObj);

char* cloudkeys_amazonkms_getsslcertserialnumber(void* lpObj);

char* cloudkeys_amazonkms_getsslcertsignaturealgorithm(void* lpObj);

int cloudkeys_amazonkms_getsslcertstore(void* lpObj, char** lpSSLCertStore, int* lenSSLCertStore);
int cloudkeys_amazonkms_setsslcertstore(void* lpObj, const char* lpSSLCertStore, int lenSSLCertStore);

char* cloudkeys_amazonkms_getsslcertstorepassword(void* lpObj);
int cloudkeys_amazonkms_setsslcertstorepassword(void* lpObj, const char* lpszSSLCertStorePassword);

int cloudkeys_amazonkms_getsslcertstoretype(void* lpObj);
int cloudkeys_amazonkms_setsslcertstoretype(void* lpObj, int iSSLCertStoreType);

char* cloudkeys_amazonkms_getsslcertsubjectaltnames(void* lpObj);

char* cloudkeys_amazonkms_getsslcertthumbprintmd5(void* lpObj);

char* cloudkeys_amazonkms_getsslcertthumbprintsha1(void* lpObj);

char* cloudkeys_amazonkms_getsslcertthumbprintsha256(void* lpObj);

char* cloudkeys_amazonkms_getsslcertusage(void* lpObj);

int cloudkeys_amazonkms_getsslcertusageflags(void* lpObj);

char* cloudkeys_amazonkms_getsslcertversion(void* lpObj);

char* cloudkeys_amazonkms_getsslcertsubject(void* lpObj);
int cloudkeys_amazonkms_setsslcertsubject(void* lpObj, const char* lpszSSLCertSubject);

int cloudkeys_amazonkms_getsslcertencoded(void* lpObj, char** lpSSLCertEncoded, int* lenSSLCertEncoded);
int cloudkeys_amazonkms_setsslcertencoded(void* lpObj, const char* lpSSLCertEncoded, int lenSSLCertEncoded);

QString GetSSLCertEffectiveDate();

QString GetSSLCertExpirationDate();

QString GetSSLCertExtendedKeyUsage();

QString GetSSLCertFingerprint();

QString GetSSLCertFingerprintSHA1();

QString GetSSLCertFingerprintSHA256();

QString GetSSLCertIssuer();

QString GetSSLCertPrivateKey();

bool GetSSLCertPrivateKeyAvailable();

QString GetSSLCertPrivateKeyContainer();

QString GetSSLCertPublicKey();

QString GetSSLCertPublicKeyAlgorithm();

int GetSSLCertPublicKeyLength();

QString GetSSLCertSerialNumber();

QString GetSSLCertSignatureAlgorithm();

QByteArray GetSSLCertStore();
int SetSSLCertStore(QByteArray qbaSSLCertStore);

QString GetSSLCertStorePassword();
int SetSSLCertStorePassword(QString qsSSLCertStorePassword);

int GetSSLCertStoreType();
int SetSSLCertStoreType(int iSSLCertStoreType);

QString GetSSLCertSubjectAltNames();

QString GetSSLCertThumbprintMD5();

QString GetSSLCertThumbprintSHA1();

QString GetSSLCertThumbprintSHA256();

QString GetSSLCertUsage();

int GetSSLCertUsageFlags();

QString GetSSLCertVersion();

QString GetSSLCertSubject();
int SetSSLCertSubject(QString qsSSLCertSubject);

QByteArray GetSSLCertEncoded();
int SetSSLCertEncoded(QByteArray qbaSSLCertEncoded);

Remarks

This property includes 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 Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Data Type

CloudKeysCertificate

SSLProvider Property (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

Unicode (Windows)
INT GetSSLProvider();
INT SetSSLProvider(INT iSSLProvider);

SSLP_AUTOMATIC(0), 
SSLP_PLATFORM(1), 
SSLP_INTERNAL(2)

int cloudkeys_amazonkms_getsslprovider(void* lpObj);
int cloudkeys_amazonkms_setsslprovider(void* lpObj, int iSSLProvider);

int GetSSLProvider();
int SetSSLProvider(int iSSLProvider);

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

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, on Windows, the class will use the platform implementation. On Linux/macOS, the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols, the internal implementation is used on all platforms.

Data Type

Integer

SSLServerCert Property (AmazonKMS Class)

The server certificate for the last established connection.

Syntax

• C++
• C
• Qt

CloudKeysCertificate* GetSSLServerCert();

char* cloudkeys_amazonkms_getsslservercerteffectivedate(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertexpirationdate(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertextendedkeyusage(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertfingerprint(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertfingerprintsha1(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertfingerprintsha256(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertissuer(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertprivatekey(void* lpObj);

int cloudkeys_amazonkms_getsslservercertprivatekeyavailable(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertprivatekeycontainer(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertpublickey(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertpublickeyalgorithm(void* lpObj);

int cloudkeys_amazonkms_getsslservercertpublickeylength(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertserialnumber(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertsignaturealgorithm(void* lpObj);

int cloudkeys_amazonkms_getsslservercertstore(void* lpObj, char** lpSSLServerCertStore, int* lenSSLServerCertStore);

char* cloudkeys_amazonkms_getsslservercertstorepassword(void* lpObj);

int cloudkeys_amazonkms_getsslservercertstoretype(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertsubjectaltnames(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertthumbprintmd5(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertthumbprintsha1(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertthumbprintsha256(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertusage(void* lpObj);

int cloudkeys_amazonkms_getsslservercertusageflags(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertversion(void* lpObj);

char* cloudkeys_amazonkms_getsslservercertsubject(void* lpObj);

int cloudkeys_amazonkms_getsslservercertencoded(void* lpObj, char** lpSSLServerCertEncoded, int* lenSSLServerCertEncoded);

QString GetSSLServerCertEffectiveDate();

QString GetSSLServerCertExpirationDate();

QString GetSSLServerCertExtendedKeyUsage();

QString GetSSLServerCertFingerprint();

QString GetSSLServerCertFingerprintSHA1();

QString GetSSLServerCertFingerprintSHA256();

QString GetSSLServerCertIssuer();

QString GetSSLServerCertPrivateKey();

bool GetSSLServerCertPrivateKeyAvailable();

QString GetSSLServerCertPrivateKeyContainer();

QString GetSSLServerCertPublicKey();

QString GetSSLServerCertPublicKeyAlgorithm();

int GetSSLServerCertPublicKeyLength();

QString GetSSLServerCertSerialNumber();

QString GetSSLServerCertSignatureAlgorithm();

QByteArray GetSSLServerCertStore();

QString GetSSLServerCertStorePassword();

int GetSSLServerCertStoreType();

QString GetSSLServerCertSubjectAltNames();

QString GetSSLServerCertThumbprintMD5();

QString GetSSLServerCertThumbprintSHA1();

QString GetSSLServerCertThumbprintSHA256();

QString GetSSLServerCertUsage();

int GetSSLServerCertUsageFlags();

QString GetSSLServerCertVersion();

QString GetSSLServerCertSubject();

QByteArray GetSSLServerCertEncoded();

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.

Data Type

CloudKeysCertificate

Timeout Property (AmazonKMS Class)

The timeout for the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTimeout();
int SetTimeout(int iTimeout);

Unicode (Windows)
INT GetTimeout();
INT SetTimeout(INT iTimeout);

int cloudkeys_amazonkms_gettimeout(void* lpObj);
int cloudkeys_amazonkms_settimeout(void* lpObj, int iTimeout);

int GetTimeout();
int SetTimeout(int iTimeout);

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 fails with an error.

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.

Data Type

Integer

AddEncryptionContextItem Method (AmazonKMS Class)

Adds an item to the EncryptionContext properties.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddEncryptionContextItem(const char* lpszName, const char* lpszValue);

Unicode (Windows)
INT AddEncryptionContextItem(LPCWSTR lpszName, LPCWSTR lpszValue);

int cloudkeys_amazonkms_addencryptioncontextitem(void* lpObj, const char* lpszName, const char* lpszValue);

int AddEncryptionContextItem(const QString& qsName, const QString& qsValue);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

AddQueryParam Method (AmazonKMS Class)

Adds a query parameter to the QueryParams properties.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddQueryParam(const char* lpszName, const char* lpszValue);

Unicode (Windows)
INT AddQueryParam(LPCWSTR lpszName, LPCWSTR lpszValue);

int cloudkeys_amazonkms_addqueryparam(void* lpObj, const char* lpszName, const char* lpszValue);

int AddQueryParam(const QString& qsName, const QString& qsValue);

Remarks

This method is used to add a query parameter to the QueryParams 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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CancelKeyDeletion Method (AmazonKMS Class)

Cancels the deletion of the specified KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CancelKeyDeletion(const char* lpszKeyId);

Unicode (Windows)
INT CancelKeyDeletion(LPCWSTR lpszKeyId);

int cloudkeys_amazonkms_cancelkeydeletion(void* lpObj, const char* lpszKeyId);

int CancelKeyDeletion(const QString& qsKeyId);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ClearKeyData Method (AmazonKMS Class)

Clears information stored in the KeyData properties.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ClearKeyData(int bPlaintextOnly);

Unicode (Windows)
INT ClearKeyData(BOOL bPlaintextOnly);

int cloudkeys_amazonkms_clearkeydata(void* lpObj, int bPlaintextOnly);

int ClearKeyData(bool bPlaintextOnly);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (AmazonKMS Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cloudkeys_amazonkms_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateAlias Method (AmazonKMS Class)

Creates a new alias.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateAlias(const char* lpszName, const char* lpszKeyId);

Unicode (Windows)
INT CreateAlias(LPCWSTR lpszName, LPCWSTR lpszKeyId);

int cloudkeys_amazonkms_createalias(void* lpObj, const char* lpszName, const char* lpszKeyId);

int CreateAlias(const QString& qsName, const QString& qsKeyId);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CreateKey Method (AmazonKMS Class)

Creates a new KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* CreateKey(const char* lpszKeySpec, int bForSigning, const char* lpszDescription);

Unicode (Windows)
LPWSTR CreateKey(LPCWSTR lpszKeySpec, BOOL bForSigning, LPCWSTR lpszDescription);

char* cloudkeys_amazonkms_createkey(void* lpObj, const char* lpszKeySpec, int bForSigning, const char* lpszDescription);

QString CreateKey(const QString& qsKeySpec, bool bForSigning, const QString& qsDescription);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Decrypt Method (AmazonKMS Class)

Decrypts data using a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Decrypt(const char* lpszKeyId, const char* lpszAlgorithm);

Unicode (Windows)
INT Decrypt(LPCWSTR lpszKeyId, LPCWSTR lpszAlgorithm);

int cloudkeys_amazonkms_decrypt(void* lpObj, const char* lpszKeyId, const char* lpszAlgorithm);

int Decrypt(const QString& qsKeyId, const QString& qsAlgorithm);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteAlias Method (AmazonKMS Class)

Deletes an alias.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteAlias(const char* lpszAliasName);

Unicode (Windows)
INT DeleteAlias(LPCWSTR lpszAliasName);

int cloudkeys_amazonkms_deletealias(void* lpObj, const char* lpszAliasName);

int DeleteAlias(const QString& qsAliasName);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DoEvents Method (AmazonKMS Class)

This method processes events from the internal message queue.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();

int cloudkeys_amazonkms_doevents(void* lpObj);

int DoEvents();

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Encrypt Method (AmazonKMS Class)

Encrypts data using a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Encrypt(const char* lpszKeyId, const char* lpszAlgorithm);

Unicode (Windows)
INT Encrypt(LPCWSTR lpszKeyId, LPCWSTR lpszAlgorithm);

int cloudkeys_amazonkms_encrypt(void* lpObj, const char* lpszKeyId, const char* lpszAlgorithm);

int Encrypt(const QString& qsKeyId, const QString& qsAlgorithm);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GenerateDataKey Method (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GenerateDataKey(const char* lpszKeySpec, const char* lpszKeyId, int bIncludePlaintext);

Unicode (Windows)
INT GenerateDataKey(LPCWSTR lpszKeySpec, LPCWSTR lpszKeyId, BOOL bIncludePlaintext);

int cloudkeys_amazonkms_generatedatakey(void* lpObj, const char* lpszKeySpec, const char* lpszKeyId, int bIncludePlaintext);

int GenerateDataKey(const QString& qsKeySpec, const QString& qsKeyId, bool bIncludePlaintext);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GenerateDataKeyPair Method (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GenerateDataKeyPair(const char* lpszKeyPairSpec, const char* lpszKeyId, int bIncludePlaintext);

Unicode (Windows)
INT GenerateDataKeyPair(LPCWSTR lpszKeyPairSpec, LPCWSTR lpszKeyId, BOOL bIncludePlaintext);

int cloudkeys_amazonkms_generatedatakeypair(void* lpObj, const char* lpszKeyPairSpec, const char* lpszKeyId, int bIncludePlaintext);

int GenerateDataKeyPair(const QString& qsKeyPairSpec, const QString& qsKeyId, bool bIncludePlaintext);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GenerateRandomBytes Method (AmazonKMS Class)

Generates a cryptographically-secure random byte string.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GenerateRandomBytes(int iNumBytes);

Unicode (Windows)
INT GenerateRandomBytes(INT iNumBytes);

int cloudkeys_amazonkms_generaterandombytes(void* lpObj, int iNumBytes);

int GenerateRandomBytes(int iNumBytes);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetKeyInfo Method (AmazonKMS Class)

Gets information about a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetKeyInfo(const char* lpszKeyId);

Unicode (Windows)
INT GetKeyInfo(LPCWSTR lpszKeyId);

int cloudkeys_amazonkms_getkeyinfo(void* lpObj, const char* lpszKeyId);

int GetKeyInfo(const QString& qsKeyId);

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetKeyRotationStatus Method (AmazonKMS Class)

Retrieves the key rotation status for a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool GetKeyRotationStatus(const char* lpszKeyId);

Unicode (Windows)
INT GetKeyRotationStatus(LPCWSTR lpszKeyId);

bool cloudkeys_amazonkms_getkeyrotationstatus(void* lpObj, const char* lpszKeyId);

bool GetKeyRotationStatus(const QString& qsKeyId);

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.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetPublicKey Method (AmazonKMS Class)

Retrieves the public key of an asymmetric KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPublicKey(const char* lpszKeyId);

Unicode (Windows)
INT GetPublicKey(LPCWSTR lpszKeyId);

int cloudkeys_amazonkms_getpublickey(void* lpObj, const char* lpszKeyId);

int GetPublicKey(const QString& qsKeyId);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ListAliases Method (AmazonKMS Class)

Lists aliases in the current account and region.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListAliases(const char* lpszForKeyId);

Unicode (Windows)
INT ListAliases(LPCWSTR lpszForKeyId);

int cloudkeys_amazonkms_listaliases(void* lpObj, const char* lpszForKeyId);

int ListAliases(const QString& qsForKeyId);

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

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ListKeys Method (AmazonKMS Class)

Lists KMS keys in the current account and region.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListKeys();

Unicode (Windows)
INT ListKeys();

int cloudkeys_amazonkms_listkeys(void* lpObj);

int ListKeys();

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 properties. 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 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 Keys properties.

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ReEncrypt Method (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ReEncrypt(const char* lpszOldKeyId, const char* lpszOldAlgorithm, const char* lpszNewKeyId, const char* lpszNewAlgorithm);

Unicode (Windows)
INT ReEncrypt(LPCWSTR lpszOldKeyId, LPCWSTR lpszOldAlgorithm, LPCWSTR lpszNewKeyId, LPCWSTR lpszNewAlgorithm);

int cloudkeys_amazonkms_reencrypt(void* lpObj, const char* lpszOldKeyId, const char* lpszOldAlgorithm, const char* lpszNewKeyId, const char* lpszNewAlgorithm);

int ReEncrypt(const QString& qsOldKeyId, const QString& qsOldAlgorithm, const QString& qsNewKeyId, const QString& qsNewAlgorithm);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (AmazonKMS Class)

Resets the class to its initial state.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int cloudkeys_amazonkms_reset(void* lpObj);

int Reset();

Remarks

This method resets the class to its initial state.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ScheduleKeyDeletion Method (AmazonKMS Class)

Schedules the deletion of a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ScheduleKeyDeletion(const char* lpszKeyId, int iDaysToWait);

Unicode (Windows)
INT ScheduleKeyDeletion(LPCWSTR lpszKeyId, INT iDaysToWait);

int cloudkeys_amazonkms_schedulekeydeletion(void* lpObj, const char* lpszKeyId, int iDaysToWait);

int ScheduleKeyDeletion(const QString& qsKeyId, int iDaysToWait);

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SendCustomRequest Method (AmazonKMS Class)

Sends a custom request to the server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SendCustomRequest(const char* lpszAction);

Unicode (Windows)
INT SendCustomRequest(LPCWSTR lpszAction);

int cloudkeys_amazonkms_sendcustomrequest(void* lpObj, const char* lpszAction);

int SendCustomRequest(const QString& qsAction);

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
   • 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 properties; 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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetInputStream Method (AmazonKMS Class)

Sets the stream whose data should be processed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetInputStream(CloudKeysStream* sInputStream);

Unicode (Windows)
INT SetInputStream(CloudKeysStream* sInputStream);

int cloudkeys_amazonkms_setinputstream(void* lpObj, CloudKeysStream* sInputStream);

int SetInputStream(CloudKeysStream* sInputStream);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetKeyEnabled Method (AmazonKMS Class)

Enables or disables a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetKeyEnabled(const char* lpszKeyId, int bEnabled);

Unicode (Windows)
INT SetKeyEnabled(LPCWSTR lpszKeyId, BOOL bEnabled);

int cloudkeys_amazonkms_setkeyenabled(void* lpObj, const char* lpszKeyId, int bEnabled);

int SetKeyEnabled(const QString& qsKeyId, bool bEnabled);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetKeyRotationStatus Method (AmazonKMS Class)

Enables or disables automatic key rotation for a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetKeyRotationStatus(const char* lpszKeyId, int bEnabled);

Unicode (Windows)
INT SetKeyRotationStatus(LPCWSTR lpszKeyId, BOOL bEnabled);

int cloudkeys_amazonkms_setkeyrotationstatus(void* lpObj, const char* lpszKeyId, int bEnabled);

int SetKeyRotationStatus(const QString& qsKeyId, bool bEnabled);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetOutputStream Method (AmazonKMS Class)

Sets the stream to which output data should be written.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetOutputStream(CloudKeysStream* sOutputStream);

Unicode (Windows)
INT SetOutputStream(CloudKeysStream* sOutputStream);

int cloudkeys_amazonkms_setoutputstream(void* lpObj, CloudKeysStream* sOutputStream);

int SetOutputStream(CloudKeysStream* sOutputStream);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Sign Method (AmazonKMS Class)

Signs a message using a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Sign(const char* lpszKeyId, const char* lpszAlgorithm, int bIsDigest);

Unicode (Windows)
INT Sign(LPCWSTR lpszKeyId, LPCWSTR lpszAlgorithm, BOOL bIsDigest);

int cloudkeys_amazonkms_sign(void* lpObj, const char* lpszKeyId, const char* lpszAlgorithm, int bIsDigest);

int Sign(const QString& qsKeyId, const QString& qsAlgorithm, bool bIsDigest);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UpdateAlias Method (AmazonKMS Class)

Updates an alias to refer to a different KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UpdateAlias(const char* lpszAliasName, const char* lpszNewKeyId);

Unicode (Windows)
INT UpdateAlias(LPCWSTR lpszAliasName, LPCWSTR lpszNewKeyId);

int cloudkeys_amazonkms_updatealias(void* lpObj, const char* lpszAliasName, const char* lpszNewKeyId);

int UpdateAlias(const QString& qsAliasName, const QString& qsNewKeyId);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UpdateKeyDescription Method (AmazonKMS Class)

Updates a KMS key's description.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UpdateKeyDescription(const char* lpszKeyId, const char* lpszNewDescription);

Unicode (Windows)
INT UpdateKeyDescription(LPCWSTR lpszKeyId, LPCWSTR lpszNewDescription);

int cloudkeys_amazonkms_updatekeydescription(void* lpObj, const char* lpszKeyId, const char* lpszNewDescription);

int UpdateKeyDescription(const QString& qsKeyId, const QString& qsNewDescription);

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Verify Method (AmazonKMS Class)

Verifies a digital signature using a KMS key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool Verify(const char* lpszKeyId, const char* lpszAlgorithm, int bIsDigest);

Unicode (Windows)
INT Verify(LPCWSTR lpszKeyId, LPCWSTR lpszAlgorithm, BOOL bIsDigest);

bool cloudkeys_amazonkms_verify(void* lpObj, const char* lpszKeyId, const char* lpszAlgorithm, int bIsDigest);

bool Verify(const QString& qsKeyId, const QString& qsAlgorithm, bool bIsDigest);

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AliasList Event (AmazonKMS Class)

Fires once for each alias when listing aliases.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAliasList(AmazonKMSAliasListEventParams *e);

typedef struct {
  const char *ARN;
  const char *Name;
  const char *KeyId;
  int reserved;
} AmazonKMSAliasListEventParams;


Unicode (Windows)
virtual INT FireAliasList(AmazonKMSAliasListEventParams *e);

typedef struct {
  LPCWSTR ARN;
  LPCWSTR Name;
  LPCWSTR KeyId;
  INT reserved;
} AmazonKMSAliasListEventParams;

#define EID_AMAZONKMS_ALIASLIST 1

virtual INT CLOUDKEYS_CALL FireAliasList(LPSTR &lpszARN, LPSTR &lpszName, LPSTR &lpszKeyId);

class AmazonKMSAliasListEventParams {
public:
  const QString &ARN();

  const QString &Name();

  const QString &KeyId();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void AliasList(AmazonKMSAliasListEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireAliasList(AmazonKMSAliasListEventParams *e) {...}

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

This event fires when a document finishes transferring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireEndTransfer(AmazonKMSEndTransferEventParams *e);

typedef struct {
  int Direction;
  int reserved;
} AmazonKMSEndTransferEventParams;


Unicode (Windows)
virtual INT FireEndTransfer(AmazonKMSEndTransferEventParams *e);

typedef struct {
  INT Direction;
  INT reserved;
} AmazonKMSEndTransferEventParams;

#define EID_AMAZONKMS_ENDTRANSFER 2

virtual INT CLOUDKEYS_CALL FireEndTransfer(INT &iDirection);

class AmazonKMSEndTransferEventParams {
public:
  int Direction();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void EndTransfer(AmazonKMSEndTransferEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireEndTransfer(AmazonKMSEndTransferEventParams *e) {...}

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

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(AmazonKMSErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} AmazonKMSErrorEventParams;


Unicode (Windows)
virtual INT FireError(AmazonKMSErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} AmazonKMSErrorEventParams;

#define EID_AMAZONKMS_ERROR 3

virtual INT CLOUDKEYS_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class AmazonKMSErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(AmazonKMSErrorEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireError(AmazonKMSErrorEventParams *e) {...}

Remarks

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

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

Fired every time a header line comes in.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireHeader(AmazonKMSHeaderEventParams *e);

typedef struct {
  const char *Field;
  const char *Value;
  int reserved;
} AmazonKMSHeaderEventParams;


Unicode (Windows)
virtual INT FireHeader(AmazonKMSHeaderEventParams *e);

typedef struct {
  LPCWSTR Field;
  LPCWSTR Value;
  INT reserved;
} AmazonKMSHeaderEventParams;

#define EID_AMAZONKMS_HEADER 4

virtual INT CLOUDKEYS_CALL FireHeader(LPSTR &lpszField, LPSTR &lpszValue);

class AmazonKMSHeaderEventParams {
public:
  const QString &Field();

  const QString &Value();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Header(AmazonKMSHeaderEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireHeader(AmazonKMSHeaderEventParams *e) {...}

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

Fires once for each KMS key when listing KMS keys.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireKeyList(AmazonKMSKeyListEventParams *e);

typedef struct {
  const char *ARN;
  const char *Id;
  const char *AccountId;
  const char *Description;
  int Enabled;
  int AWSManaged;
  int ForSigning;
  const char *KeySpec;
  const char *Algorithms;
  int State;
  const char *CreationDate;
  const char *DeletionDate;
  int reserved;
} AmazonKMSKeyListEventParams;


Unicode (Windows)
virtual INT FireKeyList(AmazonKMSKeyListEventParams *e);

typedef struct {
  LPCWSTR ARN;
  LPCWSTR Id;
  LPCWSTR AccountId;
  LPCWSTR Description;
  BOOL Enabled;
  BOOL AWSManaged;
  BOOL ForSigning;
  LPCWSTR KeySpec;
  LPCWSTR Algorithms;
  INT State;
  LPCWSTR CreationDate;
  LPCWSTR DeletionDate;
  INT reserved;
} AmazonKMSKeyListEventParams;

#define EID_AMAZONKMS_KEYLIST 5

virtual INT CLOUDKEYS_CALL FireKeyList(LPSTR &lpszARN, LPSTR &lpszId, LPSTR &lpszAccountId, LPSTR &lpszDescription, BOOL &bEnabled, BOOL &bAWSManaged, BOOL &bForSigning, LPSTR &lpszKeySpec, LPSTR &lpszAlgorithms, INT &iState, LPSTR &lpszCreationDate, LPSTR &lpszDeletionDate);

class AmazonKMSKeyListEventParams {
public:
  const QString &ARN();

  const QString &Id();

  const QString &AccountId();

  const QString &Description();

  bool Enabled();

  bool AWSManaged();

  bool ForSigning();

  const QString &KeySpec();

  const QString &Algorithms();

  int State();

  const QString &CreationDate();

  const QString &DeletionDate();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void KeyList(AmazonKMSKeyListEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireKeyList(AmazonKMSKeyListEventParams *e) {...}

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

Fired once for each log message.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireLog(AmazonKMSLogEventParams *e);

typedef struct {
  int LogLevel;
  const char *Message;
  const char *LogType;
  int reserved;
} AmazonKMSLogEventParams;


Unicode (Windows)
virtual INT FireLog(AmazonKMSLogEventParams *e);

typedef struct {
  INT LogLevel;
  LPCWSTR Message;
  LPCWSTR LogType;
  INT reserved;
} AmazonKMSLogEventParams;

#define EID_AMAZONKMS_LOG 6

virtual INT CLOUDKEYS_CALL FireLog(INT &iLogLevel, LPSTR &lpszMessage, LPSTR &lpszLogType);

class AmazonKMSLogEventParams {
public:
  int LogLevel();

  const QString &Message();

  const QString &LogType();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Log(AmazonKMSLogEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireLog(AmazonKMSLogEventParams *e) {...}

Remarks

This event is fired 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"

SSLServerAuthentication Event (AmazonKMS Class)

Fired after the server presents its certificate to the client.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLServerAuthentication(AmazonKMSSSLServerAuthenticationEventParams *e);

typedef struct {
  const char *CertEncoded;
  int lenCertEncoded;
  const char *CertSubject;
  const char *CertIssuer;
  const char *Status;
  int Accept;
  int reserved;
} AmazonKMSSSLServerAuthenticationEventParams;


Unicode (Windows)
virtual INT FireSSLServerAuthentication(AmazonKMSSSLServerAuthenticationEventParams *e);

typedef struct {
  LPCSTR CertEncoded;
  INT lenCertEncoded;
  LPCWSTR CertSubject;
  LPCWSTR CertIssuer;
  LPCWSTR Status;
  BOOL Accept;
  INT reserved;
} AmazonKMSSSLServerAuthenticationEventParams;

#define EID_AMAZONKMS_SSLSERVERAUTHENTICATION 7

virtual INT CLOUDKEYS_CALL FireSSLServerAuthentication(LPSTR &lpCertEncoded, INT &lenCertEncoded, LPSTR &lpszCertSubject, LPSTR &lpszCertIssuer, LPSTR &lpszStatus, BOOL &bAccept);

class AmazonKMSSSLServerAuthenticationEventParams {
public:
  const QByteArray &CertEncoded();

  const QString &CertSubject();

  const QString &CertIssuer();

  const QString &Status();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLServerAuthentication(AmazonKMSSSLServerAuthenticationEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireSSLServerAuthentication(AmazonKMSSSLServerAuthenticationEventParams *e) {...}

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

Fired when secure connection progress messages are available.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSSLStatus(AmazonKMSSSLStatusEventParams *e);

typedef struct {
  const char *Message;
  int reserved;
} AmazonKMSSSLStatusEventParams;


Unicode (Windows)
virtual INT FireSSLStatus(AmazonKMSSSLStatusEventParams *e);

typedef struct {
  LPCWSTR Message;
  INT reserved;
} AmazonKMSSSLStatusEventParams;

#define EID_AMAZONKMS_SSLSTATUS 8

virtual INT CLOUDKEYS_CALL FireSSLStatus(LPSTR &lpszMessage);

class AmazonKMSSSLStatusEventParams {
public:
  const QString &Message();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SSLStatus(AmazonKMSSSLStatusEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireSSLStatus(AmazonKMSSSLStatusEventParams *e) {...}

Remarks

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

StartTransfer Event (AmazonKMS Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireStartTransfer(AmazonKMSStartTransferEventParams *e);

typedef struct {
  int Direction;
  int reserved;
} AmazonKMSStartTransferEventParams;


Unicode (Windows)
virtual INT FireStartTransfer(AmazonKMSStartTransferEventParams *e);

typedef struct {
  INT Direction;
  INT reserved;
} AmazonKMSStartTransferEventParams;

#define EID_AMAZONKMS_STARTTRANSFER 9

virtual INT CLOUDKEYS_CALL FireStartTransfer(INT &iDirection);

class AmazonKMSStartTransferEventParams {
public:
  int Direction();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void StartTransfer(AmazonKMSStartTransferEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireStartTransfer(AmazonKMSStartTransferEventParams *e) {...}

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

Fired while a document transfers (delivers document).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTransfer(AmazonKMSTransferEventParams *e);

typedef struct {
  int Direction;
  int64 BytesTransferred;
  int PercentDone;
  const char *Text;
  int lenText;
  int reserved;
} AmazonKMSTransferEventParams;


Unicode (Windows)
virtual INT FireTransfer(AmazonKMSTransferEventParams *e);

typedef struct {
  INT Direction;
  LONG64 BytesTransferred;
  INT PercentDone;
  LPCSTR Text;
  INT lenText;
  INT reserved;
} AmazonKMSTransferEventParams;

#define EID_AMAZONKMS_TRANSFER 10

virtual INT CLOUDKEYS_CALL FireTransfer(INT &iDirection, LONG64 &lBytesTransferred, INT &iPercentDone, LPSTR &lpText, INT &lenText);

class AmazonKMSTransferEventParams {
public:
  int Direction();

  qint64 BytesTransferred();

  int PercentDone();

  const QByteArray &Text();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Transfer(AmazonKMSTransferEventParams *e);

// Or, subclass AmazonKMS and override this emitter function.
virtual int FireTransfer(AmazonKMSTransferEventParams *e) {...}

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.

Syntax

CloudKeysAWSAlias (declared in cloudkeys.h)

Remarks

This type represents an Amazon KMS alias.

Fields

AWSContextItem Type

An Amazon KMS encryption context item.

Syntax

CloudKeysAWSContextItem (declared in cloudkeys.h)

Remarks

This type represents an Amazon KMS encryption context item.

Fields

Constructors

AWSContextItem()

AWSContextItem(const char* lpszName, const char* lpszValue)

AWSKey Type

An AWS KMS key.

Syntax

CloudKeysAWSKey (declared in cloudkeys.h)

Remarks

This type represents an AWS KMS key.

Fields

AWSKeyData Type

Key information downloaded from Amazon KMS.

Syntax

CloudKeysAWSKeyData (declared in cloudkeys.h)

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.

Syntax

CloudKeysCertificate (declared in cloudkeys.h)

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

Certificate()

Certificate(const char* lpEncoded, int lenEncoded)

Certificate(int iStoreType, const char* lpStore, int lenStore, const char* lpszStorePassword, const char* lpszSubject)

Firewall Type

The firewall the component will connect through.

Syntax

CloudKeysFirewall (declared in cloudkeys.h)

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

Firewall()

Header Type

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

Syntax

CloudKeysHeader (declared in cloudkeys.h)

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

Header()

Header(const char* lpszField, const char* lpszValue)

Proxy Type

The proxy the component will connect to.

Syntax

CloudKeysProxy (declared in cloudkeys.h)

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

Proxy()

Proxy(const char* lpszServer, int iPort)

Proxy(const char* lpszServer, int iPort, const char* lpszUser, const char* lpszPassword)

QueryParam Type

A query parameter to send in the request.

Syntax

CloudKeysQueryParam (declared in cloudkeys.h)

Remarks

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

Fields

Constructors

QueryParam()

QueryParam(const char* lpszName, const char* lpszValue)

CloudKeysList Type

Syntax

CloudKeysList<T> (declared in cloudkeys.h)

Remarks

CloudKeysList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the AmazonKMS class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

CloudKeysStream Type

Syntax

CloudKeysStream (declared in cloudkeys.h)

Remarks

The AmazonKMS class includes one or more API members that take a stream object as a parameter. To use such API members, create a concrete class that implements the CloudKeysStream interface and pass the AmazonKMS class an instance of that concrete class.

When implementing the CloudKeysStream interface's properties and methods, they must behave as described below. If the concrete class's implementation does not behave as expected, undefined behavior may occur.