Using the AWS Encryption SDK for .NET on macOS

Using the AWS Encryption SDK for .NET requires additional setup on macOS. First, ensure Homebrew is installed, as well as your desired .NET SDK (brew install dotnet-sdk). Then follow the instructions under either Apple M1-based Macs or Intel-based Macs according to the type of Mac you're running.

If you're unsure which type of Mac you're running, run uname -m in a shell. This prints "arm64" if running on M1, or prints "x86_64" instead if running on Intel (or on M1 in x86-64 emulation mode / Rosetta).

Apple M1-based Macs

These instructions are based on the .NET SDK M1 documentation issue: https://github.com/dotnet/sdk/issues/22380. If you run into issues, please first check the troubleshooting tips in that thread before opening an issue here.

One-time setup

First, install Rosetta (x86-64 emulation for M1-based Macs) if it's not already installed:

$ /usr/sbin/softwareupdate --install-rosetta

In addition to the arm64-native Homebrew installation, create an x86-64-native Homebrew installation as follows:

$ arch -x86_64 zsh
$ cd /usr/local
$ mkdir homebrew
$ curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew

If zsh doesn't work, try using bash:

$ arch -x86_64 bash
$ curl -O https://github.com/Homebrew/brew/tarball/master
$ cat master | tar xz --strip 1
$ cd homebrew

Next, install OpenSSL 1.1 for x86-64 and a x86-64-native .NET runtime:

$ arch -x86_64 /usr/local/homebrew/bin/brew install [email protected]/lib

# This .NET SDK installation will coexist with the native installation, but in a separate directory
$ arch -x86_64 /usr/local/homebrew/bin/brew install dotnet-sdk

If for some reason you can't use homebrew to install the .NET SDK (for example, if you need to install an older version), you can download the .pkg file from Microsoft and install the .NET SDK manually like so:

# Make sure to download the OSX x64 distribution 
arch -x86_64 /usr/sbin/installer -pkg ~/Downloads/dotnet-runtime-VERSION-osx-x64.pkg -target / 

Running your application

When running a .NET application that uses the AWS Encryption SDK for .NET, include the OpenSSL directory in the dynamic linker path at runtime, and specify the x64 architecture for dotnet commands:

$ export DYLD_LIBRARY_PATH="/usr/local/homebrew/opt/[email protected]/lib"
$ dotnet run -a x64 [ARGS...]

Intel-based Macs

One-time setup

Install OpenSSL 1.1:

$ brew install [email protected]

Running your application

When running a .NET application that uses the AWS Encryption SDK for .NET, include the OpenSSL directory in the dynamic linker path at runtime:

$ export DYLD_LIBRARY_PATH="/usr/local/opt/[email protected]/lib"
$ dotnet run [ARGS...]

Troubleshooting

No usable version of libssl was found

If the .NET runtime cannot locate your OpenSSL 1.1 libraries, you may encounter an error that says:

No usable version of libssl was found

Ensure that you set the DYLD_LIBRARY_PATH environment variable as instructed above.

Algorithm 'AesGcm' is not supported on this platform

If you are using an M1-based Mac and did not correctly install the x86-64-native .NET SDK/runtime, you may encounter an error that says one of the following:

AES encrypt error: Algorithm 'AesGcm' is not supported on this platform.

AES decrypt error: Algorithm 'AesGcm' is not supported on this platform.

Ensure that you install the x86-64-native .NET SDK/runtime as instructed above.