Setting up

The AWS SDK for Swift is a cross-platform, open source Swift package that lets applications and tools built using Swift make full use of the services offered by AWS. Using the SDK, you can build Swift applications that work with Amazon S3, Amazon EC2, DynamoDB, and more.

The SDK package is imported into your project using the Swift Package Manager (SPM), which is part of the standard Swift toolchain.

Prerelease documentation

This is prerelease documentation for an SDK in preview release. It may be incomplete and is subject to change.

In addition, versions of the SDK prior to version 1.0.0 may have flaws, and no guarantee is made about the API’s stability. Changes can and will occur that break compatibility during the prerelease stage. These releases are not intended for use in production code!

When you’ve finished following the steps in this article, or have confirmed that everything is configured as described, you’re ready to begin developing using the AWS SDK for Swift.

Overview

To make requests to AWS using the AWS SDK for Swift, you need the following:

• An active AWS account

• An AWS Identity and Access Management (IAM) user with:

  • A programmatic access key

  • Permissions to use the AWS resources your application will access

• A development environment with:

  • Your access key configured as credentials for AWS

  • Version 5.4 or later of the Swift toolchain. If you don’t have this, you’ll install it as part of the steps below.

Note

Linux users: The SDK for Swift currently requires libcrypto version 1.1, which is not automatically installed during the process outlined in the documentation referenced above. To install it, be sure to install OpenSSL 1.1 and its development package. Using the yum package manager, for example:

$ sudo yum install openssl11 openssl11-devel

After finishing these steps, you’re ready to use the SDK to develop Swift projects that access AWS services.

Set up AWS access

Before installing the Swift tools, let’s make sure your environment is configured to let your project access AWS services. This section covers creating an AWS account if you don’t have one, adding an IAM user to the account for secure access to the account and its services, and setting the environment variables used by the SDK for Swift to fetch your access credentials.

Create an account

If you do not have an AWS account, visit the Amazon Web Services sign-up page and follow the on-screen prompts to create and activate a new account.

For more detailed instructions, see How do I create and activate a new AWS account?.

After you activate your new AWS account, follow the instructions in Creating your first IAM admin user and group in the IAM User Guide. Use this account instead of the root account when accessing the AWS Console. For more information, see Security best practices in the IAM User Guide.

Create an IAM user and programmatic access key

To use the AWS SDK for Swift to access AWS, you need an AWS account and AWS credentials. To increase the security of your AWS account, for access credentials, we recommend that you use an IAM user instead of your AWS account credentials.

Note

For an overview of IAM users and why they are important for the security of your account, see AWS security in the Amazon Web Services General Reference.

For instructions on creating an access key for an existing IAM user, see Programmatic access in the IAM User Guide.

1. Go to the IAM console (you may need to sign in to AWS first).

2. Click Users in the sidebar to view your IAM users.

3. If you don’t have any IAM users set up, click Create New Users to create one.

4. Select the IAM user in the list that you’ll use to access AWS.

5. Open the Security Credentials tab, and click Create Access Key. NOTE: You can have a maximum of two active access keys for any given IAM user. If your IAM user has two access keys already, then you’ll need to delete one of them before creating a new key.

6. On the resulting dialog box, click the Download Credentials button to download the credential file to your computer, or click Show User Security Credentials to view the IAM user’s access key ID and secret access key (which you can copy and paste).

Important

There is no way to obtain the secret access key once you close the dialog box. You can, however, delete its associated access key ID and create a new one.

Set default credentials and Region

To make requests to AWS using the AWS SDK for Swift, you must use cryptographically-signed credentials issued by AWS. With AWS SDKs and Tools like the AWS SDK for Swift, you use a programmatic access key, consisting of an Access Key ID and and a Secret Access Key, as credentials. You should set your credentials as the default credentials for accessing AWS with your application.

If you already have an IAM account created, see Create an for instructions on creating a programmatic access key.

You should also set a default AWS Region for accessing AWS with your application. Some operations require a Region to be set. For the best network performance, you can select a Region that is geographically near to you or your customers.

The most common way to set the default credentials and AWS Region is to use the shared config and credentials files. You can also set the default credentials and Region using environment variables.

Set the default credentials

Select one of these options to set the default credentials:

• Set credentials in the AWS credentials profile file on your local system, located at:

  • ~/.aws/credentials on Linux, macOS, or Unix

  • C:\Users\USERNAME\.aws\credentials on Windows

This file should contain lines in the following format:

[default]
aws_access_key_id = your_access_key_id
aws_secret_access_key = your_secret_access_key

Substitute your own AWS credentials values for the values your_access_key_id and your_secret_access_key. The access key ID will look something like AKIAIOSFODNN7EXAMPLE, while the secret access key will look like a jumble of letters and numbers, such as je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY.

• Set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

To set these variables on Linux, macOS, or Unix, use export :

export AWS_ACCESS_KEY_ID=your_access_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_access_key

To set these variables on Windows, use set :

set AWS_ACCESS_KEY_ID=your_access_key_id
set AWS_SECRET_ACCESS_KEY=your_secret_access_key

Set the default Region

Select one of these options to set the default AWS Region:

• Set the AWS Region in the AWS config file on your local system, located at:

  • ~/.aws/config on Linux, macOS, or Unix

  • C:\Users\USERNAME\.aws\config on Windows

This file should contain lines in the following format:

[default]
region = your_aws_region

Substitute your desired AWS Region (for example, "us-west-2") for your_aws_region.

• Set the AWS_REGION environment variable.

On Linux, macOS, or Unix, use export :

export AWS_REGION=your_aws_region

On Windows, use set :

set AWS_REGION=your_aws_region

Where your_aws_region is the desired AWS Region name.

For additional information about setting credentials and Region, see The .aws/credentials and .aws/config files, AWS Region, and Using environment variables in the AWS SDKs and Tools Reference Guide.

Note

If you plan to develop a macOS desktop application, keep in mind that due to sandbox restrictions, the SDK is unable to access your ~/.aws/config and ~/.aws/credentials files, as there is no entitlement available to grant access to the ~/.aws directory. See Security and authentication when testing on macOS for details.

Set up your Swift development environment

The SDK for Swift requires at least version 5.4 of Swift. This can be installed either standalone or as part of the Xcode development environment on macOS.

• Swift 5.4 toolchain or later. If you wish to use the SDK’s asynchronous functions, you should instead use Swift 5.5 or later. On macOS, Swift 5.4 is part of the Xcode 12.5 environment, while Swift 5.5 is included with Xcode 13.

• An AWS account. If you don’t have one already, you can create one using the AWS portal.

Important

A bug in Xcode 13 causes build failures when using the AWS SDK for Swift on macOS 11 Big Sur. If you encounter this issue, update to Xcode 13.1.

Install Swift

On macOS, the easiest way to install Swift is to simply install Apple’s Xcode IDE, which includes Swift and all the standard libraries and tools that go with it. This can be found on the macOS App Store.

If you’re using Linux or Windows, or don’t want to install Xcode on macOS, the Swift organization’s web site has detailed instructions to install and set up the Swift toolchain.

Check the Swift tools version number

If Swift is already installed, you can verify the version number using the command swift --version. The output will look similar to one of the following examples.

Checking the Swift version on macOS

$ swift --version
swift-driver version: 1.26 Apple Swift version 5.5 (swiftlang-1300.0.20.104 clang-1300.0.21.1)
Target: x86_64-apple-macosx11.0

Checking the Swift version on Linux

$ swift --version
Swift version 5.4.2 (swift-5.4.2-RELEASE)
Target: x86_64-unknown-linux-gnu

For more information about the configuration and credentials files shared among the AWS Command Line Interface and the various AWS SDKs, see the AWS SDKs and Tools Reference Guide.

Security and authentication when testing on macOS

Configuring the App Sandbox

If your SDK for Swift project is a desktop application that you’re building in Xcode, you will need to enable the App Sandbox capability and turn on the "Outgoing Connections (Client)" entitlement so that the SDK can communicate with AWS.

First, open the macOS target’s Signing & Capabilities panel, shown below.

Click the "+ Capability" button near the top left of this panel to bring up the box listing the available capabilities. In this box, locate the "App Sandbox" capability and double-click on it to add it to your target.

Next, back in your target’s "Signing & Capabilities" panel, find the new "App Sandbox" section and make sure that next to "Network," the "Outgoing Connections (Client)" checkbox is selected in the following image.

Using AWS access keys on macOS

Although shipping applications should typically use Cognito, OAuth, or other technologies to handle authentication, rather than requiring the direct use of AWS access keys, you may need to use these low-level credentials during development and testing.

macOS security features for desktop applications don’t allow applications to access files without express user permission, so the SDK can’t automatically configure clients using the contents of the CLI’s ~/.aws/config and ~/.aws/credentials files. Instead, you need to use the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to specify the authentication keys for your AWS account. This is already done if you followed the guidance in Getting started. If not, look there for details on setting these up.

There is a special case: when running projects from within Xcode, the environment you have set up for your shell is not automatically inherited. Because of this, if you want to test your code using your AWS account’s access key ID and secret access key, you need to set up the runtime environment for your application in the Xcode scheme for your development device. To configure the environment for a particular target in your Xcode project, switch to that target, then choose "Edit Scheme" in Xcode’s "Product" menu.

This will open the scheme editor window for your project. Click on the "Run" phase in the left sidebar, then "Arguments" in the tab bar near the top of the window.

Under "Environment Variables," click the "+" icon to add AWS_REGION and set its value to the desired region (in the screenshot above, it’s set to "us-east-2"). Then add AWS_ACCESS_KEY_ID and its value, then AWS_SECRET_ACCESS_KEY and its value. Close the window once you have these configured and your scheme’s Run configuration looks similar to the above.

Important

Be sure to disable the "Shared" checkbox before pushing your code to any public version control repository such as GitHub. Otherwise, your AWS access key and secret access key will be included in the publicly shared content.

Your project should now be able to use the SDK to connect to AWS services.

Next steps

Now that your tools and environment are ready for you to begin developing with AWS SDK for Swift, see Getting started, which demonstrates how to create and build a Swift project using AWS services.