Web Crypto API

[역사]

버전	변경 사항
v23.5.0	`Ed25519` 및 `X25519` 알고리즘이 이제 안정되었습니다.
v19.0.0	`Ed25519`, `Ed448`, `X25519`, `X448` 알고리즘을 제외하고 더 이상 실험적이지 않습니다.
v20.0.0, v18.17.0	이제 인수는 다른 Web Crypto API 구현과 마찬가지로 WebIDL 정의에 따라 강제 변환되고 유효성이 검사됩니다.
v18.4.0, v16.17.0	독점적인 `'node.keyObject'` 가져오기/내보내기 형식이 제거되었습니다.
v18.4.0, v16.17.0	독점적인 `'NODE-DSA'`, `'NODE-DH'`, `'NODE-SCRYPT'` 알고리즘이 제거되었습니다.
v18.4.0, v16.17.0	`'Ed25519'`, `'Ed448'`, `'X25519'`, `'X448'` 알고리즘이 추가되었습니다.
v18.4.0, v16.17.0	독점적인 `'NODE-ED25519'` 및 `'NODE-ED448'` 알고리즘이 제거되었습니다.
v18.4.0, v16.17.0	독점적인 `'NODE-X25519'` 및 `'NODE-X448'` 이름 지정된 곡선이 `'ECDH'` 알고리즘에서 제거되었습니다.

[안정: 2 - 안정]

안정: 2 안정성: 2 - 안정

Node.js는 표준 Web Crypto API의 구현을 제공합니다.

이 모듈에 액세스하려면 globalThis.crypto 또는 require('node:crypto').webcrypto를 사용하십시오.

const { subtle } = globalThis.crypto

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

  const enc = new TextEncoder()
  const message = enc.encode('나는 컵케이크를 좋아합니다')

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

예

키 생성

<SubtleCrypto> 클래스를 사용하여 대칭 (비밀) 키 또는 비대칭 키 쌍 (공개 키 및 개인 키)을 생성할 수 있습니다.

AES 키

const { subtle } = globalThis.crypto

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

  return key
}

ECDSA 키 쌍

const { subtle } = globalThis.crypto

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

  return { publicKey, privateKey }
}

Ed25519/X25519 키 쌍

const { subtle } = globalThis.crypto

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

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

HMAC 키

const { subtle } = globalThis.crypto

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

  return key
}

RSA 키 쌍

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

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

  return { publicKey, privateKey }
}

암호화 및 복호화

const crypto = globalThis.crypto

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

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

  return {
    key,
    iv,
    ciphertext,
  }
}

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

  return dec.decode(plaintext)
}

키 내보내기 및 가져오기

const { subtle } = globalThis.crypto

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

  return subtle.exportKey(format, key)
}

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

  return key
}

키 래핑 및 래핑 해제

const { subtle } = globalThis.crypto

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

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

  return { wrappedKey, wrappingKey }
}

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

  return key
}

서명 및 확인

const { subtle } = globalThis.crypto

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

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

비트 및 키 파생

const { subtle } = globalThis.crypto

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

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

다이제스트

const { subtle } = globalThis.crypto

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

알고리즘 매트릭스

이 표는 Node.js Web Crypto API 구현에서 지원되는 알고리즘과 각 알고리즘에 대해 지원되는 API를 자세히 설명합니다.

알고리즘	`generateKey`	`exportKey`	`importKey`	`encrypt`	`decrypt`	`wrapKey`	`unwrapKey`	`deriveBits`	`deriveKey`	`sign`	`verify`	`digest`
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔							✔	✔
`'RSA-PSS'`	✔	✔	✔							✔	✔
`'RSA-OAEP'`	✔	✔	✔	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔							✔	✔
`'Ed25519'`	✔	✔	✔							✔	✔
`'Ed448'`	✔	✔	✔							✔	✔
`'ECDH'`	✔	✔	✔					✔	✔
`'X25519'`	✔	✔	✔					✔	✔
`'X448'`	✔	✔	✔					✔	✔
`'AES-CTR'`	✔	✔	✔	✔	✔	✔	✔
`'AES-CBC'`	✔	✔	✔	✔	✔	✔	✔
`'AES-GCM'`	✔	✔	✔	✔	✔	✔	✔
`'AES-KW'`	✔	✔	✔			✔	✔
`'HMAC'`	✔	✔	✔							✔	✔
`'HKDF'`		✔	✔					✔	✔
`'PBKDF2'`		✔	✔					✔	✔
`'SHA-1'`												✔
`'SHA-256'`												✔
`'SHA-384'`												✔
`'SHA-512'`												✔

클래스: `Crypto`

추가된 버전: v15.0.0

globalThis.crypto는 Crypto 클래스의 인스턴스입니다. Crypto는 암호화 API의 나머지 부분에 대한 액세스를 제공하는 싱글톤입니다.

`crypto.subtle`

추가된 버전: v15.0.0

유형: <SubtleCrypto>

SubtleCrypto API에 대한 액세스를 제공합니다.

`crypto.getRandomValues(typedArray)`

추가된 버전: v15.0.0

typedArray <Buffer> | <TypedArray>
반환: <Buffer> | <TypedArray>

암호화적으로 강력한 임의 값을 생성합니다. 주어진 typedArray는 임의 값으로 채워지고 typedArray에 대한 참조가 반환됩니다.

주어진 typedArray는 <TypedArray>의 정수 기반 인스턴스여야 합니다. 즉, Float32Array 및 Float64Array는 허용되지 않습니다.

주어진 typedArray가 65,536바이트보다 크면 오류가 발생합니다.

`crypto.randomUUID()`

추가된 버전: v16.7.0

반환 값: <string>

임의의 RFC 4122 버전 4 UUID를 생성합니다. UUID는 암호화 의사 난수 생성기를 사용하여 생성됩니다.

클래스: `CryptoKey`

추가된 버전: v15.0.0

`cryptoKey.algorithm`

추가된 버전: v15.0.0

유형: <AesKeyGenParams> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams>

키를 사용할 수 있는 알고리즘과 추가 알고리즘 특정 매개변수를 자세히 설명하는 객체입니다.

읽기 전용입니다.

`cryptoKey.extractable`

추가된 버전: v15.0.0

유형: <boolean>

true이면, <CryptoKey>를 subtleCrypto.exportKey() 또는 subtleCrypto.wrapKey()를 사용하여 추출할 수 있습니다.

읽기 전용입니다.

`cryptoKey.type`

추가된 버전: v15.0.0

유형: <string> 'secret', 'private' 또는 'public' 중 하나입니다.

키가 대칭('secret')인지 비대칭('private' 또는 'public') 키인지 식별하는 문자열입니다.

`cryptoKey.usages`

추가된 버전: v15.0.0

유형: <string[]>

키를 사용할 수 있는 작업을 식별하는 문자열 배열입니다.

가능한 사용법은 다음과 같습니다:

'encrypt' - 키를 사용하여 데이터를 암호화할 수 있습니다.
'decrypt' - 키를 사용하여 데이터를 복호화할 수 있습니다.
'sign' - 키를 사용하여 디지털 서명을 생성할 수 있습니다.
'verify' - 키를 사용하여 디지털 서명을 확인할 수 있습니다.
'deriveKey' - 키를 사용하여 새 키를 파생시킬 수 있습니다.
'deriveBits' - 키를 사용하여 비트를 파생시킬 수 있습니다.
'wrapKey' - 키를 사용하여 다른 키를 래핑할 수 있습니다.
'unwrapKey' - 키를 사용하여 다른 키의 래핑을 해제할 수 있습니다.

유효한 키 사용법은 키 알고리즘(cryptokey.algorithm.name으로 식별)에 따라 달라집니다.

키 유형	`'encrypt'`	`'decrypt'`	`'sign'`	`'verify'`	`'deriveKey'`	`'deriveBits'`	`'wrapKey'`	`'unwrapKey'`
`'AES-CBC'`	✔	✔					✔	✔
`'AES-CTR'`	✔	✔					✔	✔
`'AES-GCM'`	✔	✔					✔	✔
`'AES-KW'`							✔	✔
`'ECDH'`					✔	✔
`'X25519'`					✔	✔
`'X448'`					✔	✔
`'ECDSA'`			✔	✔
`'Ed25519'`			✔	✔
`'Ed448'`			✔	✔
`'HDKF'`					✔	✔
`'HMAC'`			✔	✔
`'PBKDF2'`					✔	✔
`'RSA-OAEP'`	✔	✔					✔	✔
`'RSA-PSS'`			✔	✔
`'RSASSA-PKCS1-v1_5'`			✔	✔

Class: `CryptoKeyPair`

Added in: v15.0.0

CryptoKeyPair는 publicKey와 privateKey 속성을 가진 단순한 딕셔너리 객체로, 비대칭 키 쌍을 나타냅니다.

`cryptoKeyPair.privateKey`

Added in: v15.0.0

Type: <CryptoKey> type이 'private'인 <CryptoKey>.

`cryptoKeyPair.publicKey`

Added in: v15.0.0

Type: <CryptoKey> type이 'public'인 <CryptoKey>.

Class: `SubtleCrypto`

Added in: v15.0.0

`subtle.decrypt(algorithm, key, data)`

Added in: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Returns: <Promise> <ArrayBuffer>로 완료됩니다.

algorithm에 지정된 메서드 및 매개변수와 key에서 제공된 키 재료를 사용하여 subtle.decrypt()는 제공된 data를 해독하려고 시도합니다. 성공하면 반환된 Promise는 일반 텍스트 결과를 포함하는 <ArrayBuffer>로 해결됩니다.

현재 지원되는 알고리즘은 다음과 같습니다.

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

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

[History]

버전	변경 사항
v22.5.0, v20.17.0	`length` 매개변수가 이제 `'ECDH'`, `'X25519'`, 및 `'X448'`에 대해 선택 사항입니다.
v18.4.0, v16.17.0	`'X25519'` 및 `'X448'` 알고리즘이 추가되었습니다.
v15.0.0	v15.0.0에 추가됨

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
length: <number> | <null> 기본값: null
반환 값: <Promise> <ArrayBuffer>로 이행됩니다.

algorithm에 지정된 방법 및 매개변수와 baseKey에서 제공하는 키 자료를 사용하여, subtle.deriveBits()는 length 비트를 생성하려고 시도합니다.

length가 제공되지 않거나 null인 경우, 주어진 알고리즘의 최대 비트 수가 생성됩니다. 이는 'ECDH', 'X25519', 및 'X448' 알고리즘에 허용되며, 다른 알고리즘의 경우 length는 숫자여야 합니다.

성공하면 반환된 프로미스는 생성된 데이터를 포함하는 <ArrayBuffer>로 확인됩니다.

현재 지원되는 알고리즘은 다음과 같습니다.

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

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

[History]

버전	변경 사항
v18.4.0, v16.17.0	`'X25519'` 및 `'X448'` 알고리즘이 추가되었습니다.
v15.0.0	v15.0.0에 추가됨

algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>
baseKey: <CryptoKey>
derivedKeyAlgorithm: <HmacKeyGenParams> | [<AesKeyGenParams>](/ko/api/webcrypto#class-aeskey генparams)
extractable: <boolean>
keyUsages: <string[]> 키 사용법을 참조하십시오.
반환 값: <Promise> <CryptoKey>로 이행됩니다.

algorithm에 지정된 방법 및 매개변수와 baseKey에서 제공하는 키 자료를 사용하여, subtle.deriveKey()는 derivedKeyAlgorithm의 방법 및 매개변수를 기반으로 새로운 <CryptoKey>를 생성하려고 시도합니다.

subtle.deriveKey()를 호출하는 것은 subtle.deriveBits()를 호출하여 원시 키 자료를 생성한 다음, deriveKeyAlgorithm, extractable 및 keyUsages 매개변수를 입력으로 사용하여 subtle.importKey() 메서드에 결과를 전달하는 것과 같습니다.

현재 지원되는 알고리즘은 다음과 같습니다.

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

`subtle.digest(algorithm, data)`

추가된 버전: v15.0.0

algorithm: <string> | <Object>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
반환 값: <Promise> <ArrayBuffer>로 이행됩니다.

algorithm으로 식별된 메서드를 사용하여 subtle.digest()는 data의 다이제스트를 생성하려고 시도합니다. 성공하면 반환된 프로미스가 계산된 다이제스트를 포함하는 <ArrayBuffer>로 처리됩니다.

algorithm이 <string>으로 제공된 경우 다음 중 하나여야 합니다.

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

algorithm이 <Object>으로 제공된 경우, 해당 값은 위의 값 중 하나인 name 속성이 있어야 합니다.

`subtle.encrypt(algorithm, key, data)`

추가된 버전: v15.0.0

algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
반환 값: <Promise> <ArrayBuffer>로 이행됩니다.

algorithm으로 지정된 방법 및 매개변수와 key에서 제공하는 키 재료를 사용하여 subtle.encrypt()는 data를 암호화하려고 시도합니다. 성공하면 반환된 프로미스가 암호화된 결과를 포함하는 <ArrayBuffer>로 처리됩니다.

현재 지원되는 알고리즘은 다음과 같습니다.

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

`subtle.exportKey(format, key)`

[연혁]

버전	변경 사항
v18.4.0, v16.17.0	`'Ed25519'`, `'Ed448'`, `'X25519'`, 및 `'X448'` 알고리즘이 추가되었습니다.
v15.9.0	`'NODE-DSA'` JWK 내보내기가 제거되었습니다.
v15.0.0	추가됨: v15.0.0

format: <string> 'raw', 'pkcs8', 'spki', 또는 'jwk' 중 하나여야 합니다.
key: <CryptoKey>
반환 값: <Promise> <ArrayBuffer> | <Object>로 이행됩니다.

주어진 키를 지원되는 경우 지정된 형식으로 내보냅니다.

<CryptoKey>를 추출할 수 없는 경우 반환된 프로미스가 거부됩니다.

format이 'pkcs8' 또는 'spki'이고 내보내기가 성공하면 반환된 프로미스는 내보낸 키 데이터를 포함하는 <ArrayBuffer>로 이행됩니다.

format이 'jwk'이고 내보내기가 성공하면 반환된 프로미스는 JSON 웹 키 사양을 준수하는 JavaScript 객체로 이행됩니다.

키 유형	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`
`'HMAC'`			✔	✔
`'PBKDF2'`
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.generateKey(algorithm, extractable, keyUsages)`

추가됨: v15.0.0

algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>
extractable: <boolean>
keyUsages: <string[]> 키 사용을 참조하세요.
반환 값: <Promise> <CryptoKey> | <CryptoKeyPair>로 이행됩니다.

algorithm에 제공된 메서드 및 매개변수를 사용하여 subtle.generateKey()는 새 키 재료를 생성하려고 시도합니다. 사용된 메서드에 따라 메서드는 단일 <CryptoKey> 또는 <CryptoKeyPair>를 생성할 수 있습니다.

지원되는 <CryptoKeyPair> (공개 키 및 개인 키) 생성 알고리즘은 다음과 같습니다.

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

지원되는 <CryptoKey> (비밀 키) 생성 알고리즘은 다음과 같습니다.

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

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

[기록]

버전	변경 사항
v18.4.0, v16.17.0	`'Ed25519'`, `'Ed448'`, `'X25519'`, 및 `'X448'` 알고리즘 추가.
v15.9.0	`'NODE-DSA'` JWK 가져오기 제거.
v15.0.0	다음 버전에서 추가됨: v15.0.0

format: <string> 'raw', 'pkcs8', 'spki', 또는 'jwk' 중 하나여야 합니다.
keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>
algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> 키 용도를 참조하십시오.
반환: <Promise> <CryptoKey>로 완료됩니다.

subtle.importKey() 메서드는 제공된 keyData를 지정된 format으로 해석하여 제공된 algorithm, extractable 및 keyUsages 인수를 사용하여 <CryptoKey> 인스턴스를 생성하려고 시도합니다. 가져오기가 성공하면 반환된 프라미스가 생성된 <CryptoKey>로 해결됩니다.

'PBKDF2' 키를 가져오는 경우 extractable은 false여야 합니다.

현재 지원되는 알고리즘은 다음과 같습니다.

키 유형	`'spki'`	`'pkcs8'`	`'jwk'`	`'raw'`
`'AES-CBC'`			✔	✔
`'AES-CTR'`			✔	✔
`'AES-GCM'`			✔	✔
`'AES-KW'`			✔	✔
`'ECDH'`	✔	✔	✔	✔
`'X25519'`	✔	✔	✔	✔
`'X448'`	✔	✔	✔	✔
`'ECDSA'`	✔	✔	✔	✔
`'Ed25519'`	✔	✔	✔	✔
`'Ed448'`	✔	✔	✔	✔
`'HDKF'`				✔
`'HMAC'`			✔	✔
`'PBKDF2'`				✔
`'RSA-OAEP'`	✔	✔	✔
`'RSA-PSS'`	✔	✔	✔
`'RSASSA-PKCS1-v1_5'`	✔	✔	✔

`subtle.sign(algorithm, key, data)`

[기록]

버전	변경 사항
v18.4.0, v16.17.0	`'Ed25519'` 및 `'Ed448'` 알고리즘 추가.
v15.0.0	v15.0.0에 추가됨

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
반환: <Promise> <ArrayBuffer>로 이행됨

algorithm에 의해 주어진 방법 및 매개변수와 key에 의해 제공된 키 자료를 사용하여 subtle.sign()은 data의 암호화 서명을 생성하려고 시도합니다. 성공하면 생성된 서명을 포함하는 <ArrayBuffer>로 반환된 promise가 해결됩니다.

현재 지원되는 알고리즘은 다음과 같습니다.

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

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

v15.0.0에 추가됨

format: <string> 'raw', 'pkcs8', 'spki' 또는 'jwk' 중 하나여야 합니다.
wrappedKey: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
unwrappingKey: <CryptoKey>
unwrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
unwrappedKeyAlgo: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>
extractable: <boolean>
keyUsages: <string[]> 키 용도를 참조하십시오.
반환: <Promise> <CryptoKey>로 이행됨

암호화에서 "키 래핑"은 키 자료를 내보낸 다음 암호화하는 것을 의미합니다. subtle.unwrapKey() 메서드는 래핑된 키를 해독하고 <CryptoKey> 인스턴스를 만들려고 시도합니다. 이는 먼저 암호화된 키 데이터에서 subtle.decrypt()를 호출(입력으로 wrappedKey, unwrapAlgo 및 unwrappingKey 인수를 사용)한 다음 결과를 입력으로 unwrappedKeyAlgo, extractable 및 keyUsages 인수를 사용하여 subtle.importKey() 메서드로 전달하는 것과 같습니다. 성공하면 반환된 promise는 <CryptoKey> 객체로 해결됩니다.

현재 지원되는 래핑 알고리즘은 다음과 같습니다.

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

지원되는 래핑 해제 키 알고리즘은 다음과 같습니다.

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

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

[기록]

버전	변경 사항
v18.4.0, v16.17.0	`'Ed25519'` 및 `'Ed448'` 알고리즘이 추가되었습니다.
v15.0.0	v15.0.0에 추가되었습니다.

algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>
key: <CryptoKey>
signature: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
반환: <Promise> <boolean>으로 이행됩니다.

algorithm에 주어진 메서드 및 매개변수와 key에서 제공하는 키 자료를 사용하여 subtle.verify()는 signature가 data의 유효한 암호화 서명인지 확인하려고 시도합니다. 반환된 Promise는 true 또는 false로 확인됩니다.

현재 지원되는 알고리즘은 다음과 같습니다.

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

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

v15.0.0에 추가됨

format: <string> 'raw', 'pkcs8', 'spki' 또는 'jwk' 중 하나여야 합니다.
key: <CryptoKey>
wrappingKey: <CryptoKey>
wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>
반환: <Promise> <ArrayBuffer>으로 이행됩니다.

암호화에서 "키 래핑"은 키 자료를 내보낸 다음 암호화하는 것을 의미합니다. subtle.wrapKey() 메서드는 키 자료를 format에서 식별된 형식으로 내보낸 다음 wrapAlgo에서 지정한 방법 및 매개변수와 wrappingKey에서 제공한 키 자료를 사용하여 암호화합니다. 이는 format과 key를 인수로 사용하여 subtle.exportKey()를 호출한 다음 결과를 wrappingKey와 wrapAlgo를 입력으로 사용하여 subtle.encrypt() 메서드에 전달하는 것과 같습니다. 성공하면 반환된 Promise는 암호화된 키 데이터를 포함하는 <ArrayBuffer>로 확인됩니다.

현재 지원되는 래핑 알고리즘은 다음과 같습니다.

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

알고리즘 매개변수

알고리즘 매개변수 객체는 다양한 <SubtleCrypto> 메서드에서 사용되는 메서드와 매개변수를 정의합니다. 여기에서는 "클래스"로 설명되지만, 단순한 JavaScript 딕셔너리 객체입니다.

클래스: `AlgorithmIdentifier`

추가된 버전: v18.4.0, v16.17.0

`algorithmIdentifier.name`

추가된 버전: v18.4.0, v16.17.0

유형: <string>

클래스: `AesCbcParams`

추가된 버전: v15.0.0

`aesCbcParams.iv`

추가된 버전: v15.0.0

유형: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

초기화 벡터를 제공합니다. 정확히 16바이트 길이여야 하며 예측 불가능하고 암호화적으로 무작위여야 합니다.

`aesCbcParams.name`

추가된 버전: v15.0.0

유형: <string> 'AES-CBC'여야 합니다.

클래스: `AesCtrParams`

추가된 버전: v15.0.0

`aesCtrParams.counter`

추가된 버전: v15.0.0

유형: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

카운터 블록의 초기 값입니다. 정확히 16바이트 길이여야 합니다.

AES-CTR 메서드는 블록의 가장 오른쪽 length 비트를 카운터로 사용하고 나머지 비트를 nonce로 사용합니다.

`aesCtrParams.length`

추가된 버전: v15.0.0

유형: <number> aesCtrParams.counter에서 카운터로 사용할 비트 수입니다.

`aesCtrParams.name`

추가된 버전: v15.0.0

타입: <string> 'AES-CTR'이어야 합니다.

클래스: `AesGcmParams`

추가된 버전: v15.0.0

`aesGcmParams.additionalData`

추가된 버전: v15.0.0

타입: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

AES-GCM 메서드를 사용할 때, additionalData는 암호화되지는 않지만 데이터 인증에 포함되는 추가 입력입니다. additionalData 사용은 선택 사항입니다.

`aesGcmParams.iv`

추가된 버전: v15.0.0

타입: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

초기화 벡터는 주어진 키를 사용하여 모든 암호화 작업에서 고유해야 합니다.

이상적으로, 이것은 동일한 키를 사용하는 모든 호출에서 고유성이 보장되도록 계산된 결정론적 12바이트 값입니다. 또는, 초기화 벡터는 적어도 12개의 암호학적으로 임의적인 바이트로 구성될 수 있습니다. AES-GCM에 대한 초기화 벡터 생성에 대한 자세한 내용은 NIST SP 800-38D의 섹션 8을 참조하십시오.

`aesGcmParams.name`

추가된 버전: v15.0.0

타입: <string> 'AES-GCM'이어야 합니다.

`aesGcmParams.tagLength`

추가된 버전: v15.0.0

유형: <number> 생성된 인증 태그의 비트 단위 크기입니다. 이 값은 32, 64, 96, 104, 112, 120 또는 128 중 하나여야 합니다. 기본값: 128.

클래스: `AesKeyGenParams`

추가된 버전: v15.0.0

`aesKeyGenParams.length`

추가된 버전: v15.0.0

유형: <number>

생성될 AES 키의 길이입니다. 이것은 128, 192 또는 256 중 하나여야 합니다.

`aesKeyGenParams.name`

추가된 버전: v15.0.0

유형: <string> 'AES-CBC', 'AES-CTR', 'AES-GCM' 또는 'AES-KW' 중 하나여야 합니다.

클래스: `EcdhKeyDeriveParams`

추가된 버전: v15.0.0

`ecdhKeyDeriveParams.name`

추가된 버전: v15.0.0

유형: <string> 'ECDH', 'X25519' 또는 'X448' 중 하나여야 합니다.

`ecdhKeyDeriveParams.public`

추가된 버전: v15.0.0

유형: <CryptoKey>

ECDH 키 파생은 한 당사자의 개인 키와 다른 당사자의 공개 키를 입력으로 사용하여 공통 공유 비밀을 생성하는 방식으로 작동합니다. ecdhKeyDeriveParams.public 속성은 다른 당사자의 공개 키로 설정됩니다.

클래스: `EcdsaParams`

추가된 버전: v15.0.0

`ecdsaParams.hash`

추가된 버전: v15.0.0

유형: <string> | <Object>

<string>으로 표현되는 경우 값은 다음 중 하나여야 합니다.

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

<Object>로 표현되는 경우 객체는 위에 나열된 값 중 하나인 name 속성을 가져야 합니다.

`ecdsaParams.name`

추가된 버전: v15.0.0

유형: <string> 'ECDSA'여야 합니다.

클래스: `EcKeyGenParams`

추가된 버전: v15.0.0

`ecKeyGenParams.name`

추가된 버전: v15.0.0

유형: <string> 'ECDSA' 또는 'ECDH' 중 하나여야 합니다.

`ecKeyGenParams.namedCurve`

추가된 버전: v15.0.0

유형: <string> 'P-256', 'P-384', 'P-521' 중 하나여야 합니다.

클래스: `EcKeyImportParams`

추가된 버전: v15.0.0

`ecKeyImportParams.name`

추가된 버전: v15.0.0

유형: <string> 'ECDSA' 또는 'ECDH' 중 하나여야 합니다.

`ecKeyImportParams.namedCurve`

추가된 버전: v15.0.0

유형: <string> 'P-256', 'P-384', 'P-521' 중 하나여야 합니다.

클래스: `Ed448Params`

추가된 버전: v15.0.0

`ed448Params.name`

추가된 버전: v18.4.0, v16.17.0

유형: <string> 'Ed448'이어야 합니다.

`ed448Params.context`

추가된 버전: v18.4.0, v16.17.0

유형: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>

context 멤버는 메시지와 연결할 선택적 컨텍스트 데이터를 나타냅니다. Node.js Web Crypto API 구현은 컨텍스트를 전혀 제공하지 않는 것과 동일한 0 길이 컨텍스트만 지원합니다.

클래스: `HkdfParams`

추가된 버전: v15.0.0

`hkdfParams.hash`

추가된 버전: v15.0.0

타입: <string> | <Object>

<string>으로 표현되는 경우, 값은 다음 중 하나여야 합니다.

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

<Object>로 표현되는 경우, 객체는 위에 나열된 값 중 하나인 name 속성을 가져야 합니다.

`hkdfParams.info`

추가된 버전: v15.0.0

타입: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

HKDF 알고리즘에 응용 프로그램 특정 컨텍스트 입력을 제공합니다. 길이는 0일 수 있지만 제공해야 합니다.

`hkdfParams.name`

추가된 버전: v15.0.0

타입: <string> 'HKDF'여야 합니다.

`hkdfParams.salt`

추가된 버전: v15.0.0

타입: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

솔트 값은 HKDF 알고리즘의 강도를 크게 향상시킵니다. 임의 또는 의사 난수여야 하며, 다이제스트 함수의 출력과 길이가 같아야 합니다 (예를 들어 'SHA-256'을 다이제스트로 사용하는 경우, 솔트는 256비트의 임의 데이터여야 합니다).

클래스: `HmacImportParams`

추가된 버전: v15.0.0

`hmacImportParams.hash`

추가된 버전: v15.0.0

유형: <string> | <Object>

<string>으로 표현되는 경우 값은 다음 중 하나여야 합니다.

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

<Object>로 표현되는 경우 객체는 값이 위에 나열된 값 중 하나인 name 속성을 가져야 합니다.

`hmacImportParams.length`

추가된 버전: v15.0.0

유형: <number>

HMAC 키의 선택적 비트 수입니다. 이는 선택 사항이며 대부분의 경우 생략해야 합니다.

`hmacImportParams.name`

추가된 버전: v15.0.0

유형: <string> 'HMAC'여야 합니다.

클래스: `HmacKeyGenParams`

추가된 버전: v15.0.0

`hmacKeyGenParams.hash`

추가된 버전: v15.0.0

유형: <string> | <Object>

<string>으로 표현되는 경우 값은 다음 중 하나여야 합니다.

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

<Object>로 표현되는 경우 객체는 값이 위에 나열된 값 중 하나인 name 속성을 가져야 합니다.

`hmacKeyGenParams.length`

추가된 버전: v15.0.0

유형: <number>

HMAC 키에 대해 생성할 비트 수입니다. 생략하면 길이는 사용된 해시 알고리즘에 따라 결정됩니다. 이는 선택 사항이며 대부분의 경우 생략해야 합니다.

`hmacKeyGenParams.name`

추가된 버전: v15.0.0

유형: <string> 'HMAC'이어야 합니다.

클래스: `Pbkdf2Params`

추가된 버전: v15.0.0

`pbkdb2Params.hash`

추가된 버전: v15.0.0

유형: <string> | <Object>

<string>으로 표현된 경우, 값은 다음 중 하나여야 합니다.

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

<Object>로 표현된 경우, 객체는 위에 나열된 값 중 하나인 name 속성을 가져야 합니다.

`pbkdf2Params.iterations`

추가된 버전: v15.0.0

유형: <number>

PBKDF2 알고리즘이 비트를 파생할 때 수행해야 하는 반복 횟수입니다.

`pbkdf2Params.name`

추가된 버전: v15.0.0

유형: <string> 'PBKDF2'이어야 합니다.

`pbkdf2Params.salt`

추가된 버전: v15.0.0

유형: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

최소 16바이트의 임의 또는 의사 임의 바이트여야 합니다.

클래스: `RsaHashedImportParams`

추가된 버전: v15.0.0

`rsaHashedImportParams.hash`

추가된 버전: v15.0.0

유형: <string> | <Object>

<string>으로 표현된 경우, 값은 다음 중 하나여야 합니다.

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

<Object>로 표현된 경우, 객체는 위에 나열된 값 중 하나인 name 속성을 가져야 합니다.

`rsaHashedImportParams.name`

추가된 버전: v15.0.0

유형: <string> 'RSASSA-PKCS1-v1_5', 'RSA-PSS', 또는 'RSA-OAEP' 중 하나여야 합니다.

클래스: `RsaHashedKeyGenParams`

추가된 버전: v15.0.0

`rsaHashedKeyGenParams.hash`

추가된 버전: v15.0.0

유형: <string> | <Object>

<string>으로 표현되는 경우 다음 값 중 하나여야 합니다.

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

<Object>로 표현되는 경우 객체에는 값이 위에 나열된 값 중 하나인 name 속성이 있어야 합니다.

`rsaHashedKeyGenParams.modulusLength`

추가된 버전: v15.0.0

유형: <number>

RSA 모듈러스의 비트 단위 길이입니다. 모범 사례로, 이 값은 최소 2048이어야 합니다.

`rsaHashedKeyGenParams.name`

추가된 버전: v15.0.0

유형: <string> 'RSASSA-PKCS1-v1_5', 'RSA-PSS', 또는 'RSA-OAEP' 중 하나여야 합니다.

`rsaHashedKeyGenParams.publicExponent`

추가된 버전: v15.0.0

유형: <Uint8Array>

RSA 공개 지수입니다. 이 값은 32비트 내에 맞아야 하는 빅 엔디안, 부호 없는 정수를 포함하는 <Uint8Array>여야 합니다. <Uint8Array>는 임의의 개수의 선행 제로 비트를 포함할 수 있습니다. 값은 소수여야 합니다. 다른 값을 사용할 이유가 없다면 공개 지수로 new Uint8Array([1, 0, 1]) (65537)을 사용하십시오.

클래스: `RsaOaepParams`

추가된 버전: v15.0.0

`rsaOaepParams.label`

추가된 버전: v15.0.0

타입: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>

암호화되지 않지만 생성된 암호 텍스트에 바인딩되는 추가 바이트 컬렉션입니다.

rsaOaepParams.label 파라미터는 선택 사항입니다.

`rsaOaepParams.name`

추가된 버전: v15.0.0

타입: <string> 'RSA-OAEP'여야 합니다.

클래스: `RsaPssParams`

추가된 버전: v15.0.0

`rsaPssParams.name`

추가된 버전: v15.0.0

타입: <string> 'RSA-PSS'여야 합니다.

`rsaPssParams.saltLength`

추가된 버전: v15.0.0

타입: <number>

사용할 임의 솔트의 길이 (바이트)입니다.

Web Crypto API ​

예 ​

키 생성 ​

AES 키 ​

ECDSA 키 쌍 ​

Ed25519/X25519 키 쌍 ​

HMAC 키 ​

RSA 키 쌍 ​

암호화 및 복호화 ​

키 내보내기 및 가져오기 ​

키 래핑 및 래핑 해제 ​

서명 및 확인 ​

비트 및 키 파생 ​

다이제스트 ​

알고리즘 매트릭스 ​

클래스: Crypto ​

crypto.subtle ​

crypto.getRandomValues(typedArray) ​

crypto.randomUUID() ​

클래스: CryptoKey ​

cryptoKey.algorithm ​

cryptoKey.extractable ​

cryptoKey.type ​

cryptoKey.usages ​

Class: CryptoKeyPair ​

cryptoKeyPair.privateKey ​

cryptoKeyPair.publicKey ​

Class: SubtleCrypto ​

subtle.decrypt(algorithm, key, data) ​

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

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

subtle.digest(algorithm, data) ​

subtle.encrypt(algorithm, key, data) ​

subtle.exportKey(format, key) ​

subtle.generateKey(algorithm, extractable, keyUsages) ​

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

subtle.sign(algorithm, key, data) ​

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

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

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

알고리즘 매개변수 ​

클래스: AlgorithmIdentifier ​

algorithmIdentifier.name ​

클래스: AesCbcParams ​

aesCbcParams.iv ​

aesCbcParams.name ​

클래스: AesCtrParams ​

aesCtrParams.counter ​

aesCtrParams.length ​

aesCtrParams.name ​

클래스: AesGcmParams ​

aesGcmParams.additionalData ​

aesGcmParams.iv ​

aesGcmParams.name ​

aesGcmParams.tagLength ​

클래스: AesKeyGenParams ​

aesKeyGenParams.length ​

aesKeyGenParams.name ​

클래스: EcdhKeyDeriveParams ​

ecdhKeyDeriveParams.name ​

ecdhKeyDeriveParams.public ​

클래스: EcdsaParams ​

ecdsaParams.hash ​

ecdsaParams.name ​

클래스: EcKeyGenParams ​

ecKeyGenParams.name ​

ecKeyGenParams.namedCurve ​

클래스: EcKeyImportParams ​

ecKeyImportParams.name ​

ecKeyImportParams.namedCurve ​

클래스: Ed448Params ​

ed448Params.name ​

ed448Params.context ​

클래스: HkdfParams ​

hkdfParams.hash ​

hkdfParams.info ​

hkdfParams.name ​

hkdfParams.salt ​

클래스: HmacImportParams ​

hmacImportParams.hash ​

Web Crypto API

예

키 생성

AES 키

ECDSA 키 쌍

Ed25519/X25519 키 쌍

HMAC 키

RSA 키 쌍

암호화 및 복호화

키 내보내기 및 가져오기

키 래핑 및 래핑 해제

서명 및 확인

비트 및 키 파생

다이제스트

알고리즘 매트릭스

클래스: `Crypto`

`crypto.subtle`

`crypto.getRandomValues(typedArray)`

`crypto.randomUUID()`

클래스: `CryptoKey`

`cryptoKey.algorithm`

`cryptoKey.extractable`

`cryptoKey.type`

`cryptoKey.usages`

Class: `CryptoKeyPair`

`cryptoKeyPair.privateKey`

`cryptoKeyPair.publicKey`

Class: `SubtleCrypto`

`subtle.decrypt(algorithm, key, data)`

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

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

`subtle.digest(algorithm, data)`

`subtle.encrypt(algorithm, key, data)`

`subtle.exportKey(format, key)`

`subtle.generateKey(algorithm, extractable, keyUsages)`

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

`subtle.sign(algorithm, key, data)`

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

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

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

알고리즘 매개변수

클래스: `AlgorithmIdentifier`

`algorithmIdentifier.name`

클래스: `AesCbcParams`

`aesCbcParams.iv`

`aesCbcParams.name`

클래스: `AesCtrParams`

`aesCtrParams.counter`

`aesCtrParams.length`

`aesCtrParams.name`

클래스: `AesGcmParams`

`aesGcmParams.additionalData`

`aesGcmParams.iv`

`aesGcmParams.name`

`aesGcmParams.tagLength`

클래스: `AesKeyGenParams`

`aesKeyGenParams.length`

`aesKeyGenParams.name`

클래스: `EcdhKeyDeriveParams`

`ecdhKeyDeriveParams.name`

`ecdhKeyDeriveParams.public`

클래스: `EcdsaParams`

`ecdsaParams.hash`

`ecdsaParams.name`

클래스: `EcKeyGenParams`

`ecKeyGenParams.name`

`ecKeyGenParams.namedCurve`

클래스: `EcKeyImportParams`

`ecKeyImportParams.name`

`ecKeyImportParams.namedCurve`

클래스: `Ed448Params`

`ed448Params.name`

`ed448Params.context`

클래스: `HkdfParams`

`hkdfParams.hash`

`hkdfParams.info`

`hkdfParams.name`

`hkdfParams.salt`

클래스: `HmacImportParams`

`hmacImportParams.hash`