# Use `Encrypt` with an AWS SDK or CLI
The following code examples show how to use `Encrypt`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](example_kms_Scenario_Basics_section.md)
------
#### [ CLI ]
**AWS CLI**
**Example 1: To encrypt the contents of a file on Linux or MacOS**
The following `encrypt` command demonstrates the recommended way to encrypt data with the AWS CLI.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
The command does several things:
Uses the `--plaintext` parameter to indicate the data to encrypt. This parameter value must be base64-encoded.The value of the `plaintext` parameter must be base64-encoded, or you must use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.If the file is not in the current directory, type the full path to file. For example: `fileb:///var/tmp/ExamplePlaintextFile` or `fileb://C:\Temp\ExamplePlaintextFile`. For more information about reading AWS CLI parameter values from a file, see [Loading Parameters from a File](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-file) in the *AWS Command Line Interface User Guide* and [Best Practices for Local File Parameters](https://blogs.aws.amazon.com/cli/post/TxLWWN1O25V1HE/Best-Practices-for-Local-File-Parameters) on the AWS Command Line Tool Blog.Uses the `--output` and `--query` parameters to control the command's output.These parameters extract the encrypted data, called the *ciphertext*, from the command's output.For more information about controlling output, see [Controlling Command Output](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html) in the *AWS Command Line Interface User Guide*.Uses the `base64` utility to decode the extracted output into binary data.The ciphertext that is returned by a successful `encrypt` command is base64-encoded text. You must decode this text before you can use the AWS CLI to decrypt it.Saves the binary ciphertext to a file.The final part of the command (`> ExampleEncryptedFile`) saves the binary ciphertext to a file to make decryption easier. For an example command that uses the AWS CLI to decrypt data, see the decrypt examples.
**Example 2: Using the AWS CLI to encrypt data on Windows**
This example is the same as the previous one, except that it uses the `certutil` tool instead of `base64`. This procedure requires two commands, as shown in the following example.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob > C:\Temp\ExampleEncryptedFile.base64
certutil -decode C:\Temp\ExampleEncryptedFile.base64 C:\Temp\ExampleEncryptedFile
```
**Example 3: Encrypting with an asymmetric KMS key**
The following `encrypt` command shows how to encrypt plaintext with an asymmetric KMS key. The `--encryption-algorithm` parameter is required. As in all `encrypt` CLI commands, the `plaintext` parameter must be base64-encoded, or you must use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encryption-algorithm RSAES_OAEP_SHA_256 \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
This command produces no output.
+ For API details, see [Encrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/encrypt.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/kms#code-examples).
```
/**
* Encrypts the given text asynchronously using the specified KMS client and key ID.
*
* @param keyId the ID of the KMS key to use for encryption
* @param text the text to encrypt
* @return a CompletableFuture that completes with the encrypted data as an SdkBytes object
*/
public CompletableFuture encryptDataAsync(String keyId, String text) {
SdkBytes myBytes = SdkBytes.fromUtf8String(text);
EncryptRequest encryptRequest = EncryptRequest.builder()
.keyId(keyId)
.plaintext(myBytes)
.build();
CompletableFuture responseFuture = getAsyncClient().encrypt(encryptRequest).toCompletableFuture();
return responseFuture.whenComplete((response, ex) -> {
if (response != null) {
String algorithm = response.encryptionAlgorithm().toString();
logger.info("The string was encrypted with algorithm {}.", algorithm);
} else {
throw new RuntimeException(ex);
}
}).thenApply(EncryptResponse::ciphertextBlob);
}
```
+ For API details, see [Encrypt](https://docs.aws.amazon.com/goto/SdkForJavaV2/kms-2014-11-01/Encrypt) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/kms#code-examples).
```
suspend fun encryptData(keyIdValue: String): ByteArray? {
val text = "This is the text to encrypt by using the AWS KMS Service"
val myBytes: ByteArray = text.toByteArray()
val encryptRequest =
EncryptRequest {
keyId = keyIdValue
plaintext = myBytes
}
KmsClient.fromEnvironment { region = "us-west-2" }.use { kmsClient ->
val response = kmsClient.encrypt(encryptRequest)
val algorithm: String = response.encryptionAlgorithm.toString()
println("The encryption algorithm is $algorithm")
// Return the encrypted data.
return response.ciphertextBlob
}
}
suspend fun decryptData(
encryptedDataVal: ByteArray?,
keyIdVal: String?,
) {
val decryptRequest =
DecryptRequest {
ciphertextBlob = encryptedDataVal
keyId = keyIdVal
}
KmsClient { region = "us-west-2" }.use { kmsClient ->
val decryptResponse = kmsClient.decrypt(decryptRequest)
val myVal = decryptResponse.plaintext
// Print the decrypted data.
print(myVal)
}
}
```
+ For API details, see [Encrypt](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ PHP ]
**SDK for PHP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/kms#code-examples).
```
/***
* @param string $keyId
* @param string $text
* @return Result
*/
public function encrypt(string $keyId, string $text)
{
try {
return $this->client->encrypt([
'KeyId' => $keyId,
'Plaintext' => $text,
]);
}catch(KmsException $caught){
if($caught->getAwsErrorMessage() == "DisabledException"){
echo "The request was rejected because the specified KMS key is not enabled.\n";
}
throw $caught;
}
}
```
+ For API details, see [Encrypt](https://docs.aws.amazon.com/goto/SdkForPHPV3/kms-2014-11-01/Encrypt) in *AWS SDK for PHP API Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/kms#code-examples).
```
class KeyEncrypt:
def __init__(self, kms_client):
self.kms_client = kms_client
@classmethod
def from_client(cls) -> "KeyEncrypt":
"""
Creates a KeyEncrypt instance with a default KMS client.
:return: An instance of KeyEncrypt initialized with the default KMS client.
"""
kms_client = boto3.client("kms")
return cls(kms_client)
def encrypt(self, key_id: str, text: str) -> bytes:
"""
Encrypts text by using the specified key.
:param key_id: The ARN or ID of the key to use for encryption.
:param text: The text to encrypt.
:return: The encrypted version of the text.
"""
try:
response = self.kms_client.encrypt(KeyId=key_id, Plaintext=text.encode())
print(
f"The string was encrypted with algorithm {response['EncryptionAlgorithm']}"
)
return response["CiphertextBlob"]
except ClientError as err:
if err.response["Error"]["Code"] == "DisabledException":
logger.error(
"Could not encrypt because the key %s is disabled.", key_id
)
else:
logger.error(
"Couldn't encrypt text. Here's why: %s",
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [Encrypt](https://docs.aws.amazon.com/goto/boto3/kms-2014-11-01/Encrypt) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ Ruby ]
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/kms#code-examples).
```
require 'aws-sdk-kms' # v2: require 'aws-sdk'
# ARN of the AWS KMS key.
#
# Replace the fictitious key ARN with a valid key ID
keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
text = '1234567890'
client = Aws::KMS::Client.new(region: 'us-west-2')
resp = client.encrypt({
key_id: keyId,
plaintext: text
})
# Display a readable version of the resulting encrypted blob.
puts 'Blob:'
puts resp.ciphertext_blob.unpack('H*')
```
+ For API details, see [Encrypt](https://docs.aws.amazon.com/goto/SdkForRubyV3/kms-2014-11-01/Encrypt) in *AWS SDK for Ruby API Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/kms#code-examples).
```
async fn encrypt_string(
verbose: bool,
client: &Client,
text: &str,
key: &str,
out_file: &str,
) -> Result<(), Error> {
let blob = Blob::new(text.as_bytes());
let resp = client.encrypt().key_id(key).plaintext(blob).send().await?;
// Did we get an encrypted blob?
let blob = resp.ciphertext_blob.expect("Could not get encrypted text");
let bytes = blob.as_ref();
let s = base64::encode(bytes);
let mut ofile = File::create(out_file).expect("unable to create file");
ofile.write_all(s.as_bytes()).expect("unable to write");
if verbose {
println!("Wrote the following to {:?}", out_file);
println!("{}", s);
}
Ok(())
}
```
+ For API details, see [Encrypt](https://docs.rs/aws-sdk-kms/latest/aws_sdk_kms/client/struct.Client.html#method.encrypt) in *AWS SDK for Rust API reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/kms#code-examples).
```
TRY.
" iv_key_id = 'arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab'
" iv_plaintext contains the data to encrypt
oo_result = lo_kms->encrypt(
iv_keyid = iv_key_id
iv_plaintext = iv_plaintext
).
MESSAGE 'Text encrypted successfully.' TYPE 'I'.
CATCH /aws1/cx_kmsdisabledexception.
MESSAGE 'The key is disabled.' TYPE 'E'.
CATCH /aws1/cx_kmsnotfoundexception.
MESSAGE 'Key not found.' TYPE 'E'.
CATCH /aws1/cx_kmskmsinternalex.
MESSAGE 'An internal error occurred.' TYPE 'E'.
ENDTRY.
```
+ For API details, see [Encrypt](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
For a complete list of AWS SDK developer guides and code examples, see [Using this service with an AWS SDK](sdk-general-information-section.md). This topic also includes information about getting started and details about previous SDK versions.