crypto: add key object API

This commit makes multiple important changes:
1. A new key object API is introduced. The KeyObject class itself is
not exposed to users, instead, several new APIs can be used to
construct key objects: createSecretKey, createPrivateKey and
createPublicKey. The new API also allows to convert between
different key formats, and even though the API itself is not
compatible to the WebCrypto standard in any way, it makes
interoperability much simpler.
2. Key objects can be used instead of the raw key material in all
relevant crypto APIs.
3. The handling of asymmetric keys has been unified and greatly
improved. Node.js now fully supports both PEM-encoded and
DER-encoded public and private keys.
4. Conversions between buffers and strings have been moved to native
code for sensitive data such as symmetric keys due to security
considerations such as zeroing temporary buffers.
5. For compatibility with older versions of the crypto API, this
change allows to specify Buffers and strings as the "passphrase"
option when reading or writing an encoded key. Note that this
can result in unexpected behavior if the password contains a
null byte.
PR-URL: #24234
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: tniessen

doc/api/crypto.md

@@ -763,6 +763,11 @@ The selected public or private key encoding is incompatible with other options.
 
 An invalid [crypto digest algorithm][] was specified.
 
+<aid="ERR_CRYPTO_INVALID_KEY_OBJECT_TYPE"></a>
+### ERR_CRYPTO_INVALID_KEY_OBJECT_TYPE
+
+The given crypto key object's type is invalid for the attempted operation.
+
 <aid="ERR_CRYPTO_INVALID_STATE"></a>
 ### ERR_CRYPTO_INVALID_STATE
 

doc/api/errors.md

@@ -59,6 +59,11 @@ const {
  generateKeyPair,
  generateKeyPairSync
 }=require('internal/crypto/keygen');
+const{
+ createSecretKey,
+ createPublicKey,
+ createPrivateKey
+}=require('internal/crypto/keys');
 const{
  DiffieHellman,
  DiffieHellmanGroup,
@@ -149,6 +154,9 @@ module.exports = exports = {
  createECDH,
  createHash,
  createHmac,
+ createPrivateKey,
+ createPublicKey,
+ createSecretKey,
  createSign,
  createVerify,
  getCiphers,

lib/crypto.js

@@ -12,6 +12,11 @@ const {
 }=require('internal/errors').codes;
 const{ validateString }=require('internal/validators');
 
+const{
+ preparePrivateKey,
+ preparePublicOrPrivateKey,
+ prepareSecretKey
+}=require('internal/crypto/keys');
 const{
  getDefaultEncoding,
  kHandle,
@@ -38,19 +43,25 @@ const { deprecate, normalizeEncoding } = require('internal/util');
 // Lazy loaded for startup performance.
 letStringDecoder;
 
-functionrsaFunctionFor(method,defaultPadding){
+functionrsaFunctionFor(method,defaultPadding,keyType){
 return(options,buffer)=>{
-constkey=options.key||options;
+const{ format, type, data, passphrase }=
+keyType==='private' ?
+preparePrivateKey(options) :
+preparePublicOrPrivateKey(options);
 constpadding=options.padding||defaultPadding;
-constpassphrase=options.passphrase||null;
-returnmethod(toBuf(key),buffer,padding,passphrase);
+returnmethod(data,format,type,passphrase,buffer,padding);
 };
 }
 
-constpublicEncrypt=rsaFunctionFor(_publicEncrypt,RSA_PKCS1_OAEP_PADDING);
-constpublicDecrypt=rsaFunctionFor(_publicDecrypt,RSA_PKCS1_PADDING);
-constprivateEncrypt=rsaFunctionFor(_privateEncrypt,RSA_PKCS1_PADDING);
-constprivateDecrypt=rsaFunctionFor(_privateDecrypt,RSA_PKCS1_OAEP_PADDING);
+constpublicEncrypt=rsaFunctionFor(_publicEncrypt,RSA_PKCS1_OAEP_PADDING,
+'public');
+constpublicDecrypt=rsaFunctionFor(_publicDecrypt,RSA_PKCS1_PADDING,
+'private');
+constprivateEncrypt=rsaFunctionFor(_privateEncrypt,RSA_PKCS1_PADDING,
+'private');
+constprivateDecrypt=rsaFunctionFor(_privateDecrypt,RSA_PKCS1_OAEP_PADDING,
+'public');
 
 functiongetDecoder(decoder,encoding){
 encoding=normalizeEncoding(encoding);
@@ -105,11 +116,7 @@ function createCipher(cipher, password, options, decipher) {
 
 functioncreateCipherWithIV(cipher,key,options,decipher,iv){
 validateString(cipher,'cipher');
-key=toBuf(key);
-if(!isArrayBufferView(key)){
-throwinvalidArrayBufferView('key',key);
-}
-
+key=prepareSecretKey(key);
 iv=toBuf(iv);
 if(iv!==null&&!isArrayBufferView(iv)){
 throwinvalidArrayBufferView('iv',iv);

lib/internal/crypto/cipher.js

@@ -12,6 +12,10 @@ const {
  toBuf
 }=require('internal/crypto/util');
 
+const{
+ prepareSecretKey
+}=require('internal/crypto/keys');
+
 const{ Buffer }=require('buffer');
 
 const{
@@ -88,10 +92,7 @@ function Hmac(hmac, key, options) {
 if(!(thisinstanceofHmac))
 returnnewHmac(hmac,key,options);
 validateString(hmac,'hmac');
-if(typeofkey!=='string'&&!isArrayBufferView(key)){
-thrownewERR_INVALID_ARG_TYPE('key',
-['string','TypedArray','DataView'],key);
-}
+key=prepareSecretKey(key);
 this[kHandle]=new_Hmac();
 this[kHandle].init(hmac,toBuf(key));
 this[kState]={

lib/internal/crypto/hash.js

@@ -6,24 +6,32 @@ const {
  generateKeyPairDSA,
  generateKeyPairEC,
 OPENSSL_EC_NAMED_CURVE,
-OPENSSL_EC_EXPLICIT_CURVE,
-PK_ENCODING_PKCS1,
-PK_ENCODING_PKCS8,
-PK_ENCODING_SPKI,
-PK_ENCODING_SEC1,
-PK_FORMAT_DER,
-PK_FORMAT_PEM
+OPENSSL_EC_EXPLICIT_CURVE
 }=internalBinding('crypto');
+const{
+ parsePublicKeyEncoding,
+ parsePrivateKeyEncoding,
+
+ PublicKeyObject,
+ PrivateKeyObject
+}=require('internal/crypto/keys');
 const{ customPromisifyArgs }=require('internal/util');
 const{ isUint32, validateString }=require('internal/validators');
 const{
-ERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS,
 ERR_INVALID_ARG_TYPE,
 ERR_INVALID_ARG_VALUE,
 ERR_INVALID_CALLBACK,
 ERR_INVALID_OPT_VALUE
 }=require('internal/errors').codes;
 
+const{ isArrayBufferView }=require('internal/util/types');
+
+functionwrapKey(key,ctor){
+if(typeofkey==='string'||isArrayBufferView(key))
+returnkey;
+returnnewctor(key);
+}
+
 functiongenerateKeyPair(type,options,callback){
 if(typeofoptions==='function'){
 callback=options;
@@ -38,6 +46,9 @@ function generateKeyPair(type, options, callback) {
 constwrap=newAsyncWrap(Providers.KEYPAIRGENREQUEST);
 wrap.ondone=(ex,pubkey,privkey)=>{
 if(ex)returncallback.call(wrap,ex);
+// If no encoding was chosen, return key objects instead.
+pubkey=wrapKey(pubkey,PublicKeyObject);
+privkey=wrapKey(privkey,PrivateKeyObject);
 callback.call(wrap,null,pubkey,privkey);
 };
 
@@ -69,86 +80,32 @@ function handleError(impl, wrap) {
 functionparseKeyEncoding(keyType,options){
 const{ publicKeyEncoding, privateKeyEncoding }=options;
 
-if(publicKeyEncoding==null||typeofpublicKeyEncoding!=='object')
-thrownewERR_INVALID_OPT_VALUE('publicKeyEncoding',publicKeyEncoding);
-
-const{format: strPublicFormat,type: strPublicType}=publicKeyEncoding;
-
-letpublicType;
-if(strPublicType==='pkcs1'){
-if(keyType!=='rsa'){
-thrownewERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS(
-strPublicType,'can only be used for RSA keys');
-}
-publicType=PK_ENCODING_PKCS1;
-}elseif(strPublicType==='spki'){
-publicType=PK_ENCODING_SPKI;
+letpublicFormat,publicType;
+if(publicKeyEncoding==null){
+publicFormat=publicType=undefined;
+}elseif(typeofpublicKeyEncoding==='object'){
+({
+format: publicFormat,
+type: publicType
+}=parsePublicKeyEncoding(publicKeyEncoding,keyType,
+'publicKeyEncoding'));
 }else{
-thrownewERR_INVALID_OPT_VALUE('publicKeyEncoding.type',strPublicType);
+thrownewERR_INVALID_OPT_VALUE('publicKeyEncoding',publicKeyEncoding);
 }
 
-letpublicFormat;
-if(strPublicFormat==='der'){
-publicFormat=PK_FORMAT_DER;
-}elseif(strPublicFormat==='pem'){
-publicFormat=PK_FORMAT_PEM;
+letprivateFormat,privateType,cipher,passphrase;
+if(privateKeyEncoding==null){
+privateFormat=privateType=undefined;
+}elseif(typeofprivateKeyEncoding==='object'){
+({
+format: privateFormat,
+type: privateType,
+ cipher,
+ passphrase
+}=parsePrivateKeyEncoding(privateKeyEncoding,keyType,
+'privateKeyEncoding'));
 }else{
-thrownewERR_INVALID_OPT_VALUE('publicKeyEncoding.format',
-strPublicFormat);
-}
-
-if(privateKeyEncoding==null||typeofprivateKeyEncoding!=='object')
 thrownewERR_INVALID_OPT_VALUE('privateKeyEncoding',privateKeyEncoding);
-
-const{
- cipher,
- passphrase,
-format: strPrivateFormat,
-type: strPrivateType
-}=privateKeyEncoding;
-
-letprivateType;
-if(strPrivateType==='pkcs1'){
-if(keyType!=='rsa'){
-thrownewERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS(
-strPrivateType,'can only be used for RSA keys');
-}
-privateType=PK_ENCODING_PKCS1;
-}elseif(strPrivateType==='pkcs8'){
-privateType=PK_ENCODING_PKCS8;
-}elseif(strPrivateType==='sec1'){
-if(keyType!=='ec'){
-thrownewERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS(
-strPrivateType,'can only be used for EC keys');
-}
-privateType=PK_ENCODING_SEC1;
-}else{
-thrownewERR_INVALID_OPT_VALUE('privateKeyEncoding.type',strPrivateType);
-}
-
-letprivateFormat;
-if(strPrivateFormat==='der'){
-privateFormat=PK_FORMAT_DER;
-}elseif(strPrivateFormat==='pem'){
-privateFormat=PK_FORMAT_PEM;
-}else{
-thrownewERR_INVALID_OPT_VALUE('privateKeyEncoding.format',
-strPrivateFormat);
-}
-
-if(cipher!=null){
-if(typeofcipher!=='string')
-thrownewERR_INVALID_OPT_VALUE('privateKeyEncoding.cipher',cipher);
-if(privateFormat===PK_FORMAT_DER&&
-(privateType===PK_ENCODING_PKCS1||
-privateType===PK_ENCODING_SEC1)){
-thrownewERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS(
-strPrivateType,'does not support encryption');
-}
-if(typeofpassphrase!=='string'){
-thrownewERR_INVALID_OPT_VALUE('privateKeyEncoding.passphrase',
-passphrase);
-}
 }
 
 return{
@@ -181,8 +138,8 @@ function check(type, options, callback) {
 }
 
 impl=(wrap)=>generateKeyPairRSA(modulusLength,publicExponent,
-publicType,publicFormat,
-privateType,privateFormat,
+publicFormat,publicType,
+privateFormat,privateType,
 cipher,passphrase,wrap);
 }
 break;
@@ -200,8 +157,8 @@ function check(type, options, callback) {
 }
 
 impl=(wrap)=>generateKeyPairDSA(modulusLength,divisorLength,
-publicType,publicFormat,
-privateType,privateFormat,
+publicFormat,publicType,
+privateFormat,privateType,
 cipher,passphrase,wrap);
 }
 break;
@@ -219,8 +176,8 @@ function check(type, options, callback) {
 thrownewERR_INVALID_OPT_VALUE('paramEncoding',paramEncoding);
 
 impl=(wrap)=>generateKeyPairEC(namedCurve,paramEncoding,
-publicType,publicFormat,
-privateType,privateFormat,
+publicFormat,publicType,
+privateFormat,privateType,
 cipher,passphrase,wrap);
 }
 break;