AmazonKMS Class

Properties   Methods   Events   Config Settings   Errors  

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

Class Name

CloudKeys_AmazonKMS

Procedural Interface

 cloudkeys_amazonkms_open();
 cloudkeys_amazonkms_close($res);
 cloudkeys_amazonkms_register_callback($res, $id, $function);
 cloudkeys_amazonkms_get_last_error($res);
 cloudkeys_amazonkms_get_last_error_code($res);
 cloudkeys_amazonkms_set($res, $id, $index, $value);
 cloudkeys_amazonkms_get($res, $id, $index);
 cloudkeys_amazonkms_do_addencryptioncontextitem($res, $name, $value);
 cloudkeys_amazonkms_do_addqueryparam($res, $name, $value);
 cloudkeys_amazonkms_do_cancelkeydeletion($res, $keyid);
 cloudkeys_amazonkms_do_clearkeydata($res, $plaintextonly);
 cloudkeys_amazonkms_do_config($res, $configurationstring);
 cloudkeys_amazonkms_do_createalias($res, $name, $keyid);
 cloudkeys_amazonkms_do_createkey($res, $keyspec, $forsigning, $description);
 cloudkeys_amazonkms_do_decrypt($res, $keyid, $algorithm);
 cloudkeys_amazonkms_do_deletealias($res, $aliasname);
 cloudkeys_amazonkms_do_doevents($res);
 cloudkeys_amazonkms_do_encrypt($res, $keyid, $algorithm);
 cloudkeys_amazonkms_do_generatedatakey($res, $keyspec, $keyid, $includeplaintext);
 cloudkeys_amazonkms_do_generatedatakeypair($res, $keypairspec, $keyid, $includeplaintext);
 cloudkeys_amazonkms_do_generaterandombytes($res, $numbytes);
 cloudkeys_amazonkms_do_getkeyinfo($res, $keyid);
 cloudkeys_amazonkms_do_getkeyrotationstatus($res, $keyid);
 cloudkeys_amazonkms_do_getpublickey($res, $keyid);
 cloudkeys_amazonkms_do_listaliases($res, $forkeyid);
 cloudkeys_amazonkms_do_listkeys($res);
 cloudkeys_amazonkms_do_reencrypt($res, $oldkeyid, $oldalgorithm, $newkeyid, $newalgorithm);
 cloudkeys_amazonkms_do_reset($res);
 cloudkeys_amazonkms_do_schedulekeydeletion($res, $keyid, $daystowait);
 cloudkeys_amazonkms_do_sendcustomrequest($res, $action);
 cloudkeys_amazonkms_do_setkeyenabled($res, $keyid, $enabled);
 cloudkeys_amazonkms_do_setkeyrotationstatus($res, $keyid, $enabled);
 cloudkeys_amazonkms_do_sign($res, $keyid, $algorithm, $isdigest);
 cloudkeys_amazonkms_do_updatealias($res, $aliasname, $newkeyid);
 cloudkeys_amazonkms_do_updatekeydescription($res, $keyid, $newdescription);
 cloudkeys_amazonkms_do_verify($res, $keyid, $algorithm, $isdigest);

Remarks

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

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

Resource Terminology

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

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

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

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

Using the Class

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

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

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

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

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

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

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

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

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

Property List

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

Method List

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

Event List

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

Config Settings

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

AccessKey Property (CloudKeys_AmazonKMS Class)

The access key to use for authentication.

Object Oriented Interface

public function getAccessKey();


public function setAccessKey($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 1 );


cloudkeys_amazonkms_set($res, 1, $value );

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

AliasCount Property (CloudKeys_AmazonKMS Class)

The number of records in the Alias arrays.

Object Oriented Interface

public function getAliasCount();

Procedural Interface

cloudkeys_amazonkms_get($res, 2 );

Default Value

0

Remarks

This property controls the size of the following arrays:

• AliasARN
• AliasKeyId
• AliasName

The array indices start at 0 and end at AliasCount - 1.

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

Data Type

Integer

AliasARN Property (CloudKeys_AmazonKMS Class)

The Amazon resource name (ARN) of the alias.

Object Oriented Interface

public function getAliasARN($aliasindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 3 , $aliasindex);

Default Value

''

Remarks

The Amazon resource name (ARN) of the alias.

This property reflects the Amazon resource name (ARN) of the alias.

The $aliasindex parameter specifies the index of the item in the array. The size of the array is controlled by the AliasCount property.

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

Data Type

String

AliasKeyId Property (CloudKeys_AmazonKMS Class)

The Id of the KMS key that the alias is associated with.

Object Oriented Interface

public function getAliasKeyId($aliasindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 4 , $aliasindex);

Default Value

''

Remarks

The Id of the KMS key that the alias is associated with.

This property reflects the Id of the KMS key that the alias is associated with.

Note that AWS pre-creates certain aliases, so it is possible for this property to be empty.

The $aliasindex parameter specifies the index of the item in the array. The size of the array is controlled by the AliasCount property.

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

Data Type

String

AliasName Property (CloudKeys_AmazonKMS Class)

The name of the alias.

Object Oriented Interface

public function getAliasName($aliasindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 5 , $aliasindex);

Default Value

''

Remarks

The name of the alias.

This property reflects the name of the alias, including the alias/ prefix.

The $aliasindex parameter specifies the index of the item in the array. The size of the array is controlled by the AliasCount property.

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

Data Type

String

AliasMarker Property (CloudKeys_AmazonKMS Class)

A marker indicating what page of aliases to return next.

Object Oriented Interface

public function getAliasMarker();


public function setAliasMarker($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 6 );


cloudkeys_amazonkms_set($res, 6, $value );

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

EncryptionContextCount Property (CloudKeys_AmazonKMS Class)

The number of records in the EncryptionContext arrays.

Object Oriented Interface

public function getEncryptionContextCount();


public function setEncryptionContextCount($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 7 );


cloudkeys_amazonkms_set($res, 7, $value );

Default Value

0

Remarks

This property controls the size of the following arrays:

• EncryptionContextName
• EncryptionContextValue

The array indices start at 0 and end at EncryptionContextCount - 1.

This property is not available at design time.

Data Type

Integer

EncryptionContextName Property (CloudKeys_AmazonKMS Class)

The name of the context item.

Object Oriented Interface

public function getEncryptionContextName($encryptioncontextindex);


public function setEncryptionContextName($encryptioncontextindex, $value);

Procedural Interface

cloudkeys_amazonkms_get($res, 8 , $encryptioncontextindex);


cloudkeys_amazonkms_set($res, 8, $value , $encryptioncontextindex);

Default Value

''

Remarks

The name of the context item.

This property specifies the name of the context item.

The $encryptioncontextindex parameter specifies the index of the item in the array. The size of the array is controlled by the EncryptionContextCount property.

This property is not available at design time.

Data Type

String

EncryptionContextValue Property (CloudKeys_AmazonKMS Class)

The value of the context item.

Object Oriented Interface

public function getEncryptionContextValue($encryptioncontextindex);


public function setEncryptionContextValue($encryptioncontextindex, $value);

Procedural Interface

cloudkeys_amazonkms_get($res, 9 , $encryptioncontextindex);


cloudkeys_amazonkms_set($res, 9, $value , $encryptioncontextindex);

Default Value

''

Remarks

The value of the context item.

This property specifies the value of the context item.

The $encryptioncontextindex parameter specifies the index of the item in the array. The size of the array is controlled by the EncryptionContextCount property.

This property is not available at design time.

Data Type

String

FirewallAutoDetect Property (CloudKeys_AmazonKMS Class)

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

Object Oriented Interface

public function getFirewallAutoDetect();


public function setFirewallAutoDetect($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 10 );


cloudkeys_amazonkms_set($res, 10, $value );

Default Value

false

Remarks

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

Data Type

Boolean

FirewallType Property (CloudKeys_AmazonKMS Class)

This property determines the type of firewall to connect through.

Object Oriented Interface

public function getFirewallType();


public function setFirewallType($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 11 );


cloudkeys_amazonkms_set($res, 11, $value );

Default Value

0

Remarks

This property determines the type of firewall to connect through. The applicable values are as follows:

Data Type

Integer

FirewallHost Property (CloudKeys_AmazonKMS Class)

This property contains the name or IP address of firewall (optional).

Object Oriented Interface

public function getFirewallHost();


public function setFirewallHost($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 12 );


cloudkeys_amazonkms_set($res, 12, $value );

Default Value

''

Remarks

This property contains the name or IP address of firewall (optional). If a FirewallHost is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the class fails with an error.

Data Type

String

FirewallPassword Property (CloudKeys_AmazonKMS Class)

This property contains a password if authentication is to be used when connecting through the firewall.

Object Oriented Interface

public function getFirewallPassword();


public function setFirewallPassword($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 13 );


cloudkeys_amazonkms_set($res, 13, $value );

Default Value

''

Remarks

This property contains a password if authentication is to be used when connecting through the firewall. If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

Data Type

String

FirewallPort Property (CloudKeys_AmazonKMS Class)

This property contains the transmission control protocol (TCP) port for the firewall Host .

Object Oriented Interface

public function getFirewallPort();


public function setFirewallPort($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 14 );


cloudkeys_amazonkms_set($res, 14, $value );

Default Value

0

Remarks

This property contains the transmission control protocol (TCP) port for the firewall FirewallHost. See the description of the FirewallHost property for details.

Note: This property is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

Data Type

Integer

FirewallUser Property (CloudKeys_AmazonKMS Class)

This property contains a user name if authentication is to be used connecting through a firewall.

Object Oriented Interface

public function getFirewallUser();


public function setFirewallUser($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 15 );


cloudkeys_amazonkms_set($res, 15, $value );

Default Value

''

Remarks

This property contains a user name if authentication is to be used connecting through a firewall. If the FirewallHost is specified, this property and FirewallPassword properties are used to connect and authenticate to the given Firewall. If the authentication fails, the class fails with an error.

Data Type

String

Idle Property (CloudKeys_AmazonKMS Class)

The current status of the class.

Object Oriented Interface

public function getIdle();

Procedural Interface

cloudkeys_amazonkms_get($res, 16 );

Default Value

true

Remarks

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

This property is read-only.

Data Type

Boolean

IncludeKeyDetails Property (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function getIncludeKeyDetails();


public function setIncludeKeyDetails($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 17 );


cloudkeys_amazonkms_set($res, 17, $value );

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 KeyARN and KeyId of each KMS key.

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

This property is not available at design time.

Data Type

Boolean

InputData Property (CloudKeys_AmazonKMS Class)

The data to process.

Object Oriented Interface

public function getInputData();


public function setInputData($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 18 );


cloudkeys_amazonkms_set($res, 18, $value );

Default Value

''

Remarks

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

Input Sources & Output Destinations

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

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

1. The InputFile property
2. The InputData property

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

1. The OutputFile property
2. The OutputData property

This property is not available at design time.

Data Type

Binary String

InputFile Property (CloudKeys_AmazonKMS Class)

The file whose data should be processed.

Object Oriented Interface

public function getInputFile();


public function setInputFile($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 19 );


cloudkeys_amazonkms_set($res, 19, $value );

Default Value

''

Remarks

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

Input Sources & Output Destinations

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

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

1. The InputFile property
2. The InputData property

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

1. The OutputFile property
2. The OutputData property

Data Type

String

KeyDataAlgorithms Property (CloudKeys_AmazonKMS Class)

The algorithms supported by the public key.

Object Oriented Interface

public function getKeyDataAlgorithms();

Procedural Interface

cloudkeys_amazonkms_get($res, 20 );

Default Value

''

Remarks

The algorithms supported by the public key.

When GetPublicKey is called, this property will contain a comma-separated list of algorithms that the KeyPublicKey can be used with. Always empty when GenerateDataKey or GenerateDataKeyPair is called.

If KeyForSigning is false, possible values are:

• SYMMETRIC_DEFAULT
• RSAES_OAEP_SHA_1
• RSAES_OAEP_SHA_256

If KeyForSigning 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

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

Data Type

String

KeyDataARN Property (CloudKeys_AmazonKMS Class)

The Amazon resource name (ARN) of the associated KMS key.

Object Oriented Interface

public function getKeyDataARN();

Procedural Interface

cloudkeys_amazonkms_get($res, 21 );

Default Value

''

Remarks

The Amazon resource name (ARN) of the associated KMS key.

When GetPublicKey is called, this property reflects the Amazon resource name (ARN) of the KMS key whose KeyPublicKey was downloaded.

When GenerateDataKey or GenerateDataKeyPair is called, this property reflects the ARN of the KMS key that encrypted the data key or the data key pair's private key (respectively) that is stored in KeyEncryptedKey.

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

Data Type

String

KeyDataEncryptedKey Property (CloudKeys_AmazonKMS Class)

The encrypted key or private key data.

Object Oriented Interface

public function getKeyDataEncryptedKey();

Procedural Interface

cloudkeys_amazonkms_get($res, 22 );

Default Value

''

Remarks

The encrypted key or private key data.

When GenerateDataKey is called, this property reflects the encrypted data key that was downloaded. When GenerateDataKeyPair is called, this property reflects the encrypted private key of the data key pair that was downloaded.

In the case of GenerateDataKeyPair, note that the actual private key data will be in DER format upon decryption. It is up to the application to convert it to another format after decryption if necessary.

Always empty when GetPublicKey is called.

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

Data Type

Binary String

KeyDataForSigning Property (CloudKeys_AmazonKMS Class)

Whether the public key is for signing or encryption.

Object Oriented Interface

public function getKeyDataForSigning();

Procedural Interface

cloudkeys_amazonkms_get($res, 23 );

Default Value

false

Remarks

Whether the public key is for signing or encryption.

When GetPublicKey is called, this property reflects whether the downloaded KeyPublicKey is to be used for verification (true) or encryption (false).

Always false when GenerateDataKey or GenerateDataKeyPair is called.

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

Data Type

Boolean

KeyDataKeySpec Property (CloudKeys_AmazonKMS Class)

The key spec of the downloaded key data.

Object Oriented Interface

public function getKeyDataKeySpec();

Procedural Interface

cloudkeys_amazonkms_get($res, 24 );

Default Value

''

Remarks

The key spec of the downloaded key data.

When GetPublicKey is called, this property reflects the spec of the KMS key whose KeyPublicKey was downloaded, and the 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)

When GenerateDataKey is called, this property reflects either the spec of the data key or the size of the data key in bytes (whichever was passed to the method); one of:

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

When GenerateDataKeyPair is called, this property reflects the spec of the data key pair, and the possible values are the same as they are for GetPublicKey.

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

Data Type

String

KeyDataPlaintextKey Property (CloudKeys_AmazonKMS Class)

The plaintext key or private key data.

Object Oriented Interface

public function getKeyDataPlaintextKey();

Procedural Interface

cloudkeys_amazonkms_get($res, 25 );

Default Value

''

Remarks

The plaintext key or private key data.

If, when GenerateDataKey or GenerateDataKeyPair is called, the IncludePlaintext parameter was true, this property will reflect the plaintext data key or private key of the data key pair (respectively) that was downloaded. Otherwise, it will be empty.

In the case of GenerateDataKeyPair, this property exposes the private key in PEM format for convenience.

Always empty when GetPublicKey is called.

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

Data Type

Binary String

KeyDataPublicKey Property (CloudKeys_AmazonKMS Class)

The public key.

Object Oriented Interface

public function getKeyDataPublicKey();

Procedural Interface

cloudkeys_amazonkms_get($res, 26 );

Default Value

''

Remarks

The public key.

When GetPublicKey is called, this property will reflect the public key of the KMS key. When GenerateDataKeyPair is called, this property will reflect the public key of the data key pair. The public key is exposed in PEM format for convenience.

Always empty when GenerateDataKey is called.

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

Data Type

String

KeyMarker Property (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function getKeyMarker();


public function setKeyMarker($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 27 );


cloudkeys_amazonkms_set($res, 27, $value );

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

KeyCount Property (CloudKeys_AmazonKMS Class)

The number of records in the Key arrays.

Object Oriented Interface

public function getKeyCount();

Procedural Interface

cloudkeys_amazonkms_get($res, 28 );

Default Value

0

Remarks

This property controls the size of the following arrays:

• KeyAccountId
• KeyAlgorithms
• KeyARN
• KeyAWSManaged
• KeyCloudHSMClusterId
• KeyCreationDate
• KeyCustomKeyStoreId
• KeyDataAlgorithms
• KeyDataARN
• KeyDataEncryptedKey
• KeyDataForSigning
• KeyDataKeySpec
• KeyDataPlaintextKey
• KeyDataPublicKey
• KeyDeletionDate
• KeyDescription
• KeyEnabled
• KeyExpirationDate
• KeyForSigning
• KeyId
• KeyKeySpec
• KeyOrigin
• KeyState

The array indices start at 0 and end at KeyCount - 1.

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

Data Type

Integer

KeyAccountId Property (CloudKeys_AmazonKMS Class)

The Id of the AWS account that owns the KMS key.

Object Oriented Interface

public function getKeyAccountId($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 29 , $keyindex);

Default Value

''

Remarks

The Id of the AWS account that owns the KMS key.

This property reflects the Id of the AWS account that owns the KMS key.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyAlgorithms Property (CloudKeys_AmazonKMS Class)

A comma-separated list of algorithms that the KMS key supports.

Object Oriented Interface

public function getKeyAlgorithms($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 30 , $keyindex);

Default Value

''

Remarks

A comma-separated list of algorithms that the KMS key supports.

This property reflects a comma-separated list of algorithms that the KMS key supports.

If KeyForSigning is false, possible values are:

• SYMMETRIC_DEFAULT
• RSAES_OAEP_SHA_1
• RSAES_OAEP_SHA_256

If KeyForSigning 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

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyARN Property (CloudKeys_AmazonKMS Class)

The Amazon resource name (ARN) of the KMS key.

Object Oriented Interface

public function getKeyARN($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 31 , $keyindex);

Default Value

''

Remarks

The Amazon resource name (ARN) of the KMS key.

This property reflects the Amazon resource name (ARN) of the KMS key.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyAWSManaged Property (CloudKeys_AmazonKMS Class)

Whether the KMS key is AWS-managed.

Object Oriented Interface

public function getKeyAWSManaged($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 32 , $keyindex);

Default Value

false

Remarks

Whether the KMS key is AWS-managed.

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

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyCloudHSMClusterId Property (CloudKeys_AmazonKMS Class)

The Id of the CloudHSM cluster the KMS key's key material resides in, if applicable.

Object Oriented Interface

public function getKeyCloudHSMClusterId($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 33 , $keyindex);

Default Value

''

Remarks

The Id of the CloudHSM cluster the KMS key's key material resides in, if applicable.

If the KMS key resides in a custom key store, this property reflects the Id of the CloudHSM that the KMS key's key material resides in.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyCreationDate Property (CloudKeys_AmazonKMS Class)

The creation date of the KMS key.

Object Oriented Interface

public function getKeyCreationDate($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 34 , $keyindex);

Default Value

''

Remarks

The creation date of the KMS key.

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

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyCustomKeyStoreId Property (CloudKeys_AmazonKMS Class)

The Id of the custom key store that the KMS key resides in, if applicable.

Object Oriented Interface

public function getKeyCustomKeyStoreId($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 35 , $keyindex);

Default Value

''

Remarks

The Id of the custom key store that the KMS key resides in, if applicable.

If the KMS key resides in a custom key store, this property reflects the Id of said custom key store.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyDeletionDate Property (CloudKeys_AmazonKMS Class)

The date at which the KMS key will be deleted, if applicable.

Object Oriented Interface

public function getKeyDeletionDate($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 36 , $keyindex);

Default Value

''

Remarks

The date at which the KMS key will be deleted, if applicable.

If the KMS key's KeyState is aksPendingDeletion (2), this property will reflect the deletion date, in seconds since the Unix epoch (including fractional seconds).

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyDescription Property (CloudKeys_AmazonKMS Class)

The KMS key's description.

Object Oriented Interface

public function getKeyDescription($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 37 , $keyindex);

Default Value

''

Remarks

The KMS key's description.

This property reflects the KMS key's description. To change a KMS key's description, use the UpdateKeyDescription method.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyEnabled Property (CloudKeys_AmazonKMS Class)

Whether the KMS key is enabled.

Object Oriented Interface

public function getKeyEnabled($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 38 , $keyindex);

Default Value

false

Remarks

Whether the KMS key is enabled.

This property reflects whether the KMS key is currently enabled.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyExpirationDate Property (CloudKeys_AmazonKMS Class)

The date at which the KMS key's key material will expire, if applicable.

Object Oriented Interface

public function getKeyExpirationDate($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 39 , $keyindex);

Default Value

''

Remarks

The date at which the KMS key's key material will expire, if applicable.

If the KMS key's key material KeyOrigin is akoExternal (1), and the external key material has an expiration date, this property will reflect said date, in seconds since the Unix epoch (including fractional seconds).

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyForSigning Property (CloudKeys_AmazonKMS Class)

Whether the KMS key is for signing or encryption.

Object Oriented Interface

public function getKeyForSigning($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 40 , $keyindex);

Default Value

false

Remarks

Whether the KMS key is for signing or encryption.

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

A KMS key's usage determines which cryptographic operations it can be used for. For example, a KMS key with signing/verification usage can be used for Sign and Verify operations, but not for Encrypt, Decrypt or ReEncrypt operations.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyId Property (CloudKeys_AmazonKMS Class)

The Id of the KMS key.

Object Oriented Interface

public function getKeyId($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 41 , $keyindex);

Default Value

''

Remarks

The Id of the KMS key.

This property reflects the Id of the KMS key.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyKeySpec Property (CloudKeys_AmazonKMS Class)

The key spec of the KMS key.

Object Oriented Interface

public function getKeyKeySpec($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 42 , $keyindex);

Default Value

''

Remarks

The key spec of the KMS key.

This property 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)

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyOrigin Property (CloudKeys_AmazonKMS Class)

The origin of the KMS key's key material.

Object Oriented Interface

public function getKeyOrigin($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 43 , $keyindex);

Default Value

0

Remarks

The origin of the KMS key's key material.

This property reflects the origin of the KMS key's key material. Possible values are:

• akoKMS (0): Key material from Amazon KMS. (Also the default value used when ListKeys is called.)
• akoExternal (1): External key material imported into Amazon KMS.
• akoCloudHSM (2): Key material from an Amazon CloudHSM cluster.

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Integer

KeyState Property (CloudKeys_AmazonKMS Class)

The KMS key's state.

Object Oriented Interface

public function getKeyState($keyindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 44 , $keyindex);

Default Value

0

Remarks

The KMS key's state.

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

The $keyindex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Integer

LocalHost Property (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function getLocalHost();


public function setLocalHost($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 45 );


cloudkeys_amazonkms_set($res, 45, $value );

Default Value

''

Remarks

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

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

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

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

Data Type

String

OtherHeaders Property (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function getOtherHeaders();


public function setOtherHeaders($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 46 );


cloudkeys_amazonkms_set($res, 46, $value );

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

The output data.

Object Oriented Interface

public function getOutputData();


public function setOutputData($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 47 );


cloudkeys_amazonkms_set($res, 47, $value );

Default Value

''

Remarks

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

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

Input Sources & Output Destinations

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

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

1. The InputFile property
2. The InputData property

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

1. The OutputFile property
2. The OutputData property

This property is not available at design time.

Data Type

Binary String

OutputFile Property (CloudKeys_AmazonKMS Class)

The file to which output data should be written.

Object Oriented Interface

public function getOutputFile();


public function setOutputFile($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 48 );


cloudkeys_amazonkms_set($res, 48, $value );

Default Value

''

Remarks

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

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

Input Sources & Output Destinations

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

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

1. The InputFile property
2. The InputData property

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

1. The OutputFile property
2. The OutputData property

Data Type

String

Overwrite Property (CloudKeys_AmazonKMS Class)

Whether the output file should be overwritten if necessary.

Object Oriented Interface

public function getOverwrite();


public function setOverwrite($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 49 );


cloudkeys_amazonkms_set($res, 49, $value );

Default Value

false

Remarks

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

Data Type

Boolean

ParsedHeaderCount Property (CloudKeys_AmazonKMS Class)

The number of records in the ParsedHeader arrays.

Object Oriented Interface

public function getParsedHeaderCount();

Procedural Interface

cloudkeys_amazonkms_get($res, 50 );

Default Value

0

Remarks

This property controls the size of the following arrays:

• ParsedHeaderField
• ParsedHeaderValue

The array indices start at 0 and end at ParsedHeaderCount - 1.

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

Data Type

Integer

ParsedHeaderField Property (CloudKeys_AmazonKMS Class)

This property contains the name of the HTTP header (this is the same case as it is delivered).

Object Oriented Interface

public function getParsedHeaderField($parsedheaderindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 51 , $parsedheaderindex);

Default Value

''

Remarks

This property contains the name of the HTTP Header (this is the same case as it is delivered).

The $parsedheaderindex parameter specifies the index of the item in the array. The size of the array is controlled by the ParsedHeaderCount property.

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

Data Type

String

ParsedHeaderValue Property (CloudKeys_AmazonKMS Class)

This property contains the header contents.

Object Oriented Interface

public function getParsedHeaderValue($parsedheaderindex);

Procedural Interface

cloudkeys_amazonkms_get($res, 52 , $parsedheaderindex);

Default Value

''

Remarks

This property contains the Header contents.

The $parsedheaderindex parameter specifies the index of the item in the array. The size of the array is controlled by the ParsedHeaderCount property.

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

Data Type

String

ProxyAuthScheme Property (CloudKeys_AmazonKMS Class)

This property is used to tell the class which type of authorization to perform when connecting to the proxy.

Object Oriented Interface

public function getProxyAuthScheme();


public function setProxyAuthScheme($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 53 );


cloudkeys_amazonkms_set($res, 53, $value );

Default Value

0

Remarks

This property is used to tell the class which type of authorization to perform when connecting to the proxy. This is used only when the ProxyUser and ProxyPassword properties are set.

ProxyAuthScheme should be set to authNone (3) when no authentication is expected.

By default, ProxyAuthScheme is authBasic (0), and if the ProxyUser and ProxyPassword properties are set, the component will attempt basic authentication.

If ProxyAuthScheme is set to authDigest (1), digest authentication will be attempted instead.

If ProxyAuthScheme is set to authProprietary (2), then the authorization token will not be generated by the class. Look at the configuration file for the class being used to find more information about manually setting this token.

If ProxyAuthScheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of ProxyUser and ProxyPassword.

Data Type

Integer

ProxyAutoDetect Property (CloudKeys_AmazonKMS Class)

This property tells the class whether or not to automatically detect and use proxy system settings, if available.

Object Oriented Interface

public function getProxyAutoDetect();


public function setProxyAutoDetect($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 54 );


cloudkeys_amazonkms_set($res, 54, $value );

Default Value

false

Remarks

This property tells the class whether or not to automatically detect and use proxy system settings, if available. The default value is false.

Data Type

Boolean

ProxyPassword Property (CloudKeys_AmazonKMS Class)

This property contains a password if authentication is to be used for the proxy.

Object Oriented Interface

public function getProxyPassword();


public function setProxyPassword($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 55 );


cloudkeys_amazonkms_set($res, 55, $value );

Default Value

''

Remarks

This property contains a password if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

ProxyPort Property (CloudKeys_AmazonKMS Class)

This property contains the Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Object Oriented Interface

public function getProxyPort();


public function setProxyPort($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 56 );


cloudkeys_amazonkms_set($res, 56, $value );

Default Value

80

Remarks

This property contains the Transmission Control Protocol (TCP) port for the proxy ProxyServer (default 80). See the description of the ProxyServer property for details.

Data Type

Integer

ProxyServer Property (CloudKeys_AmazonKMS Class)

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Object Oriented Interface

public function getProxyServer();


public function setProxyServer($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 57 );


cloudkeys_amazonkms_set($res, 57, $value );

Default Value

''

Remarks

If a proxy ProxyServer is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the ProxyServer property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the ProxyServer property is set to the corresponding address. If the search is not successful, an error is returned.

Data Type

String

ProxySSL Property (CloudKeys_AmazonKMS Class)

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Object Oriented Interface

public function getProxySSL();


public function setProxySSL($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 58 );


cloudkeys_amazonkms_set($res, 58, $value );

Default Value

0

Remarks

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

Data Type

Integer

ProxyUser Property (CloudKeys_AmazonKMS Class)

This property contains a user name, if authentication is to be used for the proxy.

Object Oriented Interface

public function getProxyUser();


public function setProxyUser($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 59 );


cloudkeys_amazonkms_set($res, 59, $value );

Default Value

''

Remarks

This property contains a user name, if authentication is to be used for the proxy.

If ProxyAuthScheme is set to Basic Authentication, the ProxyUser and ProxyPassword are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If ProxyAuthScheme is set to Digest Authentication, the ProxyUser and ProxyPassword properties are used to respond to the Digest Authentication challenge from the server.

If ProxyAuthScheme is set to NTLM Authentication, the ProxyUser and ProxyPassword properties are used to authenticate through NTLM negotiation.

Data Type

String

QueryParamCount Property (CloudKeys_AmazonKMS Class)

The number of records in the QueryParam arrays.

Object Oriented Interface

public function getQueryParamCount();


public function setQueryParamCount($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 60 );


cloudkeys_amazonkms_set($res, 60, $value );

Default Value

0

Remarks

This property controls the size of the following arrays:

• QueryParamName
• QueryParamValue

The array indices start at 0 and end at QueryParamCount - 1.

This property is not available at design time.

Data Type

Integer

QueryParamName Property (CloudKeys_AmazonKMS Class)

The name of the query parameter.

Object Oriented Interface

public function getQueryParamName($queryparamindex);


public function setQueryParamName($queryparamindex, $value);

Procedural Interface

cloudkeys_amazonkms_get($res, 61 , $queryparamindex);


cloudkeys_amazonkms_set($res, 61, $value , $queryparamindex);

Default Value

''

Remarks

The name of the query parameter.

This property specifies the name of the query parameter.

The $queryparamindex parameter specifies the index of the item in the array. The size of the array is controlled by the QueryParamCount property.

This property is not available at design time.

Data Type

String

QueryParamValue Property (CloudKeys_AmazonKMS Class)

The value of the query parameter.

Object Oriented Interface

public function getQueryParamValue($queryparamindex);


public function setQueryParamValue($queryparamindex, $value);

Procedural Interface

cloudkeys_amazonkms_get($res, 62 , $queryparamindex);


cloudkeys_amazonkms_set($res, 62, $value , $queryparamindex);

Default Value

''

Remarks

The value of the query parameter.

This property specifies the value of the query parameter. The class will automatically URL-encode this value when sending the request.

The $queryparamindex parameter specifies the index of the item in the array. The size of the array is controlled by the QueryParamCount property.

This property is not available at design time.

Data Type

String

Region Property (CloudKeys_AmazonKMS Class)

The region that the class will make requests against.

Object Oriented Interface

public function getRegion();


public function setRegion($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 63 );


cloudkeys_amazonkms_set($res, 63, $value );

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

The secret key to use for authentication.

Object Oriented Interface

public function getSecretKey();


public function setSecretKey($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 64 );


cloudkeys_amazonkms_set($res, 64, $value );

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

SSLAcceptServerCertEncoded Property (CloudKeys_AmazonKMS Class)

This is the certificate (PEM/base64 encoded).

Object Oriented Interface

public function getSSLAcceptServerCertEncoded();


public function setSSLAcceptServerCertEncoded($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 66 );


cloudkeys_amazonkms_set($res, 66, $value );

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The SSLAcceptServerCertStore and SSLAcceptServerCertSubject properties also may be used to specify a certificate.

When SSLAcceptServerCertEncoded is set, a search is initiated in the current SSLAcceptServerCertStore for the private key of the certificate. If the key is found, SSLAcceptServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLAcceptServerCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertEncoded Property (CloudKeys_AmazonKMS Class)

This is the certificate (PEM/base64 encoded).

Object Oriented Interface

public function getSSLCertEncoded();


public function setSSLCertEncoded($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 94 );


cloudkeys_amazonkms_set($res, 94, $value );

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The SSLCertStore and SSLCertSubject properties also may be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLCertSubject is set to an empty string.

This property is not available at design time.

Data Type

Binary String

SSLCertStore Property (CloudKeys_AmazonKMS Class)

This is the name of the certificate store for the client certificate.

Object Oriented Interface

public function getSSLCertStore();


public function setSSLCertStore($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 110 );


cloudkeys_amazonkms_set($res, 110, $value );

Default Value

'MY'

Remarks

This is the name of the certificate store for the client certificate.

The SSLCertStoreType property denotes the type of the certificate store specified by SSLCertStore. If the store is password protected, specify the password in SSLCertStorePassword.

SSLCertStore is used in conjunction with the SSLCertSubject property to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please see the SSLCertSubject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

Data Type

Binary String

SSLCertStorePassword Property (CloudKeys_AmazonKMS Class)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Object Oriented Interface

public function getSSLCertStorePassword();


public function setSSLCertStorePassword($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 111 );


cloudkeys_amazonkms_set($res, 111, $value );

Default Value

''

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

SSLCertStoreType Property (CloudKeys_AmazonKMS Class)

This is the type of certificate store for this certificate.

Object Oriented Interface

public function getSSLCertStoreType();


public function setSSLCertStoreType($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 112 );


cloudkeys_amazonkms_set($res, 112, $value );

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used the class will automatically determine the type. This property can take one of the following values:

Data Type

Integer

SSLCertSubject Property (CloudKeys_AmazonKMS Class)

This is the subject of the certificate used for client authentication.

Object Oriented Interface

public function getSSLCertSubject();


public function setSSLCertSubject($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 113 );


cloudkeys_amazonkms_set($res, 113, $value );

Default Value

''

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For instance "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are displayed below.

If a field value contains a comma it must be quoted.

Data Type

String

SSLProvider Property (CloudKeys_AmazonKMS Class)

This specifies the SSL/TLS implementation to use.

Object Oriented Interface

public function getSSLProvider();


public function setSSLProvider($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 121 );


cloudkeys_amazonkms_set($res, 121, $value );

Default Value

0

Remarks

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

Possible values are:

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

When Automatic is selected, 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

SSLServerCertEncoded Property (CloudKeys_AmazonKMS Class)

This is the certificate (PEM/base64 encoded).

Object Oriented Interface

public function getSSLServerCertEncoded();

Procedural Interface

cloudkeys_amazonkms_get($res, 123 );

Default Value

''

Remarks

This is the certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The SSLServerCertStore and SSLServerCertSubject properties also may be used to specify a certificate.

When SSLServerCertEncoded is set, a search is initiated in the current SSLServerCertStore for the private key of the certificate. If the key is found, SSLServerCertSubject is updated to reflect the full subject of the selected certificate; otherwise, SSLServerCertSubject is set to an empty string.

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

Data Type

Binary String

Timeout Property (CloudKeys_AmazonKMS Class)

A timeout for the class.

Object Oriented Interface

public function getTimeout();


public function setTimeout($value);

Procedural Interface

cloudkeys_amazonkms_get($res, 150 );


cloudkeys_amazonkms_set($res, 150, $value );

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.

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

The default value for the Timeout property is 60 seconds.

Data Type

Integer

AddEncryptionContextItem Method (CloudKeys_AmazonKMS Class)

Adds an item to the EncryptionContext properties.

Object Oriented Interface

public function doAddEncryptionContextItem($name, $value);

Procedural Interface

cloudkeys_amazonkms_do_addencryptioncontextitem($res, $name, $value);

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.

AddQueryParam Method (CloudKeys_AmazonKMS Class)

Adds a query parameter to the QueryParams properties.

Object Oriented Interface

public function doAddQueryParam($name, $value);

Procedural Interface

cloudkeys_amazonkms_do_addqueryparam($res, $name, $value);

Remarks

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

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

CancelKeyDeletion Method (CloudKeys_AmazonKMS Class)

Cancels the deletion of the specified KMS key.

Object Oriented Interface

public function doCancelKeyDeletion($keyid);

Procedural Interface

cloudkeys_amazonkms_do_cancelkeydeletion($res, $keyid);

Remarks

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

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

ClearKeyData Method (CloudKeys_AmazonKMS Class)

Clears information stored in the KeyData properties.

Object Oriented Interface

public function doClearKeyData($plaintextonly);

Procedural Interface

cloudkeys_amazonkms_do_clearkeydata($res, $plaintextonly);

Remarks

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

Config Method (CloudKeys_AmazonKMS Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

cloudkeys_amazonkms_do_config($res, $configurationstring);

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.

CreateAlias Method (CloudKeys_AmazonKMS Class)

Creates a new alias.

Object Oriented Interface

public function doCreateAlias($name, $keyid);

Procedural Interface

cloudkeys_amazonkms_do_createalias($res, $name, $keyid);

Remarks

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

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

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

CreateKey Method (CloudKeys_AmazonKMS Class)

Creates a new KMS key.

Object Oriented Interface

public function doCreateKey($keyspec, $forsigning, $description);

Procedural Interface

cloudkeys_amazonkms_do_createkey($res, $keyspec, $forsigning, $description);

Remarks

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

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

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

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

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

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

Decrypt Method (CloudKeys_AmazonKMS Class)

Decrypts data using a KMS key.

Object Oriented Interface

public function doDecrypt($keyid, $algorithm);

Procedural Interface

cloudkeys_amazonkms_do_decrypt($res, $keyid, $algorithm);

Remarks

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

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

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

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

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

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

DeleteAlias Method (CloudKeys_AmazonKMS Class)

Deletes an alias.

Object Oriented Interface

public function doDeleteAlias($aliasname);

Procedural Interface

cloudkeys_amazonkms_do_deletealias($res, $aliasname);

Remarks

This method deletes the alias with the given AliasName.

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

DoEvents Method (CloudKeys_AmazonKMS Class)

Processes events from the internal message queue.

Object Oriented Interface

public function doEvents();

Procedural Interface

cloudkeys_amazonkms_do_doevents($res);

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.

Encrypt Method (CloudKeys_AmazonKMS Class)

Encrypts data using a KMS key.

Object Oriented Interface

public function doEncrypt($keyid, $algorithm);

Procedural Interface

cloudkeys_amazonkms_do_encrypt($res, $keyid, $algorithm);

Remarks

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

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

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

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

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

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

GenerateDataKey Method (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function doGenerateDataKey($keyspec, $keyid, $includeplaintext);

Procedural Interface

cloudkeys_amazonkms_do_generatedatakey($res, $keyspec, $keyid, $includeplaintext);

Remarks

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

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

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

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

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

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

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

• Its KeyState is anything other than aksEnabled (0).
• It is asymmetric (see KeyKeySpec).
• It is for signing/verification instead of encryption/decryption (see KeyForSigning).
• It is an AWS-managed KMS key (see KeyAWSManaged).

GenerateDataKeyPair Method (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function doGenerateDataKeyPair($keypairspec, $keyid, $includeplaintext);

Procedural Interface

cloudkeys_amazonkms_do_generatedatakeypair($res, $keypairspec, $keyid, $includeplaintext);

Remarks

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

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

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

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

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

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

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

• Its KeyState is anything other than aksEnabled (0).
• It is asymmetric (see KeyKeySpec).
• It is for signing/verification instead of encryption/decryption (see KeyForSigning).
• It is an AWS-managed KMS key (see KeyAWSManaged).

GenerateRandomBytes Method (CloudKeys_AmazonKMS Class)

Generates a cryptographically-secure random byte string.

Object Oriented Interface

public function doGenerateRandomBytes($numbytes);

Procedural Interface

cloudkeys_amazonkms_do_generaterandombytes($res, $numbytes);

Remarks

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

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

GetKeyInfo Method (CloudKeys_AmazonKMS Class)

Gets information about a KMS key.

Object Oriented Interface

public function doGetKeyInfo($keyid);

Procedural Interface

cloudkeys_amazonkms_do_getkeyinfo($res, $keyid);

Remarks

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

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

GetKeyRotationStatus Method (CloudKeys_AmazonKMS Class)

Retrieves the key rotation status for a KMS key.

Object Oriented Interface

public function doGetKeyRotationStatus($keyid);

Procedural Interface

cloudkeys_amazonkms_do_getkeyrotationstatus($res, $keyid);

Remarks

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

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

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

GetPublicKey Method (CloudKeys_AmazonKMS Class)

Retrieves the public key of an asymmetric KMS key.

Object Oriented Interface

public function doGetPublicKey($keyid);

Procedural Interface

cloudkeys_amazonkms_do_getpublickey($res, $keyid);

Remarks

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

• KeyDataAlgorithms
• KeyDataARN
• KeyDataForSigning
• KeyDataKeySpec
• KeyDataPublicKey

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

• Its KeyState is anything other than aksEnabled (0).
• It is symmetric (see KeyKeySpec).
• It is an AWS-managed KMS key (see KeyAWSManaged).

ListAliases Method (CloudKeys_AmazonKMS Class)

Lists aliases in the current account and region.

Object Oriented Interface

public function doListAliases($forkeyid);

Procedural Interface

cloudkeys_amazonkms_do_listaliases($res, $forkeyid);

Remarks

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

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

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

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

ListKeys Method (CloudKeys_AmazonKMS Class)

Lists KMS keys in the current account and region.

Object Oriented Interface

public function doListKeys();

Procedural Interface

cloudkeys_amazonkms_do_listkeys($res);

Remarks

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

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

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

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

ReEncrypt Method (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function doReEncrypt($oldkeyid, $oldalgorithm, $newkeyid, $newalgorithm);

Procedural Interface

cloudkeys_amazonkms_do_reencrypt($res, $oldkeyid, $oldalgorithm, $newkeyid, $newalgorithm);

Remarks

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

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

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

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

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

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

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

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

Reset Method (CloudKeys_AmazonKMS Class)

Resets the class to its initial state.

Object Oriented Interface

public function doReset();

Procedural Interface

cloudkeys_amazonkms_do_reset($res);

Remarks

This method resets the class to its initial state.

ScheduleKeyDeletion Method (CloudKeys_AmazonKMS Class)

Schedules the deletion of a KMS key.

Object Oriented Interface

public function doScheduleKeyDeletion($keyid, $daystowait);

Procedural Interface

cloudkeys_amazonkms_do_schedulekeydeletion($res, $keyid, $daystowait);

Remarks

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

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

SendCustomRequest Method (CloudKeys_AmazonKMS Class)

Sends a custom request to the server.

Object Oriented Interface

public function doSendCustomRequest($action);

Procedural Interface

cloudkeys_amazonkms_do_sendcustomrequest($res, $action);

Remarks

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

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

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

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

SetKeyEnabled Method (CloudKeys_AmazonKMS Class)

Enables or disables a KMS key.

Object Oriented Interface

public function doSetKeyEnabled($keyid, $enabled);

Procedural Interface

cloudkeys_amazonkms_do_setkeyenabled($res, $keyid, $enabled);

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

SetKeyRotationStatus Method (CloudKeys_AmazonKMS Class)

Enables or disables automatic key rotation for a KMS key.

Object Oriented Interface

public function doSetKeyRotationStatus($keyid, $enabled);

Procedural Interface

cloudkeys_amazonkms_do_setkeyrotationstatus($res, $keyid, $enabled);

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 KeyState is anything other than aksEnabled (0).
• It is asymmetric (see KeyKeySpec).
• It has imported key material (see KeyOrigin).
• It resides in a custom key store (see KeyCustomKeyStoreId).
• It is an AWS-managed KMS key (see KeyAWSManaged).

Sign Method (CloudKeys_AmazonKMS Class)

Signs a message using a KMS key.

Object Oriented Interface

public function doSign($keyid, $algorithm, $isdigest);

Procedural Interface

cloudkeys_amazonkms_do_sign($res, $keyid, $algorithm, $isdigest);

Remarks

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

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

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

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

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

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

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

• Its KeyState is anything other than aksEnabled (0).
• It is symmetric (see KeyKeySpec).
• It is for encryption/decryption instead of signing/verification (see KeyForSigning).
• It is an AWS-managed KMS key (see KeyAWSManaged).

UpdateAlias Method (CloudKeys_AmazonKMS Class)

Updates an alias to refer to a different KMS key.

Object Oriented Interface

public function doUpdateAlias($aliasname, $newkeyid);

Procedural Interface

cloudkeys_amazonkms_do_updatealias($res, $aliasname, $newkeyid);

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

UpdateKeyDescription Method (CloudKeys_AmazonKMS Class)

Updates a KMS key's description.

Object Oriented Interface

public function doUpdateKeyDescription($keyid, $newdescription);

Procedural Interface

cloudkeys_amazonkms_do_updatekeydescription($res, $keyid, $newdescription);

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

Verify Method (CloudKeys_AmazonKMS Class)

Verifies a digital signature using a KMS key.

Object Oriented Interface

public function doVerify($keyid, $algorithm, $isdigest);

Procedural Interface

cloudkeys_amazonkms_do_verify($res, $keyid, $algorithm, $isdigest);

Remarks

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

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

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

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

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

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

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

• Its KeyState is anything other than aksEnabled (0).
• It is symmetric (see KeyKeySpec).
• It is for encryption/decryption instead of signing/verification (see KeyForSigning).
• It is an AWS-managed KMS key (see KeyAWSManaged).

AliasList Event (CloudKeys_AmazonKMS Class)

Fires once for each alias when listing aliases.

Object Oriented Interface

public function fireAliasList($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 1, array($this, 'fireAliasList'));

Parameter List

 'arn'
 'name'
 'keyid'

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

This event fires when a document finishes transferring.

Object Oriented Interface

public function fireEndTransfer($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 2, array($this, 'fireEndTransfer'));

Parameter List

 'direction'

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

Information about errors during data delivery.

Object Oriented Interface

public function fireError($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 3, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

Remarks

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

ErrorCode contains an error code and Description 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 (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function fireHeader($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 4, array($this, 'fireHeader'));

Parameter List

 'field'
 'value'

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

Fires once for each KMS key when listing KMS keys.

Object Oriented Interface

public function fireKeyList($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 5, array($this, 'fireKeyList'));

Parameter List

 'arn'
 'id'
 'accountid'
 'description'
 'enabled'
 'awsmanaged'
 'forsigning'
 'keyspec'
 'algorithms'
 'state'
 'creationdate'
 'deletiondate'

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

• SYMMETRIC_DEFAULT
• RSAES_OAEP_SHA_1
• RSAES_OAEP_SHA_256

If KeyForSigning 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 (CloudKeys_AmazonKMS Class)

This event fires once for each log message.

Object Oriented Interface

public function fireLog($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 6, array($this, 'fireLog'));

Parameter List

 'loglevel'
 'message'
 'logtype'

Remarks

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

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

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

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

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

Message is the log entry.

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

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

SSLServerAuthentication Event (CloudKeys_AmazonKMS Class)

Fired after the server presents its certificate to the client.

Object Oriented Interface

public function fireSSLServerAuthentication($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 7, array($this, 'fireSSLServerAuthentication'));

Parameter List

 'certencoded'
 'certsubject'
 'certissuer'
 'status'
 'accept'

Remarks

This event is where the client can decide whether to continue with the connection process or not. 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 to continue or not.

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

Shows the progress of the secure connection.

Object Oriented Interface

public function fireSSLStatus($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 8, array($this, 'fireSSLStatus'));

Parameter List

 'message'

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

StartTransfer Event (CloudKeys_AmazonKMS Class)

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

Object Oriented Interface

public function fireStartTransfer($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 9, array($this, 'fireStartTransfer'));

Parameter List

 'direction'

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

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

Object Oriented Interface

public function fireTransfer($param);

Procedural Interface

cloudkeys_amazonkms_register_callback($res, 10, array($this, 'fireTransfer'));

Parameter List

 'direction'
 'bytestransferred'
 'percentdone'
 'text'

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.

Config Settings (AmazonKMS Class)

AmazonKMS Config Settings

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

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

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

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

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

Socket Config Settings

Base Config Settings

Trappable Errors (AmazonKMS Class)

Common Errors

The class may also return one of the following error codes, which are inherited from other classes.

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors