crypto: implement randomuuid

Signed-off-by: James M Snell <[email protected]> PR-URL: #36729 Backport-PR-URL: #36945 Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Filip Skokan <[email protected]> Reviewed-By: Ben Coe <[email protected]>

Author: jasnell

benchmark/crypto/randomUUID.js

@@ -0,0 +1,17 @@
+'use strict';
+
+constcommon=require('../common.js');
+const{ randomUUID }=require('crypto');
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+disableEntropyCache: [0,1],
+});
+
+functionmain({ n, disableEntropyCache }){
+disableEntropyCache=!!disableEntropyCache;
+bench.start();
+for(leti=0;i<n;++i)
+randomUUID({ disableEntropyCache });
+bench.end(n);
+}

doc/api/crypto.md

@@ -2841,6 +2841,20 @@ const n = crypto.randomInt(1, 7);
 console.log(`The dice rolled: ${n}`);
 ```
 
+### `crypto.randomUUID([options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+*`options`{Object}
+*`disableEntropyCache`{boolean} By default, to improve performance,
+ Node.js generates and caches enough random data to generate up to
+ 128 random UUIDs. To generate a UUID without using the cache, set
+`disableEntropyCache` to `true`. **Defaults**: `false`.
+* Returns:{string}
+
+Generates a random [RFC 4122][] Version 4 UUID.
+
 ### `crypto.scrypt(password, salt, keylen[, options], callback)`
 <!-- YAML
 added: v10.5.0
@@ -3582,6 +3596,7 @@ See the [list of SSL OP Flags][] for details.
 [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
 [RFC 3610]: https://www.rfc-editor.org/rfc/rfc3610.txt
 [RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt
+[RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt
 [RFC 5208]: https://www.rfc-editor.org/rfc/rfc5208.txt
 [`Buffer`]: buffer.md
 [`EVP_BytesToKey`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html

doc/api/errors.md

@@ -1704,6 +1704,12 @@ compiled with ICU support.
 
 A non-context-aware native addon was loaded in a process that disallows them.
 
+<aid="ERR_OPERATION_FAILED"></a>
+### `ERR_OPERATION_FAILED`
+
+An operation failed. This is typically used to signal the general failure of an
+asynchronous operation.
+
 <aid="ERR_OUT_OF_RANGE"></a>
 ### `ERR_OUT_OF_RANGE`
 

lib/crypto.js

@@ -53,7 +53,8 @@ const{
  randomBytes,
  randomFill,
  randomFillSync,
- randomInt
+ randomInt,
+ randomUUID,
 }=require('internal/crypto/random');
 const{
  pbkdf2,
@@ -186,6 +187,7 @@ module.exports ={
  randomFill,
  randomFillSync,
  randomInt,
+ randomUUID,
  scrypt,
  scryptSync,
 sign: signOneShot,

lib/internal/crypto/random.js

@@ -7,14 +7,27 @@ const{
 }=primordials;
 
 const{ AsyncWrap, Providers }=internalBinding('async_wrap');
-const{ kMaxLength }=require('buffer');
-const{randomBytes: _randomBytes}=internalBinding('crypto');
 const{
-ERR_INVALID_ARG_TYPE,
-ERR_INVALID_CALLBACK,
-ERR_OUT_OF_RANGE
-}=require('internal/errors').codes;
-const{ validateNumber }=require('internal/validators');
+ Buffer,
+ kMaxLength,
+}=require('buffer');
+const{
+randomBytes: _randomBytes,
+ secureBuffer,
+}=internalBinding('crypto');
+const{
+codes: {
+ERR_INVALID_ARG_TYPE,
+ERR_INVALID_CALLBACK,
+ERR_OUT_OF_RANGE,
+ERR_OPERATION_FAILED,
+}
+}=require('internal/errors');
+const{
+ validateBoolean,
+ validateNumber,
+ validateObject,
+}=require('internal/validators');
 const{ isArrayBufferView }=require('internal/util/types');
 const{ FastBuffer }=require('internal/buffer');
 
@@ -203,9 +216,113 @@ function handleError(ex, buf){
 returnbuf;
 }
 
+// Implements an RFC 4122 version 4 random UUID.
+// To improve performance, random data is generated in batches
+// large enough to cover kBatchSize UUID's at a time. The uuidData
+// and uuid buffers are reused. Each call to randomUUID() consumes
+// 16 bytes from the buffer.
+
+constkHexDigits=[
+48,49,50,51,52,53,54,55,
+56,57,97,98,99,100,101,102
+];
+
+constkBatchSize=128;
+letuuidData;
+letuuidNotBuffered;
+letuuid;
+letuuidBatch=0;
+
+functiongetBufferedUUID(){
+if(uuidData===undefined){
+uuidData=secureBuffer(16*kBatchSize);
+if(uuidData===undefined)
+thrownewERR_OPERATION_FAILED('Out of memory');
+}
+
+if(uuidBatch===0)randomFillSync(uuidData);
+uuidBatch=(uuidBatch+1)%kBatchSize;
+returnuuidData.slice(uuidBatch*16,(uuidBatch*16)+16);
+}
+
+functionrandomUUID(options){
+if(options!==undefined)
+validateObject(options,'options');
+const{
+ disableEntropyCache =false,
+}={ ...options};
+
+validateBoolean(disableEntropyCache,'options.disableEntropyCache');
+
+if(uuid===undefined){
+uuid=Buffer.alloc(36,'-');
+uuid[14]=52;// '4', identifies the UUID version
+}
+
+letuuidBuf;
+if(!disableEntropyCache){
+uuidBuf=getBufferedUUID();
+}else{
+uuidBuf=uuidNotBuffered;
+if(uuidBuf===undefined)
+uuidBuf=uuidNotBuffered=secureBuffer(16);
+if(uuidBuf===undefined)
+thrownewERR_OPERATION_FAILED('Out of memory');
+randomFillSync(uuidBuf);
+}
+
+// Variant byte: 10xxxxxx (variant 1)
+uuidBuf[8]=(uuidBuf[8]&0x3f)|0x80;
+
+// This function is structured the way it is for performance.
+// The uuid buffer stores the serialization of the random
+// bytes from uuidData.
+// xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+letn=0;
+uuid[0]=kHexDigits[uuidBuf[n]>>4];
+uuid[1]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[2]=kHexDigits[uuidBuf[n]>>4];
+uuid[3]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[4]=kHexDigits[uuidBuf[n]>>4];
+uuid[5]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[6]=kHexDigits[uuidBuf[n]>>4];
+uuid[7]=kHexDigits[uuidBuf[n++]&0xf];
+// -
+uuid[9]=kHexDigits[uuidBuf[n]>>4];
+uuid[10]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[11]=kHexDigits[uuidBuf[n]>>4];
+uuid[12]=kHexDigits[uuidBuf[n++]&0xf];
+// -
+// 4, uuid[14] is set already...
+uuid[15]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[16]=kHexDigits[uuidBuf[n]>>4];
+uuid[17]=kHexDigits[uuidBuf[n++]&0xf];
+// -
+uuid[19]=kHexDigits[uuidBuf[n]>>4];
+uuid[20]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[21]=kHexDigits[uuidBuf[n]>>4];
+uuid[22]=kHexDigits[uuidBuf[n++]&0xf];
+// -
+uuid[24]=kHexDigits[uuidBuf[n]>>4];
+uuid[25]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[26]=kHexDigits[uuidBuf[n]>>4];
+uuid[27]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[28]=kHexDigits[uuidBuf[n]>>4];
+uuid[29]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[30]=kHexDigits[uuidBuf[n]>>4];
+uuid[31]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[32]=kHexDigits[uuidBuf[n]>>4];
+uuid[33]=kHexDigits[uuidBuf[n++]&0xf];
+uuid[34]=kHexDigits[uuidBuf[n]>>4];
+uuid[35]=kHexDigits[uuidBuf[n]&0xf];
+
+returnuuid.latin1Slice(0,36);
+}
+
 module.exports={
  randomBytes,
  randomFill,
  randomFillSync,
- randomInt
+ randomInt,
+ randomUUID,
 };

lib/internal/errors.js

@@ -1259,6 +1259,7 @@ E('ERR_NO_CRYPTO',
 'Node.js is not compiled with OpenSSL crypto support',Error);
 E('ERR_NO_ICU',
 '%s is not supported on Node.js compiled without ICU',TypeError);
+E('ERR_OPERATION_FAILED','Operation failed: %s',Error);
 E('ERR_OUT_OF_RANGE',
 (str,range,input,replaceDefaultBoolean=false)=>{
 assert(range,'Missing "range" argument');

src/node_crypto.cc

@@ -67,7 +67,9 @@ namespace crypto{
 using node::THROW_ERR_TLS_INVALID_PROTOCOL_METHOD;
 
 using v8::Array;
+using v8::ArrayBuffer;
 using v8::ArrayBufferView;
+using v8::BackingStore;
 using v8::Boolean;
 using v8::ConstructorBehavior;
 using v8::Context;
@@ -97,6 +99,7 @@ using v8::SideEffectType;
 using v8::Signature;
 using v8::String;
 using v8::Uint32;
+using v8::Uint8Array;
 using v8::Undefined;
 using v8::Value;
 
@@ -6944,6 +6947,35 @@ void SetFipsCrypto(const FunctionCallbackInfo<Value>& args){
 }
 #endif/* NODE_FIPS_MODE */
 
+namespace{
+// SecureBuffer uses openssl to allocate a Uint8Array using
+// OPENSSL_secure_malloc. Because we do not yet actually
+// make use of secure heap, this has the same semantics as
+// using OPENSSL_malloc. However, if the secure heap is
+// initialized, SecureBuffer will automatically use it.
+voidSecureBuffer(const FunctionCallbackInfo<Value>& args){
+CHECK(args[0]->IsUint32());
+ Environment* env = Environment::GetCurrent(args);
+uint32_t len = args[0].As<Uint32>()->Value();
+char* data = static_cast<char*>(OPENSSL_secure_malloc(len));
+if (data == nullptr){
+// There's no memory available for the allocation.
+// Return nothing.
+return;
+ }
+memset(data, 0, len);
+ std::shared_ptr<BackingStore> store =
+ArrayBuffer::NewBackingStore(
+ data,
+ len,
+ [](void* data, size_t len, void* deleter_data){
+OPENSSL_secure_clear_free(data, len);
+ },
+ data);
+ Local<ArrayBuffer> buffer = ArrayBuffer::New(env->isolate(), store);
+ args.GetReturnValue().Set(Uint8Array::New(buffer, 0, len));
+}
+} // namespace
 
 voidInitialize(Local<Object> target,
  Local<Value> unused,
@@ -7038,6 +7070,8 @@ void Initialize(Local<Object> target,
 #ifndef OPENSSL_NO_SCRYPT
  env->SetMethod(target, "scrypt", Scrypt);
 #endif// OPENSSL_NO_SCRYPT
+
+ env->SetMethod(target, "secureBuffer", SecureBuffer);
 }
 
 } // namespace crypto

test/parallel/test-crypto-randomuuid.js

@@ -0,0 +1,58 @@
+'use strict';
+
+constcommon=require('../common');
+
+if(!common.hasCrypto)
+common.skip('missing crypto');
+
+constassert=require('assert');
+const{
+ randomUUID,
+}=require('crypto');
+
+constlast=newSet([
+'00000000-0000-0000-0000-000000000000'
+]);
+
+functiontestMatch(uuid){
+assert.match(
+uuid,
+/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+}
+
+// Generate a number of UUID's to make sure we're
+// not just generating the same value over and over
+// and to make sure the batching changes the random
+// bytes.
+for(letn=0;n<130;n++){
+constuuid=randomUUID();
+assert(!last.has(uuid));
+last.add(uuid);
+assert.strictEqual(typeofuuid,'string');
+assert.strictEqual(uuid.length,36);
+testMatch(uuid);
+
+// Check that version 4 identifier was populated.
+assert.strictEqual(
+Buffer.from(uuid.substr(14,2),'hex')[0]&0x40,0x40);
+
+// Check that clock_seq_hi_and_reserved was populated with reserved bits.
+assert.strictEqual(
+Buffer.from(uuid.substr(19,2),'hex')[0]&0b1100_0000,0b1000_0000);
+}
+
+// Test non-buffered UUID's
+{
+testMatch(randomUUID({disableEntropyCache: true}));
+testMatch(randomUUID({disableEntropyCache: true}));
+testMatch(randomUUID({disableEntropyCache: true}));
+testMatch(randomUUID({disableEntropyCache: true}));
+
+assert.throws(()=>randomUUID(1),{
+code: 'ERR_INVALID_ARG_TYPE'
+});
+
+assert.throws(()=>randomUUID({disableEntropyCache: ''}),{
+code: 'ERR_INVALID_ARG_TYPE'
+});
+}