SubtleCrypto
Baseline
Widely available
*
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.
* Some parts of this feature may have varying levels of support.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Note: This feature is available in Web Workers.
Giao diện SubtleCrypto của Web Crypto API cung cấp một số hàm mật mã cấp thấp.
Tên giao diện bao gồm thuật ngữ "subtle" (tinh tế) để chỉ ra rằng nhiều thuật toán của nó có các yêu cầu sử dụng tinh tế, và do đó phải được sử dụng cẩn thận để cung cấp các đảm bảo bảo mật phù hợp.
Một thực thể của SubtleCrypto có sẵn dưới dạng thuộc tính subtle của giao diện Crypto, giao diện này có sẵn trong cửa sổ thông qua thuộc tính Window.crypto và trong worker thông qua thuộc tính WorkerGlobalScope.crypto.
Warning: API này cung cấp một số nguyên thủy mật mã cấp thấp. Rất dễ lạm dụng chúng và những cạm bẫy liên quan có thể rất tinh tế.
Ngay cả khi bạn sử dụng đúng các hàm mật mã cơ bản, việc quản lý khóa bảo mật và thiết kế hệ thống bảo mật tổng thể là cực kỳ khó thực hiện đúng, và thường là lĩnh vực của các chuyên gia bảo mật.
Lỗi trong thiết kế và triển khai hệ thống bảo mật có thể làm cho hệ thống bảo mật trở nên hoàn toàn vô hiệu.
Vui lòng học hỏi và thử nghiệm, nhưng đừng đảm bảo hoặc ngụ ý về tính bảo mật của công việc trước khi một người có kiến thức chuyên môn về lĩnh vực này xem xét kỹ lưỡng. Crypto 101 Course có thể là nơi tuyệt vời để bắt đầu học về thiết kế và triển khai các hệ thống bảo mật.
Thuộc tính thực thể
Giao diện này không kế thừa bất kỳ thuộc tính nào vì nó không có giao diện cha.
Phương thức thực thể
Giao diện này không kế thừa bất kỳ phương thức nào vì nó không có giao diện cha.
SubtleCrypto.encrypt()-
Trả về một
Promiseđược fulfill với dữ liệu đã mã hóa tương ứng với văn bản gốc, thuật toán và khóa được truyền làm tham số. SubtleCrypto.decrypt()-
Trả về một
Promiseđược fulfill với dữ liệu gốc tương ứng với văn bản đã mã hóa, thuật toán và khóa được truyền làm tham số. SubtleCrypto.sign()-
Trả về một
Promiseđược fulfill với chữ ký số tương ứng với văn bản, thuật toán và khóa được truyền làm tham số. SubtleCrypto.verify()-
Trả về một
Promiseđược fulfill với giá trị boolean cho biết chữ ký được truyền làm tham số có khớp với văn bản, thuật toán và khóa cũng được truyền làm tham số hay không. SubtleCrypto.digest()-
Trả về một
Promiseđược fulfill với giá trị digest được tạo từ thuật toán và văn bản được truyền làm tham số. SubtleCrypto.generateKey()-
Trả về một
Promiseđược fulfill với mộtCryptoKeymới được tạo (cho thuật toán đối xứng) hoặc mộtCryptoKeyPairchứa hai khóa mới được tạo (cho thuật toán bất đối xứng). Những khóa này sẽ khớp với thuật toán, cách sử dụng và khả năng trích xuất được truyền làm tham số. SubtleCrypto.deriveKey()-
Trả về một
Promiseđược fulfill với mộtCryptoKeymới được tạo từ khóa chính và thuật toán cụ thể được truyền làm tham số. SubtleCrypto.deriveBits()-
Trả về một
Promiseđược fulfill với một bộ đệm bit giả ngẫu nhiên mới được tạo từ khóa chính và thuật toán cụ thể được truyền làm tham số. SubtleCrypto.importKey()-
Trả về một
Promiseđược fulfill với mộtCryptoKeytương ứng với định dạng, thuật toán, dữ liệu khóa thô, cách sử dụng và khả năng trích xuất được truyền làm tham số. SubtleCrypto.exportKey()-
Trả về một
Promiseđược fulfill với dữ liệu khóa thô chứa khóa ở định dạng được yêu cầu. SubtleCrypto.wrapKey()-
Trả về một
Promiseđược fulfill với một khóa đối xứng đã được bọc để sử dụng (truyền và lưu trữ) trong môi trường không bảo mật. Khóa đã bọc khớp với định dạng được chỉ định trong các tham số đã cho, và việc bọc được thực hiện bằng khóa bọc đã cho, sử dụng thuật toán được chỉ định. SubtleCrypto.unwrapKey()-
Trả về một
Promiseđược fulfill với mộtCryptoKeytương ứng với khóa đã bọc được truyền trong tham số.
Sử dụng SubtleCrypto
Chúng ta có thể chia các hàm được triển khai bởi API này thành hai nhóm: các hàm mật mã và các hàm quản lý khóa.
Các hàm mật mã
Đây là các hàm bạn có thể sử dụng để triển khai các tính năng bảo mật như quyền riêng tư và xác thực trong hệ thống. API SubtleCrypto cung cấp các hàm mật mã sau:
Các hàm quản lý khóa
Ngoại trừ digest(), tất cả các hàm mật mã trong API đều sử dụng khóa mật mã. Trong API SubtleCrypto, một khóa mật mã được biểu diễn bằng đối tượng CryptoKey. Để thực hiện các thao tác như ký và mã hóa, bạn truyền đối tượng CryptoKey vào hàm sign() hoặc encrypt().
Tạo và phái sinh khóa
Cả hai hàm generateKey() và deriveKey() đều tạo đối tượng CryptoKey mới.
Sự khác biệt là generateKey() sẽ tạo ra một giá trị khóa riêng biệt mới mỗi khi bạn gọi nó, trong khi deriveKey() phái sinh một khóa từ một số tài liệu khóa ban đầu. Nếu bạn cung cấp cùng tài liệu khóa cho hai lệnh gọi riêng biệt đến deriveKey(), bạn sẽ nhận được hai đối tượng CryptoKey có cùng giá trị cơ bản. Điều này hữu ích nếu, ví dụ, bạn muốn phái sinh một khóa mã hóa từ mật khẩu và sau đó phái sinh cùng khóa đó từ cùng mật khẩu để giải mã dữ liệu.
Nhập và xuất khóa
Để làm cho khóa khả dụng bên ngoài ứng dụng của bạn, bạn cần xuất khóa, và đó là mục đích của exportKey(). Bạn có thể chọn một trong số định dạng xuất.
Ngược lại với exportKey() là importKey(). Bạn có thể nhập khóa từ các hệ thống khác, và hỗ trợ cho các định dạng chuẩn như PKCS #8 và JSON Web Key giúp bạn thực hiện điều này. Hàm exportKey() xuất khóa ở định dạng không mã hóa.
Nếu khóa nhạy cảm, bạn nên sử dụng wrapKey(), hàm này xuất khóa rồi mã hóa nó bằng một khóa khác; API gọi là "khóa bọc khóa".
Ngược lại với wrapKey() là unwrapKey(), hàm này giải mã rồi nhập khóa.
Lưu trữ khóa
CryptoKey là một serializable object, cho phép lưu trữ và truy xuất khóa bằng các API lưu trữ web chuẩn.
Đặc tả kỹ thuật dự kiến rằng hầu hết các nhà phát triển sẽ sử dụng IndexedDB API, lưu trữ các đối tượng CryptoKey theo một số định danh chuỗi khóa có ý nghĩa đối với ứng dụng, cùng với bất kỳ siêu dữ liệu nào khác mà ứng dụng thấy hữu ích.
Điều này cho phép lưu trữ và truy xuất CryptoKey mà không cần phải exposing giá trị khóa cơ bản của nó cho ứng dụng hoặc môi trường JavaScript.
Các thuật toán được hỗ trợ
Các hàm mật mã được cung cấp bởi Web Crypto API có thể được thực hiện bởi một hoặc nhiều thuật toán mật mã khác nhau: đối số algorithm truyền cho hàm cho biết thuật toán nào sẽ sử dụng. Một số thuật toán cần thêm tham số: trong những trường hợp này, đối số algorithm là một đối tượng từ điển bao gồm các tham số bổ sung.
Bảng dưới đây tóm tắt những thuật toán nào phù hợp cho những thao tác mật mã nào:
|
sign verify |
encrypt decrypt |
digest |
deriveBits deriveKey |
wrapKey unwrapKey |
generateKey exportKey |
importKey | |
|---|---|---|---|---|---|---|---|
| RSASSA-PKCS1-v1_5 | ✓ | ✓ | ✓ | ||||
| RSA-PSS | ✓ | ✓ | ✓ | ||||
| ECDSA | ✓ | ✓ | ✓ | ||||
| Ed25519 | ✓ | ✓ | ✓ | ||||
| HMAC | ✓ | ✓ | ✓ | ||||
| RSA-OAEP | ✓ | ✓ | ✓ | ✓ | |||
| AES-CTR | ✓ | ✓ | ✓ | ✓ | |||
| AES-CBC | ✓ | ✓ | ✓ | ✓ | |||
| AES-GCM | ✓ | ✓ | ✓ | ✓ | |||
| AES-KW | ✓ | ✓ | ✓ | ||||
| SHA-1 | ✓ | ||||||
| SHA-256 | ✓ | ||||||
| SHA-384 | ✓ | ||||||
| SHA-512 | ✓ | ||||||
| ECDH | ✓ | ✓ | ✓ | ||||
| X25519 | ✓ | ✓ | ✓ | ||||
| HKDF | ✓ | ✓ | |||||
| PBKDF2 | ✓ | ✓ |
Đặc tả kỹ thuật
| Specification |
|---|
| Web Cryptography Level 2 # subtlecrypto-interface |
Tương thích trình duyệt
Xem thêm
- Web Crypto API
- Các công dụng phi mật mã của SubtleCrypto
- Bảo mật web
- Quyền riêng tư, quyền và bảo mật thông tin
CryptovàCrypto.subtle.- Crypto 101: khóa học giới thiệu về mật mã.