Token is not encrypted, despite claims

[Freaky]

This token is encrypted and signed using a secret key generated by your rails application, so a hacker who gets a hold of it can't modify it

rock-solid encryption technology

Tokens are base64-encoded and signed with HMAC-SHA256. There's no encryption anywhere whatsoever.

[jdickey]

A MAC "accepts as input a secret key and an arbitrary-length message to be authenticated, and outputs a MAC (sometimes known as a tag). The MAC value protects both a message's data integrity as well as its authenticity, by allowing verifiers (who also possess the secret key) to detect any changes to the message content.". It's "sometimes called a keyed (cryptographic) hash function (however, cryptographic hash function is only one of the possible ways to generate MACs)". This is basic enough to be in the Wikipedia article on Message authentication code; anyone who's had any professional involvement with crypto and/­or secure comms, including the people who taught me on-the-job 30 years ago, take this to be nearly as basic as "two plus two equals four".

It does not encrypt the message itself and it's not possible to produce original plaintext given only an HMAC token; the token accompanies the payload it was generated from (and then signed). Anyone else who has the secret key which was used to generate the HMAC may generate an HMAC using the claimed algorithm from the claimed content and claimed secret key; if the new HMAC matches that in the token, then the "claimed" qualifier drops off the message and sender/signer.

Naturally, therefore, one needs to send the payload (in the form in which it was signed, usually cleartext) along with but separately from the HMAC signature; this is typically accomplished by encoding the latter in, say, an email header, where the email body contains the plaintext being signed. It's good practice to sign and authenticate attachments separately; the system that we developed back in the day would en­crypt and sign the attachments, and add the manifest to a MIME-Multipart message (this was long before RFC 2015, let alone RFC 3156).

You have what looks to be some good code here; shame that you're either misrepresenting it or, more charitably, misunderstanding its basic purpose.

[undercase]

You're right. I have used "encryption" too broadly in the documentation. This is not a security flaw in the library, as all that is needed for authentication is signing, but I will fix the language issue.

[jdickey]

I never claimed it was a security flaw, merely that it's orthogonal to what most people think of as "secure message transfer", which involves encrypting the plaintext. I'm glad to see that you're going to work on the wording, though.

Good luck with the project.