doc: fix crypto.hkdf callback derivedKey type

[panva]

crypto.hkdf('sha512', 'key', 'salt', 'info', 64, console.log)
// ArrayBuffer {
//  [Uint8Contents]: <24 15 6e 2c 35 52 5b aa f3 d0 fb b9 2b 73 4c 80 32 a1 10 a3 f1 2e 25 96 e4 41 e1 92 48 70 d8 4c 3a 50 06 52 a7 23 73 80 24 43 24 51 04 6f d2 37 ef ad 83 92 fb 68 6c 52 77 a5 9e 01 05 39 16 53>,
//  byteLength: 64
// }

The example snippet below this block as well as hkdfSync are correct in that ArrayBuffer is returned.

[github-actions]

Fast-track has been requested by @panva. Please 👍 to approve.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/39141/

[tniessen]

Buffer is consistent with the rest of the Node.js crypto API though... why does this not return a Buffer? :(

[tniessen]

So... we have three key derivation functions now: crypto.pbkdf2, crypto.scrypt, and crypto.hkdf. All three accept a callback and all three callbacks accept the arguments (err, derivedKey), but derivedKey has different types?!

[panva]

Buffer is consistent with the rest of the Node.js crypto API though... why does this not return a Buffer? :(

@jasnell would be best to answer with confidence. But if i was to guess, hkdf was built in because it is required for the SubtleCrypto interface. As such as it was built with the return types that interface requires and was then just exposed as-is without thinking about it "fitting in" with the rest.

I was also surprised to see ArrayBuffer returned, I expected a Buffer both from "that's how node crypto works" perspective as well as docs.

[panva]

@tniessen @jasnell do you see a way we could change the return type to be more fitting now?

[tniessen]

Personally, I'd consider the current behavior a bug, but even if we changed it to match the documentation, it would be inconsistent with hkdfSync, which returns an ArrayBuffer (and is documented as such). Changing both to return Buffer is either impossible or, at least, semver-major :(

[panva]

[tniessen]

Refs: #39471

[github-actions]

Commit Queue failed

- Loading data for nodejs/node/pull/39453
✔  Done loading data for nodejs/node/pull/39453
----------------------------------- PR info ------------------------------------
Title      doc: fix crypto.hkdf callback derivedKey type (#39453)
Author     Filip Skokan  (@panva)
Branch     panva:doc-hkdf-fix -> nodejs:master
Labels     crypto, doc, fast-track
Commits    1
 - doc: fix crypto.hkdf callback derivedKey type
Committers 1
 - Filip Skokan 
PR-URL: https://github.com/nodejs/node/pull/39453
Reviewed-By: James M Snell 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/39453
Reviewed-By: James M Snell 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Mon, 19 Jul 2021 20:42:16 GMT
   ✔  Approvals: 1
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/39453#pullrequestreview-710559837
   ℹ  This PR is being fast-tracked
   ✖  This PR needs to wait 3 more hours to land (or 0 hours if there is one more approval)
   ✔  Last GitHub Actions successful
   ℹ  Green GitHub Actions CI is sufficient
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/1066883872

[github-actions]

Landed in c1354ff...5ad6a99