واجهة برمجة التشفير على الويب

[السجل]

الإصدار	التغييرات
v23.5.0	خوارزميات Ed25519 و X25519 أصبحت الآن مستقرة.
v19.0.0	لم تعد تجريبية باستثناء خوارزميات Ed25519، Ed448، X25519، و X448.
v20.0.0، v18.17.0	يتم الآن إجبار الوسائط والتحقق منها وفقًا لتعريفات WebIDL الخاصة بها كما هو الحال في عمليات تنفيذ واجهة برمجة التشفير على الويب الأخرى.
v18.4.0، v16.17.0	تمت إزالة تنسيق الاستيراد/التصدير الخاص 'node.keyObject'.
v18.4.0، v16.17.0	تمت إزالة الخوارزميات الخاصة 'NODE-DSA'، 'NODE-DH'، و 'NODE-SCRYPT'.
v18.4.0، v16.17.0	تمت إضافة خوارزميات 'Ed25519'، 'Ed448'، 'X25519'، و 'X448'.
v18.4.0، v16.17.0	تمت إزالة الخوارزميات الخاصة 'NODE-ED25519' و 'NODE-ED448'.
v18.4.0، v16.17.0	تمت إزالة المنحنيات المسماة الخاصة 'NODE-X25519' و 'NODE-X448' من خوارزمية 'ECDH'.

[مستقر: 2 - مستقر]

مستقر: 2 استقرار: 2 - مستقر

يوفر Node.js تنفيذًا لواجهة برمجة التشفير القياسية على الويب Web Crypto API.

استخدم globalThis.crypto أو require('node:crypto').webcrypto للوصول إلى هذا الوحدة.

const { subtle } = globalThis.crypto

;(async function () {
  const key = await subtle.generateKey(
    {
      name: 'HMAC',
      hash: 'SHA-256',
      length: 256,
    },
    true,
    ['sign', 'verify']
  )

  const enc = new TextEncoder()
  const message = enc.encode('I love cupcakes')

  const digest = await subtle.sign(
    {
      name: 'HMAC',
    },
    key,
    message
  )
})()

أمثلة

إنشاء مفاتيح

يمكن استخدام فئة <SubtleCrypto> لإنشاء مفاتيح متناظرة (سرية) أو أزواج مفاتيح غير متناظرة (مفتاح عام ومفتاح خاص).

مفاتيح AES

const { subtle } = globalThis.crypto

async function generateAesKey(length = 256) {
  const key = await subtle.generateKey(
    {
      name: 'AES-CBC',
      length,
    },
    true,
    ['encrypt', 'decrypt']
  )

  return key
}

أزواج مفاتيح ECDSA

const { subtle } = globalThis.crypto

async function generateEcKey(namedCurve = 'P-521') {
  const { publicKey, privateKey } = await subtle.generateKey(
    {
      name: 'ECDSA',
      namedCurve,
    },
    true,
    ['sign', 'verify']
  )

  return { publicKey, privateKey }
}

أزواج مفاتيح Ed25519/X25519

const { subtle } = globalThis.crypto

async function generateEd25519Key() {
  return subtle.generateKey(
    {
      name: 'Ed25519',
    },
    true,
    ['sign', 'verify']
  )
}

async function generateX25519Key() {
  return subtle.generateKey(
    {
      name: 'X25519',
    },
    true,
    ['deriveKey']
  )
}

مفاتيح HMAC

const { subtle } = globalThis.crypto

async function generateHmacKey(hash = 'SHA-256') {
  const key = await subtle.generateKey(
    {
      name: 'HMAC',
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return key
}

أزواج مفاتيح RSA

const { subtle } = globalThis.crypto
const publicExponent = new Uint8Array([1, 0, 1])

async function generateRsaKey(modulusLength = 2048, hash = 'SHA-256') {
  const { publicKey, privateKey } = await subtle.generateKey(
    {
      name: 'RSASSA-PKCS1-v1_5',
      modulusLength,
      publicExponent,
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return { publicKey, privateKey }
}

التشفير وفك التشفير

const crypto = globalThis.crypto

async function aesEncrypt(plaintext) {
  const ec = new TextEncoder()
  const key = await generateAesKey()
  const iv = crypto.getRandomValues(new Uint8Array(16))

  const ciphertext = await crypto.subtle.encrypt(
    {
      name: 'AES-CBC',
      iv,
    },
    key,
    ec.encode(plaintext)
  )

  return {
    key,
    iv,
    ciphertext,
  }
}

async function aesDecrypt(ciphertext, key, iv) {
  const dec = new TextDecoder()
  const plaintext = await crypto.subtle.decrypt(
    {
      name: 'AES-CBC',
      iv,
    },
    key,
    ciphertext
  )

  return dec.decode(plaintext)
}

تصدير واستيراد المفاتيح

const { subtle } = globalThis.crypto

async function generateAndExportHmacKey(format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.generateKey(
    {
      name: 'HMAC',
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return subtle.exportKey(format, key)
}

async function importHmacKey(keyData, format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.importKey(
    format,
    keyData,
    {
      name: 'HMAC',
      hash,
    },
    true,
    ['sign', 'verify']
  )

  return key
}

لفّ مفاتيح فكّها

const { subtle } = globalThis.crypto

async function generateAndWrapHmacKey(format = 'jwk', hash = 'SHA-512') {
  const [key, wrappingKey] = await Promise.all([
    subtle.generateKey(
      {
        name: 'HMAC',
        hash,
      },
      true,
      ['sign', 'verify']
    ),
    subtle.generateKey(
      {
        name: 'AES-KW',
        length: 256,
      },
      true,
      ['wrapKey', 'unwrapKey']
    ),
  ])

  const wrappedKey = await subtle.wrapKey(format, key, wrappingKey, 'AES-KW')

  return { wrappedKey, wrappingKey }
}

async function unwrapHmacKey(wrappedKey, wrappingKey, format = 'jwk', hash = 'SHA-512') {
  const key = await subtle.unwrapKey(format, wrappedKey, wrappingKey, 'AES-KW', { name: 'HMAC', hash }, true, [
    'sign',
    'verify',
  ])

  return key
}

التوقيع والتحقق

const { subtle } = globalThis.crypto

async function sign(key, data) {
  const ec = new TextEncoder()
  const signature = await subtle.sign('RSASSA-PKCS1-v1_5', key, ec.encode(data))
  return signature
}

async function verify(key, signature, data) {
  const ec = new TextEncoder()
  const verified = await subtle.verify('RSASSA-PKCS1-v1_5', key, signature, ec.encode(data))
  return verified
}

اشتقاق البتات والمفاتيح

const { subtle } = globalThis.crypto

async function pbkdf2(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder()
  const key = await subtle.importKey('raw', ec.encode(pass), 'PBKDF2', false, ['deriveBits'])
  const bits = await subtle.deriveBits(
    {
      name: 'PBKDF2',
      hash: 'SHA-512',
      salt: ec.encode(salt),
      iterations,
    },
    key,
    length
  )
  return bits
}

async function pbkdf2Key(pass, salt, iterations = 1000, length = 256) {
  const ec = new TextEncoder()
  const keyMaterial = await subtle.importKey('raw', ec.encode(pass), 'PBKDF2', false, ['deriveKey'])
  const key = await subtle.deriveKey(
    {
      name: 'PBKDF2',
      hash: 'SHA-512',
      salt: ec.encode(salt),
      iterations,
    },
    keyMaterial,
    {
      name: 'AES-GCM',
      length,
    },
    true,
    ['encrypt', 'decrypt']
  )
  return key
}

مُلخّص

const { subtle } = globalThis.crypto

async function digest(data, algorithm = 'SHA-512') {
  const ec = new TextEncoder()
  const digest = await subtle.digest(algorithm, ec.encode(data))
  return digest
}

مصفوفة الخوارزميات

يُفصّل الجدول الخوارزميات التي تدعمها مكتبة واجهة برمجة التطبيقات المشفرة في Node.js وواجهات برمجة التطبيقات المدعومة لكل منها:

الخوارزمية	generateKey	exportKey	importKey	encrypt	decrypt	wrapKey	unwrapKey	deriveBits	deriveKey	sign	verify	digest
'RSASSA-PKCS1-v1_5'	✔	✔	✔							✔	✔
'RSA-PSS'	✔	✔	✔							✔	✔
'RSA-OAEP'	✔	✔	✔	✔	✔	✔	✔
'ECDSA'	✔	✔	✔							✔	✔
'Ed25519'	✔	✔	✔							✔	✔
'Ed448'	✔	✔	✔							✔	✔
'ECDH'	✔	✔	✔					✔	✔
'X25519'	✔	✔	✔					✔	✔
'X448'	✔	✔	✔					✔	✔
'AES-CTR'	✔	✔	✔	✔	✔	✔	✔
'AES-CBC'	✔	✔	✔	✔	✔	✔	✔
'AES-GCM'	✔	✔	✔	✔	✔	✔	✔
'AES-KW'	✔	✔	✔			✔	✔
'HMAC'	✔	✔	✔							✔	✔
'HKDF'		✔	✔					✔	✔
'PBKDF2'		✔	✔					✔	✔
'SHA-1'												✔
'SHA-256'												✔
'SHA-384'												✔
'SHA-512'												✔

الصنف: Crypto

مُضاف في: v15.0.0

globalThis.crypto هي مثيل للصنف Crypto. Crypto هي كائن مفرد يوفر الوصول إلى باقي واجهة برمجة التطبيقات المشفرة.

crypto.subtle

مُضاف في: v15.0.0

• النوع: <SubtleCrypto>

يوفر الوصول إلى واجهة برمجة التطبيقات SubtleCrypto.

crypto.getRandomValues(typedArray)

مُضاف في: v15.0.0

• typedArray <Buffer> | <TypedArray>
• القيمة المُرجعة: <Buffer> | <TypedArray>

يُولّد قيمًا عشوائية قوية تشفيرياً. يتم ملء typedArray المُعطى بقيم عشوائية، ويتم إرجاع مرجع إلى typedArray.

يجب أن يكون typedArray المُعطى مثيلًا قائمًا على الأعداد الصحيحة من <TypedArray>، أي أن Float32Array و Float64Array غير مُقبولين.

سيتم إطلاق خطأ إذا كان حجم typedArray المُعطى أكبر من 65,536 بايت.

crypto.randomUUID()

مضاف في: v16.7.0

• قيمة الإرجاع: <string>

يولد معرفًا فريدًا عالميًا (UUID) عشوائيًا من الإصدار 4 وفقًا لـ RFC 4122. يتم توليد معرف UUID باستخدام مولد أعداد عشوائية زائف مشفر.

Class: CryptoKey

مضاف في: v15.0.0

cryptoKey.algorithm

مضاف في: v15.0.0

• النوع: <AesKeyGenParams> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams>

كائن يحدد الخوارزمية التي يمكن استخدام المفتاح معها بالإضافة إلى معلمات إضافية خاصة بالخوارزمية.

قراءة فقط.

cryptoKey.extractable

مضاف في: v15.0.0

• النوع: <boolean>

عندما تكون قيمته true، يمكن استخراج <CryptoKey> باستخدام إما subtleCrypto.exportKey() أو subtleCrypto.wrapKey().

قراءة فقط.

cryptoKey.type

مضاف في: v15.0.0

• النوع: <string> أحد 'secret', 'private', أو 'public'.

سلسلة تحدد ما إذا كان المفتاح مفتاحًا متماثلًا ('secret') أو غير متماثل ('private' أو 'public').

cryptoKey.usages

مضاف في: v15.0.0

• النوع: <string[]>

مصفوفة من السلاسل التي تحدد العمليات التي يمكن استخدام المفتاح معها.

الاستخدامات الممكنة هي:

• 'encrypt' - يمكن استخدام المفتاح لتشفير البيانات.
• 'decrypt' - يمكن استخدام المفتاح لفك تشفير البيانات.
• 'sign' - يمكن استخدام المفتاح لإنشاء توقيعات رقمية.
• 'verify' - يمكن استخدام المفتاح للتحقق من صحة التوقيعات الرقمية.
• 'deriveKey' - يمكن استخدام المفتاح لاشتقاق مفتاح جديد.
• 'deriveBits' - يمكن استخدام المفتاح لاشتقاق بتات.
• 'wrapKey' - يمكن استخدام المفتاح لـلف مفتاح آخر.
• 'unwrapKey' - يمكن استخدام المفتاح لفك لف مفتاح آخر.

تعتمد استخدامات المفاتيح الصالحة على خوارزمية المفتاح (التي يتم تحديدها بواسطة cryptokey.algorithm.name).

نوع المفتاح	'encrypt'	'decrypt'	'sign'	'verify'	'deriveKey'	'deriveBits'	'wrapKey'	'unwrapKey'
'AES-CBC'	✔	✔					✔	✔
'AES-CTR'	✔	✔					✔	✔
'AES-GCM'	✔	✔					✔	✔
'AES-KW'							✔	✔
'ECDH'					✔	✔
'X25519'					✔	✔
'X448'					✔	✔
'ECDSA'			✔	✔
'Ed25519'			✔	✔
'Ed448'			✔	✔
'HDKF'					✔	✔
'HMAC'			✔	✔
'PBKDF2'					✔	✔
'RSA-OAEP'	✔	✔					✔	✔
'RSA-PSS'			✔	✔
'RSASSA-PKCS1-v1_5'			✔	✔

Class: CryptoKeyPair

تم الإضافة في: v15.0.0

CryptoKeyPair هو كائن قاموس بسيط يحتوي على خاصيتي publicKey و privateKey، ويمثل زوج مفاتيح غير متماثل.

cryptoKeyPair.privateKey

تم الإضافة في: v15.0.0

• النوع: <CryptoKey> <CryptoKey> حيث سيكون نوعه 'private'.

cryptoKeyPair.publicKey

تم الإضافة في: v15.0.0

• النوع: <CryptoKey> <CryptoKey> حيث سيكون نوعه 'public'.

Class: SubtleCrypto

تم الإضافة في: v15.0.0

subtle.decrypt(algorithm, key, data)

تم الإضافة في: v15.0.0

• algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
• key: <CryptoKey>
• data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• القيمة المُرجعة: <Promise> يتم الوفاء به مع <ArrayBuffer>

باستخدام الأسلوب والمعلمات المحددة في algorithm والمواد الرئيسية التي يوفرها key، تحاول subtle.decrypt() فك تشفير data المُقدمة. في حالة النجاح، سيتم حل الوعد المُرجع مع <ArrayBuffer> تحتوي على نتيجة النص العادي.

الخوارزميات المدعومة حاليًا تتضمن:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'

subtle.deriveBits(algorithm, baseKey[, length])

[History]

الإصدار	التغييرات
v22.5.0, v20.17.0	أصبحت معلمة الطول اختيارية الآن لـ 'ECDH', 'X25519', و 'X448'.
v18.4.0, v16.17.0	تمت إضافة خوارزميات 'X25519', و 'X448'.
v15.0.0	تمت الإضافة في: v15.0.0

• algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
• baseKey: <CryptoKey>
• length: <number> | <null> الافتراضي: null
• الإرجاع: <Promise> يتم الوفاء بوعد بـ <ArrayBuffer>

باستخدام الأسلوب والمعلمات المحددة في algorithm ومادة التشفير المقدمة بواسطة baseKey، تحاول subtle.deriveBits() توليد length بت.

عندما لا يتم توفير length أو يكون null، يتم توليد الحد الأقصى لعدد البتات لخوارزمية معينة. يُسمح بذلك لخوارزميات 'ECDH', 'X25519', و 'X448'، أما بالنسبة للخوارزميات الأخرى، فيجب أن يكون length رقمًا.

إذا نجحت العملية، فسيتم حل الوعد المُرجع مع <ArrayBuffer> يحتوي على البيانات المُولدة.

تشمل الخوارزميات المدعومة حاليًا:

• 'ECDH'
• 'X25519'
• 'X448'
• 'HKDF'
• 'PBKDF2'

subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)

[History]

الإصدار	التغييرات
v18.4.0, v16.17.0	تمت إضافة خوارزميات 'X25519', و 'X448'.
v15.0.0	تمت الإضافة في: v15.0.0

• algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
• baseKey: <CryptoKey>
• derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>
• extractable: <boolean>
• keyUsages: <string[]> انظر استخدامات المفتاح.
• الإرجاع: <Promise> يتم الوفاء بوعد بـ <CryptoKey>

باستخدام الأسلوب والمعلمات المحددة في algorithm، ومادة التشفير المقدمة بواسطة baseKey، تحاول subtle.deriveKey() توليد <CryptoKey> جديد بناءً على الأسلوب والمعلمات في derivedKeyAlgorithm.

إن استدعاء subtle.deriveKey() يعادل استدعاء subtle.deriveBits() لتوليد مادة تشفير خام، ثم تمرير النتيجة إلى أسلوب subtle.importKey() باستخدام معلمات deriveKeyAlgorithm, extractable, و keyUsages كمدخل.

تشمل الخوارزميات المدعومة حاليًا:

• 'ECDH'
• 'X25519'
• 'X448'
• 'HKDF'
• 'PBKDF2'

subtle.digest(algorithm, data)

مضاف في: v15.0.0

• algorithm: <string> | <Object>
• data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• قيمة الإرجاع: <Promise> تُحقق بوعد <ArrayBuffer>

باستخدام الأسلوب المحدد بواسطة algorithm، تحاول subtle.digest() إنشاء مُلخص لـ data. في حالة النجاح، يتم حل الوعد المُرجع بـ <ArrayBuffer> يحتوي على المُلخص المحسوب.

إذا تم توفير algorithm كـ <string>، فيجب أن يكون أحدها:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم توفير algorithm كـ <Object>، فيجب أن يكون لديه خاصية name وقيمتها واحدة من القيم المذكورة أعلاه.

subtle.encrypt(algorithm, key, data)

مضاف في: v15.0.0

• algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
• key: <CryptoKey>
• data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• قيمة الإرجاع: <Promise> تُحقق بوعد <ArrayBuffer>

باستخدام الأسلوب والمعلمات المحددة بواسطة algorithm ومواد التشفير المقدمة بواسطة key، تحاول subtle.encrypt() تشفير data. في حالة النجاح، يتم حل الوعد المُرجع بـ <ArrayBuffer> يحتوي على النتيجة المشفرة.

تتضمن الخوارزميات المدعومة حاليًا:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'

subtle.exportKey(format, key)

[السجل]

الإصدار	التغييرات
v18.4.0, v16.17.0	تمت إضافة خوارزميات 'Ed25519', 'Ed448', 'X25519', و'X448'.
v15.9.0	تمت إزالة تصدير JWK لـ 'NODE-DSA'.
v15.0.0	تمت الإضافة في: v15.0.0

• format: <سلسلة> يجب أن يكون أحد القيم 'raw', 'pkcs8', 'spki', أو 'jwk'.
• key: <CryptoKey>
• القيمة المُرجعّة: <Promise> يتم الوفاء بوعد بـ <ArrayBuffer> | <Object>.

تصدير المفتاح المعطى بالتنسيق المحدد، إذا كان مدعومًا.

إذا لم يكن <CryptoKey> قابلًا للاستخراج، فسيتم رفض الوعد المُرجع.

عندما يكون format إما 'pkcs8' أو 'spki' ويكون التصدير ناجحًا، سيتم حل الوعد المُرجع باستخدام <ArrayBuffer> يحتوي على بيانات المفتاح المُصدرة.

عندما يكون format هو 'jwk' ويكون التصدير ناجحًا، سيتم حل الوعد المُرجع باستخدام كائن جافا سكريبت يتوافق مع مواصفات مفتاح الويب JSON.

نوع المفتاح	'spki'	'pkcs8'	'jwk'	'raw'
'AES-CBC'			✔	✔
'AES-CTR'			✔	✔
'AES-GCM'			✔	✔
'AES-KW'			✔	✔
'ECDH'	✔	✔	✔	✔
'ECDSA'	✔	✔	✔	✔
'Ed25519'	✔	✔	✔	✔
'Ed448'	✔	✔	✔	✔
'HDKF'
'HMAC'			✔	✔
'PBKDF2'
'RSA-OAEP'	✔	✔	✔
'RSA-PSS'	✔	✔	✔
'RSASSA-PKCS1-v1_5'	✔	✔	✔

subtle.generateKey(algorithm, extractable, keyUsages)

تمت الإضافة في: v15.0.0

• algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>

• extractable: <قيمة منطقية>

• keyUsages: <سلسلة []> انظر استخدامات المفتاح.

• القيمة المُرجعّة: <Promise> يتم الوفاء بوعد بـ <CryptoKey> | <CryptoKeyPair>

باستخدام الأسلوب والمعلمات المُقدّمة في algorithm، تحاول subtle.generateKey() إنشاء مادة تشفير جديدة. اعتمادًا على الأسلوب المُستخدم، قد يُنشئ الأسلوب إما <CryptoKey> واحدًا أو <CryptoKeyPair>.

تتضمن خوارزميات إنشاء <CryptoKeyPair> (المفتاح العام والخاص) المُدعّمة:

• 'RSASSA-PKCS1-v1_5'
• 'RSA-PSS'
• 'RSA-OAEP'
• 'ECDSA'
• 'Ed25519'
• 'Ed448'
• 'ECDH'
• 'X25519'
• 'X448'

تتضمن خوارزميات إنشاء <CryptoKey> (المفتاح السري) المُدعّمة:

• 'HMAC'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'
• 'AES-KW'

subtle.importKey(format, keyData, algorithm, extractable, keyUsages)

[السجل]

الإصدار	التغييرات
v18.4.0، v16.17.0	تمت إضافة خوارزميات 'Ed25519', 'Ed448', 'X25519', و 'X448'.
v15.9.0	تمت إزالة استيراد JWK 'NODE-DSA'.
v15.0.0	تمت الإضافة في: v15.0.0

• format: <سلسلة> يجب أن يكون أحد 'raw', 'pkcs8', 'spki', أو 'jwk'.

• keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <كائن>

• algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable: <قيمة منطقية>

• keyUsages: <سلسلة[]> انظر استخدامات المفتاح.

• القيمة المُرجعة: <وعد> يتم الوفاء به مع <CryptoKey>

تحاول طريقة subtle.importKey() تفسير keyData المُقدّم كـ format مُعطى لإنشاء مثيل <CryptoKey> باستخدام الوسيطات algorithm, extractable, و keyUsages المُقدّمة. إذا نجح الاستيراد، فسيتم حل الوعد المُرجّع باستخدام <CryptoKey> المُنشأ.

إذا كان استيراد مفتاح 'PBKDF2'، فيجب أن يكون extractable مساويًا لـ false.

تتضمن الخوارزميات المدعومة حاليًا:

نوع المفتاح	'spki'	'pkcs8'	'jwk'	'raw'
'AES-CBC'			✔	✔
'AES-CTR'			✔	✔
'AES-GCM'			✔	✔
'AES-KW'			✔	✔
'ECDH'	✔	✔	✔	✔
'X25519'	✔	✔	✔	✔
'X448'	✔	✔	✔	✔
'ECDSA'	✔	✔	✔	✔
'Ed25519'	✔	✔	✔	✔
'Ed448'	✔	✔	✔	✔
'HDKF'				✔
'HMAC'			✔	✔
'PBKDF2'				✔
'RSA-OAEP'	✔	✔	✔
'RSA-PSS'	✔	✔	✔
'RSASSA-PKCS1-v1_5'	✔	✔	✔

subtle.sign(algorithm, key, data)

[السجل]

الإصدار	التغييرات
v18.4.0, v16.17.0	تمت إضافة خوارزميات 'Ed25519', و 'Ed448'
v15.0.0	تمت الإضافة في: v15.0.0

• algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
• key: <CryptoKey>
• data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• القيمة المرجعة: <Promise> تُوفي بوعد <ArrayBuffer>

باستخدام الأسلوب والمعلمات التي يوفرها algorithm والمواد الرئيسية التي يوفرها key، تحاول subtle.sign() إنشاء توقيع تشفيري لـ data. في حالة النجاح، يتم حل الوعد المُرجع بـ <ArrayBuffer> يحتوي على التوقيع المُنشأ.

الخوارزميات المدعومة حاليًا تتضمن:

• 'RSASSA-PKCS1-v1_5'
• 'RSA-PSS'
• 'ECDSA'
• 'Ed25519'
• 'Ed448'
• 'HMAC'

subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)

تمت الإضافة في: v15.0.0

• format: <string> يجب أن يكون أحد 'raw', 'pkcs8', 'spki', أو 'jwk'.

• wrappedKey: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

• unwrappingKey: <CryptoKey>

• unwrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>

• unwrappedKeyAlgo: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>

• extractable: <boolean>

• keyUsages: <string[]> انظر استخدامات المفتاح.

• القيمة المرجعة: <Promise> تُوفي بوعد <CryptoKey>

في التشفير، يشير "لف مفتاح" إلى تصدير المواد الرئيسية ثم تشفيرها. تحاول طريقة subtle.unwrapKey() فك تشفير مفتاح ملفوف وإنشاء مثيل <CryptoKey>. وهو ما يعادل استدعاء subtle.decrypt() أولاً على بيانات المفتاح المشفرة (باستخدام وسيطات wrappedKey، و unwrapAlgo، و unwrappingKey كمدخل) ثم تمرير النتائج إلى طريقة subtle.importKey() باستخدام وسيطات unwrappedKeyAlgo، و extractable، و keyUsages كمدخلات. في حالة النجاح، يتم حل الوعد المُرجع بمثال كائن <CryptoKey>.

خوارزميات اللف المدعومة حاليًا تتضمن:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'
• 'AES-KW'

خوارزميات المفتاح المفكوك المدعومة تتضمن:

• 'RSASSA-PKCS1-v1_5'
• 'RSA-PSS'
• 'RSA-OAEP'
• 'ECDSA'
• 'Ed25519'
• 'Ed448'
• 'ECDH'
• 'X25519'
• 'X448'
• 'HMAC'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'
• 'AES-KW'

subtle.verify(algorithm, key, signature, data)

[السجل]

الإصدار	التغييرات
v18.4.0، v16.17.0	تمت إضافة خوارزميات 'Ed25519' و 'Ed448'
v15.0.0	تمت الإضافة في: v15.0.0

• algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
• key: <CryptoKey>
• signature: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
• القيمة المُرجعة: <Promise> يتم الوفاء بها بـ <boolean>

باستخدام الأسلوب والمعلمات الواردة في algorithm والمادة الرئيسية المقدمة بواسطة key، تحاول subtle.verify() التحقق من أن signature هو توقيع تشفير صالح لـ data. يتم حل الوعد المُرجع بقيمة true أو false.

تتضمن الخوارزميات المدعومة حاليًا:

• 'RSASSA-PKCS1-v1_5'
• 'RSA-PSS'
• 'ECDSA'
• 'Ed25519'
• 'Ed448'
• 'HMAC'

subtle.wrapKey(format, key, wrappingKey, wrapAlgo)

تمت الإضافة في: v15.0.0

• format: <string> يجب أن يكون أحد القيم 'raw', 'pkcs8', 'spki', أو 'jwk'.
• key: <CryptoKey>
• wrappingKey: <CryptoKey>
• wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
• القيمة المُرجعة: <Promise> يتم الوفاء بها بـ <ArrayBuffer>

في التشفير، يشير "لف مفتاح" إلى تصدير مادة التشفير ثم تشفيرها. تقوم طريقة subtle.wrapKey() بتصدير مادة التشفير إلى التنسيق المحدد بواسطة format، ثم تشفيرها باستخدام الأسلوب والمعلمات المحددة بواسطة wrapAlgo ومادة التشفير المقدمة بواسطة wrappingKey. وهي مكافئة لاستدعاء subtle.exportKey() باستخدام format و key كوسيطات، ثم تمرير النتيجة إلى طريقة subtle.encrypt() باستخدام wrappingKey و wrapAlgo كمدخلات. إذا نجحت العملية، فسيتم حل الوعد المُرجع بـ <ArrayBuffer> يحتوي على بيانات المفتاح المشفرة.

تتضمن خوارزميات اللف المدعومة حاليًا:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'
• 'AES-KW'

معلمات الخوارزمية

تُعرّف كائنات معلمات الخوارزمية الأساليب والمعلمات التي تستخدمها طرق <SubtleCrypto> المختلفة. وبينما تُوصف هنا بأنها "فئات"، إلا أنها كائنات قواميس جافا سكريبت بسيطة.

الفئة: AlgorithmIdentifier

مضافة في: v18.4.0، v16.17.0

algorithmIdentifier.name

مضافة في: v18.4.0، v16.17.0

• النوع: <string>

الفئة: AesCbcParams

مضافة في: v15.0.0

aesCbcParams.iv

مضافة في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

يوفر متجه البدء. يجب أن يكون طوله 16 بايت بالضبط، ويجب أن يكون غير قابل للتنبؤ به وعشوائيًا من الناحية التشفيرية.

aesCbcParams.name

مضافة في: v15.0.0

• النوع: <string> يجب أن يكون 'AES-CBC'

الفئة: AesCtrParams

مضافة في: v15.0.0

aesCtrParams.counter

مضافة في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

القيمة الأولية لكتلة العداد. يجب أن يكون طولها 16 بايت بالضبط.

تستخدم طريقة AES-CTR أقصى بتات length من الكتلة كعداد، والبتات المتبقية كرقم عشوائي.

aesCtrParams.length

مضافة في: v15.0.0

• النوع: <number> عدد البتات في aesCtrParams.counter التي سيتم استخدامها كعداد.

aesCtrParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون 'AES-CTR'.

الفئة: AesGcmParams

تم الإضافة في: v15.0.0

aesGcmParams.additionalData

تم الإضافة في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

مع طريقة AES-GCM، فإن additionalData هو إدخال إضافي لا يتم تشفيره ولكنه مُضمن في مصادقة البيانات. استخدام additionalData اختياري.

aesGcmParams.iv

تم الإضافة في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

يجب أن يكون متجه الإنشاء فريدًا لكل عملية تشفير باستخدام مفتاح معين.

من الناحية المثالية، هذه قيمة حتمية مكونة من 12 بايت تُحسب بطريقة تضمن أنها فريدة عبر جميع عمليات الاستدعاء التي تستخدم نفس المفتاح. بدلاً من ذلك، قد يتكون متجه الإنشاء من 12 بايت عشوائية مشفرة على الأقل. لمزيد من المعلومات حول إنشاء متجهات الإنشاء لـ AES-GCM، يُرجى الرجوع إلى القسم 8 من NIST SP 800-38D.

aesGcmParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون 'AES-GCM'.

aesGcmParams.tagLength

تم الإضافة في: v15.0.0

• النوع: <number> حجم علامة المصادقة المُولدة بالبتات. يجب أن تكون هذه القيم إحدى القيم التالية: 32, 64, 96, 104, 112, 120, أو 128. الافتراضي: 128.

الصف: AesKeyGenParams

تم الإضافة في: v15.0.0

aesKeyGenParams.length

تم الإضافة في: v15.0.0

• النوع: <number>

طول مفتاح AES المراد توليده. يجب أن يكون إما 128, 192, أو 256.

aesKeyGenParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون أحد القيم التالية: 'AES-CBC', 'AES-CTR', 'AES-GCM', أو 'AES-KW'

الصف: EcdhKeyDeriveParams

تم الإضافة في: v15.0.0

ecdhKeyDeriveParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون 'ECDH', 'X25519', أو 'X448'.

ecdhKeyDeriveParams.public

تم الإضافة في: v15.0.0

• النوع: <CryptoKey>

تعمل عملية اشتقاق مفتاح ECDH عن طريق أخذ مفتاح خاص لطرف واحد ومفتاح عام لطرف آخر كمدخل - باستخدام كليهما لإنشاء سر مشترك. يتم تعيين خاصية ecdhKeyDeriveParams.public إلى المفتاح العام للطرف الآخر.

الصف: EcdsaParams

تم الإضافة في: v15.0.0

ecdsaParams.hash

تم الإضافة في: v15.0.0

• النوع: <string> | <Object>

إذا تم تمثيله كـ <string>، فيجب أن تكون القيمة إحدى القيم التالية:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم تمثيله كـ <Object>، فيجب أن يحتوي الكائن على خاصية name تكون قيمتها إحدى القيم المذكورة أعلاه.

ecdsaParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون 'ECDSA'.

الصنف: EcKeyGenParams

تم الإضافة في: v15.0.0

ecKeyGenParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون واحداً من 'ECDSA' أو 'ECDH'.

ecKeyGenParams.namedCurve

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون واحداً من 'P-256', 'P-384', 'P-521'.

الصنف: EcKeyImportParams

تم الإضافة في: v15.0.0

ecKeyImportParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون واحداً من 'ECDSA' أو 'ECDH'.

ecKeyImportParams.namedCurve

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون واحداً من 'P-256', 'P-384', 'P-521'.

الصنف: Ed448Params

تم الإضافة في: v15.0.0

ed448Params.name

تم الإضافة في: v18.4.0, v16.17.0

• النوع: <string> يجب أن يكون 'Ed448'.

ed448Params.context

تم الإضافة في: v18.4.0, v16.17.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

يمثل عضو context بيانات السياق الاختيارية لربطها بالرسالة. يدعم تنفيذ واجهة برمجة تطبيقات Web Crypto من Node.js سياقًا بطول صفري فقط، وهو ما يعادل عدم توفير سياق على الإطلاق.

الصنف: HkdfParams

تم الإضافة في: v15.0.0

hkdfParams.hash

تم الإضافة في: v15.0.0

• النوع: <string> | <Object>

إذا تم تمثيلها كـ <string>، يجب أن تكون القيمة إحدى القيم التالية:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم تمثيلها كـ <Object>، يجب أن يحتوي الكائن على خاصية name قيمة إحدى القيم المذكورة أعلاه.

hkdfParams.info

تم الإضافة في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

يوفر مدخلًا سياقيًا محددًا للتطبيق لخوارزمية HKDF. يمكن أن يكون هذا بطول صفري ولكن يجب توفيره.

hkdfParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن تكون 'HKDF'.

hkdfParams.salt

تم الإضافة في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

تقوم قيمة الملح بتحسين قوة خوارزمية HKDF بشكل كبير. يجب أن تكون عشوائية أو شبه عشوائية ويجب أن يكون لها نفس طول مخرجات دالة التجزئة (على سبيل المثال، إذا كنت تستخدم 'SHA-256' كدالة التجزئة، فيجب أن تكون قيمة الملح 256 بت من البيانات العشوائية).

الصف: HmacImportParams

مضاف في: v15.0.0

hmacImportParams.hash

مضاف في: v15.0.0

• النوع: <string> | <Object>

إذا تم تمثيله كـ <string>، يجب أن تكون القيمة إحدى القيم التالية:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم تمثيله كـ <Object>، يجب أن يحتوي الكائن على خاصية name قيمة الخاصية هي إحدى القيم المذكورة أعلاه.

hmacImportParams.length

مضاف في: v15.0.0

• النوع: <number>

عدد بتات مفتاح HMAC الاختياري. هذا اختياري ويجب حذفه في معظم الحالات.

hmacImportParams.name

مضاف في: v15.0.0

• النوع: <string> يجب أن يكون 'HMAC'.

الصف: HmacKeyGenParams

مضاف في: v15.0.0

hmacKeyGenParams.hash

مضاف في: v15.0.0

• النوع: <string> | <Object>

إذا تم تمثيله كـ <string>، يجب أن تكون القيمة إحدى القيم التالية:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم تمثيله كـ <Object>، يجب أن يحتوي الكائن على خاصية name قيمة الخاصية هي إحدى القيم المذكورة أعلاه.

hmacKeyGenParams.length

مضاف في: v15.0.0

• النوع: <number>

عدد البتات التي سيتم إنشاؤها لمفتاح HMAC. إذا تم حذفه، فسيتم تحديد الطول بواسطة خوارزمية التجزئة المستخدمة. هذا اختياري ويجب حذفه في معظم الحالات.

hmacKeyGenParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون 'HMAC'.

الفئة: Pbkdf2Params

تم الإضافة في: v15.0.0

pbkdb2Params.hash

تم الإضافة في: v15.0.0

• النوع: <string> | <Object>

إذا تم تمثيله كـ <string>، يجب أن تكون القيمة واحدة من:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم تمثيله كـ <Object>، يجب أن يحتوي الكائن على خاصية name قيمتها واحدة من القيم المذكورة أعلاه.

pbkdf2Params.iterations

تم الإضافة في: v15.0.0

• النوع: <number>

عدد مرات التكرار التي يجب أن تقوم بها خوارزمية PBKDF2 عند اشتقاق البتات.

pbkdf2Params.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون 'PBKDF2'.

pbkdf2Params.salt

تم الإضافة في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

يجب أن يكون على الأقل 16 بايت عشوائية أو شبه عشوائية.

الفئة: RsaHashedImportParams

تم الإضافة في: v15.0.0

rsaHashedImportParams.hash

تم الإضافة في: v15.0.0

• النوع: <string> | <Object>

إذا تم تمثيله كـ <string>، يجب أن تكون القيمة واحدة من:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم تمثيله كـ <Object>، يجب أن يحتوي الكائن على خاصية name قيمتها واحدة من القيم المذكورة أعلاه.

rsaHashedImportParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون أحد القيم 'RSASSA-PKCS1-v1_5', 'RSA-PSS', أو 'RSA-OAEP'.

الصنف: RsaHashedKeyGenParams

تم الإضافة في: v15.0.0

rsaHashedKeyGenParams.hash

تم الإضافة في: v15.0.0

• النوع: <string> | <Object>

إذا تم تمثيله كـ <string>، يجب أن تكون القيمة إحدى القيم التالية:

• 'SHA-1'
• 'SHA-256'
• 'SHA-384'
• 'SHA-512'

إذا تم تمثيله كـ <Object>، يجب أن يحتوي الكائن على خاصية name قيمة إحدى القيم المذكورة أعلاه.

rsaHashedKeyGenParams.modulusLength

تم الإضافة في: v15.0.0

• النوع: <number>

طول مُعامل RSA بالبتات. كأفضل ممارسة، يجب أن يكون هذا على الأقل 2048.

rsaHashedKeyGenParams.name

تم الإضافة في: v15.0.0

• النوع: <string> يجب أن يكون أحد القيم 'RSASSA-PKCS1-v1_5', 'RSA-PSS', أو 'RSA-OAEP'.

rsaHashedKeyGenParams.publicExponent

تم الإضافة في: v15.0.0

• النوع: <Uint8Array>

أسّ المُعامل العام لـ RSA. يجب أن يكون هذا <Uint8Array> يحتوي على عدد صحيح بدون إشارة، كبير النهاية، ويجب أن يتناسب مع 32 بت. قد يحتوي <Uint8Array> على عدد تعسفي من بتات الصفر الرائدة. يجب أن تكون القيمة عددًا أوليًا. ما لم يكن هناك سبب لاستخدام قيمة مختلفة، استخدم new Uint8Array([1, 0, 1]) (65537) كمعامل عام.

صنف: RsaOaepParams

مضاف في: v15.0.0

rsaOaepParams.label

مضاف في: v15.0.0

• النوع: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

مجموعة إضافية من البايتات لن يتم تشفيرها، ولكن سيتم ربطها بنص التشفير المُولّد.

معلمة rsaOaepParams.label اختيارية.

rsaOaepParams.name

مضاف في: v15.0.0

• النوع: <string> يجب أن تكون 'RSA-OAEP'.

صنف: RsaPssParams

مضاف في: v15.0.0

rsaPssParams.name

مضاف في: v15.0.0

• النوع: <string> يجب أن تكون 'RSA-PSS'.

rsaPssParams.saltLength

مضاف في: v15.0.0

• النوع: <number>

طول (بالبايت) الملح العشوائي المُراد استخدامه.

الحواشي