I wanted to implement a way to generate an RSA public/private key pair and protect the private key with a password.

Looking into the Web crypto api, I thought the wrapKey/unwrapKey pair was the way to go. But then I got confused, and the documentation is not really helping because it seems to assume you know everything about cryptography.

What I'm really stumped on is, why do we need a wrapKey/unwrapKey in the first place? Can't you generate a symmetric key and encrypt the RSA private key with the symmetric key, and later decrypt it with the same symmetric key?


1 Answer 1


I get nausea every time I look at the WebCrypto API documentation, so if all you get is confusion, consider yourself lucky.

From what I can tell by reading the W3C Web Cryptography API recommendation of 2017, in particular the §19 Algorithm Overview table, the only difference is that the AES-KW algorithm of RFC 3394 supports wrapKey/unwrapKey but not encrypt/decrypt.

The intent appears to be that you use wrapKey/unwrapKey when you know the plaintext is itself a short uniform random octet string, but encrypt/decrypt if it has any other structure to its distribution; then if you attempt to use encrypt/decrypt with AES-KW, the API will noisily fail because you might be trying to use it with structured data, which AES-KW is unfit to conceal.

For all other documented encryption schemes, public-key or secret-key, wrapKey/unwrapKey just defers to encrypt/decrypt. So there's no idea of KEM at all, which simultaneously generates a key and encapsulates it for you. One can hope that they will introduce a KEM API in the next version of the specification, since with NIST PQCRYPTO it appears the world is finally, nearly two decades after Shoup introduced the concept, converging on it as the basic way to do public-key encryption.

  • 1
    $\begingroup$ Thanks. That makes sense. Also it's great to know I'm not the crazy one to be confused! $\endgroup$
    – Vlad
    Dec 30, 2017 at 22:38
  • $\begingroup$ @Squeamish Ossifrage, why is AES-KW unfit to conceal structure and where in the Web Cryptography API spec does it say that it's supposed to fail for e.g. an RSA-OAEP private key? $\endgroup$
    – ByteEater
    Jun 25, 2020 at 23:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.