dan/jose
1
0
Fork 0
mirror of https://github.com/danbulant/jose synced 2026-05-24 20:41:46 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: extend KeyLike documentation

Browse source
This commit is contained in:
Filip Skokan 2021-03-31 11:54:41 +02:00
parent a850303ffb
commit b806c6dfbf
1 changed files with 60 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
src/types.d.ts vendored
View file

@ -79,23 +79,70 @@ export interface GetKeyFunction<T, T2> {
(protectedHeader: T, token: T2): Promise<KeyLike>
}
/* eslint-disable jsdoc/check-indentation */
/* eslint-disable jsdoc/require-description-complete-sentence */
/**
* KeyLike are platform-specific references to keying material.
*
* - [KeyObject](https://nodejs.org/api/crypto.html#crypto_class_keyobject) instances come from
* node's [crypto module](https://nodejs.org/api/crypto.html), e.g.:
* - [crypto.generateKeyPair](https://nodejs.org/api/crypto.html#crypto_crypto_generatekeypair_type_options_callback)
* - [crypto.createPublicKey](https://nodejs.org/api/crypto.html#crypto_crypto_createpublickey_key)
* - [crypto.createPrivateKey](https://nodejs.org/api/crypto.html#crypto_crypto_createprivatekey_key)
* - [crypto.createSecretKey](https://nodejs.org/api/crypto.html#crypto_crypto_createsecretkey_key_encoding)
* - [CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) instances come from
* [Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI), e.g.:
* - [SubtleCrypto.importKey](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey)
* - [SubtleCrypto.generateKey](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
* - [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
* [KeyObject](https://nodejs.org/api/crypto.html#crypto_class_keyobject) is a representation of a
* key/secret available in the Node.js runtime. You can obtain a KeyObject instance e.g. from:
*
* - [crypto.generateKeyPair](https://nodejs.org/api/crypto.html#crypto_crypto_generatekeypair_type_options_callback)
* - [crypto.createPublicKey](https://nodejs.org/api/crypto.html#crypto_crypto_createpublickey_key)
* - [crypto.createPrivateKey](https://nodejs.org/api/crypto.html#crypto_crypto_createprivatekey_key)
* - [crypto.createSecretKey](https://nodejs.org/api/crypto.html#crypto_crypto_createsecretkey_key_encoding)
* - [crypto.generateKeyPair](https://nodejs.org/api/crypto.html#crypto_crypto_generatekeypair_type_options_callback)
* - [jose/jwk/parse](../functions/jwk_parse.parsejwk.md#readme)
*
* [CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) is a representation of a
* key/secret available in the Browser runtime. You can obtain a CryptoKey instance e.g. from:
*
* - [SubtleCrypto.importKey](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey)
* - [SubtleCrypto.generateKey](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
* - [jose/jwk/parse](../functions/jwk_parse.parsejwk.md#readme)
*
* [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
* is used exclusively for symmetric secret representations, a CryptoKey or KeyObject is
* preferred, but in Web Crypto API this isn't an option for some algorithms.
* preferred, but in Web Crypto API this isn't an option for some algorithms. In Node.js runtime
* [Buffer](https://nodejs.org/api/buffer.html#buffer_buffer)s are instances of Uint8Array.
*
* @example (node) Public KeyObject from a PEM public key
* ```js
* import { createPublicKey } from 'crypto'
*
* const publicKey = createPublicKey(pem)
* ```
*
* @example (node) Private KeyObject from a PEM private key
* ```js
* import { createPrivateKey } from 'crypto'
*
* const privateKey = createPrivateKey(pem)
* ```
*
* @example (node) Secret KeyObject from hex encoded random bytes
* ```js
* import { createSecretKey } from 'crypto'
*
* const secretKey = createSecretKey(Buffer.from('7f908df6c8bd634f769c073a48986d77677b79bc6aa19b106f976f2db18d38c2', 'hex'))
* ```
*
* @example (all runtimes) KeyLike from a JSON Web Key (JWK)
* ```js
* import { parseJwk } from 'jose/jwk/parse'
*
* const ecPublicKey = await parseJwk({
* crv: 'P-256',
* kty: 'EC',
* x: 'ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw',
* y: '_LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo'
* }, 'ES256')
*
* const rsaPublicKey = await parseJwk({
* kty: 'RSA',
* e: 'AQAB',
* n: '12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ'
* }, 'PS256')
* ```
*/
export type KeyLike = KeyObject | CryptoKey | Uint8Array
/* eslint-enable */