[CryptoAPI] Crypto API 2.0 is coming!

Forge Component
Published on 2018-11-11 by Ricardo Silva
18 votes
Published on 2018-11-11 by Ricardo Silva


Some of you might have noticed the release of version 2.0.0 of CryptoAPI.

I haven't released any new version of CryptoAPI because it was kind of in what I thought was a good place, but I have decided to turn that around.

For CryptoAPI 2 I want to take things to a new level, so here are some of the changes, the reasons behind those changes, and philosophy going forward (which I hope to be able to keep up with).

API Revamp

While trying to keep each individual function relatively simple, CryptoAPI 1 was getting a bit cluttered.

I have revamped the core API (encrypt, decrypt, etc) to be simpler. There's ONE encrypt function, which is the one you should use, which takes a key. You can create keys in a couple of different ways.

With this I hope to bring some clarity and less confusion to newcomers: keys are always a binary blob, there's only one function to encrypt.

Removed functionality

I have removed the following functionality from CryptoAPI:

  • GenerateGUID -- from what I read, my worries about the builtin not being cryptographically secure were unfounded. You should use the builtin function for the same functionality and it should be perfectly fine.
  • GetPrivateKey -- This is a hard one. I removed this mostly to try and promote better key management practices. One shouldn't just use the same key for everything, and having this easy-to-obtain key could promote bad use of the key and weakening it by producing too many outputs with it. I don't want to get too technical, but you can still make use of the private key with some of the new functionality.
  • Det_Encrypt -- I added this as a neat curiosity, but almost immediately regretted it. People might feel tempted to use this "mode" because of the smaller encrypted size, and that's just the wrong reason to do it. The purpose of this mode was to allow encrypted searchable fields, which I have serious doubts anyone is using it for this purpose, so I have removed it. For all other uses, Encrypt is the way to go.

Added functionality

Because I don't just want to take stuff away, I have expanded (or plan to in some cases) CryptoAPI with some long desired features:

  • ComputeMac now lets you choose the algorithm to use
  • Added CompareMac for a secure Mac comparison without fear of timing attacks on hash comparison. I might still change the name for this one as it is also useful for comparing hashes, not just mac's.
  • Added GeneratePassword, a secure way to generate passwords using a Cryptographically Secure Random Number Generator (which the platform's version does not use), and the full breadth of alphanumeric characters (not just lower case letters + digits, like the platform one).
  • Added functionality to Save keys. This will allow you to securely communicate a key with a third party using their RSA public key, or save it using the environment's very own symmetric key. This is intended to promote good key generation practice and having different keys for different purposes.
  • RSA signing. I hadn't provided this in v1 because I was unsure whether the .NET builtin functionality was secure. I am still investigating this to provide the best possible alternative (PSS signing), but this functionality will be available soon.
  • Support for PEM-encoded RSA keys. .NET doesn't seem to natively support this, so I was shying away from building my own PEM reader or picking one up from the internets. No more. This common format will be supported in CryptoAPI v2 (not yet available, but will be soon).
  • AWS Sig V4 implementation for REST calls. While not yet implemented, I fully intend to add an AWS Sig v4 implementation which you can simply drop into a REST request to Amazon and it will be properly signed.

Philosophy going forward

CryptoAPI v1 was a humble attempt at providing simple to use high level cryptographic primitives. This is why I shied away from giving users too much freedom. With that freedom users could make more mistakes and end up with insecure implementations.

While I will still maintain high standards for the implementations and the OutSystems-y API, CryptoAPI v2 will not be so humble.

I now aim to take over Crypto with OutSystems and be the goto component for ANYTHING crypto related.

Don't be surprised if I start "absorbing" other components' functionality if they're crypto related (e.g. JTW Token generation / validation), or if I incorporate other high level encryption primitive schemas, if they're sufficiently used.

Also don't be surprised if some functionality starts to be ported to Mobile runtime.

This also means I'm a lot more open for ideas. If you have something crypto that needs to be implemented, let me know and we might be able to arrange for it to be added to CryptoAPI.

If you have an implementation you'd like to contribute with, also feel free to throw it at me.

Hey Ricardo,

Good to read this! It's great you found some time and motivation to do this!

Hi Ricardo,

Thanks for the good work. I already have a BCrypt implementation on the forge and I had on my todo list to implement Argon2 and Scrypt. You were thinking of including any of this algorithms?



I was intending to replace the HashPassword with something stronger, maybe even allow the end user to choose the algorithm.

BCrypt, SCrypt and Argon are definitely worth looking into.

When I get sometime I will check if you already included scrypt and argon. If not I will implement it and if you want you just need to use the same code. Just let us know when you do it and I will remove my components. We really don't need so many components doing the same thing.

Hi Marcelo,

Version 2.1 of CryptoAPI includes support for PBKDF2, BCrypt and SCrypt hashing of passwords.

I left out Argon2 because:

  • couldn't find a .net library implementing argon2id version
  • parameterization seems a bit too complex at the moment

I might revisit this in the future.

Default is BCrypt which is the most battle tested algorithm of the 3, but all 3 should be fine to use.

Hi Ricardo,

Thanks a lot for those improvements. I will deprecate my BCrypt component.

Just some thoughts for improvement:



Hi Marcelo,

Thanks for noticing the BCrypt bug I had. Version 2.1.1 fixes it.

BCrypt and SCrypt do have salt. I don't set it myself, but the underlying libraries do.

That one doesn't directly implement argon2, it uses Sodium for that. Looking into this library it seems that it uses a native, unmanaged dll for the actual implementations. From what I read, these kind of libraries are not very friendly to get to work under IIS, so it might prove to be a challenge to OutSystems-ify it.

In any case, the major problem I currently have with argon2 is not so much the finding an implementation, but the parameterization bit. I'll still need to wrap my head around this in order to be able to simplify it for general use.