• Introduction
• Articles We've Written
• Alexa
• The Team
• Let's Talk
• eBooks

Developing for Alexa using Elixir (Part Three)

Part Three: The Making of LessVerifiesAlexa

In the first post of this series we went into an overview of how Alexa works from both an end-user and a developer’s point of view. The second post describes the actual making of So Near

While we were certifying the skill we ran into an unexpected snag: Amazon will automatically verify that your endpoint checks the authenticity of the messages it receives. It’s not enough to give you an API key, because anyone could, at least in theory, get between their servers and yours and cause all sorts of trouble.

So Amazon signs their own messages using an X509 certificate and a private key. And there’s this whole crazy dance that has to happen between your server and Amazon in order to verify this message.

This is you verifying Alexa’s message

Checking the signature on the dotted line

Elixir is still pretty new as far as programming languages go. So we quickly discovered that we would have to solve this problem ourselves. Now we could have tried going down the quick and dirty route of shelling out to the command line and using the openssl utility. But we always try to stay away from shelling out to command line utilities given user input — that can always leave you open to gaping security holes.

Could we solve this problem using strictly what Elixir, Erlang and OTP provide us with? We knew Erlang had a public_key module so we figured we’d start there.

Verification Basics.

Before you get to the signature part, which is the slightly tricky part of the process, there are a few basics checks that need to be made. They are:

• Checking that the request is intended for your app (you get the app id in the request)
• Checking that the request was submitted in the last 150 seconds.
• Grabbing the URL of Amazon’s key from a URL header.
• Ensuring that URL points to Alexa’s AWS storage bucket.
• Grabbing the certificate that the URL points to, to verify the signature of the message.

All of this is pretty straightforward stuff. Refer to the package’s code if you want to see the actual implementations for these parts.

Getting a hold of the certificate data.

The first thing we need to do in order to verify the signature is decode the data in the PEM we downloaded, using :public_key.pem_decode/1 This returns a bundle of certificates that we then need to decode into Erlang records.

certs = pem
  |> :public_key.pem_decode()
  |> Enum.map(&get_cert_value/1)
decoded_certs = Enum.map(certs, &decode_cert/1)

get_cert_value/1 is a simple pattern match, but decode_cert/1 is where we start to deal with records. The way Erlang’s :public_key module works is that an Erlang header gets generated from an ASN.1 schema for what the contents of a public key look like. So first we need to grab hold of this schema:

@pubkey_schema Record.extract_all(from_lib: "public_key/include/OTP-PUB-KEY.hrl”)`

And then we need to write a little helper to help us traverse the nested structure of this record. Each of the entries in this record is actually a tuple, hence the use of elem/2.

defp get_field(record, field) do
  record_type = elem(record, 0)
  idx = @pubkey_schema[record_type]
    |> Keyword.keys
    |> Enum.find_index(&(&1 == field))

  elem(record, idx + 1)
end

So with that out of the way, let’s take a look at our decode_cert/1 function.

defp decode_cert(cert) do
  cert
  |> :public_key.pkix_decode_cert(:otp)
  |> get_field(:tbsCertificate)
end

In case you’re wondering, tbs stands for to be signed. This is where all of the certificate data we need is located.

Checking the certificate.

So there are a few checks that LessVerifiesAlexa runs against the certificate.

• check_cert_dates/1 ensures that certificates in the chain are still valid based on their dates.
• check_san/1 checks that the cert chain does indeed hold a certificate that is signed by Amazon by looking at the domain the certificate is registered against.
• check_cert_path/1 Ensures that the certificate chain we have ends with a trusted root-level certificate. The certifi package was a godsend for this, and the fact that it’s bundled with quite a few Erlang/Elixir packages means there’s a good chance it’s already a part of your dependencies.
• confirm_payload_signature/3 does the actual work of verifying the body of the request against the signature. It looks like this:

defp confirm_payload_signature(cert, req_signature, raw_body) do
  :public_key.verify(
    raw_body,
    :sha,
    Base.decode64!(req_signature, ignore: :whitespace),
    public_key(cert)
  )
end

The public_key/1 helper function looks like this:

defp public_key(cert) do
  cert
    |> get_field(:subjectPublicKeyInfo)
    |> get_field(:subjectPublicKey)
end

Checking the signature is one of the simplest parts of the process. I won’t bore you to death with all the details of how the other parts work, feel free to look at the source and ask any questions you want in the comments section. The other parts are more complicated than what you’re seeing here. But after those checks go through, we know that our certificate is valid.

Publishing a hex package.

Once all these issues were resolved, it was time to package the solution up and publish it. Testing wasn’t too complicated: - you inject the HTTP client rather than hardcoding it so you can stub out the HTTP requests. - badssl.com had all kinds of invalid certs we needed for testing this stuff out. Big props to the folks behind that project, they saved us a ton of tinkering with SSL certificates.

ExDoc makes writing documentation so easy it’s not even worth mentioning.

And one last thing. We used dialyxir in this project and it is so worth the price of admission. With few specs written, it caught a couple of bugs after a refactoring session which the tests didn’t catch. Yes, that means the coverage wasn’t good enough, but I would have missed that had it not been for dialyzer. Seriously, use it, you’ll feel much more confident in your code if you put in just a little bit of effort.

The Life-Changing Magic of Banging Your Head Against The Wall Trying Stuff Out

Tucked away behind the neat description you’re reading here is a whole lot of reading documentation, consulting the header I mentioned before, trying to make sense of RFC 5280, and actually reading through public_key.erl.

Dealing with this stuff often seems so daunting that many developers just give up on it altogether. But if there’s one thing that will magically change your life as a developer, that’s the realization that nothing you deal with is magic. Sometimes you have to get your hands dirty and poke at complex nested data that you can’t make heads or tail of — that was the case here. Sometimes you have to, gasp, look an algorithm or data structure up and see what the implications of using it. Sometimes it’s jumping head first into a new framework or stack, or even a different domain altogether.

But there is no magic. Code is code. At the end of the day, especially if you’re dealing with open source and have the luxury of popping the trunk and inspecting things for yourself, you will figure out how things work. Just don’t give up and say “I don’t know how to do this”. Take a break, thing of something else and come back at the problem with a fresh pair of eyes. Constantly ask yourself “what is it that I don’t understand here?” and find the answer to that question. Soon enough, you’ll find you know everything you need to get the job done.

Share this article via:

Linkedin |

Facebook |

Twitter

LessEverything, Inc. © 2018