Using Self-Signed Certificates for Amazon Alexa Skills

If you want to implement your own Alexa Skills for your Amazon Echo and don’t intend to make them public, you can use a self-signed certificate for your web service where you host the skill.

I’ve been impressed on how many developers can’t make this work and have opted to use a Lambda function as a proxy, when it is very easy to create the self-signed certificate.

If you intend to publish your skill then you’d need to buy a SSL Certificate. These steps won’t help you.  You also need a real and trusted SSL Certificate if you want to host audio files to be used with the Audio SSML Tag.

Create a Self-Signed Certificate using OpenSSL

Note: The following steps will be performed in a Linux host with an Apache Web Server.

First verify that you have the openssl package installed in your server.  I think all Linux distributions come with this package pre-installed nowadays.  If you have a Debian-based Linux distribution like Mint, Ubuntu or Debian itself you can check that out with the following command:

$ dpkg -l openssl
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name                         Version             Architecture        Description
+++-============================-===================-===================-==============================================================
ii  openssl                      1.0.2d-3            amd64               Secure Sockets Layer toolkit - cryptographic utility

In order to create a SSL certificate that works with the Amazon Alexa Skills you first need to create a private key using this openssl tool. We’re going to store all certificates and keys under the folder /etc/ssl/alexa.  Create the private key as follows:

root@kagura:/etc/ssl$ mkdir alexa
root@kagura:/etc/ssl$ cd alexa
root@kagura:/etc/ssl/alexa$ openssl genrsa -out private-key.pem 2048
Generating RSA private key, 2048 bit long modulus
...................................................+++
.....................................................................+++
e is 65537 (0x10001)

So what’s just happened? We created a new RSA key of 2048 bits and it is stored in a file named private-key.pem. The longer the key, the most secure it is. If you’re wondering why it is called RSA it’s because those are the initial letters of the last names of its creators (Ron Rivest, Adi Shamir, and Leonard Adleman).

We will now use the openssl  application called req”, mainly used to create certificate requests, but can also create a self-signed certificate.  But first, since Amazon needs the fully qualified domain name of the server that is hosting the skill to be included in the certificate as a Subject Alternative Name, we’re going to create a configuration file for this req application to make things a lot easier.

Let’s create the configuration file as follows:

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no
 
[req_distinguished_name]
C = US
ST = Provide your two letter state abbreviation
L = Provide the name of the city in which you are located
O = Provide a name for your organization
CN = Provide a name for the skill
 
[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @subject_alternate_names
 
[subject_alternate_names]
DNS.1 = Provide your fully qualified domain name

You need to provide the name of the state, city, organization and the name of your Amazon skill in the req_distinguished_name section. After that you have to provide the fully qualified domain name of your server in the subject_alternate_names section. That’s an extension of the version 3 of the X.509 standard format of public key certificates.

Your domain name must be exactly the same as the one used in your skill’s endpoint.  That means if your endpoint is https://skills.thescorpius.com/myskill then the fully qualified domain name you’re going to provide as a Subject Alternative Name must be skills.thescorpius.com.

Here’s an example for a Skill hosted in skills.thescorpius.com:

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no

[req_distinguished_name]
C = US
ST = FL
L = Miami
O = Scorpius
CN = Scorpius Skill

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @subject_alternate_names

[subject_alternate_names]
DNS.1 = skills.thescorpius.com

Now we’re ready to create the self-signed certificate like this:

root@kagura:/etc/ssl$ mkdir alexa
root@kagura:/etc/ssl/alexa$ openssl req -new -x509 -days 365 -key private-key.pem -config configuration.cnf -out certificate.pem

And now we have our certificate called certificate.pem that will last exactly one year from today.

Now go to the Amazon Developer Portal, go to your skill, click Edit and then SSL Certificate. Select the option I will upload a self-signed certificate in X.509 format and paste the contents of the certificate.pem file there.

 

Configuring the Self-Signed Certificate in an Apache Web Server

If you’re using an Apache Web Server to host your skill then you have to configure the recently created SSL certificate in it. Locate the configuration of your virtual host where your skill is being hosted and add the following lines:

SSLEngine on

SSLCertificateFile      /etc/ssl/alexa/certificate.pem
SSLCertificateKeyFile   /etc/ssl/alexa/private-key.pem

So it should look something similar to this:

<VirtualHost _default_:443>
	ServerName skills.thescorpius.com

        (...)

	SSLEngine on

	SSLCertificateFile      /etc/ssl/alexa/certificate.pem
	SSLCertificateKeyFile   /etc/ssl/alexa/private-key.pem

</VirtualHost>

Restart your Apache Web Server and your skill should start to work immediately!