密鑰派生(ArkTS)

以HKDF256密鑰為例，完成密鑰派生。具體的場景介紹及支持的算法規格。

開發步驟

生成密鑰

指定密鑰別名。
初始化密鑰屬性集，可指定參數HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG（可選），用于標識基于該密鑰派生出的密鑰是否由HUKS管理。
- 當TAG設置為HUKS_STORAGE_ONLY_USED_IN_HUKS時，表示基于該密鑰派生出的密鑰，由HUKS管理，可保證派生密鑰全生命周期不出安全環境。
- 當TAG設置為HUKS_STORAGE_KEY_EXPORT_ALLOWED時，表示基于該密鑰派生出的密鑰，返回給調用方管理，由業務自行保證密鑰安全。
- 若業務未設置TAG的具體值，表示基于該密鑰派生出的密鑰，即可由HUKS管理，也可返回給調用方管理，業務可在后續派生時再選擇使用何種方式保護密鑰。
- 開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
調用[generateKeyItem]生成密鑰，具體請參考[密鑰生成]。

除此之外，開發者也可以參考[密鑰導入]，導入已有的密鑰。

密鑰派生

獲取密鑰別名、指定對應的屬性參數HuksOptions。
可指定參數HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG（可選），用于標識派生得到的密鑰是否由HUKS管理。

生成	派生	規格
HUKS_STORAGE_ONLY_USED_IN_HUKS	HUKS_STORAGE_ONLY_USED_IN_HUKS	密鑰由HUKS管理
HUKS_STORAGE_KEY_EXPORT_ALLOWED	HUKS_STORAGE_KEY_EXPORT_ALLOWED	密鑰返回給調用方管理
未指定TAG具體值	HUKS_STORAGE_ONLY_USED_IN_HUKS	密鑰由HUKS管理
未指定TAG具體值	HUKS_STORAGE_KEY_EXPORT_ALLOWED	密鑰返回給調用方管理
未指定TAG具體值	未指定TAG具體值	密鑰返回給調用方管理

注：派生時指定的TAG值，不可與生成時指定的TAG值沖突。表格中僅列舉有效的指定方式。

調用[initSession]初始化密鑰會話，并獲取會話的句柄handle。
調用[updateSession]更新密鑰會話。
調用[finishSession]結束密鑰會話，完成派生。

QQ截圖20240705210937.png

刪除密鑰

當密鑰廢棄不用時，需要調用[deleteKeyItem]刪除密鑰，具體請參考[密鑰刪除]

/*
 * 以下以HKDF256密鑰的Promise操作使用為例
 */
import { huks } from '@kit.UniversalKeystoreKit';

/*
 * 確定密鑰別名和封裝密鑰屬性參數集
 */
let srcKeyAlias = "hkdf_Key";
let deriveHkdfInData = "deriveHkdfTestIndata";
let handle: number;
let finishOutData: Uint8Array;
let HuksKeyDeriveKeySize = 32;
/* 集成生成密鑰參數集 */
let properties: Array< huks.HuksParam > = [
  {
    tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
    value: huks.HuksKeyAlg.HUKS_ALG_AES,
  }, {
  tag: huks.HuksTag.HUKS_TAG_PURPOSE,
  value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DERIVE,
}, {
  tag: huks.HuksTag.HUKS_TAG_DIGEST,
  value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256,
}, {
  tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
  value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128,
}, {
  tag: huks.HuksTag.HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG,
  value: huks.HuksKeyStorageType.HUKS_STORAGE_ONLY_USED_IN_HUKS,
}];

let huksOptions: huks.HuksOptions = {
  properties: properties,
  inData: new Uint8Array(new Array())
}
/* 集成init時密鑰參數集 */
let initProperties: Array< huks.HuksParam > = [{
  tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
  value: huks.HuksKeyAlg.HUKS_ALG_HKDF,
}, {
  tag: huks.HuksTag.HUKS_TAG_PURPOSE,
  value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DERIVE,
}, {
  tag: huks.HuksTag.HUKS_TAG_DIGEST,
  value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256,
}, {
  tag: huks.HuksTag.HUKS_TAG_DERIVE_KEY_SIZE,
  value: HuksKeyDeriveKeySize,
}];

let initOptions: huks.HuksOptions = {
  properties: initProperties,
  inData: new Uint8Array(new Array())
}
/* 集成finish時密鑰參數集 */
let finishProperties: Array< huks.HuksParam > = [{
  tag: huks.HuksTag.HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG,
  value: huks.HuksKeyStorageType.HUKS_STORAGE_ONLY_USED_IN_HUKS,
}, {
  tag: huks.HuksTag.HUKS_TAG_IS_KEY_ALIAS,
  value: true,
}, {
  tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
  value: huks.HuksKeyAlg.HUKS_ALG_AES,
}, {
  tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
  value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256,
}, {
  tag: huks.HuksTag.HUKS_TAG_PURPOSE,
  value:
  huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT |
  huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT,
}, {
  tag: huks.HuksTag.HUKS_TAG_DIGEST,
  value: huks.HuksKeyDigest.HUKS_DIGEST_NONE,
}, {
  tag: huks.HuksTag.HUKS_TAG_KEY_ALIAS,
  value: StringToUint8Array(srcKeyAlias),
}, {
  tag: huks.HuksTag.HUKS_TAG_PADDING,
  value: huks.HuksKeyPadding.HUKS_PADDING_NONE,
}, {
  tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
  value: huks.HuksCipherMode.HUKS_MODE_ECB,
}];
let finishOptions: huks.HuksOptions = {
  properties: finishProperties,
  inData: new Uint8Array(new Array())
}

function StringToUint8Array(str: String) {
  let arr: number[] = new Array();
  for (let i = 0, j = str.length; i < j; ++i) {
    arr.push(str.charCodeAt(i));
  }
  return new Uint8Array(arr);
}

class throwObject {
  isThrow = false;
}

function generateKeyItem(keyAlias: string, huksOptions: huks.HuksOptions, throwObject: throwObject) {
  return new Promise< void >((resolve, reject) = > {
    try {
      huks.generateKeyItem(keyAlias, huksOptions, (error, data) = > {
        if (error) {
          reject(error);
        } else {
          resolve(data);
        }
      });
    } catch (error) {
      throwObject.isThrow = true;
      throw (error as Error);
    }
  });
}

async function publicGenKeyFunc(keyAlias: string, huksOptions: huks.HuksOptions) {
  console.info(`enter promise generateKeyItem`);
  let throwObject: throwObject = { isThrow: false };
  try {
    await generateKeyItem(keyAlias, huksOptions, throwObject)
      .then((data) = > {
        console.info(`promise: generateKeyItem success, data = ${JSON.stringify(data)}`);
      })
      .catch((error: Error) = > {
        if (throwObject.isThrow) {
          throw (error as Error);
        } else {
          console.error(`promise: generateKeyItem failed, ${JSON.stringify(error)}`);
        }
      });
  } catch (error) {
    console.error(`promise: generateKeyItem input arg invalid, ${JSON.stringify(error)}`);
  }
}

function initSession(keyAlias: string, huksOptions: huks.HuksOptions, throwObject: throwObject) {
  return new Promise< huks.HuksSessionHandle >((resolve, reject) = > {
    try {
      huks.initSession(keyAlias, huksOptions, (error, data) = > {
        if (error) {
          reject(error);
        } else {
          resolve(data);
        }
      });
    } catch (error) {
      throwObject.isThrow = true;
      throw (error as Error);
    }
  });
}

async function publicInitFunc(keyAlias: string, huksOptions: huks.HuksOptions) {
  console.info(`enter promise doInit`);
  let throwObject: throwObject = { isThrow: false };
  try {
    await initSession(keyAlias, huksOptions, throwObject)
      .then((data) = > {
        console.info(`promise: doInit success, data = ${JSON.stringify(data)}`);
        handle = data.handle;
      })
      .catch((error: Error) = > {
        if (throwObject.isThrow) {
          throw (error as Error);
        } else {
          console.error(`promise: doInit failed, ${JSON.stringify(error)}`);
        }
      });
  } catch (error) {
    console.error(`promise: doInit input arg invalid, ${JSON.stringify(error)}`);
  }
}

function updateSession(handle: number, huksOptions: huks.HuksOptions, throwObject: throwObject) {
  return new Promise< huks.HuksOptions >((resolve, reject) = > {
    try {
      huks.updateSession(handle, huksOptions, (error, data) = > {
        if (error) {
          reject(error);
        } else {
          resolve(data);
        }
      });
    } catch (error) {
      throwObject.isThrow = true;
      throw (error as Error);
    }
  });
}

async function publicUpdateFunc(handle: number, huksOptions: huks.HuksOptions) {
  console.info(`enter promise doUpdate`);
  let throwObject: throwObject = { isThrow: false };
  try {
    await updateSession(handle, huksOptions, throwObject)
      .then((data) = > {
        console.info(`promise: doUpdate success, data = ${JSON.stringify(data)}`);
      })
      .catch((error: Error) = > {
        if (throwObject.isThrow) {
          throw (error as Error);
        } else {
          console.error(`promise: doUpdate failed, ${JSON.stringify(error)}`);
        }
      });
  } catch (error) {
    console.error(`promise: doUpdate input arg invalid, ${JSON.stringify(error)}`);
  }
}

function finishSession(handle: number, huksOptions: huks.HuksOptions, throwObject: throwObject) {
  return new Promise< huks.HuksReturnResult >((resolve, reject) = > {
    try {
      huks.finishSession(handle, huksOptions, (error, data) = > {
        if (error) {
          reject(error);
        } else {
          resolve(data);
        }
      });
    } catch (error) {
      throwObject.isThrow = true;
      throw (error as Error);
    }
  });
}

async function publicFinishFunc(handle: number, huksOptions: huks.HuksOptions) {
  console.info(`enter promise doFinish`);
  let throwObject: throwObject = { isThrow: false };
  try {
    await finishSession(handle, huksOptions, throwObject)
      .then((data) = > {
        finishOutData = data.outData as Uint8Array;
        console.info(`promise: doFinish success, data = ${JSON.stringify(data)}`);
      })
      .catch((error: Error) = > {
        if (throwObject.isThrow) {
          throw (error as Error);
        } else {
          console.error(`promise: doFinish failed, ${JSON.stringify(error)}`);
        }
      });
  } catch (error) {
    console.error(`promise: doFinish input arg invalid, ${JSON.stringify(error)}`);
  }
}

function deleteKeyItem(keyAlias: string, huksOptions: huks.HuksOptions, throwObject: throwObject) {
  return new Promise< void >((resolve, reject) = > {
    try {
      huks.deleteKeyItem(keyAlias, huksOptions, (error, data) = > {
        if (error) {
          reject(error);
        } else {
          resolve(data);
        }
      });
    } catch (error) {
      throwObject.isThrow = true;
      throw (error as Error);
    }
  });
}

async function publicDeleteKeyFunc(keyAlias: string, huksOptions: huks.HuksOptions) {
  console.info(`enter promise deleteKeyItem`);
  let throwObject: throwObject = { isThrow: false };
  try {
    await deleteKeyItem(keyAlias, huksOptions, throwObject)
      .then((data) = > {
        console.info(`promise: deleteKeyItem key success, data = ${JSON.stringify(data)}`);
      })
      .catch((error: Error) = > {
        if (throwObject.isThrow) {
          throw (error as Error);
        } else {
          console.error(`promise: deleteKeyItem failed, ${JSON.stringify(error)}`);
        }
      });
  } catch (error) {
    console.error(`promise: deleteKeyItem input arg invalid, ${JSON.stringify(error)}`);
  }
}

async function testDerive() {
  /* 生成密鑰 */
  await publicGenKeyFunc(srcKeyAlias, huksOptions);
  /* 進行派生操作 */
  await publicInitFunc(srcKeyAlias, initOptions);
  initOptions.inData = StringToUint8Array(deriveHkdfInData);
  await publicUpdateFunc(handle, initOptions);
  await publicFinishFunc(handle, finishOptions);
  await publicDeleteKeyFunc(srcKeyAlias, huksOptions);
}