iDoc.dev

العربية

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
Русский

العربية

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
Русский

الوضع الداكن

التشفير ​

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

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

رمز المصدر: lib/crypto.js

يوفر الوحدة النمطية node:crypto وظائف تشفيرية تتضمن مجموعة من أغلفة دالات OpenSSL الخاصة بالهاش وHMAC والتشفير وفك التشفير والتوقيع والتحقق.

js
const { createHmac } = await import('node:crypto')

const secret = 'abcdefg'
const hash = createHmac('sha256', secret).update('I love cupcakes').digest('hex')
console.log(hash)
// يطبع:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e
js
const { createHmac } = require('node:crypto')

const secret = 'abcdefg'
const hash = createHmac('sha256', secret).update('I love cupcakes').digest('hex')
console.log(hash)
// يطبع:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e

تحديد ما إذا كان دعم التشفير غير متوفر ​

من الممكن إنشاء Node.js بدون تضمين دعم الوحدة النمطية node:crypto. في مثل هذه الحالات، سيؤدي محاولة import من crypto أو استدعاء require('node:crypto') إلى إرسال خطأ.

عند استخدام CommonJS، يمكن التقاط الخطأ الذي تم إرساله باستخدام try/catch:

js
let crypto
try {
  crypto = require('node:crypto')
} catch (err) {
  console.error('دعم التشفير معطل!')
}

عند استخدام الكلمة الأساسية import لـ ESM النحوية، لا يمكن التقاط الخطأ إلا إذا تم تسجيل مُعالِج لـ process.on('uncaughtException') قبل أي محاولة لتحميل الوحدة النمطية (باستخدام، على سبيل المثال، وحدة نمطية مُحمّلة مسبقًا).

عند استخدام ESM، إذا كانت هناك فرصة لتنفيذ التعليمات البرمجية على بنية Node.js حيث لم يتم تمكين دعم التشفير، فكر في استخدام دالة import() بدلاً من الكلمة الأساسية import النحوية:

js
let crypto
try {
  crypto = await import('node:crypto')
} catch (err) {
  console.error('دعم التشفير معطل!')
}

الصنف: Certificate ​

مُضاف في: v0.11.8

SPKAC هي آلية طلب توقيع الشهادة التي تم تنفيذها في الأصل بواسطة Netscape وتم تحديدها رسميًا كجزء من عنصر keygen في HTML5.

\<keygen\> مُعطلة منذ HTML 5.2 ولا يجب استخدام هذا العنصر في المشاريع الجديدة بعد الآن.

يوفر مُعامل node:crypto الصنف Certificate للعمل مع بيانات SPKAC. الاستخدام الأكثر شيوعًا هو معالجة المخرجات التي تم إنشاؤها بواسطة عنصر HTML5 \<keygen\>. يستخدم Node.js تنفيذ OpenSSL لـ SPKAC داخليًا.

الطريقة الثابتة: Certificate.exportChallenge(spkac[, encoding]) ​

[السجل]

الإصدارالتغييرات
v15.0.0يمكن أن تكون وسيطة spkac عبارة عن ArrayBuffer. تم تحديد حجم وسيطة spkac بحد أقصى 2**31 - 1 بايت.
v9.0.0مُضاف في: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// يطبع: التحدي كسلسلة UTF8
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// يطبع: التحدي كسلسلة UTF8

طريقة ثابتة: Certificate.exportPublicKey(spkac[, encoding]) ​

[السجل]

الإصدارالتغييرات
v15.0.0يمكن أن تكون وسيطة spkac عبارة عن ArrayBuffer. تم تحديد حجم وسيطة spkac بحد أقصى 2**31 - 1 بايت.
v9.0.0تمت الإضافة في: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// يطبع: المفتاح العام كـ <Buffer ...>
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// يطبع: المفتاح العام كـ <Buffer ...>

طريقة ثابتة: Certificate.verifySpkac(spkac[, encoding]) ​

[السجل]

الإصدارالتغييرات
v15.0.0يمكن أن تكون وسيطة spkac عبارة عن ArrayBuffer. تمت إضافة التشفير. تم تحديد حجم وسيطة spkac بحد أقصى 2**31 - 1 بايت.
v9.0.0تمت الإضافة في: v9.0.0
js
import { Buffer } from 'node:buffer'
const { Certificate } = await import('node:crypto')

const spkac = getSpkacSomehow()
console.log(Certificate.verifySpkac(Buffer.from(spkac)))
// يطبع: true أو false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

const spkac = getSpkacSomehow()
console.log(Certificate.verifySpkac(Buffer.from(spkac)))
// يطبع: true أو false

واجهة برمجة التطبيقات القديمة (Legacy API) ​

[مستقر: 0 - مُهمل]

مستقر: 0 استقرار: 0 - مُهمل

باعتبارها واجهة قديمة، من الممكن إنشاء مثيلات جديدة من فئة crypto.Certificate كما هو موضح في الأمثلة أدناه.

new crypto.Certificate() ​

يمكن إنشاء مثيلات من فئة Certificate باستخدام الكلمة المفتاحية new أو باستدعاء crypto.Certificate() كدالة:

js
const { Certificate } = await import('node:crypto')

const cert1 = new Certificate()
const cert2 = Certificate()
js
const { Certificate } = require('node:crypto')

const cert1 = new Certificate()
const cert2 = Certificate()

certificate.exportChallenge(spkac[, encoding]) ​

مُضاف في: v0.11.8

js
const { Certificate } = await import('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// يُطبع: التحدي كسلسلة UTF8
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// يُطبع: التحدي كسلسلة UTF8

certificate.exportPublicKey(spkac[, encoding]) ​

مضاف في: v0.11.8

js
const { Certificate } = await import('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const publicKey = cert.exportPublicKey(spkac)
console.log(publicKey)
// يطبع: المفتاح العام كـ <Buffer ...>
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const publicKey = cert.exportPublicKey(spkac)
console.log(publicKey)
// يطبع: المفتاح العام كـ <Buffer ...>

certificate.verifySpkac(spkac[, encoding]) ​

مضاف في: v0.11.8

js
import { Buffer } from 'node:buffer'
const { Certificate } = await import('node:crypto')

const cert = Certificate()
const spkac = getSpkacSomehow()
console.log(cert.verifySpkac(Buffer.from(spkac)))
// يطبع: true أو false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

const cert = Certificate()
const spkac = getSpkacSomehow()
console.log(cert.verifySpkac(Buffer.from(spkac)))
// يطبع: true أو false

الصنف: Cipher ​

مضاف في: v0.1.94

تُستخدم مثيلات من فئة Cipher لتشفير البيانات. يمكن استخدام الفئة بإحدى طريقتين:

  • كـدفق قابل للقراءة والكتابة، حيث يتم كتابة البيانات العادية غير المشفرة لإنتاج بيانات مشفرة على الجانب القابل للقراءة، أو
  • باستخدام طريقتي cipher.update() وcipher.final() لإنتاج البيانات المشفرة.

تُستخدم طريقة crypto.createCipheriv() لإنشاء مثيلات Cipher. لا يجب إنشاء كائنات Cipher مباشرةً باستخدام الكلمة الأساسية new.

مثال: استخدام كائنات Cipher كدفقات:

js
const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// أولاً، سنقوم بإنشاء المفتاح. يعتمد طول المفتاح على الخوارزمية.
// في هذه الحالة بالنسبة إلى aes192، هو 24 بايت (192 بت).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // بعد ذلك، سنقوم بإنشاء متجه بدء عشوائي
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // بمجرد أن نحصل على المفتاح و iv، يمكننا إنشاء واستخدام الشفرة...
    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = ''
    cipher.setEncoding('hex')

    cipher.on('data', chunk => (encrypted += chunk))
    cipher.on('end', () => console.log(encrypted))

    cipher.write('some clear text data')
    cipher.end()
  })
})
js
const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// أولاً، سنقوم بإنشاء المفتاح. يعتمد طول المفتاح على الخوارزمية.
// في هذه الحالة بالنسبة إلى aes192، هو 24 بايت (192 بت).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // بعد ذلك، سنقوم بإنشاء متجه بدء عشوائي
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // بمجرد أن نحصل على المفتاح و iv، يمكننا إنشاء واستخدام الشفرة...
    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = ''
    cipher.setEncoding('hex')

    cipher.on('data', chunk => (encrypted += chunk))
    cipher.on('end', () => console.log(encrypted))

    cipher.write('some clear text data')
    cipher.end()
  })
})

مثال: استخدام Cipher والدفقات المسلسلة:

js
import { createReadStream, createWriteStream } from 'node:fs'

import { pipeline } from 'node:stream'

const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// أولاً، سنقوم بإنشاء المفتاح. يعتمد طول المفتاح على الخوارزمية.
// في هذه الحالة بالنسبة إلى aes192، هو 24 بايت (192 بت).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // بعد ذلك، سنقوم بإنشاء متجه بدء عشوائي
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    const input = createReadStream('test.js')
    const output = createWriteStream('test.enc')

    pipeline(input, cipher, output, err => {
      if (err) throw err
    })
  })
})
js
const { createReadStream, createWriteStream } = require('node:fs')

const { pipeline } = require('node:stream')

const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// أولاً، سنقوم بإنشاء المفتاح. يعتمد طول المفتاح على الخوارزمية.
// في هذه الحالة بالنسبة إلى aes192، هو 24 بايت (192 بت).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // بعد ذلك، سنقوم بإنشاء متجه بدء عشوائي
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    const input = createReadStream('test.js')
    const output = createWriteStream('test.enc')

    pipeline(input, cipher, output, err => {
      if (err) throw err
    })
  })
})

مثال: استخدام طريقتي cipher.update() وcipher.final():

js
const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// أولاً، سنقوم بإنشاء المفتاح. يعتمد طول المفتاح على الخوارزمية.
// في هذه الحالة بالنسبة إلى aes192، هو 24 بايت (192 بت).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // بعد ذلك، سنقوم بإنشاء متجه بدء عشوائي
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex')
    encrypted += cipher.final('hex')
    console.log(encrypted)
  })
})
js
const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// أولاً، سنقوم بإنشاء المفتاح. يعتمد طول المفتاح على الخوارزمية.
// في هذه الحالة بالنسبة إلى aes192، هو 24 بايت (192 بت).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // بعد ذلك، سنقوم بإنشاء متجه بدء عشوائي
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex')
    encrypted += cipher.final('hex')
    console.log(encrypted)
  })
})

cipher.final([outputEncoding]) ​

مضاف في: v0.1.94

  • outputEncoding <string> التشفير لقيمة الإرجاع.
  • القيمة المُرجعّة: <Buffer> | <string> أي محتوى مشفر متبقي. إذا تم تحديد outputEncoding، فسيتم إرجاع سلسلة نصية. إذا لم يتم توفير outputEncoding، فسيتم إرجاع Buffer.

بمجرد استدعاء طريقة cipher.final()، لم يعد بإمكان كائن Cipher تشفير البيانات. ستؤدي محاولات استدعاء cipher.final() أكثر من مرة إلى إرسال خطأ.

cipher.getAuthTag() ​

مضاف في: v1.0.0

  • القيمة المُرجعّة: <Buffer> عند استخدام وضع تشفير مُصادق عليه (GCM، CCM، OCB، وchacha20-poly1305 مدعومة حاليًا)، تُرجع طريقة cipher.getAuthTag() Buffer يحتوي على علامة المصادقة التي تم حسابها من البيانات المُعطاة.

يجب فقط استدعاء طريقة cipher.getAuthTag() بعد اكتمال التشفير باستخدام طريقة cipher.final().

إذا تم تعيين خيار authTagLength أثناء إنشاء مثيل cipher، فستعيد هذه الوظيفة بالضبط authTagLength بايت.

cipher.setAAD(buffer[, options]) ​

مضاف في: v1.0.0

عند استخدام وضع تشفير مُصادق عليه (GCM، CCM، OCB، وchacha20-poly1305 مدعومة حاليًا)، تُعيّن طريقة cipher.setAAD() القيمة المُستخدمة لمعلمة الإدخال البيانات المُصادق عليها إضافيًا (AAD).

خيار plaintextLength اختياري لـ GCM و OCB. عند استخدام CCM، يجب تحديد خيار plaintextLength ويجب أن تتطابق قيمته مع طول النص العادي بالبايت. انظر وضع CCM.

يجب استدعاء طريقة cipher.setAAD() قبل cipher.update().

cipher.setAutoPadding([autoPadding]) ​

مضاف في: v0.7.1

  • autoPadding <boolean> الافتراضي: true
  • القيمة المُرجعة: <Cipher> نفس مثيل Cipher لاستخدام الربط بالسلسلة.

عند استخدام خوارزميات تشفير الكتل، ستقوم فئة Cipher تلقائيًا بإضافة حشو إلى بيانات الإدخال إلى حجم الكتلة المناسب. لإلغاء الحشو الافتراضي، اتصل بـ cipher.setAutoPadding(false).

عندما يكون autoPadding هو false، يجب أن يكون طول بيانات الإدخال بأكملها مضاعفًا لحجم كتلة التشفير، أو أن cipher.final() سيرمي خطأ. إن تعطيل الحشو التلقائي مفيد للحشو غير القياسي، على سبيل المثال، باستخدام 0x0 بدلاً من حشو PKCS.

يجب استدعاء طريقة cipher.setAutoPadding() قبل cipher.final().

cipher.update(data[, inputEncoding][, outputEncoding]) ​

[السجل]

الإصدارالتغييرات
v6.0.0تغيرت قيمة inputEncoding الافتراضية من binary إلى utf8.
v0.1.94مضاف في: v0.1.94

يقوم بتحديث التشفير مع data. إذا تم إعطاء وسيطة inputEncoding، فإن وسيطة data هي سلسلة نصية تستخدم التشفير المحدد. إذا لم يتم إعطاء وسيطة inputEncoding، فيجب أن تكون data عبارة عن Buffer، TypedArray، أو DataView. إذا كانت data عبارة عن Buffer، TypedArray، أو DataView، فسيتم تجاهل inputEncoding.

يحدد outputEncoding تنسيق إخراج البيانات المشفرة. إذا تم تحديد outputEncoding، فسيتم إرجاع سلسلة نصية باستخدام التشفير المحدد. إذا لم يتم توفير outputEncoding، فسيتم إرجاع Buffer.

يمكن استدعاء طريقة cipher.update() عدة مرات مع بيانات جديدة حتى يتم استدعاء cipher.final(). سيؤدي استدعاء cipher.update() بعد cipher.final() إلى إلقاء خطأ.

الصنف: Decipher ​

تم الإضافة في: v0.1.94

تُستخدم مثيلات فئة Decipher لفك تشفير البيانات. يمكن استخدام الفئة بإحدى طريقتين:

  • كـدفق قابل للقراءة والكتابة، حيث يتم كتابة البيانات المشفرة العادية لإنتاج بيانات غير مشفرة على الجانب القابل للقراءة، أو
  • باستخدام طريقتي decipher.update() وdecipher.final() لإنتاج البيانات غير المشفرة.

تُستخدم طريقة crypto.createDecipheriv() لإنشاء مثيلات Decipher. لا يجب إنشاء كائنات Decipher مباشرةً باستخدام الكلمة المفتاحية new.

مثال: استخدام كائنات Decipher كدفقات:

js
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// يعتمد طول المفتاح على الخوارزمية. في هذه الحالة بالنسبة لـ aes192، هو
// 24 بايت (192 بت).
// استخدم `crypto.scrypt()` غير المتزامن بدلاً من ذلك.
const key = scryptSync(password, 'salt', 24)
// عادةً ما يتم تمرير IV مع نص مشفر.
const iv = Buffer.alloc(16, 0) // متجه البدء.

const decipher = createDecipheriv(algorithm, key, iv)

let decrypted = ''
decipher.on('readable', () => {
  let chunk
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8')
  }
})
decipher.on('end', () => {
  console.log(decrypted)
  // يطبع: some clear text data
})

// مشفر بنفس الخوارزمية والمفتاح و IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// يعتمد طول المفتاح على الخوارزمية. في هذه الحالة بالنسبة لـ aes192، هو
// 24 بايت (192 بت).
// استخدم `crypto.scrypt()` غير المتزامن بدلاً من ذلك.
const key = scryptSync(password, 'salt', 24)
// عادةً ما يتم تمرير IV مع نص مشفر.
const iv = Buffer.alloc(16, 0) // متجه البدء.

const decipher = createDecipheriv(algorithm, key, iv)

let decrypted = ''
decipher.on('readable', () => {
  let chunk
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8')
  }
})
decipher.on('end', () => {
  console.log(decrypted)
  // يطبع: some clear text data
})

// مشفر بنفس الخوارزمية والمفتاح و IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()

مثال: استخدام Decipher والدفقات المُوصّلة:

js
import { createReadStream, createWriteStream } from 'node:fs'
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// استخدم `crypto.scrypt()` غير المتزامن بدلاً من ذلك.
const key = scryptSync(password, 'salt', 24)
// عادةً ما يتم تمرير IV مع نص مشفر.
const iv = Buffer.alloc(16, 0) // متجه البدء.

const decipher = createDecipheriv(algorithm, key, iv)

const input = createReadStream('test.enc')
const output = createWriteStream('test.js')

input.pipe(decipher).pipe(output)
js
const { createReadStream, createWriteStream } = require('node:fs')
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// استخدم `crypto.scrypt()` غير المتزامن بدلاً من ذلك.
const key = scryptSync(password, 'salt', 24)
// عادةً ما يتم تمرير IV مع نص مشفر.
const iv = Buffer.alloc(16, 0) // متجه البدء.

const decipher = createDecipheriv(algorithm, key, iv)

const input = createReadStream('test.enc')
const output = createWriteStream('test.js')

input.pipe(decipher).pipe(output)

مثال: استخدام طريقتي decipher.update() وdecipher.final():

js
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// استخدم `crypto.scrypt()` غير المتزامن بدلاً من ذلك.
const key = scryptSync(password, 'salt', 24)
// عادةً ما يتم تمرير IV مع نص مشفر.
const iv = Buffer.alloc(16, 0) // متجه البدء.

const decipher = createDecipheriv(algorithm, key, iv)

// مشفر باستخدام نفس الخوارزمية والمفتاح و IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// يطبع: some clear text data
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// استخدم `crypto.scrypt()` غير المتزامن بدلاً من ذلك.
const key = scryptSync(password, 'salt', 24)
// عادةً ما يتم تمرير IV مع نص مشفر.
const iv = Buffer.alloc(16, 0) // متجه البدء.

const decipher = createDecipheriv(algorithm, key, iv)

// مشفر باستخدام نفس الخوارزمية والمفتاح و IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// يطبع: some clear text data

decipher.final([outputEncoding]) ​

مضاف في: v0.1.94

  • outputEncoding <string> التشفير لقيمة الإرجاع.
  • الإرجاع: <Buffer> | <string> أي محتوى فك تشفير متبقي. إذا تم تحديد outputEncoding، يتم إرجاع سلسلة. إذا لم يتم توفير outputEncoding، يتم إرجاع Buffer.

بمجرد استدعاء طريقة decipher.final()، لا يمكن استخدام كائن Decipher لفك تشفير البيانات بعد الآن. ستؤدي محاولات استدعاء decipher.final() أكثر من مرة إلى إلقاء خطأ.

decipher.setAAD(buffer[, options]) ​

[السجل]

الإصدارالتغييرات
v15.0.0يمكن أن تكون وسيطة المصفوفة سلسلة أو ArrayBuffer وهي محدودة بحد أقصى 2 ** 31 - 1 بايت.
v7.2.0هذه الطريقة تُرجع الآن مرجعًا إلى decipher.
v1.0.0مضاف في: v1.0.0

عند استخدام وضع التشفير الموثق (GCM, CCM, OCB, وchacha20-poly1305 مدعومة حاليًا)، تحدد طريقة decipher.setAAD() القيمة المستخدمة لمعلمة الإدخال البيانات الإضافية الموثقة (AAD).

وسيطة options اختيارية لـ GCM. عند استخدام CCM، يجب تحديد خيار plaintextLength ويجب أن تتطابق قيمته مع طول نص التشفير بالبايت. انظر وضع CCM.

يجب استدعاء طريقة decipher.setAAD() قبل decipher.update().

عند تمرير سلسلة كـ buffer، يرجى مراعاة المحاذير عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات المشفرة.

decipher.setAuthTag(buffer[, encoding]) ​

[السجل]

الإصدارالتغييرات
v22.0.0, v20.13.0استخدام أطوال علامات GCM بخلاف 128 بت بدون تحديد خيار authTagLength عند إنشاء decipher أمر عفا عليه الزمن.
v15.0.0يمكن أن تكون وسيطة buffer سلسلة أو ArrayBuffer وهي محدودة بحد أقصى 2 ** 31 - 1 بايت.
v11.0.0تُلقي هذه الطريقة الآن خطأً إذا كان طول علامة GCM غير صالح.
v7.2.0تُعيد هذه الطريقة الآن مرجعًا إلى decipher.
v1.0.0تمت الإضافة في: v1.0.0

عند استخدام وضع تشفير موثق (GCM, CCM, OCB, وchacha20-poly1305 مدعومة حاليًا)، تُستخدم طريقة decipher.setAuthTag() لإدخال علامة المصادقة المستلمة. إذا لم يتم توفير أي علامة، أو إذا تم العبث بنص الشيفرة، فسوف يُلقي decipher.final() خطأً، مما يشير إلى أنه يجب تجاهل نص الشيفرة نظرًا لفشل المصادقة. إذا كان طول العلامة غير صالح وفقًا لـ NIST SP 800-38D أو لا يتطابق مع قيمة خيار authTagLength، فستُلقي decipher.setAuthTag() خطأً.

يجب استدعاء طريقة decipher.setAuthTag() قبل decipher.update() لوضع CCM أو قبل decipher.final() لأنماط GCM وOCB وchacha20-poly1305. لا يمكن استدعاء decipher.setAuthTag() إلا مرة واحدة.

عند تمرير سلسلة كعلامة مصادقة، يرجى مراعاة المحاذير عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات المشفرة.

decipher.setAutoPadding([autoPadding]) ​

مضاف في: v0.7.1

  • autoPadding <boolean> افتراضي: true
  • قيمة الإرجاع: <Decipher> نفس Decipher للسلسلة الطريقة.

عندما يتم تشفير البيانات بدون حشو كتلة قياسي، فإن استدعاء decipher.setAutoPadding(false) سيؤدي إلى تعطيل الحشو التلقائي لمنع decipher.final() من التحقق من الحشو وإزالته.

لن يعمل إيقاف الحشو التلقائي إلا إذا كان طول بيانات الإدخال مضاعفًا لحجم كتلة الشفرات.

يجب استدعاء طريقة decipher.setAutoPadding() قبل decipher.final().

decipher.update(data[, inputEncoding][, outputEncoding]) ​

[السجل]

الإصدارالتغييرات
v6.0.0تم تغيير inputEncoding الافتراضي من binary إلى utf8.
v0.1.94مضاف في: v0.1.94

يقوم بتحديث decipher ببيانات data. إذا تم تقديم وسيطة inputEncoding، فإن وسيطة data هي سلسلة تستخدم التشفير المحدد. إذا لم يتم تقديم وسيطة inputEncoding، فيجب أن تكون data عبارة عن Buffer. إذا كانت data عبارة عن Buffer ، فسيتم تجاهل inputEncoding.

يحدد outputEncoding تنسيق إخراج البيانات المشفرة. إذا تم تحديد outputEncoding، فسيتم إرجاع سلسلة تستخدم التشفير المحدد. إذا لم يتم تقديم أي outputEncoding، فسيتم إرجاع Buffer.

يمكن استدعاء طريقة decipher.update() عدة مرات مع بيانات جديدة حتى يتم استدعاء decipher.final(). سيؤدي استدعاء decipher.update() بعد decipher.final() إلى إرسال خطأ.

حتى إذا كانت الشفرة الأساسية تنفذ المصادقة، فقد تكون صحة وسلامة النص العادي المُرجع من هذه الوظيفة غير مؤكدة في هذا الوقت. بالنسبة لخوارزميات التشفير الموثقة، يتم عمومًا إنشاء الموثوقية فقط عندما يستدعي التطبيق decipher.final().

الصنف: DiffieHellman ​

مضاف في: v0.5.0

يُعدُّ صنف DiffieHellman أداةً مساعدةً لإنشاء عمليات تبادل مفاتيح Diffie-Hellman.

يمكن إنشاء مثيلات من صنف DiffieHellman باستخدام دالة crypto.createDiffieHellman().

js
import assert from 'node:assert'

const { createDiffieHellman } = await import('node:crypto')

// توليد مفاتيح أليس...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// توليد مفاتيح بوب...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// التبادل وتوليد السر...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

// موافق
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
js
const assert = require('node:assert')

const { createDiffieHellman } = require('node:crypto')

// توليد مفاتيح أليس...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// توليد مفاتيح بوب...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// التبادل وتوليد السر...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

// موافق
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))

diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding]) ​

مضاف في: v0.5.0

يحسب السر المشترك باستخدام otherPublicKey كمفتاح عام للطرف الآخر، ويرجع السر المشترك المحسوب. يتم تفسير المفتاح المُقدّم باستخدام inputEncoding المُحدد، ويتم ترميز السر باستخدام outputEncoding المُحدد. إذا لم يتم توفير inputEncoding، فمن المتوقع أن يكون otherPublicKey عبارة عن Buffer، أو TypedArray، أو DataView.

إذا تم إعطاء outputEncoding، فسيتم إرجاع سلسلة؛ خلاف ذلك، سيتم إرجاع Buffer.

diffieHellman.generateKeys([encoding]) ​

مضاف في: v0.5.0

يُولّد قيم مفاتيح Diffie-Hellman الخاصة والعامة ما لم يتم توليدها أو حسابها بالفعل، ويرجع المفتاح العام بالتشفير المحدد encoding. يجب نقل هذا المفتاح إلى الطرف الآخر. إذا تم توفير encoding، فسيتم إرجاع سلسلة؛ خلاف ذلك، سيتم إرجاع Buffer.

هذه الدالة هي غلاف رقيق حول DH_generate_key(). على وجه الخصوص، بمجرد توليد أو تعيين مفتاح خاص، فإن استدعاء هذه الدالة يقوم فقط بتحديث المفتاح العام ولكن لا يُولّد مفتاحًا خاصًا جديدًا.

diffieHellman.getGenerator([encoding]) ​

مضاف في: v0.5.0

يرجع مُولّد Diffie-Hellman بالتشفير المحدد encoding. إذا تم توفير encoding، فسيتم إرجاع سلسلة؛ خلاف ذلك، سيتم إرجاع Buffer.

diffieHellman.getPrime([encoding]) ​

مضاف في: v0.5.0

يرجع عدد أولي Diffie-Hellman بالتشفير المحدد encoding. إذا تم توفير encoding، فسيتم إرجاع سلسلة؛ خلاف ذلك، سيتم إرجاع Buffer.

diffieHellman.getPrivateKey([encoding]) ​

مضاف في: v0.5.0

يُعيد المفتاح الخاص لـ Diffie-Hellman بالتشفير المحدد. إذا تم توفير encoding ، فسيتم إرجاع سلسلة ؛ خلاف ذلك ، يتم إرجاع Buffer.

diffieHellman.getPublicKey([encoding]) ​

مضاف في: v0.5.0

يُعيد المفتاح العام لـ Diffie-Hellman بالتشفير المحدد. إذا تم توفير encoding ، فسيتم إرجاع سلسلة ؛ خلاف ذلك ، يتم إرجاع Buffer.

diffieHellman.setPrivateKey(privateKey[, encoding]) ​

مضاف في: v0.5.0

يُعيّن المفتاح الخاص لـ Diffie-Hellman. إذا تم توفير وسيطة encoding، يُتوقع أن يكون privateKey سلسلة. إذا لم يتم توفير encoding، يُتوقع أن يكون privateKey Buffer، أو TypedArray، أو DataView.

لا تُحسب هذه الدالة المفتاح العام المرتبط تلقائيًا. يمكن استخدام diffieHellman.setPublicKey() أو diffieHellman.generateKeys() لتوفير المفتاح العام يدويًا أو اشتقاقه تلقائيًا.

diffieHellman.setPublicKey(publicKey[, encoding]) ​

أضيف في: v0.5.0

يحدد المفتاح العام لـ Diffie-Hellman. إذا تم توفير وسيطة encoding، يُتوقع أن يكون publicKey سلسلة. إذا لم يتم توفير أي encoding، يُتوقع أن يكون publicKey Buffer، أو TypedArray، أو DataView.

diffieHellman.verifyError ​

أضيف في: v0.11.12

حقل بت يحتوي على أي تحذيرات و/أو أخطاء ناتجة عن فحص تم خلال تهيئة كائن DiffieHellman.

القيم التالية صالحة لهذه الخاصية (كما هو محدد في وحدة node:constants):

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

Class: DiffieHellmanGroup ​

أضيف في: v0.7.5

تأخذ فئة DiffieHellmanGroup مجموعة modp معروفة كوسيطتها. تعمل بنفس طريقة DiffieHellman، إلا أنها لا تسمح بتغيير مفاتيحها بعد إنشائها. بمعنى آخر، إنها لا تُنفذ طرق setPublicKey() أو setPrivateKey().

js
const { createDiffieHellmanGroup } = await import('node:crypto')
const dh = createDiffieHellmanGroup('modp16')
js
const { createDiffieHellmanGroup } = require('node:crypto')
const dh = createDiffieHellmanGroup('modp16')

يتم دعم المجموعات التالية:

  • 'modp14' (2048 بت، RFC 3526 القسم 3)
  • 'modp15' (3072 بت، RFC 3526 القسم 4)
  • 'modp16' (4096 بت، RFC 3526 القسم 5)
  • 'modp17' (6144 بت، RFC 3526 القسم 6)
  • 'modp18' (8192 بت، RFC 3526 القسم 7)

لا تزال المجموعات التالية مدعومة ولكنها مُهملة (انظر التحذيرات):

  • 'modp1' (768 بت، RFC 2409 القسم 6.1)
  • 'modp2' (1024 بت، RFC 2409 القسم 6.2)
  • 'modp5' (1536 بت، RFC 3526 القسم 2)

قد تتم إزالة هذه المجموعات المُهملة في إصدارات Node.js المستقبلية.

الصف: ECDH ​

مضاف في: v0.11.14

يُعدُّ الصف ECDH أداةً مساعدةً لإنشاء عمليات تبادل مفاتيح إهليلجية منحنى ديفى-هيلمن (ECDH).

يمكن إنشاء مثيلات من الصف ECDH باستخدام دالة crypto.createECDH().

js
import assert from 'node:assert'

const { createECDH } = await import('node:crypto')

// توليد مفاتيح أليس...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// توليد مفاتيح بوب...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// التبادل وتوليد السر...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
// حسنًا
js
const assert = require('node:assert')

const { createECDH } = require('node:crypto')

// توليد مفاتيح أليس...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// توليد مفاتيح بوب...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// التبادل وتوليد السر...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
// حسنًا

طريقة ثابتة: ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]]) ​

مضاف في: v10.0.0

يحوّل المفتاح العام لـ EC Diffie-Hellman المحدد بواسطة key و curve إلى التنسيق المحدد بواسطة format. تحدد وسيطة format ترميز النقطة ويمكن أن تكون 'compressed' أو 'uncompressed' أو 'hybrid'. يتم تفسير المفتاح المقدم باستخدام inputEncoding المحدد، ويتم ترميز المفتاح المُرجع باستخدام outputEncoding المحدد.

استخدم crypto.getCurves() للحصول على قائمة بأسماء المنحنيات المتاحة. في إصدارات OpenSSL الحديثة، سيعرض openssl ecparam -list_curves أيضًا اسم ووصف كل منحنى بيضاوي متاح.

إذا لم يتم تحديد format، فسيتم إرجاع النقطة بتنسيق 'uncompressed'.

إذا لم يتم توفير inputEncoding، فمن المتوقع أن يكون key عبارة عن Buffer، أو TypedArray، أو DataView.

مثال (فك ضغط مفتاح):

js
const { createECDH, ECDH } = await import('node:crypto')

const ecdh = createECDH('secp256k1')
ecdh.generateKeys()

const compressedKey = ecdh.getPublicKey('hex', 'compressed')

const uncompressedKey = ECDH.convertKey(compressedKey, 'secp256k1', 'hex', 'hex', 'uncompressed')

// يجب أن يكون المفتاح المُحوّل والمفتاح العام غير المضغوط متطابقين
console.log(uncompressedKey === ecdh.getPublicKey('hex'))
js
const { createECDH, ECDH } = require('node:crypto')

const ecdh = createECDH('secp256k1')
ecdh.generateKeys()

const compressedKey = ecdh.getPublicKey('hex', 'compressed')

const uncompressedKey = ECDH.convertKey(compressedKey, 'secp256k1', 'hex', 'hex', 'uncompressed')

// يجب أن يكون المفتاح المُحوّل والمفتاح العام غير المضغوط متطابقين
console.log(uncompressedKey === ecdh.getPublicKey('hex'))

ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding]) ​

[History]

الإصدارالتغييرات
v10.0.0تم تغيير تنسيق الخطأ لدعم أفضل لخطأ المفتاح العام غير صالح.
v6.0.0تم تغيير inputEncoding الافتراضي من binary إلى utf8.
v0.11.14تمت الإضافة في: v0.11.14

تحسب السر المُشترك باستخدام otherPublicKey كمفتاح عام للطرف الآخر، وتُعيد السر المُشترك المحسوب. يتم تفسير المفتاح المُعطى باستخدام inputEncoding المُحدد، ويتم ترميز السر المُرجع باستخدام outputEncoding المُحدد. إذا لم يتم توفير inputEncoding، فمن المتوقع أن يكون otherPublicKey عبارة عن Buffer، أو TypedArray، أو DataView.

إذا تم إعطاء outputEncoding سلسلة، فسيتم إرجاع سلسلة؛ خلاف ذلك، يتم إرجاع Buffer.

سيرمي ecdh.computeSecret خطأ ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY عندما يكون otherPublicKey خارج منحنى إهليلجي. نظرًا لأن otherPublicKey يتم توفيره عادةً من مستخدم بعيد عبر شبكة غير آمنة، فتأكد من معالجة هذا الاستثناء وفقًا لذلك.

ecdh.generateKeys([encoding[, format]]) ​

مضاف في: v0.11.14

يُولّد قيم مفاتيح EC Diffie-Hellman الخاصة والعامة، ويرجع المفتاح العام بالتنسيق و الترميز المحددين. يجب نقل هذا المفتاح إلى الطرف الآخر.

تحدد وسيطة format ترميز النقطة ويمكن أن تكون 'compressed' أو 'uncompressed'. إذا لم يتم تحديد format، فسيتم إرجاع النقطة بتنسيق 'uncompressed'.

إذا تم توفير encoding، فسيتم إرجاع سلسلة؛ وإلا فسيتم إرجاع Buffer.

ecdh.getPrivateKey([encoding]) ​

مضاف في: v0.11.14

  • encoding <string> ترميز التشفير لقيمة الإرجاع.
  • القيمة المُرجعة: <Buffer> | <string> مفتاح EC Diffie-Hellman الخاص بالترميز المحدد.

إذا تم تحديد encoding، فسيتم إرجاع سلسلة؛ وإلا فسيتم إرجاع Buffer.

ecdh.getPublicKey([encoding][, format]) ​

مضاف في: v0.11.14

  • encoding <string> ترميز التشفير لقيمة الإرجاع.
  • format <string> افتراضي: 'uncompressed'
  • القيمة المُرجعة: <Buffer> | <string> المفتاح العام لـ EC Diffie-Hellman بالترميز والتنسيق المحددين.

تحدد وسيطة format ترميز النقطة ويمكن أن تكون 'compressed' أو 'uncompressed'. إذا لم يتم تحديد format، فسيتم إرجاع النقطة بتنسيق 'uncompressed'.

إذا تم تحديد encoding، فسيتم إرجاع سلسلة؛ وإلا فسيتم إرجاع Buffer.

ecdh.setPrivateKey(privateKey[, encoding]) ​

مضاف في: v0.11.14

يُعيّن المفتاح الخاص لـ EC Diffie-Hellman. إذا تم توفير encoding، يُتوقع أن يكون privateKey سلسلة؛ خلافًا لذلك، يُتوقع أن يكون privateKey Buffer، أو TypedArray، أو DataView.

إذا لم يكن privateKey صالحًا للمنحنى المحدد عند إنشاء كائن ECDH، فسيتم إلقاء خطأ. عند تعيين المفتاح الخاص، يتم أيضًا إنشاء النقطة العامة (المفتاح) المرتبطة به وتعيينها في كائن ECDH.

ecdh.setPublicKey(publicKey[, encoding]) ​

مضاف في: v0.11.14

مُحذَف منذ: v5.2.0

[مستقر: 0 - مُحذَف]

مستقر: 0 ثبات: 0 - مُحذَف

يُعيّن المفتاح العام لـ EC Diffie-Hellman. إذا تم توفير encoding، يُتوقع أن يكون publicKey سلسلة؛ خلافًا لذلك، يُتوقع أن يكون Buffer، أو TypedArray، أو DataView.

لا يوجد عادةً سبب لاستدعاء هذه الطريقة لأن ECDH يتطلب فقط مفتاحًا خاصًا ومفتاحًا عامًا للطرف الآخر لحساب السر المشترك. عادةً ما يتم استدعاء ecdh.generateKeys() أو ecdh.setPrivateKey(). تحاول طريقة ecdh.setPrivateKey() إنشاء النقطة/المفتاح العام المرتبط بالمفتاح الخاص الذي يتم تعيينه.

مثال (الحصول على سر مشترك):

js
const { createECDH, createHash } = await import('node:crypto')

const alice = createECDH('secp256k1')
const bob = createECDH('secp256k1')

// هذه طريقة مختصرة لتحديد أحد مفاتيح Alice الخاصة السابقة. سيكون من غير الحكمة استخدام مفتاح خاص متوقع كهذا في تطبيق حقيقي.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// يستخدم Bob زوجًا جديدًا من المفاتيح المشفرة بقوة عشوائية زائفة
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

// يجب أن تكون قيمة aliceSecret و bobSecret هي نفس قيمة السر المشترك
console.log(aliceSecret === bobSecret)
js
const { createECDH, createHash } = require('node:crypto')

const alice = createECDH('secp256k1')
const bob = createECDH('secp256k1')

// هذه طريقة مختصرة لتحديد أحد مفاتيح Alice الخاصة السابقة. سيكون من غير الحكمة استخدام مفتاح خاص متوقع كهذا في تطبيق حقيقي.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// يستخدم Bob زوجًا جديدًا من المفاتيح المشفرة بقوة عشوائية زائفة
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

// يجب أن تكون قيمة aliceSecret و bobSecret هي نفس قيمة السر المشترك
console.log(aliceSecret === bobSecret)

الصنف: Hash ​

مضاف في: v0.1.92

يُعدُّ صنف Hash أداةً مساعدةً لإنشاء خلاصات هاش للبيانات. ويمكن استخدامه بإحدى طريقتين:

  • كـدفق قابل للقراءة والكتابة، حيث تُكتب البيانات لإنتاج خلاصة هاش محسوبة على الجانب القابل للقراءة، أو
  • باستخدام طريقتي hash.update() وhash.digest() لإنتاج الهاش المحسوب.

تُستخدم طريقة crypto.createHash() لإنشاء مثيلات Hash. ولا يجب إنشاء كائنات Hash مباشرةً باستخدام الكلمة الأساسية new.

مثال: استخدام كائنات Hash كدفقات:

js
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة دفق
  // الهاش.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // يطبع:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('some data to hash')
hash.end()
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة دفق
  // الهاش.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // يطبع:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('some data to hash')
hash.end()

مثال: استخدام Hash والدفقات المسلسلة:

js
import { createReadStream } from 'node:fs'
import { stdout } from 'node:process'
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

const input = createReadStream('test.js')
input.pipe(hash).setEncoding('hex').pipe(stdout)
js
const { createReadStream } = require('node:fs')
const { createHash } = require('node:crypto')
const { stdout } = require('node:process')

const hash = createHash('sha256')

const input = createReadStream('test.js')
input.pipe(hash).setEncoding('hex').pipe(stdout)

مثال: استخدام طريقتي hash.update() وhash.digest():

js
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.update('some data to hash')
console.log(hash.digest('hex'))
// يطبع:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.update('some data to hash')
console.log(hash.digest('hex'))
// يطبع:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50

hash.copy([options]) ​

مضاف في: v13.1.0

يُنشئ كائن Hash جديدًا يحتوي على نسخة عميقة من الحالة الداخلية لكائن Hash الحالي.

تتحكم وسيطة options الاختيارية في سلوك الدفق. بالنسبة إلى دوال التجزئة XOF مثل 'shake256'، يمكن استخدام خيار outputLength لتحديد طول المخرجات المطلوب بالبايت.

يتم إرسال خطأ عند محاولة نسخ كائن Hash بعد استدعاء طريقة hash.digest().

js
// حساب تجزئة متدحرجة.
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.update('one')
console.log(hash.copy().digest('hex'))

hash.update('two')
console.log(hash.copy().digest('hex'))

hash.update('three')
console.log(hash.copy().digest('hex'))

// إلخ.
js
// حساب تجزئة متدحرجة.
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.update('one')
console.log(hash.copy().digest('hex'))

hash.update('two')
console.log(hash.copy().digest('hex'))

hash.update('three')
console.log(hash.copy().digest('hex'))

// إلخ.

hash.digest([encoding]) ​

مضاف في: v0.1.92

يحسب التجزئة لجميع البيانات التي تم تمريرها ليتم تجزئتها (باستخدام طريقة hash.update()). إذا تم توفير encoding، فسيتم إرجاع سلسلة؛ خلاف ذلك، يتم إرجاع Buffer.

لا يمكن استخدام كائن Hash مرة أخرى بعد استدعاء طريقة hash.digest(). ستؤدي المكالمات المتعددة إلى إرسال خطأ.

hash.update(data[, inputEncoding]) ​

[السجل]

الإصدارالتغييرات
v6.0.0تغيرت قيمة inputEncoding الافتراضية من binary إلى utf8.
v0.1.92تمت الإضافة في: v0.1.92

يقوم بتحديث محتوى التجزئة بالبيانات المعطاة data، وترميزها مُعطى في inputEncoding. إذا لم يتم توفير encoding، وكانت data سلسلة، يتم فرض ترميز 'utf8'. إذا كانت data عبارة عن عازلة، TypedArray، أو DataView، يتم تجاهل inputEncoding.

يمكن استدعاء هذا عدة مرات مع بيانات جديدة كما يتم بثها.

الفئة: Hmac ​

تمت الإضافة في: v0.1.94

تُعد فئة Hmac أداة مساعدة لإنشاء خلاصات HMAC مشفرة. يمكن استخدامها بإحدى طريقتين:

  • كـبث قابل للقراءة والكتابة، حيث يتم كتابة البيانات لإنتاج خلاصة HMAC محسوبة على الجانب القابل للقراءة، أو
  • باستخدام طريقتي hmac.update() و hmac.digest() لإنتاج خلاصة HMAC المحسوبة.

تُستخدم طريقة crypto.createHmac() لإنشاء مثيلات Hmac. لا يجب إنشاء كائنات Hmac مباشرةً باستخدام الكلمة الرئيسية new.

مثال: استخدام كائنات Hmac كبث:

js
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة
  // دفق التجزئة.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // يطبع:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

hmac.write('some data to hash')
hmac.end()
js
const { createHmac } = require('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة
  // دفق التجزئة.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // يطبع:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

hmac.write('some data to hash')
hmac.end()

مثال: استخدام Hmac ودفقات الأنابيب:

js
import { createReadStream } from 'node:fs'
import { stdout } from 'node:process'
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream('test.js')
input.pipe(hmac).pipe(stdout)
js
const { createReadStream } = require('node:fs')
const { createHmac } = require('node:crypto')
const { stdout } = require('node:process')

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream('test.js')
input.pipe(hmac).pipe(stdout)

مثال: استخدام طريقتي hmac.update() و hmac.digest():

js
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.update('some data to hash')
console.log(hmac.digest('hex'))
// يطبع:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
js
const { createHmac } = require('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.update('some data to hash')
console.log(hmac.digest('hex'))
// يطبع:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e

hmac.digest([encoding]) ​

مضاف في: v0.1.94

يحسب خلاصة HMAC لجميع البيانات المُمررة باستخدام hmac.update(). إذا تم توفير encoding ، فسيتم إرجاع سلسلة؛ خلاف ذلك، سيتم إرجاع Buffer؛

لا يمكن استخدام كائن Hmac مرة أخرى بعد استدعاء hmac.digest(). ستؤدي المكالمات المتعددة لـ hmac.digest() إلى إلقاء خطأ.

hmac.update(data[, inputEncoding]) ​

[السجل]

الإصدارالتغييرات
v6.0.0تغيرت قيمة inputEncoding الافتراضية من binary إلى utf8.
v0.1.94مضاف في: v0.1.94

يقوم بتحديث محتوى Hmac بالبيانات المُعطاة data، والتي يتم تحديد تشفيرها في inputEncoding. إذا لم يتم توفير encoding، وكانت data سلسلة، فسيتم فرض تشفير 'utf8'. إذا كانت data عبارة عن Buffer، أو TypedArray، أو DataView، فسيتم تجاهل inputEncoding.

يمكن استدعاء هذا عدة مرات مع بيانات جديدة أثناء تدفقها.

الفئة: KeyObject ​

[السجل]

الإصدارالتغييرات
v14.5.0, v12.19.0يمكن الآن تمرير مثيلات هذه الفئة إلى مؤشرات العمل باستخدام postMessage.
v11.13.0تم تصدير هذه الفئة الآن.
v11.6.0مضاف في: v11.6.0

يستخدم Node.js فئة KeyObject لتمثيل مفتاح متماثل أو غير متماثل، وكل نوع من أنواع المفاتيح يعرض وظائف مختلفة. يتم استخدام طرق crypto.createSecretKey()، وcrypto.createPublicKey() وcrypto.createPrivateKey() لإنشاء مثيلات KeyObject. لا يجب إنشاء كائنات KeyObject مباشرةً باستخدام الكلمة المفتاحية new.

يجب على معظم التطبيقات مراعاة استخدام واجهة برمجة التطبيقات KeyObject الجديدة بدلاً من تمرير المفاتيح كسلاسل أو Buffers نظرًا لميزات الأمان المُحسّنة.

يمكن تمرير مثيلات KeyObject إلى مؤشرات العمل الأخرى عبر postMessage(). يحصل المُستقبِل على مُثيل مُنسوخ من KeyObject، ولا يلزم إدراج KeyObject في وسيطة transferList.

طريقة ثابتة: KeyObject.from(key) ​

مضاف في: v15.0.0

مثال: تحويل مثيل CryptoKey إلى KeyObject:

js
const { KeyObject } = await import('node:crypto')
const { subtle } = globalThis.crypto

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

const keyObject = KeyObject.from(key)
console.log(keyObject.symmetricKeySize)
// يطبع: 32 (حجم المفتاح المتماثل بالبايت)
js
const { KeyObject } = require('node:crypto')
const { subtle } = globalThis.crypto

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

  const keyObject = KeyObject.from(key)
  console.log(keyObject.symmetricKeySize)
  // يطبع: 32 (حجم المفتاح المتماثل بالبايت)
})()

keyObject.asymmetricKeyDetails ​

[السجل]

الإصدارالتغييرات
v16.9.0عرض معلمات تسلسل RSASSA-PSS-params لمفاتيح RSA-PSS.
v15.7.0مضاف في: v15.7.0
  • <Object>
    • modulusLength: <number> حجم المفتاح بالبت (RSA، DSA).
    • publicExponent: <bigint> الأسّ العام (RSA).
    • hashAlgorithm: <string> اسم خلاصة الرسالة (RSA-PSS).
    • mgf1HashAlgorithm: <string> اسم خلاصة الرسالة المستخدمة بواسطة MGF1 (RSA-PSS).
    • saltLength: <number> الحد الأدنى لطول الملح بالبايت (RSA-PSS).
    • divisorLength: <number> حجم q بالبت (DSA).
    • namedCurve: <string> اسم المنحنى (EC).

توجد هذه الخاصية فقط في المفاتيح غير المتماثلة. حسب نوع المفتاح، يحتوي هذا الكائن على معلومات حول المفتاح. لا يمكن استخدام أي من المعلومات التي تم الحصول عليها من خلال هذه الخاصية لتحديد المفتاح بشكل فريد أو لتقويض أمان المفتاح.

بالنسبة لمفاتيح RSA-PSS، إذا كانت مادة المفتاح تحتوي على تسلسل RSASSA-PSS-params، فسيتم تعيين خصائص hashAlgorithm و mgf1HashAlgorithm و saltLength.

قد يتم عرض تفاصيل أخرى للمفتاح من خلال هذا API باستخدام سمات إضافية.

keyObject.asymmetricKeyType ​

[History]

الإصدارالتغييرات
v13.9.0، v12.17.0تمت إضافة دعم لـ 'dh'.
v12.0.0تمت إضافة دعم لـ 'rsa-pss'.
v12.0.0هذه الخاصية تُرجع الآن undefined لمعرفات KeyObject من نوع غير معروف بدلاً من الإيقاف.
v12.0.0تمت إضافة دعم لـ 'x25519' و 'x448'.
v12.0.0تمت إضافة دعم لـ 'ed25519' و 'ed448'.
v11.6.0تمت الإضافة في: v11.6.0

بالنسبة للمفاتيح غير المتماثلة، تُمثل هذه الخاصية نوع المفتاح. أنواع المفاتيح المدعومة هي:

  • 'rsa' (OID 1.2.840.113549.1.1.1)
  • 'rsa-pss' (OID 1.2.840.113549.1.1.10)
  • 'dsa' (OID 1.2.840.10040.4.1)
  • 'ec' (OID 1.2.840.10045.2.1)
  • 'x25519' (OID 1.3.101.110)
  • 'x448' (OID 1.3.101.111)
  • 'ed25519' (OID 1.3.101.112)
  • 'ed448' (OID 1.3.101.113)
  • 'dh' (OID 1.2.840.113549.1.3.1)

هذه الخاصية هي undefined لأنواع KeyObject غير المعروفة والمفاتيح المتماثلة.

keyObject.equals(otherKeyObject) ​

تمت الإضافة في: v17.7.0، v16.15.0

يُرجع true أو false اعتمادًا على ما إذا كانت المفاتيح لها نفس النوع والقيمة والمعلمات تمامًا. هذه الطريقة ليست وقت ثابت.

keyObject.export([options]) ​

[History]

الإصدارالتغييرات
v15.9.0تمت إضافة دعم لتنسيق 'jwk'.
v11.6.0تمت الإضافة في: v11.6.0

بالنسبة للمفاتيح المتماثلة، يمكن استخدام خيارات الترميز التالية:

  • format: <string> يجب أن يكون 'buffer' (افتراضي) أو 'jwk'.

بالنسبة للمفاتيح العامة، يمكن استخدام خيارات الترميز التالية:

  • type: <string> يجب أن يكون أحدها 'pkcs1' (RSA فقط) أو 'spki'.
  • format: <string> يجب أن يكون 'pem', 'der', أو 'jwk'.

بالنسبة للمفاتيح الخاصة، يمكن استخدام خيارات الترميز التالية:

  • type: <string> يجب أن يكون أحدها 'pkcs1' (RSA فقط)، 'pkcs8' أو 'sec1' (EC فقط).
  • format: <string> يجب أن يكون 'pem', 'der', أو 'jwk'.
  • cipher: <string> إذا تم تحديده، فسيتم تشفير المفتاح الخاص باستخدام cipher و passphrase المعطى باستخدام تشفير كلمة المرور القائم على PKCS # 5 الإصدار 2.0.
  • passphrase: <string> | <Buffer> كلمة المرور المستخدمة للتشفير، انظر cipher.

يعتمد نوع النتيجة على تنسيق الترميز المحدد، عندما يكون PEM تكون النتيجة سلسلة، وعندما يكون DER سيكون عازلاً يحتوي على البيانات المشفرة كـ DER، وعندما يكون JWK سيكون كائنًا.

عندما يتم تحديد تنسيق ترميز JWK، يتم تجاهل خيارات الترميز الأخرى.

يمكن تشفير مفاتيح PKCS # 1 و SEC1 و PKCS # 8 باستخدام مزيج من خيارات cipher و format. يمكن استخدام نوع PKCS # 8 مع أي format لتشفير أي خوارزمية مفتاح (RSA أو EC أو DH) عن طريق تحديد cipher. لا يمكن تشفير PKCS # 1 و SEC1 إلا عن طريق تحديد cipher عندما يتم استخدام تنسيق PEM. للحصول على أقصى قدر من التوافق، استخدم PKCS # 8 للمفاتيح الخاصة المشفرة. نظرًا لأن PKCS # 8 يُعرّف آلية تشفير خاصة به، لا يُدعم تشفير مستوى PEM عند تشفير مفتاح PKCS # 8. راجع RFC 5208 للتشفير PKCS # 8 و RFC 1421 للتشفير PKCS # 1 و SEC1.

keyObject.symmetricKeySize ​

مضاف في: v11.6.0

بالنسبة للمفاتيح السرية، تمثل هذه الخاصية حجم المفتاح بالبايت. هذه الخاصية undefined للمفاتيح غير المتماثلة.

keyObject.toCryptoKey(algorithm, extractable, keyUsages) ​

مضاف في: v23.0.0

يُحوّل مثيل KeyObject إلى CryptoKey.

keyObject.type ​

مضاف في: v11.6.0

اعتمادًا على نوع هذا KeyObject، تكون هذه الخاصية إما 'secret' للمفاتيح السرية (المتماثلة)، أو 'public' للمفاتيح العامة (غير المتماثلة)، أو 'private' للمفاتيح الخاصة (غير المتماثلة).

Class: Sign ​

مضاف في: v0.1.92

تُعد فئة Sign أداة مساعدة لإنشاء التوقيعات. ويمكن استخدامها بإحدى طريقتين:

  • كتدفق stream قابل للكتابة، حيث يتم كتابة البيانات المراد توقيعها وتُستخدم طريقة sign.sign() لإنشاء التوقيع وإرجاعه، أو
  • باستخدام طريقتي sign.update() و sign.sign() لإنتاج التوقيع.

تُستخدم طريقة crypto.createSign() لإنشاء مثيلات Sign. الوسيطة هي اسم دالة التجزئة السلسلة التي سيتم استخدامها. لا يجب إنشاء كائنات Sign مباشرةً باستخدام الكلمة الأساسية new.

مثال: استخدام كائنات Sign و Verify كتدفقات:

js
const { generateKeyPairSync, createSign, createVerify } = await import('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
})

const sign = createSign('SHA256')
sign.write('some data to sign')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// يطبع: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
})

const sign = createSign('SHA256')
sign.write('some data to sign')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// يطبع: true

مثال: استخدام طريقتي sign.update() و verify.update():

js
const { generateKeyPairSync, createSign, createVerify } = await import('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
})

const sign = createSign('SHA256')
sign.update('some data to sign')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature))
// يطبع: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
})

const sign = createSign('SHA256')
sign.update('some data to sign')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature))
// يطبع: true

sign.sign(privateKey[, outputEncoding]) ​

[السجل]

الإصدارالتغييرات
v15.0.0يمكن أن يكون privateKey أيضًا مصفوفة ArrayBuffer و CryptoKey.
v13.2.0, v12.16.0تدعم هذه الدالة الآن توقيعات IEEE-P1363 DSA و ECDSA.
v12.0.0تدعم هذه الدالة الآن مفاتيح RSA-PSS.
v11.6.0تدعم هذه الدالة الآن كائنات المفاتيح.
v8.0.0تمت إضافة دعم لـ RSASSA-PSS وخيارات إضافية.
v0.1.92تمت الإضافة في: v0.1.92

يحسب التوقيع على جميع البيانات التي تم تمريرها باستخدام إما sign.update() أو sign.write().

إذا لم يكن privateKey عبارة عن KeyObject، فإن هذه الدالة تتصرف كما لو تم تمرير privateKey إلى crypto.createPrivateKey(). إذا كان كائنًا، فيمكن تمرير خصائص إضافية كالتالي:

  • dsaEncoding <string> بالنسبة لـ DSA و ECDSA، يحدد هذا الخيار تنسيق التوقيع المُولّد. يمكن أن يكون أحد الخيارات التالية:

    • 'der' (افتراضي): ترميز بنية التوقيع ASN.1 المُشفر بـ DER (r, s).
    • 'ieee-p1363': تنسيق التوقيع r || s كما هو مقترح في IEEE-P1363.

  • padding <integer> قيمة التعبئة الاختيارية لـ RSA، أحد الخيارات التالية:

    • crypto.constants.RSA_PKCS1_PADDING (افتراضي)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

سيستخدم RSA_PKCS1_PSS_PADDING MGF1 مع نفس دالة التجزئة المستخدمة لتوقيع الرسالة كما هو محدد في القسم 3.1 من RFC 4055، ما لم يتم تحديد دالة تجزئة MGF1 كجزء من المفتاح وفقًا للقسم 3.3 من RFC 4055.

  • saltLength <integer> طول الملح عندما تكون التعبئة RSA_PKCS1_PSS_PADDING. تعيّن القيمة الخاصة crypto.constants.RSA_PSS_SALTLEN_DIGEST طول الملح على حجم التجزئة، crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (افتراضي) تعيينه على الحد الأقصى للقيمة المسموح بها.

إذا تم توفير outputEncoding، فسيتم إرجاع سلسلة؛ بخلاف ذلك، سيتم إرجاع Buffer.

لا يمكن استخدام كائن Sign مرة أخرى بعد استدعاء طريقة sign.sign(). ستؤدي المكالمات المتعددة لـ sign.sign() إلى إرسال خطأ.

sign.update(data[, inputEncoding]) ​

[History]

الإصدارالتغييرات
v6.0.0تغيرت قيمة inputEncoding الافتراضية من binary إلى utf8.
v0.1.92تمت الإضافة في: v0.1.92

يقوم بتحديث محتوى Sign بالبيانات المعطاة data، وترميزها مُعطى في inputEncoding. إذا لم يتم توفير encoding، وكانت data سلسلة، فسيتم فرض ترميز 'utf8'. إذا كانت data عبارة عن Buffer، أو TypedArray، أو DataView، فسيتم تجاهل inputEncoding.

يمكن استدعاء هذا عدة مرات مع بيانات جديدة أثناء تدفقها.

الصنف: Verify ​

تمت الإضافة في: v0.1.92

يُعد صنف Verify أداة مساعدة للتحقق من التوقيعات. يمكن استخدامه بإحدى طريقتين:

  • كتدفق قابل للكتابة stream حيث تُستخدم البيانات المكتوبة للتحقق من التوقيع المُقدم، أو
  • باستخدام طريقتي verify.update() و verify.verify() للتحقق من التوقيع.

تُستخدم طريقة crypto.createVerify() لإنشاء مثيلات Verify. لا يجب إنشاء كائنات Verify مباشرةً باستخدام الكلمة المفتاحية new.

راجع Sign للحصول على أمثلة.

verify.update(data[, inputEncoding]) ​

[History]

الإصدارالتغييرات
v6.0.0تغيرت قيمة inputEncoding الافتراضية من binary إلى utf8.
v0.1.92تمت الإضافة في: v0.1.92

يقوم بتحديث محتوى Verify بالبيانات المعطاة data، وترميزها مُعطى في inputEncoding. إذا لم يتم توفير inputEncoding، وكانت data سلسلة، فسيتم فرض ترميز 'utf8'. إذا كانت data عبارة عن Buffer، أو TypedArray، أو DataView، فسيتم تجاهل inputEncoding.

يمكن استدعاء هذا عدة مرات مع بيانات جديدة أثناء تدفقها.

verify.verify(object, signature[, signatureEncoding]) ​

[السجل]

الإصدارالتغييرات
v15.0.0يمكن أن يكون الكائن أيضًا ArrayBuffer و CryptoKey.
v13.2.0، v12.16.0تدعم هذه الدالة الآن توقيعات IEEE-P1363 DSA و ECDSA.
v12.0.0تدعم هذه الدالة الآن مفاتيح RSA-PSS.
v11.7.0يمكن أن يكون المفتاح الآن مفتاحًا خاصًا.
v8.0.0تمت إضافة دعم لـ RSASSA-PSS وخيارات إضافية.
v0.1.92تمت الإضافة في: v0.1.92

تتحقق من البيانات المقدمة باستخدام object و signature المعطيين.

إذا لم يكن object عبارة عن KeyObject، فإن هذه الدالة تتصرف كما لو تم تمرير object إلى crypto.createPublicKey(). إذا كان كائنًا، فيمكن تمرير الخصائص الإضافية التالية:

  • dsaEncoding <string> بالنسبة إلى DSA و ECDSA، يحدد هذا الخيار تنسيق التوقيع. يمكن أن يكون أحد ما يلي:

    • 'der' (افتراضي): ترميز بنية التوقيع ASN.1 المُشفّر بواسطة DER (r, s).
    • 'ieee-p1363': تنسيق التوقيع r || s كما هو مقترح في IEEE-P1363.

  • padding <integer> قيمة التعبئة الاختيارية لـ RSA، أحد ما يلي:

    • crypto.constants.RSA_PKCS1_PADDING (افتراضي)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

سيستخدم RSA_PKCS1_PSS_PADDING MGF1 بنفس دالة التجزئة المستخدمة للتحقق من الرسالة كما هو محدد في القسم 3.1 من RFC 4055، ما لم يتم تحديد دالة تجزئة MGF1 كجزء من المفتاح وفقًا للقسم 3.3 من RFC 4055.

  • saltLength <integer> طول الملح عندما يكون التعبئة RSA_PKCS1_PSS_PADDING. تقوم القيمة الخاصة crypto.constants.RSA_PSS_SALTLEN_DIGEST بتعيين طول الملح إلى حجم التجزئة، crypto.constants.RSA_PSS_SALTLEN_AUTO (افتراضي) يتسبب في تحديده تلقائيًا.

مُعامل signature هو التوقيع المحسوب مسبقًا للبيانات، في signatureEncoding. إذا تم تحديد signatureEncoding، فمن المتوقع أن تكون signature سلسلة؛ خلاف ذلك، من المتوقع أن تكون signature عبارة عن Buffer، TypedArray، أو DataView.

لا يمكن استخدام كائن verify مرة أخرى بعد استدعاء verify.verify(). ستؤدي المكالمات المتعددة إلى verify.verify() إلى إصدار خطأ.

نظرًا لأنه يمكن اشتقاق المفاتيح العامة من المفاتيح الخاصة، يمكن تمرير مفتاح خاص بدلاً من مفتاح عام.

الصف: X509Certificate ​

مضاف في: v15.6.0

يُغلف شهادة X509 ويوفر وصولاً للقراءة فقط إلى معلوماتها.

js
const { X509Certificate } = await import('node:crypto')

const x509 = new X509Certificate('{... pem encoded cert ...}')

console.log(x509.subject)
js
const { X509Certificate } = require('node:crypto')

const x509 = new X509Certificate('{... pem encoded cert ...}')

console.log(x509.subject)

new X509Certificate(buffer) ​

مضاف في: v15.6.0

x509.ca ​

مضاف في: v15.6.0

  • النوع: <boolean> ستكون true إذا كانت هذه شهادة سلطة إصدار الشهادات (CA).

x509.checkEmail(email[, options]) ​

[السجل]

الإصدارالتغييرات
v18.0.0خيار الموضوع الآن يفترض افتراضيًا 'default'.
v17.5.0, v16.15.0يمكن الآن تعيين خيار الموضوع إلى 'default'.
v17.5.0, v16.14.1تمت إزالة خيارات wildcards, partialWildcards, multiLabelWildcards, و singleLabelSubdomains نظرًا لعدم تأثيرها.
v15.6.0مضاف في: v15.6.0

  • email <string>

  • options <Object>

    • subject <string> 'default', 'always', أو 'never'. الافتراضي: 'default'.

  • القيمة المرجعة: <string> | <undefined> تُرجع email إذا تطابقت الشهادة، undefined إذا لم تتطابق.

يتحقق مما إذا كانت الشهادة تطابق عنوان البريد الإلكتروني المعطى.

إذا كان خيار 'subject' غير مُعرّف أو مُعيّن إلى 'default', يُؤخذ موضوع الشهادة في الاعتبار فقط إذا لم يكن امتداد اسم بديل للموضوع موجودًا أو لا يحتوي على أي عناوين بريد إلكتروني.

إذا كان خيار 'subject' مُعيّنًا إلى 'always' وإذا لم يكن امتداد اسم بديل للموضوع موجودًا أو لا يحتوي على عنوان بريد إلكتروني مطابق، يُؤخذ موضوع الشهادة في الاعتبار.

إذا كان خيار 'subject' مُعيّنًا إلى 'never', لا يُؤخذ موضوع الشهادة في الاعتبار أبدًا، حتى لو لم تحتوي الشهادة على أسماء بديلة للموضوع.

x509.checkHost(name[, options]) ​

[History]

الإصدارالتغييرات
v18.0.0خيار الموضوع الآن افتراضيًا هو 'default'
v17.5.0, v16.15.0يمكن الآن تعيين خيار الموضوع إلى 'default'
v15.6.0تمت الإضافة في: v15.6.0

  • name <string>

  • options <Object>

    • subject <string> 'default', 'always', أو 'never'. الافتراضي: 'default'.
    • wildcards <boolean> الافتراضي: true.
    • partialWildcards <boolean> الافتراضي: true.
    • multiLabelWildcards <boolean> الافتراضي: false.
    • singleLabelSubdomains <boolean> الافتراضي: false.

  • الإرجاع: <string> | <undefined> يرجع اسم موضوع يتطابق مع name، أو undefined إذا لم يتطابق أي اسم موضوع مع name.

يتحقق مما إذا كانت الشهادة تطابق اسم المضيف المعطى.

إذا تطابقت الشهادة مع اسم المضيف المعطى، فسيتم إرجاع اسم الموضوع المطابق. قد يكون الاسم المُرجَع مطابقة دقيقة (مثل، foo.example.com) أو قد يحتوي على أحرف بديلة (مثل، *.example.com). نظرًا لأن مقارنات أسماء المضيف غير حساسة لحالة الأحرف، فقد يختلف اسم الموضوع المُرجَع أيضًا عن name المعطى في كتابة الأحرف الكبيرة والصغيرة.

إذا كان خيار 'subject' غير مُعرّف أو مُعيّن إلى 'default'، فسيتم اعتبار موضوع الشهادة فقط إذا لم يكن امتداد اسم البديل للموضوع موجودًا أو لم يحتوِ على أي أسماء DNS. هذا السلوك يتوافق مع RFC 2818 ("HTTP Over TLS").

إذا تم تعيين خيار 'subject' إلى 'always' وإذا لم يكن امتداد اسم البديل للموضوع موجودًا أو لم يحتوِ على اسم DNS مطابق، فسيتم اعتبار موضوع الشهادة.

إذا تم تعيين خيار 'subject' إلى 'never'، فلن يتم اعتبار موضوع الشهادة أبدًا، حتى لو لم تحتوي الشهادة على أسماء بديلة للموضوع.

x509.checkIP(ip) ​

[السجل]

الإصدارالتغييرات
v17.5.0، v16.14.1تمت إزالة وسيطة options نظرًا لعدم تأثيرها.
v15.6.0تمت الإضافة في: v15.6.0
  • ip <string>
  • القيمة المُرجعة: <string> | <undefined> تُرجع ip إذا تطابقت الشهادة، undefined إذا لم تتطابق.

يتحقق مما إذا كانت الشهادة تطابق عنوان IP المعطى (IPv4 أو IPv6).

يتم اعتبار أسماء البدائل الموضوعية iPAddress في RFC 5280 فقط، ويجب أن تتطابق مع عنوان ip المعطى تمامًا. يتم تجاهل أسماء البدائل الموضوعية الأخرى بالإضافة إلى حقل الموضوع في الشهادة.

x509.checkIssued(otherCert) ​

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

يتحقق مما إذا تم إصدار هذه الشهادة بواسطة otherCert المعطاة.

x509.checkPrivateKey(privateKey) ​

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

يتحقق مما إذا كان المفتاح العام لهذه الشهادة متوافقًا مع المفتاح الخاص المعطى.

x509.extKeyUsage ​

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

مصفوفة تُفصّل الاستخدامات الموسعة للمفتاح لهذه الشهادة.

x509.fingerprint ​

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

بصمة SHA-1 لهذه الشهادة.

نظرًا لأن SHA-1 مُكسور من الناحية التشفيرية، ولأن أمان SHA-1 أسوأ بكثير من خوارزميات التوقيع الشائعة للاستخدام في الشهادات، فكر في استخدام x509.fingerprint256 بدلاً من ذلك.

x509.fingerprint256 ​

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

بصمة SHA-256 لهذه الشهادة.

x509.fingerprint512 ​

تمت الإضافة في: v17.2.0، v16.14.0

بصمة SHA-512 لهذه الشهادة.

نظرًا لأن حساب بصمة SHA-256 يكون أسرع عادةً، ولأنه يمثل نصف حجم بصمة SHA-512، فقد يكون x509.fingerprint256 خيارًا أفضل. بينما يوفر SHA-512 مستوى أعلى من الأمان بشكل عام، فإن أمان SHA-256 يتطابق مع معظم الخوارزميات المستخدمة عادةً لتوقيع الشهادات.

x509.infoAccess ​

[السجل]

الإصدارالتغييرات
v17.3.1، v16.13.2قد يتم ترميز أجزاء من هذا النص كقيم نصية JSON استجابةً لـ CVE-2021-44532.
v15.6.0تمت الإضافة في: v15.6.0

تمثيل نصي لملحق الوصول إلى معلومات السلطة للشهادة.

هذه قائمة مفصولة بفاصل سطر من أوصاف الوصول. يبدأ كل سطر بطريقة الوصول ونوع موقع الوصول، متبوعًا بنقطتين والقيمة المرتبطة بموقع الوصول.

بعد البادئة التي تشير إلى طريقة الوصول ونوع موقع الوصول، قد يكون باقي كل سطر محاطًا بعلامات اقتباس للإشارة إلى أن القيمة عبارة عن قيمة نصية JSON. من أجل التوافق مع الإصدارات السابقة، لا تستخدم Node.js القيم النصية JSON ضمن هذه الخاصية إلا عند الضرورة لتجنب الغموض. يجب أن يكون الكود الخاص بالجهات الخارجية مستعدًا للتعامل مع كلا التنسيقين المحتملين للمدخلات.

x509.issuer ​

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

هوية المُصدر المدرجة في هذه الشهادة.

x509.issuerCertificate ​

مضاف في: v15.9.0

شهادة المُصدر أو undefined إذا لم تتوفر شهادة المُصدر.

x509.publicKey ​

مضاف في: v15.6.0

المفتاح العام <KeyObject> لهذه الشهادة.

x509.raw ​

مضاف في: v15.6.0

Buffer يحتوي على ترميز DER لهذه الشهادة.

x509.serialNumber ​

مضاف في: v15.6.0

الرقم التسلسلي لهذه الشهادة.

يتم تعيين الأرقام التسلسلية من قبل سلطات إصدار الشهادات ولا تُحدد الشهادات بشكل فريد. ضع في اعتبارك استخدام x509.fingerprint256 كمعرف فريد بدلاً من ذلك.

x509.subject ​

مضاف في: v15.6.0

الموضوع الكامل لهذه الشهادة.

x509.subjectAltName ​

[السجل]

الإصدارالتغييرات
v17.3.1, v16.13.2قد يتم ترميز أجزاء من هذا السلسلة كمتواليات سلسلة JSON استجابةً لـ CVE-2021-44532.
v15.6.0مضاف في: v15.6.0

اسم البديل للموضوع المحدد لهذه الشهادة.

هذه قائمة مفصولة بفواصل من أسماء البدائل للموضوع. يبدأ كل إدخال بسلسلة تحدد نوع اسم البديل للموضوع متبوعًا بفاصلة نقطتين والقيمة المرتبطة بالإدخال.

افترضت الإصدارات السابقة من Node.js بشكل غير صحيح أنه من الآمن تقسيم هذه الخاصية عند تسلسل الأحرف ', ' (انظر CVE-2021-44532). ومع ذلك، يمكن أن تحتوي كل من الشهادات الخبيثة والشرعية على أسماء بديلة للموضوع تتضمن هذا التسلسل عند تمثيلها كسلسلة.

بعد البادئة التي تشير إلى نوع الإدخال، قد يكون الباقي من كل إدخال محاطًا بعلامات اقتباس للإشارة إلى أن القيمة هي متوالية سلسلة JSON. من أجل التوافق مع الإصدارات السابقة، يستخدم Node.js متواليات سلسلة JSON ضمن هذه الخاصية فقط عند الضرورة لتجنب الغموض. يجب أن يكون التعليم البرمجي من جهات خارجية مُعدًا للتعامل مع كلا التنسيقين المحتملين للإدخال.

x509.toJSON() ​

مضاف في: v15.6.0

لا يوجد ترميز JSON قياسي لشهادات X509. ترجع طريقة toJSON() سلسلة نصية تحتوي على الشهادة المشفرة بترميز PEM.

x509.toLegacyObject() ​

مضاف في: v15.6.0

ترجع معلومات حول هذه الشهادة باستخدام ترميز كائن الشهادة القديم كائن الشهادة.

x509.toString() ​

مضاف في: v15.6.0

ترجع الشهادة المشفرة بترميز PEM.

x509.validFrom ​

مضاف في: v15.6.0

تاريخ/وقت بدء صلاحية هذه الشهادة.

x509.validFromDate ​

مضاف في: v23.0.0

تاريخ/وقت بدء صلاحية هذه الشهادة، محاطًا بكائن Date.

x509.validTo ​

مضاف في: v15.6.0

تاريخ/وقت انتهاء صلاحية هذه الشهادة.

x509.validToDate ​

مضاف في: v23.0.0

تاريخ/وقت انتهاء صلاحية هذه الشهادة، محاطًا بكائن Date.

x509.verify(publicKey) ​

مضاف في: v15.6.0

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

طرق وخصائص وحدة node:crypto ​

crypto.checkPrime(candidate[, options], callback) ​

[السجل]

الإصدارالتغييرات
v18.0.0إرسال مُعامل استدعاء غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.8.0تمت الإضافة في: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> عدد أولي محتمل مُشَفَّر كمتتابعة من أوكتيتات النهاية الكبيرة ذات طول تعسفي.

  • options <Object>

    • checks <number> عدد تكرارات البدائية الاحتمالية لـ Miller-Rabin التي سيتم تنفيذها. عندما تكون القيمة هي 0 (صفر)، يتم استخدام عدد من عمليات الفحص ينتج عنه معدل خطأ إيجابي كاذب لا يتجاوز 2 للمدخل العشوائي. يجب توخي الحذر عند اختيار عدد من عمليات الفحص. راجع وثائق OpenSSL لوظيفة BN_is_prime_ex خيارات nchecks لمزيد من التفاصيل. افتراضيًا: 0

  • callback <Function>

    • err <Error> مُعيّن على كائن <Error> إذا حدث خطأ أثناء الفحص.
    • result <boolean> true إذا كان المُرشح عددًا أوليًا باحتمالية خطأ أقل من 0.25 ** options.checks.

يَفحَص بدائية candidate.

crypto.checkPrimeSync(candidate[, options]) ​

مضاف في: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> عدد أولي محتمل مشفر كسلسلة من بايتات النهاية الكبيرة ذات طول تعسفي.

  • options <Object>

    • checks <number> عدد تكرارات اختبار البدائية الاحتمالية لـ Miller-Rabin التي سيتم إجراؤها. عندما تكون القيمة هي 0 (صفر)، يتم استخدام عدد من عمليات الفحص ينتج عنه معدل خطأ إيجابي كاذب لا يتجاوز 2 لإدخال عشوائي. يجب توخي الحذر عند تحديد عدد عمليات الفحص. راجع وثائق OpenSSL لوظيفة BN_is_prime_ex لخيار nchecks لمزيد من التفاصيل. افتراضي: 0

  • قيمة الإرجاع: <boolean> true إذا كان المُرشح عددًا أوليًا باحتمالية خطأ أقل من 0.25 ** options.checks.

يتحقق من بدائية candidate.

crypto.constants ​

مضاف في: v6.3.0

كائن يحتوي على ثوابت شائعة الاستخدام لعمليات التشفير والأمان. يتم وصف الثوابت المحددة حاليًا في ثوابت التشفير.

crypto.createCipheriv(algorithm, key, iv[, options]) ​

[السجل]

الإصدارالتغييرات
v17.9.0, v16.17.0أصبح خيار authTagLength اختياريًا الآن عند استخدام تشفير chacha20-poly1305 وافتراضياً 16 بايت.
v15.0.0يمكن أن تكون حجتا كلمة المرور و iv عبارة عن ArrayBuffer، وكل منهما يقتصر على حد أقصى 2 ** 31 - 1 بايت.
v11.6.0يمكن أن تكون حجة key الآن KeyObject.
v11.2.0, v10.17.0أصبح التشفير chacha20-poly1305 (متغير IETF من ChaCha20-Poly1305) مدعومًا الآن.
v10.10.0يتم دعم الشفرات في وضع OCB الآن.
v10.2.0يمكن الآن استخدام خيار authTagLength لإنتاج علامات مصادقة أقصر في وضع GCM وافتراضياً 16 بايت.
v9.9.0يمكن أن تكون معلمة iv الآن null للشفرات التي لا تحتاج إلى متجه تهيئة.
v0.1.94تمت الإضافة في: v0.1.94

يُنشئ ويرجع كائن Cipher، مع خوارزمية مُعطاة algorithm، وkey، ومتجه تهيئة (iv).

تتحكم حجة options في سلوك الدفق وهي اختيارية إلا عند استخدام تشفير في وضع CCM أو OCB (مثل 'aes-128-ccm'). في هذه الحالة، يُطلب خيار authTagLength ويحدد طول علامة المصادقة بالبايت، انظر وضع CCM. في وضع GCM، لا يُطلب خيار authTagLength ولكن يمكن استخدامه لتعيين طول علامة المصادقة التي سيتم إرجاعها بواسطة getAuthTag() وافتراضياً 16 بايت. بالنسبة إلى chacha20-poly1305، يكون خيار authTagLength افتراضيًا 16 بايت.

يعتمد algorithm على OpenSSL، والأمثلة هي 'aes192'، إلخ. في إصدارات OpenSSL الحديثة، سيعرض openssl list -cipher-algorithms خوارزميات التشفير المتاحة.

key هو المفتاح الخام الذي تستخدمه algorithm وiv هو متجه تهيئة. يجب أن تكون كلتا الحجتين سلاسل مُشفّرة بـ 'utf8'، أو Buffers، أو TypedArray، أو DataViews. قد يكون key اختيارياً KeyObject من نوع secret. إذا لم تكن هناك حاجة إلى متجه تهيئة للتشفير، فقد يكون iv null.

عند تمرير سلاسل لـ key أو iv، يرجى مراعاة المحاذير عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات التشفيرية.

يجب أن تكون متجهات التهيئة غير قابلة للتنبؤ وفريدة من نوعها؛ من الناحية المثالية، ستكون عشوائية تشفيرياً. ليس من الضروري أن تكون سرية: عادةً ما يتم فقط إضافة IVs إلى رسائل نص مشفر غير مشفرة. قد يبدو متناقضًا أن شيئًا ما يجب أن يكون غير قابل للتنبؤ وفريدًا، لكن ليس من الضروري أن يكون سريًا؛ تذكر أنه يجب ألا يتمكن المهاجم من التنبؤ مسبقًا بما سيكون عليه IV معين.

crypto.createDecipheriv(algorithm, key, iv[, options]) ​

[History]

الإصدارالتغييرات
v17.9.0, v16.17.0أصبح خيار authTagLength اختياريًا الآن عند استخدام تشفير chacha20-poly1305 وافتراضيًا 16 بايت.
v11.6.0يمكن أن يكون الوسيط key الآن KeyObject.
v11.2.0, v10.17.0أصبح تشفير chacha20-poly1305 (متغير IETF من ChaCha20-Poly1305) مدعومًا الآن.
v10.10.0يتم دعم الشفرات في وضع OCB الآن.
v10.2.0يمكن الآن استخدام خيار authTagLength للحد من أطوال علامات المصادقة GCM المقبولة.
v9.9.0يمكن أن يكون الوسيط iv الآن null بالنسبة للشفرات التي لا تحتاج إلى متجه بدء.
v0.1.94تمت الإضافة في: v0.1.94

يقوم بإنشاء وإرجاع كائن Decipher يستخدم algorithm و key ومتجه البدء المُعطى (iv).

يتحكم وسيط options في سلوك التدفق وهو اختياري إلا عند استخدام تشفير في وضع CCM أو OCB (مثل 'aes-128-ccm'). في هذه الحالة، يكون خيار authTagLength مطلوبًا ويحدد طول علامة المصادقة بالبايت، انظر وضع CCM. بالنسبة إلى AES-GCM وchacha20-poly1305، يكون خيار authTagLength افتراضيًا 16 بايت ويجب تعيينه إلى قيمة مختلفة إذا تم استخدام طول مختلف.

يعتمد algorithm على OpenSSL، والأمثلة هي 'aes192'، إلخ. في إصدارات OpenSSL الحديثة، سيعرض openssl list -cipher-algorithms خوارزميات التشفير المتاحة.

key هو المفتاح الخام الذي تستخدمه algorithm و iv هو متجه البدء. يجب أن يكون كلا الوسيطين سلاسل مُشفّرة بـ 'utf8'، أو Buffers، أو TypedArray، أو DataViews. قد يكون key اختياريًا KeyObject من نوع secret. إذا لم تكن الشفرة بحاجة إلى متجه بدء، فقد يكون iv هو null.

عند تمرير السلاسل لـ key أو iv، يرجى مراعاة التحذيرات عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات المشفرة.

يجب أن تكون متجهات البدء غير قابلة للتنبؤ وفريدة؛ من الناحية المثالية، ستكون عشوائية تشفيرية. لا يجب أن تكون سرية: عادةً ما يتم إضافة متجهات البدء إلى رسائل النص المشفر غير المشفرة. قد يبدو متناقضًا أن يكون شيء ما غير قابل للتنبؤ وفريدًا، لكن لا يجب أن يكون سريًا؛ تذكر أنه يجب ألا يتمكن المهاجم من التنبؤ مسبقًا بما سيكون عليه متجه البدء المعطى.

crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding]) ​

[History]

الإصدارالتغييرات
v8.0.0يمكن الآن أن تكون وسيطة prime أي TypedArray أو DataView.
v8.0.0يمكن أن تكون وسيطة prime الآن عبارة عن Uint8Array.
v6.0.0تغيرت القيمة الافتراضية لمعلمات التشفير من binary إلى utf8.
v0.11.12تمت الإضافة في: v0.11.12

يُنشئ كائن تبادل مفاتيح DiffieHellman باستخدام prime المُعطى ومُولِّد مُحدد اختياري.

يمكن أن تكون وسيطة generator رقمًا أو سلسلة أو Buffer. إذا لم يتم تحديد generator، فسيتم استخدام القيمة 2.

إذا تم تحديد primeEncoding، يُتوقع أن يكون prime سلسلة؛ خلاف ذلك، يُتوقع أن يكون Buffer، TypedArray، أو DataView.

إذا تم تحديد generatorEncoding، يُتوقع أن يكون generator سلسلة؛ خلاف ذلك، يُتوقع أن يكون رقمًا، أو Buffer، TypedArray، أو DataView.

crypto.createDiffieHellman(primeLength[, generator]) ​

مضاف في: v0.5.0

يقوم بإنشاء كائن تبادل مفاتيح DiffieHellman ويولد عددًا أوليًا من بتات primeLength باستخدام مُولِّد رقمي اختياري محدد. إذا لم يتم تحديد generator، فسيتم استخدام القيمة 2.

crypto.createDiffieHellmanGroup(name) ​

مضاف في: v0.9.3

مُرادف لـ crypto.getDiffieHellman()

crypto.createECDH(curveName) ​

مضاف في: v0.11.14

يقوم بإنشاء كائن تبادل مفاتيح منحنى إهليلجي Diffie-Hellman (ECDH) باستخدام منحنى مُحدد مُسبقًا مُحدد بواسطة سلسلة curveName. استخدم crypto.getCurves() للحصول على قائمة بأسماء المنحنيات المتاحة. في إصدارات OpenSSL الحديثة، سيعرض openssl ecparam -list_curves أيضًا اسم ووصف كل منحنى إهليلجي متاح.

crypto.createHash(algorithm[, options]) ​

[السجل]

الإصدارالتغييرات
v12.8.0تمت إضافة خيار outputLength لوظائف التجزئة XOF.
v0.1.92مضاف في: v0.1.92

يقوم بإنشاء وإرجاع كائن Hash يمكن استخدامه لإنشاء ملخصات التجزئة باستخدام algorithm المعطى. تتحكم وسيطة options الاختيارية في سلوك الدفق. بالنسبة لوظائف التجزئة XOF مثل 'shake256'، يمكن استخدام خيار outputLength لتحديد طول الإخراج المطلوب بالبايت.

يعتمد algorithm على الخوارزميات المتاحة المدعومة بواسطة إصدار OpenSSL على النظام الأساسي. أمثلة: 'sha256'، 'sha512'، إلخ. في الإصدارات الحديثة من OpenSSL، سيعرض openssl list -digest-algorithms خوارزميات التجزئة المتاحة.

مثال: إنشاء مجموع sha256 لملف

js
import { createReadStream } from 'node:fs'
import { argv } from 'node:process'
const { createHash } = await import('node:crypto')

const filename = argv[2]

const hash = createHash('sha256')

const input = createReadStream(filename)
input.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة دفق التجزئة.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHash } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

const hash = createHash('sha256')

const input = createReadStream(filename)
input.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة دفق التجزئة.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})

crypto.createHmac(algorithm, key[, options]) ​

[History]

الإصدارالتغييرات
v15.0.0يمكن أن يكون المفتاح أيضًا ArrayBuffer أو CryptoKey. تم إضافة خيار التشفير. لا يمكن أن يحتوي المفتاح على أكثر من 2 ** 32 - 1 بايت.
v11.6.0يمكن أن تكون وسيطة key الآن KeyObject.
v0.1.94تمت الإضافة في: v0.1.94

يُنشئ ويرجع كائن Hmac يستخدم algorithm و key المُعطاة. تتحكم وسيطة options الاختيارية في سلوك الدفق.

تعتمد algorithm على الخوارزميات المتاحة التي يدعمها إصدار OpenSSL على النظام الأساسي. أمثلة: 'sha256', 'sha512', إلخ. في الإصدارات الحديثة من OpenSSL، سيعرض openssl list -digest-algorithms خوارزميات التجزئة المتاحة.

key هو مفتاح HMAC المستخدم لإنشاء تجزئة HMAC المشفرة. إذا كان KeyObject، يجب أن يكون نوعه secret. إذا كانت سلسلة، يرجى مراعاة التحذيرات عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات المشفرة. إذا تم الحصول عليها من مصدر عشوائي آمن تشفيرياً، مثل crypto.randomBytes() أو crypto.generateKey()، يجب ألا يتجاوز طولها حجم كتلة algorithm (مثل 512 بت لـ SHA-256).

مثال: إنشاء HMAC sha256 لملف

js
import { createReadStream } from 'node:fs'
import { argv } from 'node:process'
const { createHmac } = await import('node:crypto')

const filename = argv[2]

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream(filename)
input.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة دفق التجزئة.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHmac } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream(filename)
input.on('readable', () => {
  // سيتم إنتاج عنصر واحد فقط بواسطة دفق التجزئة.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})

crypto.createPrivateKey(key) ​

[History]

الإصدارالتغييرات
v15.12.0يمكن أن يكون المفتاح أيضًا كائن JWK.
v15.0.0يمكن أن يكون المفتاح أيضًا ArrayBuffer. تمت إضافة خيار الترميز. لا يمكن أن يحتوي المفتاح على أكثر من 2 ** 32 - 1 بايت.
v11.6.0تمت الإضافة في: v11.6.0

يُنشئ ويرجع كائن مفتاح جديد يحتوي على مفتاح خاص. إذا كان key سلسلة أو Buffer، يُفترض أن يكون format هو 'pem'؛ خلاف ذلك، يجب أن يكون key كائنًا يحتوي على الخصائص الموضحة أعلاه.

إذا تم تشفير المفتاح الخاص، فيجب تحديد passphrase. يقتصر طول عبارة المرور على 1024 بايت.

crypto.createPublicKey(key) ​

[السجل]

الإصدارالتغييرات
v15.12.0يمكن أن يكون المفتاح أيضًا كائن JWK.
v15.0.0يمكن أن يكون المفتاح أيضًا مصفوفة ArrayBuffer. تمت إضافة خيار التشفير. لا يمكن أن يحتوي المفتاح على أكثر من 2 ** 32 - 1 بايت.
v11.13.0يمكن أن تكون وسيطة key الآن KeyObject من نوع private.
v11.7.0يمكن أن تكون وسيطة key الآن مفتاحًا خاصًا.
v11.6.0تمت الإضافة في: v11.6.0

يقوم بإنشاء وإرجاع كائن مفتاح جديد يحتوي على مفتاح عام. إذا كان key سلسلة أو Buffer، يُفترض أن يكون format هو 'pem'؛ إذا كان key هو KeyObject من نوع 'private'، فسيتم اشتقاق المفتاح العام من المفتاح الخاص المعطى؛ بخلاف ذلك، يجب أن يكون key كائنًا يحتوي على الخصائص الموضحة أعلاه.

إذا كان التنسيق 'pem'، فقد يكون 'key' أيضًا شهادة X.509.

بما أن المفاتيح العامة يمكن اشتقاقها من المفاتيح الخاصة، يمكن تمرير مفتاح خاص بدلاً من مفتاح عام. في هذه الحالة، تعمل هذه الدالة كما لو تم استدعاء crypto.createPrivateKey()، باستثناء أن نوع KeyObject المُرجّع سيكون 'public' وأنه لا يمكن استخراج المفتاح الخاص من KeyObject المُرجّع. وبالمثل، إذا تم إعطاء KeyObject من نوع 'private'، فسيتم إرجاع KeyObject جديد من نوع 'public' وسيكون من المستحيل استخراج المفتاح الخاص من الكائن المُرجّع.

crypto.createSecretKey(key[, encoding]) ​

[السجل]

الإصدارالتغييرات
v18.8.0، v16.18.0يمكن أن يكون المفتاح الآن بطول صفري.
v15.0.0يمكن أن يكون المفتاح أيضًا ArrayBuffer أو سلسلة. تمت إضافة وسيطة encoding. لا يمكن أن يحتوي المفتاح على أكثر من 2 ** 32 - 1 بايت.
v11.6.0تمت الإضافة في: v11.6.0

يقوم بإنشاء وإرجاع كائن مفتاح جديد يحتوي على مفتاح سري للتشفير المتماثل أو Hmac.

crypto.createSign(algorithm[, options]) ​

تمت الإضافة في: v0.1.92

يقوم بإنشاء وإرجاع كائن Sign يستخدم خوارزمية algorithm المُعطاة. استخدم crypto.getHashes() للحصول على أسماء خوارزميات التجزئة المتاحة. تتحكم وسيطة options الاختيارية في سلوك stream.Writable.

في بعض الحالات، يمكن إنشاء مثيل Sign باستخدام اسم خوارزمية التوقيع، مثل 'RSA-SHA256'، بدلاً من خوارزمية التجزئة. سيستخدم هذا خوارزمية التجزئة المقابلة. هذا لا يعمل مع جميع خوارزميات التوقيع، مثل 'ecdsa-with-SHA256'، لذلك من الأفضل دائمًا استخدام أسماء خوارزميات التجزئة.

crypto.createVerify(algorithm[, options]) ​

مضاف في: v0.1.92

يقوم بإنشاء وإرجاع كائن Verify يستخدم الخوارزمية المعطاة. استخدم crypto.getHashes() للحصول على مصفوفة من أسماء خوارزميات التوقيع المتاحة. تتحكم وسيطة options الاختيارية في سلوك stream.Writable.

في بعض الحالات، يمكن إنشاء مثيل Verify باستخدام اسم خوارزمية التوقيع، مثل 'RSA-SHA256'، بدلاً من خوارزمية التجزئة. سيستخدم هذا خوارزمية التجزئة المقابلة. هذا لا يعمل مع جميع خوارزميات التوقيع، مثل 'ecdsa-with-SHA256'، لذلك من الأفضل دائمًا استخدام أسماء خوارزميات التجزئة.

crypto.diffieHellman(options) ​

مضاف في: v13.9.0، v12.17.0

يحسب سر Diffie-Hellman بناءً على privateKey و publicKey. يجب أن يكون لدى المفتاحين نفس asymmetricKeyType، والذي يجب أن يكون أحد 'dh' (لـ Diffie-Hellman)، 'ec'، 'x448'، أو 'x25519' (لـ ECDH).

crypto.fips ​

مضاف في: v6.0.0

مُهمل منذ: v10.0.0

[مستقر: 0 - مُهمل]

مستقر: 0 استقرار: 0 - مُهمل

خاصية للتحقق والتحكم فيما إذا كان موفر تشفير متوافق مع FIPS قيد الاستخدام حاليًا. يتطلب التعيين على true إصدارًا من Node.js متوافقًا مع FIPS.

هذه الخاصية مُهملة. يرجى استخدام crypto.setFips() و crypto.getFips() بدلاً من ذلك.

crypto.generateKey(type, options, callback) ​

[History]

الإصدارالتغييرات
v18.0.0يؤدي تمرير مُراجع غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.0.0تمت الإضافة في: v15.0.0

  • type: <string> الغرض المقصود من مفتاح السر المُولّد. القيم المقبولة حاليًا هي 'hmac' و 'aes'.

  • options: <Object>

    • length: <number> طول المفتاح المُولّد بالبت. يجب أن تكون هذه قيمة أكبر من 0.
    • إذا كان type هو 'hmac'، يكون الحد الأدنى 8، والحد الأقصى للطول هو 2-1. إذا لم تكن القيمة مضاعفًا لـ 8، فسيتم اقتطاع المفتاح المُولّد إلى Math.floor(length / 8).
    • إذا كان type هو 'aes'، يجب أن يكون الطول أحد قيم 128، أو 192، أو 256.

  • callback: <Function>

يُولّد بشكل غير متزامن مفتاح سرّ عشوائيًا جديدًا من الطول المُعطى. سيحدد type عمليات التحقق التي سيتم تنفيذها على length.

js
const { generateKey } = await import('node:crypto')

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err
  console.log(key.export().toString('hex')) // 46e..........620
})
js
const { generateKey } = require('node:crypto')

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err
  console.log(key.export().toString('hex')) // 46e..........620
})

يجب ألا يتجاوز حجم مفتاح HMAC المُولّد حجم كتلة دالة التجزئة الأساسية. راجع crypto.createHmac() لمزيد من المعلومات.

crypto.generateKeyPair(type, options, callback) ​

[History]

الإصدارالتغييرات
v18.0.0تمرير مُعامل استدعاء غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v16.10.0إضافة إمكانية تعريف معلمات تسلسل RSASSA-PSS-params لأزواج مفاتيح RSA-PSS.
v13.9.0, v12.17.0إضافة دعم لـ Diffie-Hellman.
v12.0.0إضافة دعم لأزواج مفاتيح RSA-PSS.
v12.0.0إضافة إمكانية إنشاء أزواج مفاتيح X25519 و X448.
v12.0.0إضافة إمكانية إنشاء أزواج مفاتيح Ed25519 و Ed448.
v11.6.0تقوم دالتا generateKeyPair و generateKeyPairSync الآن بإنتاج كائنات مفاتيح إذا لم يتم تحديد ترميز.
v10.12.0تمت الإضافة في: v10.12.0

  • type: <string> يجب أن يكون 'rsa' أو 'rsa-pss' أو 'dsa' أو 'ec' أو 'ed25519' أو 'ed448' أو 'x25519' أو 'x448' أو 'dh'.

  • options: <Object>

    • modulusLength: <number> حجم المفتاح بالبتات (RSA، DSA).
    • publicExponent: <number> الأسّ العام (RSA). افتراضي: 0x10001.
    • hashAlgorithm: <string> اسم خلاصة الرسالة (RSA-PSS).
    • mgf1HashAlgorithm: <string> اسم خلاصة الرسالة المستخدمة بواسطة MGF1 (RSA-PSS).
    • saltLength: <number> الحد الأدنى لطول الملح بالبايت (RSA-PSS).
    • divisorLength: <number> حجم q بالبتات (DSA).
    • namedCurve: <string> اسم المنحنى الذي سيتم استخدامه (EC).
    • prime: <Buffer> معلمة العدد الأولي (DH).
    • primeLength: <number> طول العدد الأولي بالبتات (DH).
    • generator: <number> مُولِّد مخصص (DH). افتراضي: 2.
    • groupName: <string> اسم مجموعة Diffie-Hellman (DH). انظر crypto.getDiffieHellman().
    • paramEncoding: <string> يجب أن يكون 'named' أو 'explicit' (EC). افتراضي: 'named'.
    • publicKeyEncoding: <Object> انظر keyObject.export().
    • privateKeyEncoding: <Object> انظر keyObject.export().

  • callback: <Function>

يُولِّد زوج مفاتيح غير متناظر جديد من النوع المُعطى type. يتم دعم RSA و RSA-PSS و DSA و EC و Ed25519 و Ed448 و X25519 و X448 و DH حاليًا.

إذا تم تحديد publicKeyEncoding أو privateKeyEncoding، فإن هذه الدالة تتصرف كما لو تم استدعاء keyObject.export() على نتيجتها. خلاف ذلك، يتم إرجاع الجزء المُناسب من المفتاح كـ KeyObject.

يوصى بترميز المفاتيح العامة كـ 'spki' والمفاتيح الخاصة كـ 'pkcs8' مع التشفير للتخزين طويل الأجل:

js
const { generateKeyPair } = await import('node:crypto')

generateKeyPair(
  'rsa',
  {
    modulusLength: 4096,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
      cipher: 'aes-256-cbc',
      passphrase: 'top secret',
    },
  },
  (err, publicKey, privateKey) => {
    // معالجة الأخطاء واستخدام زوج المفاتيح المُولَّد.
  }
)
js
const { generateKeyPair } = require('node:crypto')

generateKeyPair(
  'rsa',
  {
    modulusLength: 4096,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
      cipher: 'aes-256-cbc',
      passphrase: 'top secret',
    },
  },
  (err, publicKey, privateKey) => {
    // معالجة الأخطاء واستخدام زوج المفاتيح المُولَّد.
  }
)

عند الإكمال، سيتم استدعاء callback مع تعيين err إلى undefined و publicKey / privateKey يمثلان زوج المفاتيح المُولَّد.

إذا تم استدعاء هذه الطريقة كنسختها util.promisify() المُعدلة، فإنها تُرجع Promise لكائن Object مع خصائص publicKey و privateKey.

crypto.generateKeyPairSync(type, options) ​

[History]

الإصدارالتغييرات
v16.10.0إضافة إمكانية تحديد معلمات تسلسل RSASSA-PSS-params لأزواج مفاتيح RSA-PSS.
v13.9.0، v12.17.0إضافة دعم لـ Diffie-Hellman.
v12.0.0إضافة دعم لأزواج مفاتيح RSA-PSS.
v12.0.0إضافة إمكانية إنشاء أزواج مفاتيح X25519 و X448.
v12.0.0إضافة إمكانية إنشاء أزواج مفاتيح Ed25519 و Ed448.
v11.6.0تقوم وظيفتا generateKeyPair و generateKeyPairSync الآن بإنتاج كائنات مفاتيح إذا لم يتم تحديد ترميز.
v10.12.0تمت الإضافة في: v10.12.0

  • type: <string> يجب أن يكون 'rsa'، 'rsa-pss'، 'dsa'، 'ec'، 'ed25519'، 'ed448'، 'x25519'، 'x448'، أو 'dh'.

  • options: <Object>

    • modulusLength: <number> حجم المفتاح بالبت (RSA، DSA).
    • publicExponent: <number> الأسّ العام (RSA). الافتراضي: 0x10001.
    • hashAlgorithm: <string> اسم مُلخّص الرسالة (RSA-PSS).
    • mgf1HashAlgorithm: <string> اسم مُلخّص الرسالة المستخدم بواسطة MGF1 (RSA-PSS).
    • saltLength: <number> الحد الأدنى لطول الملح بالبايت (RSA-PSS).
    • divisorLength: <number> حجم q بالبت (DSA).
    • namedCurve: <string> اسم المنحنى المُراد استخدامه (EC).
    • prime: <Buffer> معلمة العدد الأولي (DH).
    • primeLength: <number> طول العدد الأولي بالبت (DH).
    • generator: <number> مُولّد مخصص (DH). الافتراضي: 2.
    • groupName: <string> اسم مجموعة Diffie-Hellman (DH). انظر crypto.getDiffieHellman().
    • paramEncoding: <string> يجب أن يكون 'named' أو 'explicit' (EC). الافتراضي: 'named'.
    • publicKeyEncoding: <Object> انظر keyObject.export().
    • privateKeyEncoding: <Object> انظر keyObject.export().

  • قيمة مُعادة: <Object>

يُنشئ زوج مفاتيح غير متماثل جديد من النوع المُعطى type. يتم دعم RSA و RSA-PSS و DSA و EC و Ed25519 و Ed448 و X25519 و X448 و DH حاليًا.

إذا تم تحديد publicKeyEncoding أو privateKeyEncoding، فإن هذه الوظيفة تتصرف كما لو تم استدعاء keyObject.export() على نتيجتها. خلاف ذلك، يتم إرجاع الجزء المُناسب من المفتاح كـ KeyObject.

عند ترميز المفاتيح العامة، يُوصى باستخدام 'spki'. عند ترميز المفاتيح الخاصة، يُوصى باستخدام 'pkcs8' مع عبارة مرور قوية، والحفاظ على سرية عبارة المرور.

js
const { generateKeyPairSync } = await import('node:crypto')

const { publicKey, privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
})
js
const { generateKeyPairSync } = require('node:crypto')

const { publicKey, privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
})

تمثل القيمة المُعادة { publicKey, privateKey } زوج المفاتيح المُنشأ. عندما يتم تحديد ترميز PEM، سيكون المفتاح المُناسب سلسلة، خلاف ذلك سيكون بايت يحتوي على البيانات المُرمّزة كـ DER.

crypto.generateKeySync(type, options) ​

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

  • type: <string> الغرض المقصود من مفتاح السر المُولّد. القيم المقبولة حاليًا هي 'hmac' و 'aes'.

  • options: <Object>

    • length: <number> طول المفتاح المُولّد بالبت.
    • إذا كان type هو 'hmac', الحد الأدنى هو 8، والحد الأقصى هو 2-1. إذا لم تكن القيمة مضاعفًا لـ 8، فسيتم اقتطاع المفتاح المُولّد إلى Math.floor(length / 8).
    • إذا كان type هو 'aes', يجب أن يكون الطول أحد القيم التالية: 128, 192, أو 256.

  • القيمة المُرجعه: <KeyObject>

يُولّد بشكل متزامن مفتاح سرّ عشوائيًا جديدًا من الطول المُعطى. سيحدد type عمليات التحقق التي سيتم تنفيذها على length.

js
const { generateKeySync } = await import('node:crypto')

const key = generateKeySync('hmac', { length: 512 })
console.log(key.export().toString('hex')) // e89..........41e
js
const { generateKeySync } = require('node:crypto')

const key = generateKeySync('hmac', { length: 512 })
console.log(key.export().toString('hex')) // e89..........41e

يجب ألا يتجاوز حجم مفتاح HMAC المُولّد حجم كتلة دالة التجزئة الأساسية. راجع crypto.createHmac() لمزيد من المعلومات.

crypto.generatePrime(size[, options[, callback]]) ​

[History]

الإصدارالتغييرات
v18.0.0يؤدي تمرير مُستدعى غير صالح إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.8.0تم الإضافة في: v15.8.0

يُولّد عددًا أوليًا شبه عشوائيًا من size بت.

إذا كان options.safe هو true, فسيكون العدد الأولي عددًا أوليًا آمنًا - أي أن (prime - 1) / 2 سيكون أيضًا عددًا أوليًا.

يمكن استخدام معلمات options.add و options.rem لفرض متطلبات إضافية، مثلًا، لـ Diffie-Hellman:

  • إذا تم تعيين كل من options.add و options.rem, فسيلبي العدد الأولي الشرط الذي ينص على أن prime % add = rem.
  • إذا تم تعيين options.add فقط ولم يكن options.safe هو true, فسيلبي العدد الأولي الشرط الذي ينص على أن prime % add = 1.
  • إذا تم تعيين options.add فقط وتم تعيين options.safe على true, فسيلبي العدد الأولي بدلاً من ذلك الشرط الذي ينص على أن prime % add = 3. هذا ضروري لأن prime % add = 1 لـ options.add \> 2 سيتناقض مع الشرط الذي يفرضه options.safe.
  • يتم تجاهل options.rem إذا لم يتم إعطاء options.add.

يجب ترميز كل من options.add و options.rem كمتواليات كبيرة النهاية إذا تم إعطاؤها كـ ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer, أو DataView.

بشكل افتراضي، يتم ترميز العدد الأولي كمتسلسلة كبيرة النهاية من البايتات في <ArrayBuffer>. إذا كان خيار bigint هو true, فسيتم توفير <bigint>.

crypto.generatePrimeSync(size[, options]) ​

مضاف في: v15.8.0

يُولّد عددًا أوليًا شبه عشوائيًا بحجم size بتات.

إذا كانت قيمة options.safe هي true، فسيكون العدد الأولي عددًا أوليًا آمنًا - أي أن (prime - 1) / 2 سيكون أيضًا عددًا أوليًا.

يمكن استخدام параметران options.add و options.rem لفرض متطلبات إضافية، مثلًا، لـ Diffie-Hellman:

  • إذا تم تعيين كلاً من options.add و options.rem، فسيلبي العدد الأولي الشرط الذي ينص على أن prime % add = rem.
  • إذا تم تعيين options.add فقط ولم تكن options.safe هي true، فسيلبي العدد الأولي الشرط الذي ينص على أن prime % add = 1.
  • إذا تم تعيين options.add فقط وتم تعيين options.safe على true، فسيلبي العدد الأولي بدلاً من ذلك الشرط الذي ينص على أن prime % add = 3. هذا ضروري لأن prime % add = 1 لـ options.add \> 2 سيتعارض مع الشرط الذي تفرضه options.safe.
  • يتم تجاهل options.rem إذا لم يتم إعطاء options.add.

يجب ترميز كل من options.add و options.rem كمتواليات كبيرة النهاية إذا تم إعطاؤها كـ ArrayBuffer أو SharedArrayBuffer أو TypedArray أو Buffer أو DataView.

بشكل افتراضي، يتم ترميز العدد الأولي كمتتابعة كبيرة النهاية من البايتات في <ArrayBuffer>. إذا كانت خيار bigint هو true، فسيتم توفير <bigint>.

crypto.getCipherInfo(nameOrNid[, options]) ​

مضاف في: v15.0.0

  • nameOrNid: <string> | <number> اسم أو معرف الشفرة المراد استعلامه.

  • options: <Object>

    • keyLength: <number> طول مفتاح الاختبار.
    • ivLength: <number> طول متجه البدء للاختبار.

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

    • name <string> اسم الشفرة.
    • nid <number> معرف الشفرة.
    • blockSize <number> حجم كتلة الشفرة بالبايت. يتم حذف هذه الخاصية عندما يكون mode هو 'stream'.
    • ivLength <number> طول متجه البدء المتوقع أو الافتراضي بالبايت. يتم حذف هذه الخاصية إذا لم تستخدم الشفرة متجه بدء.
    • keyLength <number> طول المفتاح المتوقع أو الافتراضي بالبايت.
    • mode <string> وضع الشفرة. أحد الخيارات التالية: 'cbc', 'ccm', 'cfb', 'ctr', 'ecb', 'gcm', 'ocb', 'ofb', 'stream', 'wrap', 'xts'.

ترجع معلومات حول شفرة معينة.

تقبل بعض الشفرات مفاتيح ومتجهات بدء بأطوال متغيرة. بشكل افتراضي، ستعيد طريقة crypto.getCipherInfo() القيم الافتراضية لهذه الشفرات. لاختبار ما إذا كان طول مفتاح أو طول متجه بدء معين مقبولًا لشفرة معينة، استخدم خيارات keyLength و ivLength. إذا كانت القيم المعطاة غير مقبولة، فسيتم إرجاع undefined.

crypto.getCiphers() ​

أضيف في: v0.9.3

  • الإرجاع: <string[]> مصفوفة تحتوي على أسماء خوارزميات التشفير المدعومة.
js
const { getCiphers } = await import('node:crypto')

console.log(getCiphers()) // ['aes-128-cbc', 'aes-128-ccm', ...]
js
const { getCiphers } = require('node:crypto')

console.log(getCiphers()) // ['aes-128-cbc', 'aes-128-ccm', ...]

crypto.getCurves() ​

أضيف في: v2.3.0

  • الإرجاع: <string[]> مصفوفة تحتوي على أسماء المنحنيات الإهليلجية المدعومة.
js
const { getCurves } = await import('node:crypto')

console.log(getCurves()) // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]
js
const { getCurves } = require('node:crypto')

console.log(getCurves()) // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]

crypto.getDiffieHellman(groupName) ​

أضيف في: v0.7.5

يُنشئ كائن تبادل مفاتيح DiffieHellmanGroup مُعرّف مسبقًا. تُدرج المجموعات المدعومة في وثائق DiffieHellmanGroup.

يُحاكي الكائن المُرجَع واجهة الكائنات المُنشأة بواسطة crypto.createDiffieHellman()، لكنه لن يسمح بتغيير المفاتيح (باستخدام diffieHellman.setPublicKey()، على سبيل المثال). تكمن ميزة استخدام هذه الطريقة في أن الأطراف لا تضطر إلى إنشاء أو تبادل مُعامل المجموعة مسبقًا، مما يُوفر وقت المعالج والاتصال.

مثال (الحصول على سر مشترك):

js
const { getDiffieHellman } = await import('node:crypto')
const alice = getDiffieHellman('modp14')
const bob = getDiffieHellman('modp14')

alice.generateKeys()
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

/* يجب أن يكون aliceSecret و bobSecret متطابقين */
console.log(aliceSecret === bobSecret)
js
const { getDiffieHellman } = require('node:crypto')

const alice = getDiffieHellman('modp14')
const bob = getDiffieHellman('modp14')

alice.generateKeys()
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

/* يجب أن يكون aliceSecret و bobSecret متطابقين */
console.log(aliceSecret === bobSecret)

crypto.getFips() ​

مضاف في: v10.0.0

  • الإرجاع: <number> 1 إذا وفقط إذا كان موفر تشفير متوافق مع FIPS قيد الاستخدام حاليًا، 0 بخلاف ذلك. قد يُغيّر إصدار رئيسي من semver في المستقبل نوع الإرجاع لهذا الـ API إلى <boolean>.

crypto.getHashes() ​

مضاف في: v0.9.3

  • الإرجاع: <string[]> مصفوفة من أسماء خوارزميات التجزئة المدعومة، مثل 'RSA-SHA256'. تُسمى خوارزميات التجزئة أيضًا خوارزميات "الهضم".
js
const { getHashes } = await import('node:crypto')

console.log(getHashes()) // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]
js
const { getHashes } = require('node:crypto')

console.log(getHashes()) // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]

crypto.getRandomValues(typedArray) ​

مضاف في: v17.4.0

اسم مستعار مناسب لـ crypto.webcrypto.getRandomValues(). هذا التنفيذ غير متوافق مع مواصفات Web Crypto، لكتابة رمز متوافق مع الويب استخدم crypto.webcrypto.getRandomValues() بدلاً من ذلك.

crypto.hash(algorithm, data[, outputEncoding]) ​

مضاف في: v21.7.0، v20.12.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.2 - مرشح للإصدار

  • algorithm <string> | <undefined>
  • data <string> | <Buffer> | <TypedArray> | <DataView> عندما يكون data سلسلة نصية، فسيتم ترميزها بتنسيق UTF-8 قبل معالجتها. إذا رغبت في استخدام ترميز إدخال مختلف لسلسلة إدخال، فيمكن للمستخدم ترميز السلسلة إلى TypedArray باستخدام TextEncoder أو Buffer.from()، و تمرير TypedArray المُرمّز إلى هذا الواجهة البرمجية بدلاً من ذلك.
  • outputEncoding <string> | <undefined> الترميز المستخدم لترميز الملخص المُرجع. الافتراضي: 'hex'.
  • الإرجاع: <string> | <Buffer>

أداة مساعدة لإنشاء ملخصات هاش لمرة واحدة للبيانات. يمكن أن تكون أسرع من crypto.createHash() القائم على الكائنات عند معالجة كمية صغيرة من البيانات (<= 5 ميجابايت) المتوفرة بسهولة. إذا كانت البيانات كبيرة أو تم بثها، فمن المستحسن استخدام crypto.createHash() بدلاً من ذلك.

يعتمد algorithm على الخوارزميات المتاحة التي تدعمها إصدار OpenSSL على النظام الأساسي. أمثلة: 'sha256', 'sha512', إلخ. في الإصدارات الحديثة من OpenSSL، سيعرض openssl list -digest-algorithms خوارزميات التجزئة المتاحة.

مثال:

js
const crypto = require('node:crypto')
const { Buffer } = require('node:buffer')

// معالجة سلسلة نصية وإرجاع النتيجة كسلسلة مشفرة بتنسيق hex.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// ترميز سلسلة مشفرة بتنسيق base64 إلى Buffer، ومعالجتها وإرجاع
// النتيجة كـ buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))
js
import crypto from 'node:crypto'
import { Buffer } from 'node:buffer'

// معالجة سلسلة نصية وإرجاع النتيجة كسلسلة مشفرة بتنسيق hex.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// ترميز سلسلة مشفرة بتنسيق base64 إلى Buffer، ومعالجتها وإرجاع
// النتيجة كـ buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))

crypto.hkdf(digest, ikm, salt, info, keylen, callback) ​

[History]

الإصدارالتغييرات
v18.0.0يُلقي تمرير مُدعَى استدعاء غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v18.8.0، v16.18.0يمكن الآن أن تكون مادة التشفير المدخلة بطول صفري.
v15.0.0تمت الإضافة في: v15.0.0
  • digest <string> خوارزمية التجزئة المُراد استخدامها.
  • ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> مادة التشفير المدخلة. يجب توفيرها لكن يمكن أن يكون طولها صفري.
  • salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> قيمة الملح. يجب توفيرها لكن يمكن أن يكون طولها صفري.
  • info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> قيمة معلومات إضافية. يجب توفيرها لكن يمكن أن يكون طولها صفري، ولا يمكن أن يتجاوز 1024 بايت.
  • keylen <number> طول المفتاح المراد توليده. يجب أن يكون أكبر من 0. الحد الأقصى للقيمة المسموح بها هو 255 مضروبًا في عدد البايتات التي تنتجها دالة التجزئة المُختارة (على سبيل المثال، sha512 تُولّد تجزئات 64 بايت، مما يجعل الحد الأقصى لإخراج HKDF 16320 بايت).
  • callback <Function>

HKDF هي دالة اشتقاق مفتاح بسيطة مُعرّفة في RFC 5869. يتم استخدام ikm وsalt وinfo المُعطاة مع digest لاشتقاق مفتاح بطول keylen بايت.

يتم استدعاء دالة callback المُقدّمة مع وسيطين: err وderivedKey. إذا حدث خطأ أثناء اشتقاق المفتاح، فسيتم تعيين err؛ خلاف ذلك، سيكون err هو null. سيتم تمرير derivedKey المُولّد بنجاح إلى المُدعَى كـ <ArrayBuffer>. سيتم إلقاء خطأ إذا حددت أي من وسيطات الإدخال قيمًا أو أنواعًا غير صالحة.

js
import { Buffer } from 'node:buffer'
const { hkdf } = await import('node:crypto')

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
})
js
const { hkdf } = require('node:crypto')
const { Buffer } = require('node:buffer')

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
})

crypto.hkdfSync(digest, ikm, salt, info, keylen) ​

[History]

الإصدارالتغييرات
v18.8.0, v16.18.0يمكن الآن أن تكون مادة التشفير المدخلة بطول صفري.
v15.0.0تمت الإضافة في: v15.0.0
  • digest <string> خوارزمية التجزئة لاستخدامها.
  • ikm <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> | <KeyObject> مادة التشفير المدخلة. يجب تقديمها ولكن يمكن أن تكون بطول صفري.
  • salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> قيمة الملح. يجب تقديمها ولكن يمكن أن تكون بطول صفري.
  • info <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> قيمة معلومات إضافية. يجب تقديمها ولكن يمكن أن تكون بطول صفري، ولا يمكن أن تتجاوز 1024 بايت.
  • keylen <number> طول المفتاح المراد توليده. يجب أن يكون أكبر من 0. الحد الأقصى للقيمة المسموح بها هو 255 مضروبًا في عدد البايتات الناتجة عن دالة التجزئة المحددة (على سبيل المثال، sha512 تولد هاشات 64 بايت، مما يجعل الحد الأقصى لإخراج HKDF 16320 بايت).
  • القيمة المُرجعة: <ArrayBuffer>

توفر دالة اشتقاق مفتاح HKDF متزامنة كما هو محدد في RFC 5869. يتم استخدام ikm و salt و info المُعطاة مع digest لاشتقاق مفتاح من keylen بايت.

سيتم إرجاع derivedKey المُولَّد بنجاح كـ <ArrayBuffer>.

سيتم طرح خطأ إذا حددت أي من وسيطات الإدخال قيمًا أو أنواعًا غير صالحة، أو إذا تعذر توليد المفتاح المُشتق.

js
import { Buffer } from 'node:buffer'
const { hkdfSync } = await import('node:crypto')

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64)
console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
js
const { hkdfSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64)
console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'

crypto.pbkdf2(password, salt, iterations, keylen, digest, callback) ​

[السجل]

الإصدارالتغييرات
v18.0.0يُلقي تمرير مُستدعي غير صالح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.0.0يمكن أن تكون وسيطات كلمة المرور والملح أيضًا مثيلات من ArrayBuffer.
v14.0.0أصبحت وسيطة iterations مقصورة الآن على القيم الموجبة. تعاملت الإصدارات السابقة مع القيم الأخرى على أنها واحد.
v8.0.0أصبحت وسيطة digest مطلوبة دائمًا الآن.
v6.0.0أصبح استدعاء هذه الوظيفة بدون تمرير وسيطة digest قديمًا الآن وسوف يصدر تحذيرًا.
v6.0.0تغيرت ترميز الإفتراضي لـ password إذا كانت سلسلة من binary إلى utf8.
v0.5.5تمت الإضافة في: v0.5.5

يوفر تنفيذًا غير متزامن لوظيفة اشتقاق مفتاح تعتمد على كلمة المرور 2 (PBKDF2). يتم تطبيق خوارزمية هضم HMAC المحددة بواسطة digest لاشتقاق مفتاح من الطول المطلوب بالبايت (keylen) من password, salt و iterations.

يتم استدعاء دالة callback المزودة مع حُجتين: err و derivedKey. إذا حدث خطأ أثناء اشتقاق المفتاح، فسيتم تعيين err؛ خلاف ذلك، سيكون err هو null. بشكل افتراضي، سيتم تمرير derivedKey المُولّد بنجاح إلى المُستدعي كـ Buffer. سيتم إلقاء خطأ إذا حددت أي من حُجج الإدخال قيمًا أو أنواعًا غير صالحة.

يجب أن تكون وسيطة iterations رقمًا مُعيّنًا بأعلى قيمة ممكنة. كلما زاد عدد التكرارات، زاد أمان المفتاح المُشتق، لكن سيستغرق الأمر وقتًا أطول لإكماله.

يجب أن يكون salt فريدًا قدر الإمكان. يُنصح بأن يكون الملح عشوائيًا وطوله 16 بايت على الأقل. راجع NIST SP 800-132 لمزيد من التفاصيل.

عند تمرير سلاسل لـ password أو salt، يُرجى مراعاة التحذيرات عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات المشفرة.

js
const { pbkdf2 } = await import('node:crypto')

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
js
const { pbkdf2 } = require('node:crypto')

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})

يمكن استرداد مجموعة من وظائف الهضم المدعومة باستخدام crypto.getHashes().

يستخدم هذا البرنامج النصي مجموعة مؤشرات ترابط libuv، والتي قد يكون لها آثار سلبية مفاجئة على أداء بعض التطبيقات؛ راجع وثائق UV_THREADPOOL_SIZE لمزيد من المعلومات.

crypto.pbkdf2Sync(password, salt, iterations, keylen, digest) ​

[History]

الإصدارالتغييرات
v14.0.0أصبحت معلمة iterations مقيدة الآن بالقيم الموجبة. كانت الإصدارات السابقة تعامل القيم الأخرى على أنها واحد.
v6.0.0أصبح استدعاء هذه الدالة بدون تمرير معلمة digest قديمًا الآن وسوف يصدر تحذيرًا.
v6.0.0تغيرت ترميز الإفتراضي لـ password إذا كانت سلسلة من binary إلى utf8.
v0.9.3تمت الإضافة في: v0.9.3

يوفر تنفيذًا متزامنًا لـدالة اشتقاق مفتاح تعتمد على كلمة مرور 2 (PBKDF2). يتم تطبيق خوارزمية هضم HMAC المحددة بواسطة digest لاشتقاق مفتاح بطول بايت المطلوب (keylen) من password و salt و iterations.

إذا حدث خطأ، فسيتم طرح Error، وإلا سيتم إرجاع المفتاح المشتق كـ Buffer.

يجب أن تكون وسيطة iterations رقمًا مُعيّنًا بأعلى قيمة ممكنة. كلما زاد عدد التكرارات، زاد أمان المفتاح المشتق، لكن سيستغرق الأمر وقتًا أطول لإكماله.

يجب أن يكون salt فريدًا قدر الإمكان. يُنصح بأن يكون الملح عشوائيًا وطوله 16 بايت على الأقل. راجع NIST SP 800-132 للحصول على التفاصيل.

عند تمرير سلاسل لـ password أو salt، يرجى مراعاة التحذيرات عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات المشفرة.

js
const { pbkdf2Sync } = await import('node:crypto')

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512')
console.log(key.toString('hex')) // '3745e48...08d59ae'
js
const { pbkdf2Sync } = require('node:crypto')

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512')
console.log(key.toString('hex')) // '3745e48...08d59ae'

يمكن استرجاع مجموعة من دوال الهضم المدعومة باستخدام crypto.getHashes().

crypto.privateDecrypt(privateKey, buffer) ​

[History]

الإصدارالتغييرات
v21.6.2، v20.11.1، v18.19.1تم تعطيل حشو RSA_PKCS1_PADDING ما لم يدعم بنية OpenSSL الرفض الضمني.
v15.0.0تمت إضافة السلسلة، وArrayBuffer، وCryptoKey كأنواع مفاتيح مسموح بها. يمكن أن يكون oaepLabel عبارة عن ArrayBuffer. يمكن أن يكون المخزن المؤقت سلسلة أو ArrayBuffer. تقتصر جميع الأنواع التي تقبل المخازن المؤقتة على حد أقصى قدره 2 ** 31 - 1 بايت.
v12.11.0تمت إضافة خيار oaepLabel.
v12.9.0تمت إضافة خيار oaepHash.
v11.6.0تدعم هذه الوظيفة الآن كائنات المفاتيح.
v0.11.14تمت الإضافة في: v0.11.14

يقوم بفك تشفير buffer باستخدام privateKey. تم تشفير buffer مسبقًا باستخدام المفتاح العام المقابل، على سبيل المثال باستخدام crypto.publicEncrypt().

إذا لم يكن privateKey عبارة عن KeyObject، فإن هذه الوظيفة تتصرف كما لو تم تمرير privateKey إلى crypto.createPrivateKey(). إذا كان كائنًا، فيمكن تمرير خاصية padding. خلاف ذلك، تستخدم هذه الوظيفة RSA_PKCS1_OAEP_PADDING.

يتطلب استخدام crypto.constants.RSA_PKCS1_PADDING في crypto.privateDecrypt() أن يدعم OpenSSL الرفض الضمني (rsa_pkcs1_implicit_rejection). إذا لم يدعم إصدار OpenSSL الذي تستخدمه Node.js هذه الميزة، فستفشل محاولة استخدام RSA_PKCS1_PADDING.

crypto.privateEncrypt(privateKey, buffer) ​

[السجل]

الإصدارالتغييرات
v15.0.0تمت إضافة سلسلة، ArrayBuffer، وCryptoKey كأنواع مفاتيح مسموح بها. يمكن أن تكون عبارة المرور ArrayBuffer. يمكن أن تكون المخزن المؤقت سلسلة أو ArrayBuffer. جميع الأنواع التي تقبل المخازن المؤقتة محدودة بحد أقصى 2 ** 31 - 1 بايت.
v11.6.0تدعم هذه الوظيفة الآن كائنات المفاتيح.
1.1.0تمت الإضافة في: v1.1.0

يشفر buffer باستخدام privateKey. يمكن فك تشفير البيانات المُرجعة باستخدام المفتاح العام المقابل، على سبيل المثال باستخدام crypto.publicDecrypt().

إذا لم يكن privateKey KeyObject، فإن هذه الوظيفة تتصرف كما لو تم تمرير privateKey إلى crypto.createPrivateKey(). إذا كان كائنًا، فيمكن تمرير خاصية padding. خلاف ذلك، تستخدم هذه الوظيفة RSA_PKCS1_PADDING.

crypto.publicDecrypt(key, buffer) ​

[السجل]

الإصدارالتغييرات
v15.0.0تمت إضافة سلسلة، وArrayBuffer، وCryptoKey كأنواع مفاتيح مسموح بها. يمكن أن تكون عبارة المرور ArrayBuffer. يمكن أن تكون العازلة سلسلة أو ArrayBuffer. جميع الأنواع التي تقبل العوازل محدودة بحد أقصى 2 ** 31 - 1 بايت.
v11.6.0تدعم هذه الوظيفة الآن كائنات المفاتيح.
1.1.0تمت الإضافة في: v1.1.0

يقوم بفك تشفير buffer باستخدام key. تم تشفير buffer مسبقًا باستخدام المفتاح الخاص المقابل، على سبيل المثال باستخدام crypto.privateEncrypt().

إذا لم يكن key هو KeyObject، فإن هذه الوظيفة تتصرف كما لو تم تمرير key إلى crypto.createPublicKey(). إذا كان كائنًا، فيمكن تمرير خاصية padding. خلاف ذلك، تستخدم هذه الوظيفة RSA_PKCS1_PADDING.

بما أن مفاتيح RSA العامة يمكن اشتقاقها من مفاتيح خاصة، يمكن تمرير مفتاح خاص بدلاً من مفتاح عام.

crypto.publicEncrypt(key, buffer) ​

[السجل]

الإصدارالتغييرات
v15.0.0تمت إضافة سلسلة، وArrayBuffer، وCryptoKey كأنواع مفاتيح مسموح بها. يمكن أن يكون oaepLabel وكلمة المرور ArrayBuffers. يمكن أن تكون العازلة سلسلة أو ArrayBuffer. جميع الأنواع التي تقبل العوازل محدودة بحد أقصى 2 ** 31 - 1 بايت.
v12.11.0تمت إضافة خيار oaepLabel.
v12.9.0تمت إضافة خيار oaepHash.
v11.6.0تدعم هذه الدالة الآن كائنات المفاتيح.
v0.11.14تمت الإضافة في: v0.11.14

يشفر محتوى buffer باستخدام key ويعيد Buffer جديدًا Buffer يحتوي على المحتوى المشفر. يمكن فك تشفير البيانات المُرجعة باستخدام المفتاح الخاص المقابل، على سبيل المثال باستخدام crypto.privateDecrypt().

إذا لم يكن key KeyObject، فإن هذه الدالة تتصرف كما لو تم تمرير key إلى crypto.createPublicKey(). إذا كان كائنًا، فيمكن تمرير خاصية padding. خلاف ذلك، تستخدم هذه الدالة RSA_PKCS1_OAEP_PADDING.

بما أن مفاتيح RSA العامة يمكن اشتقاقها من المفاتيح الخاصة، فيمكن تمرير مفتاح خاص بدلاً من مفتاح عام.

crypto.randomBytes(size[, callback]) ​

[History]

الإصدارالتغييرات
v18.0.0تمرير مُدخل مُعطّل إلى وسيطة callback يُطرح الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v9.0.0تمرير null كوسيط لـ callback يُطرح الآن ERR_INVALID_CALLBACK.
v0.5.8تمت الإضافة في: v0.5.8

  • size <number> عدد البايتات التي سيتم توليدها. يجب ألا يكون حجم size أكبر من 2**31 - 1.

  • callback <Function>

  • قيمة مُعادة: <Buffer> إذا لم يتم توفير دالة callback.

يُولّد بيانات عشوائية زائفة قوية مشفرة. وسيطة size هي رقم يُشير إلى عدد البايتات التي سيتم توليدها.

إذا تم توفير دالة callback، فسيتم توليد البايتات بشكل غير متزامن ويتم استدعاء دالة callback مع وسيطين: err و buf. إذا حدث خطأ، فسيكون err كائن Error؛ وإلا فهو null. وسيطة buf هي Buffer تحتوي على البايتات المُولدة.

js
// غير متزامن
const { randomBytes } = await import('node:crypto')

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`)
})
js
// غير متزامن
const { randomBytes } = require('node:crypto')

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`)
})

إذا لم يتم توفير دالة callback، فسيتم توليد البايتات العشوائية بشكل متزامن ويتم إرجاعها كـ Buffer. سيتم طرح خطأ إذا كانت هناك مشكلة في توليد البايتات.

js
// متزامن
const { randomBytes } = await import('node:crypto')

const buf = randomBytes(256)
console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`)
js
// متزامن
const { randomBytes } = require('node:crypto')

const buf = randomBytes(256)
console.log(`${buf.length} bytes of random data: ${buf.toString('hex')}`)

لن تكتمل طريقة crypto.randomBytes() حتى يتوفر قدر كافٍ من الإنتروبيا. وهذا عادةً ما لا يستغرق وقتًا أطول من بضع ميلي ثوانٍ. الوقت الوحيد الذي قد يُحتمل أن يُعيق فيه توليد البايتات العشوائية لفترة أطول هو مباشرة بعد التشغيل، عندما يكون النظام بأكمله منخفض الإنتروبيا.

يستخدم هذا API مجموعة مؤشرات ترابط libuv، والتي قد يكون لها آثار سلبية ومفاجئة على أداء بعض التطبيقات؛ راجع وثائق UV_THREADPOOL_SIZE لمزيد من المعلومات.

يتم تنفيذ الإصدار غير المتزامن من crypto.randomBytes() في طلب مجموعة مؤشرات ترابط واحد. لتقليل تباين طول مهمة مجموعة مؤشرات الترابط، قسّم طلبات randomBytes الكبيرة عند القيام بذلك كجزء من تلبية طلب عميل.

crypto.randomFill(buffer[, offset][, size], callback) ​

[History]

الإصدارالتغييرات
v18.0.0تمرير مُعاودة اتصال غير صالحة إلى وسيطة callback يُلقِي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v9.0.0وسيطة buffer قد تكون أي TypedArray أو DataView.
v7.10.0, v6.13.0تمت الإضافة في: v7.10.0, v6.13.0
  • buffer <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView> يجب توفيره. يجب ألا يكون حجم buffer المُقدّم أكبر من 2**31 - 1.
  • offset <number> افتراضيًا: 0
  • size <number> افتراضيًا: buffer.length - offset. يجب ألا يكون حجم size أكبر من 2**31 - 1.
  • callback <Function> function(err, buf) {}.

هذه الدالة مشابهة لـ crypto.randomBytes() ولكنها تتطلب أن تكون الوسيطة الأولى عبارة عن Buffer سيتم تعبئتها. كما تتطلب تمرير مُعاودة اتصال.

إذا لم يتم توفير دالة callback، فسيتم إلقاء خطأ.

js
import { Buffer } from 'node:buffer'
const { randomFill } = await import('node:crypto')

const buf = Buffer.alloc(10)
randomFill(buf, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

randomFill(buf, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

// ما سبق يعادل ما يلي:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})
js
const { randomFill } = require('node:crypto')
const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(10)
randomFill(buf, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

randomFill(buf, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

// ما سبق يعادل ما يلي:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

يمكن تمرير أي مثيل من ArrayBuffer، أو TypedArray، أو DataView كـ buffer.

في حين أن هذا يشمل مثيلات Float32Array و Float64Array، لا يجب استخدام هذه الدالة لإنشاء أعداد عشوائية ذات فاصلة عائمة. قد تحتوي النتيجة على +Infinity، -Infinity، و NaN، وحتى إذا كانت المصفوفة تحتوي على أعداد منتهية فقط، فلن يتم رسمها من توزيع عشوائي موحد وليس لها حدود دنيا أو عليا ذات معنى.

js
import { Buffer } from 'node:buffer'
const { randomFill } = await import('node:crypto')

const a = new Uint32Array(10)
randomFill(a, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const b = new DataView(new ArrayBuffer(10))
randomFill(b, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const c = new ArrayBuffer(10)
randomFill(c, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf).toString('hex'))
})
js
const { randomFill } = require('node:crypto')
const { Buffer } = require('node:buffer')

const a = new Uint32Array(10)
randomFill(a, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const b = new DataView(new ArrayBuffer(10))
randomFill(b, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const c = new ArrayBuffer(10)
randomFill(c, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf).toString('hex'))
})

يستخدم هذا الواجهة البرمجية مجموعة مؤشرات ترابط libuv، والتي قد يكون لها آثار سلبية ومفاجئة على الأداء لبعض التطبيقات؛ راجع وثائق UV_THREADPOOL_SIZE لمزيد من المعلومات.

يتم تنفيذ الإصدار غير المتزامن من crypto.randomFill() في طلب واحد لمجموعة مؤشرات الترابط. لتقليل اختلاف طول مهمة مجموعة مؤشرات الترابط، قسّم طلبات randomFill الكبيرة عند القيام بذلك كجزء من تلبية طلب العميل.

crypto.randomFillSync(buffer[, offset][, size]) ​

[History]

الإصدارالتغييرات
v9.0.0جوز argument buffer أن يكون أي TypedArray أو DataView.
v7.10.0, v6.13.0تمت الإضافة في: v7.10.0, v6.13.0

الإصدار المتزامن من crypto.randomFill().

js
import { Buffer } from 'node:buffer'
const { randomFillSync } = await import('node:crypto')

const buf = Buffer.alloc(10)
console.log(randomFillSync(buf).toString('hex'))

randomFillSync(buf, 5)
console.log(buf.toString('hex'))

// ما سبق يعادل ما يلي:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))
js
const { randomFillSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(10)
console.log(randomFillSync(buf).toString('hex'))

randomFillSync(buf, 5)
console.log(buf.toString('hex'))

// ما سبق يعادل ما يلي:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))

يمكن تمرير أي مثيل من ArrayBuffer أو TypedArray أو DataView كـ buffer.

js
import { Buffer } from 'node:buffer'
const { randomFillSync } = await import('node:crypto')

const a = new Uint32Array(10)
console.log(Buffer.from(randomFillSync(a).buffer, a.byteOffset, a.byteLength).toString('hex'))

const b = new DataView(new ArrayBuffer(10))
console.log(Buffer.from(randomFillSync(b).buffer, b.byteOffset, b.byteLength).toString('hex'))

const c = new ArrayBuffer(10)
console.log(Buffer.from(randomFillSync(c)).toString('hex'))
js
const { randomFillSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const a = new Uint32Array(10)
console.log(Buffer.from(randomFillSync(a).buffer, a.byteOffset, a.byteLength).toString('hex'))

const b = new DataView(new ArrayBuffer(10))
console.log(Buffer.from(randomFillSync(b).buffer, b.byteOffset, b.byteLength).toString('hex'))

const c = new ArrayBuffer(10)
console.log(Buffer.from(randomFillSync(c)).toString('hex'))

crypto.randomInt([min, ]max[, callback]) ​

[History]

الإصدارالتغييرات
v18.0.0يؤدي تمرير مُعالِج مُعطّل إلى وسيطة callback الآن إلى إرسال ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v14.10.0, v12.19.0تمت الإضافة في: v14.10.0, v12.19.0
  • min <integer> بداية النطاق العشوائي (ضمنيًا). افتراضيًا: 0.
  • max <integer> نهاية النطاق العشوائي (مستبعد).
  • callback <Function> function(err, n) {}.

إرجاع عدد صحيح عشوائي n بحيث يكون min \<= n \< max. يتجنب هذا التنفيذ انحياز المُعامل.

يجب أن يكون النطاق (max - min) أقل من 2. يجب أن يكون كل من min و max أعدادًا صحيحة آمنة.

إذا لم يتم توفير دالة callback، فسيتم توليد العدد الصحيح العشوائي بشكل متزامن.

js
// غير متزامن
const { randomInt } = await import('node:crypto')

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`العدد العشوائي المختار من (0، 1، 2): ${n}`)
})
js
// غير متزامن
const { randomInt } = require('node:crypto')

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`العدد العشوائي المختار من (0، 1، 2): ${n}`)
})
js
// متزامن
const { randomInt } = await import('node:crypto')

const n = randomInt(3)
console.log(`العدد العشوائي المختار من (0، 1، 2): ${n}`)
js
// متزامن
const { randomInt } = require('node:crypto')

const n = randomInt(3)
console.log(`العدد العشوائي المختار من (0، 1، 2): ${n}`)
js
// مع وسيطة `min`
const { randomInt } = await import('node:crypto')

const n = randomInt(1, 7)
console.log(`رمي النرد: ${n}`)
js
// مع وسيطة `min`
const { randomInt } = require('node:crypto')

const n = randomInt(1, 7)
console.log(`رمي النرد: ${n}`)

crypto.randomUUID([options]) ​

مضاف في: v15.6.0، v14.17.0

  • options <Object>

    • disableEntropyCache <boolean> بشكل افتراضي، لتحسين الأداء، يقوم Node.js بإنشاء البيانات العشوائية وتخزينها مؤقتًا بما يكفي لإنشاء ما يصل إلى 128 UUID عشوائيًا. لإنشاء UUID بدون استخدام ذاكرة التخزين المؤقت، عيّن disableEntropyCache إلى true. الافتراضي: false.

  • الإرجاع: <string>

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

crypto.scrypt(password, salt, keylen[, options], callback) ​

[السجل]

الإصدارالتغييرات
v18.0.0يؤدي تمرير مُنعطف غير صالح إلى وسيطة callback الآن إلى طرح ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.0.0يمكن أن تكون وسيطات كلمة المرور والملح أيضًا مثيلات ArrayBuffer.
v12.8.0، v10.17.0يمكن أن تكون قيمة maxmem الآن أي عدد صحيح آمن.
v10.9.0تم إضافة أسماء الخيارات cost و blockSize و parallelization.
v10.5.0مضاف في: v10.5.0

  • password <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>

  • salt <string> | <ArrayBuffer> | <Buffer> | <TypedArray> | <DataView>

  • keylen <number>

  • options <Object>

    • cost <number> معلمة تكلفة وحدة المعالجة المركزية/الذاكرة. يجب أن تكون قوة اثنين أكبر من واحد. الافتراضي: 16384.
    • blockSize <number> معلمة حجم الكتلة. الافتراضي: 8.
    • parallelization <number> معلمة التوازي. الافتراضي: 1.
    • N <number> اسم آخر لـ cost. يمكن تحديد واحد فقط من كليهما.
    • r <number> اسم آخر لـ blockSize. يمكن تحديد واحد فقط من كليهما.
    • p <number> اسم آخر لـ parallelization. يمكن تحديد واحد فقط من كليهما.
    • maxmem <number> الحد الأعلى للذاكرة. يكون هناك خطأ عندما (تقريبًا) 128 * N * r \> maxmem. الافتراضي: 32 * 1024 * 1024.

  • callback <Function>

يوفر تطبيقًا غير متزامن لـ scrypt. Scrypt هي دالة اشتقاق مفتاح تعتمد على كلمة المرور مصممة لتكون مكلفة من الناحية الحسابية ومن حيث الذاكرة من أجل جعل هجمات القوة الغاشمة غير مجدية.

يجب أن يكون salt فريدًا قدر الإمكان. يُوصى بأن يكون الملح عشوائيًا وطوله 16 بايت على الأقل. راجع NIST SP 800-132 للحصول على التفاصيل.

عند تمرير سلاسل لـ password أو salt، يرجى مراعاة التحذيرات عند استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات التشفيرية.

يتم استدعاء دالة callback مع وسيطتين: err و derivedKey. err هو كائن استثناء عندما يفشل اشتقاق المفتاح، وإلا فإن err هو null. يتم تمرير derivedKey إلى المُنعطف كـ Buffer.

يتم طرح استثناء عندما تحدد أي من وسيطات الإدخال قيمًا أو أنواعًا غير صالحة.

js
const { scrypt } = await import('node:crypto')

// باستخدام إعدادات المصنع الافتراضية.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// باستخدام معلمة N مخصصة. يجب أن تكون قوة اثنين.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...aa39b34'
})
js
const { scrypt } = require('node:crypto')

// باستخدام إعدادات المصنع الافتراضية.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// باستخدام معلمة N مخصصة. يجب أن تكون قوة اثنين.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...aa39b34'
})

crypto.scryptSync(password, salt, keylen[, options]) ​

[History]

الإصدارالتغييرات
v12.8.0, v10.17.0يمكن الآن أن تكون قيمة maxmem أي عدد صحيح آمن.
v10.9.0تمت إضافة أسماء الخيارات cost و blockSize و parallelization.
v10.5.0تمت الإضافة في: v10.5.0

  • password <string> | <Buffer> | <TypedArray> | <DataView>

  • salt <string> | <Buffer> | <TypedArray> | <DataView>

  • keylen <number>

  • options <Object>

    • cost <number> معلمة تكلفة وحدة المعالجة المركزية/الذاكرة. يجب أن تكون قوة اثنين أكبر من واحد. الافتراضي: 16384.
    • blockSize <number> معلمة حجم الكتلة. الافتراضي: 8.
    • parallelization <number> معلمة التوازي. الافتراضي: 1.
    • N <number> اسم آخر لـ cost. يجوز تحديد واحد فقط من كليهما.
    • r <number> اسم آخر لـ blockSize. يجوز تحديد واحد فقط من كليهما.
    • p <number> اسم آخر لـ parallelization. يجوز تحديد واحد فقط من كليهما.
    • maxmem <number> الحد الأعلى للذاكرة. يكون هناك خطأ عندما (تقريبًا) 128 * N * r \> maxmem. الافتراضي: 32 * 1024 * 1024.

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

يوفر تنفيذًا متزامنًا لـ scrypt. Scrypt هي دالة اشتقاق مفتاح تعتمد على كلمة المرور مصممة لتكون مكلفة من حيث الحساب والذاكرة من أجل جعل هجمات القوة الغاشمة غير مجدية.

يجب أن يكون salt فريدًا قدر الإمكان. يوصى بأن يكون salt عشوائيًا وطوله 16 بايت على الأقل. راجع NIST SP 800-132 للحصول على التفاصيل.

عند تمرير سلاسل نصية لـ password أو salt، يرجى مراعاة التحذيرات عند استخدام السلاسل النصية كمدخلات لواجهات برمجة التطبيقات المشفرة.

يتم طرح استثناء عندما يفشل اشتقاق المفتاح، وإلا يتم إرجاع المفتاح المشتق كـ Buffer.

يتم طرح استثناء عندما تحدد أي من وسيطات الإدخال قيمًا أو أنواعًا غير صالحة.

js
const { scryptSync } = await import('node:crypto')
// باستخدام الإعدادات الافتراضية للمصنع.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// باستخدام معلمة N مخصصة. يجب أن تكون قوة اثنين.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'
js
const { scryptSync } = require('node:crypto')
// باستخدام الإعدادات الافتراضية للمصنع.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// باستخدام معلمة N مخصصة. يجب أن تكون قوة اثنين.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'

crypto.secureHeapUsed() ​

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

  • قيمة الإرجاع: <Object>
    • total <number> الحجم الإجمالي المخصص لكومة الأمان كما هو محدد باستخدام علم سطر الأوامر --secure-heap=n.
    • min <number> الحد الأدنى للتخصيص من كومة الأمان كما هو محدد باستخدام علم سطر الأوامر --secure-heap-min.
    • used <number> العدد الإجمالي للبايتات المخصصة حاليًا من كومة الأمان.
    • utilization <number> النسبة المحسوبة لـ used إلى total من البايتات المخصصة.

crypto.setEngine(engine[, flags]) ​

[السجل]

الإصدارالتغييرات
v22.4.0, v20.16.0دعم المحرك المخصص في OpenSSL 3 قديم.
v0.11.11تم الإضافة في: v0.11.11

تحميل وتعيين engine لبعض أو كل وظائف OpenSSL (يتم اختيارها بواسطة flags). دعم المحركات المخصصة في OpenSSL قديم من OpenSSL 3.

يمكن أن يكون engine إما معرفًا أو مسارًا إلى مكتبة مشاركة المحرك.

تستخدم وسيطة flags الاختيارية ENGINE_METHOD_ALL افتراضيًا. flags عبارة عن حقل بت يأخذ أحد أو مزيج من الأعلام التالية (المُعرّفة في crypto.constants):

  • crypto.constants.ENGINE_METHOD_RSA
  • crypto.constants.ENGINE_METHOD_DSA
  • crypto.constants.ENGINE_METHOD_DH
  • crypto.constants.ENGINE_METHOD_RAND
  • crypto.constants.ENGINE_METHOD_EC
  • crypto.constants.ENGINE_METHOD_CIPHERS
  • crypto.constants.ENGINE_METHOD_DIGESTS
  • crypto.constants.ENGINE_METHOD_PKEY_METHS
  • crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
  • crypto.constants.ENGINE_METHOD_ALL
  • crypto.constants.ENGINE_METHOD_NONE

crypto.setFips(bool) ​

مضاف في: v10.0.0

  • bool <boolean> true لتمكين وضع FIPS.

يُمَكّن موفر التشفير المتوافق مع FIPS في إصدار Node.js المُمكّن لـ FIPS. يُلقِي خطأ إذا لم يكن وضع FIPS متوفراً.

crypto.sign(algorithm, data, key[, callback]) ​

[السجل]

الإصدارالتغييرات
v18.0.0تمرير مُنادٍ غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.12.0تمت إضافة وسيطة مُنادٍ اختيارية.
v13.2.0, v12.16.0تدعم هذه الدالة الآن توقيعات IEEE-P1363 DSA و ECDSA.
v12.0.0مضاف في: v12.0.0

يحسب ويرجع التوقيع لـ data باستخدام المفتاح الخاص والخوارزمية المعطاة. إذا كان algorithm هو null أو undefined، فإن الخوارزمية تعتمد على نوع المفتاح (خاصةً Ed25519 و Ed448).

إذا لم يكن key هو KeyObject، فإن هذه الدالة تتصرف كما لو تم تمرير key إلى crypto.createPrivateKey(). إذا كان كائنًا، فيمكن تمرير الخصائص الإضافية التالية:

  • dsaEncoding <string> بالنسبة إلى DSA و ECDSA، يُحدد هذا الخيار تنسيق التوقيع المُولّد. يمكن أن يكون أحد ما يلي:

    • 'der' (افتراضي): ترميز هيكل توقيع ASN.1 المُشَفّر بـ DER (r, s).
    • 'ieee-p1363': تنسيق التوقيع r || s كما هو مُقترح في IEEE-P1363.

  • padding <integer> قيمة حشو اختيارية لـ RSA، أحد ما يلي:

    • crypto.constants.RSA_PKCS1_PADDING (افتراضي)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

سيستخدم RSA_PKCS1_PSS_PADDING MGF1 مع نفس دالة التجزئة المستخدمة لتوقيع الرسالة كما هو محدد في القسم 3.1 من RFC 4055.

  • saltLength <integer> طول الملح عندما يكون الحشو هو RSA_PKCS1_PSS_PADDING. تُعيّن القيمة الخاصة crypto.constants.RSA_PSS_SALTLEN_DIGEST طول الملح إلى حجم التجزئة، crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (افتراضي) تُعيّنه إلى أقصى قيمة مسموح بها.

إذا تم توفير دالة callback، فإن هذه الدالة تستخدم تجمع خيوط libuv.

crypto.subtle ​

مضاف في: v17.4.0

اسم مستعار مناسب لـ crypto.webcrypto.subtle.

crypto.timingSafeEqual(a, b) ​

[السجل]

الإصدارالتغييرات
v15.0.0يمكن أن تكون الوسيطتان a و b أيضًا ArrayBuffer.
v6.6.0مضاف في: v6.6.0

تقارن هذه الدالة البايتات الأساسية التي تمثل مثيلات ArrayBuffer أو TypedArray أو DataView المُعطاة باستخدام خوارزمية وقت ثابت.

لا تُسرب هذه الدالة معلومات توقيت من شأنها أن تسمح للمهاجم بتخمين إحدى القيم. هذا مناسب لمقارنة ملخصات HMAC أو القيم السرية مثل ملفات تعريف ارتباط المصادقة أو عناوين URL الإمكانات.

يجب أن يكون كل من a و b عبارة عن Buffer أو TypedArray أو DataView، ويجب أن يكون لهما نفس طول البايت. يتم طرح خطأ إذا كان a و b لهما أطوال بايت مختلفة.

إذا كان واحد على الأقل من a و b هو TypedArray مع أكثر من بايت لكل إدخال، مثل Uint16Array، فسيتم حساب النتيجة باستخدام ترتيب بايت النظام الأساسي.

عندما يكون كلا المدخلين عبارة عن Float32Array أو Float64Array، قد تُرجع هذه الدالة نتائج غير متوقعة بسبب ترميز IEEE 754 لأرقام الفاصلة العائمة. على وجه الخصوص، لا يعني x === y ولا Object.is(x, y) أن التمثيلات البايتية لرقمي فاصلة عائمة x و y متساوية.

لا يضمن استخدام crypto.timingSafeEqual أن الكود المحيط آمن من حيث التوقيت. يجب توخي الحذر لضمان عدم إدخال الكود المحيط ثغرات أمنية متعلقة بالتوقيت.

crypto.verify(algorithm, data, key, signature[, callback]) ​

[السجل]

الإصدارالتغييرات
v18.0.0تمرير مُعامل استدعاء غير صالح إلى وسيطة callback يُلقي الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v15.12.0تمت إضافة وسيطة مُعامل الاستدعاء الاختيارية.
v15.0.0يمكن أن تكون وسيطات البيانات والمفتاح والتوقيع أيضًا ArrayBuffer.
v13.2.0، v12.16.0تدعم هذه الوظيفة الآن توقيعات IEEE-P1363 DSA و ECDSA.
v12.0.0تمت الإضافة في: v12.0.0

تتحقق من التوقيع المعطى لـ data باستخدام المفتاح والخوارزمية المعطاة. إذا كان algorithm يساوي null أو undefined، فإن الخوارزمية تعتمد على نوع المفتاح (خاصةً Ed25519 و Ed448).

إذا لم يكن key KeyObject، فإن هذه الوظيفة تتصرف كما لو تم تمرير key إلى crypto.createPublicKey(). إذا كان كائنًا، فيمكن تمرير خصائص إضافية كما يلي:

  • dsaEncoding <سلسلة> بالنسبة إلى DSA و ECDSA، يحدد هذا الخيار تنسيق التوقيع. يمكن أن يكون أحد ما يلي:

    • 'der' (افتراضي): ترميز هيكل توقيع ASN.1 المُشفر بـ DER (r, s).
    • 'ieee-p1363': تنسيق التوقيع r || s كما هو مُقترح في IEEE-P1363.

  • padding <عدد صحيح> قيمة التعبئة الاختيارية لـ RSA، أحد ما يلي:

    • crypto.constants.RSA_PKCS1_PADDING (افتراضي)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

سيستخدم RSA_PKCS1_PSS_PADDING MGF1 مع نفس دالة التجزئة المُستخدمة لتوقيع الرسالة كما هو مُحدد في القسم 3.1 من RFC 4055.

  • saltLength <عدد صحيح> طول الملح عندما يكون التعبئة RSA_PKCS1_PSS_PADDING. تُعيّن القيمة الخاصة crypto.constants.RSA_PSS_SALTLEN_DIGEST طول الملح إلى حجم التجزئة، crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (افتراضي) تُعيّنه إلى أقصى قيمة مُسموح بها.

وسيطة signature هي التوقيع المُحسَب سابقًا لـ data.

بما أن المفاتيح العامة يمكن اشتقاقها من المفاتيح الخاصة، يمكن تمرير مفتاح خاص أو مفتاح عام لـ key.

إذا تم توفير دالة callback، فإن هذه الوظيفة تستخدم تجمع خيوط libuv.

crypto.webcrypto ​

مضاف في: v15.0.0

النوع: <Crypto> تطبيق لمعيار واجهة برمجة التطبيقات Web Crypto.

راجع وثائق واجهة برمجة التطبيقات Web Crypto للحصول على التفاصيل.

ملاحظات ​

استخدام السلاسل كمدخلات لواجهات برمجة التطبيقات المشفرة ​

لأسباب تاريخية، تقبل العديد من واجهات برمجة التطبيقات المشفرة التي تقدمها Node.js السلاسل كمدخلات حيث تعمل الخوارزمية المشفرة الأساسية على تسلسلات البايت. تتضمن هذه الحالات النصوص العادية، ونصوص الشفرات، والمفاتيح المتناظرة، ونواقل البدء، وعبارات المرور، والأملاح، وعلامات المصادقة، والبيانات المصادق عليها إضافيًا.

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

  • ليست كل تسلسلات البايت سلاسل UTF-8 صالحة. لذلك، عندما يتم اشتقاق تسلسل بايت بطول n من سلسلة، فإن إنتروبياها تكون أقل بشكل عام من إنتروبيا تسلسل بايت عشوائي أو زائف عشوائي بطول n. على سبيل المثال، لن تؤدي أي سلسلة UTF-8 إلى تسلسل البايت c0 af. يجب أن تكون المفاتيح السرية في الغالب تسلسلات بايت عشوائية أو زائفة عشوائية.
  • وبالمثل، عند تحويل تسلسلات البايت العشوائية أو الزائفة العشوائية إلى سلاسل UTF-8، قد يتم استبدال التسلسلات الفرعية التي لا تمثل نقاط رمز صالحة بعلامة الاستبدال Unicode (U+FFFD). لذلك، قد لا يكون التمثيل الباييتي لسلسلة Unicode الناتجة مساويًا لتسلسل البايت الذي تم إنشاء السلسلة منه. مخرجات الشفرات، ووظائف التجزئة، وخوارزميات التوقيع، ووظائف اشتقاق المفاتيح هي تسلسلات بايت زائفة عشوائية ويجب عدم استخدامها كسلاسل Unicode.
  • عندما يتم الحصول على السلاسل من إدخال المستخدم، يمكن تمثيل بعض أحرف Unicode بعدة طرق مكافئة تؤدي إلى تسلسلات بايت مختلفة. على سبيل المثال، عند تمرير عبارة مرور المستخدم إلى دالة اشتقاق المفتاح، مثل PBKDF2 أو scrypt، تعتمد نتيجة دالة اشتقاق المفتاح على ما إذا كانت السلسلة تستخدم أحرفًا مركبة أو مفككة. لا تقوم Node.js بتطبيع تمثيلات الأحرف. يجب على المطورين مراعاة استخدام String.prototype.normalize() على مدخلات المستخدم قبل تمريرها إلى واجهات برمجة التطبيقات المشفرة.

واجهة برمجة التطبيقات القديمة للتيارات (قبل Node.js 0.10) ​

تمت إضافة وحدة Crypto إلى Node.js قبل وجود مفهوم واجهة برمجة تطبيقات موحدة للتيارات، وقبل وجود كائنات Buffer للمعالجة البيانات الثنائية. على هذا النحو، تحتوي العديد من فئات crypto على طرق لا توجد عادةً في فئات Node.js الأخرى التي تُنفذ واجهة برمجة التطبيقات streams (مثل update()، final()، أو digest()). أيضًا، قبلت العديد من الطرق وسلّمت سلاسل مُشفّرة بـ'latin1' افتراضيًا بدلاً من كائنات Buffer. تم تغيير هذا الإعداد الافتراضي بعد Node.js v0.8 لاستخدام كائنات Buffer افتراضيًا بدلاً من ذلك.

دعم الخوارزميات الضعيفة أو المُتضرّرة ​

لا تزال وحدة node:crypto تدعم بعض الخوارزميات التي تم اختراقها بالفعل ولا يُنصح باستخدامها. تسمح واجهة برمجة التطبيقات أيضًا باستخدام الشيفرات والهاشات ذات حجم مفتاح صغير جدًا وضعيف جدًا للاستخدام الآمن.

يجب على المستخدمين تحمل المسؤولية الكاملة عن اختيار خوارزمية التشفير وحجم المفتاح وفقًا لمتطلباتهم الأمنية.

بناءً على توصيات NIST SP 800-131A:

  • لم تعد MD5 وSHA-1 مقبولة حيث تكون مقاومة التصادم مطلوبة مثل التوقيعات الرقمية.
  • يُوصى بأن يكون المفتاح المستخدم مع خوارزميات RSA وDSA وDH 2048 بت على الأقل، وأن يكون مفتاح منحنى ECDSA وECDH 224 بت على الأقل، ليكون آمنًا للاستخدام لعدة سنوات.
  • مجموعات DH من modp1 وmodp2 وmodp5 لها حجم مفتاح أصغر من 2048 بت، ولا يُنصح باستخدامها.

راجع المرجع للحصول على توصيات وتفاصيل أخرى.

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

وضع CCM ​

CCM هو أحد خوارزميات AEAD المدعومة. يجب على التطبيقات التي تستخدم هذا الوضع الالتزام ببعض القيود عند استخدام واجهة برمجة التشفير:

  • يجب تحديد طول علامة المصادقة أثناء إنشاء التشفير عن طريق تعيين خيار authTagLength ويجب أن يكون أحد القيم 4، 6، 8، 10، 12، 14 أو 16 بايت.
  • يجب أن يكون طول متجه الإنشاء (الرقم المُستخدم لمرة واحدة) N بين 7 و 13 بايت (7 ≤ N ≤ 13).
  • يقتصر طول النص العادي على 2 ** (8 * (15 - N)) بايت.
  • عند فك التشفير، يجب تعيين علامة المصادقة عبر setAuthTag() قبل استدعاء update(). خلاف ذلك، سيحدث فشل فك التشفير وfinal() سيرمي خطأً وفقًا للقسم 2.6 من RFC 3610.
  • قد يؤدي استخدام طرق التيار مثل write(data)، end(data) أو pipe() في وضع CCM إلى الفشل حيث لا يمكن لـ CCM التعامل مع أكثر من جزء واحد من البيانات لكل مثيل.
  • عند تمرير بيانات مُصادقة إضافية (AAD)، يجب تمرير طول الرسالة الفعلية بالبايت إلى setAAD() عبر خيار plaintextLength. تتضمن العديد من مكتبات التشفير علامة المصادقة في نص التشفير، مما يعني أنها تنتج نصوص تشفير بطول plaintextLength + authTagLength. لا تتضمن Node.js علامة المصادقة، لذلك يكون طول نص التشفير دائمًا plaintextLength. هذا ليس ضروريًا إذا لم يتم استخدام أي AAD.
  • بما أن CCM يعالج الرسالة بأكملها مرة واحدة، يجب استدعاء update() مرة واحدة فقط.
  • على الرغم من أن استدعاء update() كافٍ لتشفير/فك تشفير الرسالة، إلا أن التطبيقات يجب أن تستدعي final() لحساب أو التحقق من علامة المصادقة.
js
import { Buffer } from 'node:buffer'
const { createCipheriv, createDecipheriv, randomBytes } = await import('node:crypto')

const key = 'keykeykeykeykeykeykeykey'
const nonce = randomBytes(12)

const aad = Buffer.from('0123456789', 'hex')

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
const plaintext = 'Hello world'
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
})
const ciphertext = cipher.update(plaintext, 'utf8')
cipher.final()
const tag = cipher.getAuthTag()

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
decipher.setAuthTag(tag)
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
})
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8')

try {
  decipher.final()
} catch (err) {
  throw new Error('Authentication failed!', { cause: err })
}

console.log(receivedPlaintext)
js
const { Buffer } = require('node:buffer')
const { createCipheriv, createDecipheriv, randomBytes } = require('node:crypto')

const key = 'keykeykeykeykeykeykeykey'
const nonce = randomBytes(12)

const aad = Buffer.from('0123456789', 'hex')

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
const plaintext = 'Hello world'
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
})
const ciphertext = cipher.update(plaintext, 'utf8')
cipher.final()
const tag = cipher.getAuthTag()

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
decipher.setAuthTag(tag)
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
})
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8')

try {
  decipher.final()
} catch (err) {
  throw new Error('Authentication failed!', { cause: err })
}

console.log(receivedPlaintext)

وضع FIPS ​

عند استخدام OpenSSL 3، يدعم Node.js معيار FIPS 140-2 عند استخدامه مع مزود OpenSSL 3 مناسب، مثل مزود FIPS من OpenSSL 3 والذي يمكن تثبيته باتباع التعليمات الموجودة في ملف README الخاص بـ FIPS من OpenSSL.

لدعم FIPS في Node.js، ستحتاج إلى:

  • مزود OpenSSL 3 FIPS مثبت بشكل صحيح.
  • ملف تكوين وحدة FIPS OpenSSL 3 ملف تكوين وحدة FIPS.
  • ملف تكوين OpenSSL 3 يشير إلى ملف تكوين وحدة FIPS.

يجب تكوين Node.js باستخدام ملف تكوين OpenSSL يشير إلى مزود FIPS. يبدو مثال ملف التكوين كما يلي:

text
nodejs_conf = nodejs_init

.include /<المسار المطلق>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# يجب أن يتطابق اسم قسم fips مع اسم القسم داخل {#the-fips-section-name-should-match-the-section-name-inside-the}
# الملف المضمن fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

حيث أن fipsmodule.cnf هو ملف تكوين وحدة FIPS الناتج عن خطوة تثبيت مزود FIPS:

bash
openssl fipsinstall

قم بتعيين متغير البيئة OPENSSL_CONF للإشارة إلى ملف التكوين الخاص بك و OPENSSL_MODULES إلى موقع مكتبة FIPS الديناميكية. مثال:

bash
export OPENSSL_CONF=/<مسار ملف التكوين>/nodejs.cnf
export OPENSSL_MODULES=/<مسار مكتبة openssl>/ossl-modules

يمكن بعد ذلك تمكين وضع FIPS في Node.js إما عن طريق:

  • بدء تشغيل Node.js باستخدام علامات سطر الأوامر --enable-fips أو --force-fips.
  • الاتصال برمجياً بـ crypto.setFips(true).

اختياريًا، يمكن تمكين وضع FIPS في Node.js عبر ملف تكوين OpenSSL. مثال:

text
nodejs_conf = nodejs_init

.include /<المسار المطلق>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# يجب أن يتطابق اسم قسم fips مع اسم القسم داخل {#included-fipsmodulecnf}
# الملف المضمن fipsmodule.cnf.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

ثوابت التشفير ​

تنطبق الثوابت التالية التي تم تصديرها بواسطة crypto.constants على استخدامات متنوعة لوحدات node:crypto و node:tls و node:https وهي خاصة بشكل عام بـ OpenSSL.

خيارات OpenSSL ​

راجع قائمة أعلام SSL OP للحصول على التفاصيل.

الثابتالوصف
SSL_OP_ALLيطبق العديد من حلول التصحيح داخل OpenSSL. راجع https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html للحصول على التفاصيل.
SSL_OP_ALLOW_NO_DHE_KEXيُرشد OpenSSL للسماح بنمط تبادل مفاتيح غير قائم على [EC]DHE لـ TLS v1.3
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATIONيسمح بإعادة التفاوض غير الآمنة القديمة بين OpenSSL والعملاء أو الخوادم غير المُحسّنة. راجع https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CIPHER_SERVER_PREFERENCEيحاول استخدام تفضيلات الخادم بدلاً من تفضيلات العميل عند اختيار تشفير. يعتمد السلوك على إصدار البروتوكول. راجع https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CISCO_ANYCONNECTيُرشد OpenSSL لاستخدام معرف إصدار Cisco لـ DTLS_BAD_VER.
SSL_OP_COOKIE_EXCHANGEيُرشد OpenSSL لتشغيل تبادل ملفات تعريف الارتباط.
SSL_OP_CRYPTOPRO_TLSEXT_BUGيُرشد OpenSSL لإضافة امتداد server-hello من إصدار مبكر من مسودة cryptopro.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSيُرشد OpenSSL لتعطيل حلول التصحيح الخاصة بثغرة أمان SSL 3.0/TLS 1.0 المضافة في OpenSSL 0.9.6d.
SSL_OP_LEGACY_SERVER_CONNECTيسمح بالاتصال الأولي بالخوادم التي لا تدعم RI.
SSL_OP_NO_COMPRESSIONيُرشد OpenSSL لتعطيل دعم ضغط SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MACيُرشد OpenSSL لتعطيل تشفير ثم MAC.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATIONيُرشد OpenSSL لتعطيل إعادة التفاوض.
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATIONيُرشد OpenSSL لبدء جلسة جديدة دائمًا عند إجراء إعادة التفاوض.
SSL_OP_NO_SSLv2يُرشد OpenSSL لإيقاف تشغيل SSL v2
SSL_OP_NO_SSLv3يُرشد OpenSSL لإيقاف تشغيل SSL v3
SSL_OP_NO_TICKETيُرشد OpenSSL لتعطيل استخدام تذاكر RFC4507bis.
SSL_OP_NO_TLSv1يُرشد OpenSSL لإيقاف تشغيل TLS v1
SSL_OP_NO_TLSv1_1يُرشد OpenSSL لإيقاف تشغيل TLS v1.1
SSL_OP_NO_TLSv1_2يُرشد OpenSSL لإيقاف تشغيل TLS v1.2
SSL_OP_NO_TLSv1_3يُرشد OpenSSL لإيقاف تشغيل TLS v1.3
SSL_OP_PRIORITIZE_CHACHAيُرشد خادم OpenSSL لإعطاء الأولوية لـ ChaCha20-Poly1305 عندما يقوم العميل بذلك. لا يؤثر هذا الخيار إذا لم يتم تمكين SSL_OP_CIPHER_SERVER_PREFERENCE.
SSL_OP_TLS_ROLLBACK_BUGيُرشد OpenSSL لتعطيل اكتشاف هجوم التراجع عن الإصدار.

ثوابت محرّك OpenSSL ​

الثابتالوصف
ENGINE_METHOD_RSAتحديد استخدام المحرّك على RSA
ENGINE_METHOD_DSAتحديد استخدام المحرّك على DSA
ENGINE_METHOD_DHتحديد استخدام المحرّك على DH
ENGINE_METHOD_RANDتحديد استخدام المحرّك على RAND
ENGINE_METHOD_ECتحديد استخدام المحرّك على EC
ENGINE_METHOD_CIPHERSتحديد استخدام المحرّك على CIPHERS
ENGINE_METHOD_DIGESTSتحديد استخدام المحرّك على DIGESTS
ENGINE_METHOD_PKEY_METHSتحديد استخدام المحرّك على PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHSتحديد استخدام المحرّك على PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

ثوابت OpenSSL أخرى ​

الثابتالوصف
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
RSA_PKCS1_PADDING
RSA_SSLV23_PADDING
RSA_NO_PADDING
RSA_PKCS1_OAEP_PADDING
RSA_X931_PADDING
RSA_PKCS1_PSS_PADDING
RSA_PSS_SALTLEN_DIGESTيحدد طول الملح لـ RSA_PKCS1_PSS_PADDING بحجم الخلاصة عند التوقيع أو التحقق.
RSA_PSS_SALTLEN_MAX_SIGNيحدد طول الملح لـ RSA_PKCS1_PSS_PADDING بالقيمة القصوى المسموح بها عند توقيع البيانات.
RSA_PSS_SALTLEN_AUTOيتسبب في تحديد طول الملح لـ RSA_PKCS1_PSS_PADDING تلقائيًا عند التحقق من صحة التوقيع.
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

ثوابت Node.js المشفرة ​

الثابتالوصف
defaultCoreCipherListيحدد قائمة التشفير الافتراضية المضمنة التي يستخدمها Node.js.
defaultCipherListيحدد قائمة التشفير الافتراضية النشطة التي يستخدمها عملية Node.js الحالية.