@libp2p/crypto 2.0.5 → 2.0.6-025c082a

package/src/keys/index.ts

@@ -1,3 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * **Supported Key Types**
+ *
+ * The {@link generateKeyPair}, {@link marshalPublicKey}, and {@link marshalPrivateKey} functions accept a string `type` argument.
+ *
+ * Currently the `'RSA'`, `'ed25519'`, and `secp256k1` types are supported, although ed25519 and secp256k1 keys support only signing and verification of messages.
+ *
+ * For encryption / decryption support, RSA keys should be used.
+ */
+
 import 'node-forge/lib/asn1.js'
 import 'node-forge/lib/pbe.js'
 import { CodeError } from '@libp2p/interface/errors'
@@ -40,13 +52,21 @@ function typeToKey (type: string): typeof RSA | typeof Ed25519 | typeof Secp256k
   throw unsupportedKey(type)
 }
 
-// Generates a keypair of the given type and bitsize
+/**
+ * Generates a keypair of the given type and bitsize
+ *
+ * @param type
+ * @param bits -  Minimum of 1024
+ */
 export async function generateKeyPair (type: KeyTypes, bits?: number): Promise<PrivateKey> {
   return typeToKey(type).generateKeyPair(bits ?? 2048)
 }
 
-// Generates a keypair of the given type and bitsize
-// seed is a 32 byte uint8array
+/**
+ * Generates a keypair of the given type and bitsize.
+ *
+ * Seed is a 32 byte uint8array
+ */
 export async function generateKeyPairFromSeed (type: KeyTypes, seed: Uint8Array, bits?: number): Promise<PrivateKey> {
   if (type.toLowerCase() !== 'ed25519') {
     throw new CodeError('Seed key derivation is unimplemented for RSA or secp256k1', 'ERR_UNSUPPORTED_KEY_DERIVATION_TYPE')
@@ -55,8 +75,9 @@ export async function generateKeyPairFromSeed (type: KeyTypes, seed: Uint8Array,
   return Ed25519.generateKeyPairFromSeed(seed)
 }
 
-// Converts a protobuf serialized public key into its
-// representative object
+/**
+ * Converts a protobuf serialized public key into its representative object
+ */
 export function unmarshalPublicKey (buf: Uint8Array): PublicKey {
   const decoded = keysPBM.PublicKey.decode(buf)
   const data = decoded.Data ?? new Uint8Array()
@@ -73,15 +94,18 @@ export function unmarshalPublicKey (buf: Uint8Array): PublicKey {
   }
 }
 
-// Converts a public key object into a protobuf serialized public key
+/**
+ * Converts a public key object into a protobuf serialized public key
+ */
 export function marshalPublicKey (key: { bytes: Uint8Array }, type?: string): Uint8Array {
   type = (type ?? 'rsa').toLowerCase()
   typeToKey(type) // check type
   return key.bytes
 }
 
-// Converts a protobuf serialized private key into its
-// representative object
+/**
+ * Converts a protobuf serialized private key into its representative object
+ */
 export async function unmarshalPrivateKey (buf: Uint8Array): Promise<PrivateKey> {
   const decoded = keysPBM.PrivateKey.decode(buf)
   const data = decoded.Data ?? new Uint8Array()
@@ -98,7 +122,9 @@ export async function unmarshalPrivateKey (buf: Uint8Array): Promise<PrivateKey>
   }
 }
 
-// Converts a private key object into a protobuf serialized private key
+/**
+ * Converts a private key object into a protobuf serialized private key
+ */
 export function marshalPrivateKey (key: { bytes: Uint8Array }, type?: string): Uint8Array {
   type = (type ?? 'rsa').toLowerCase()
   typeToKey(type) // check type
@@ -106,9 +132,9 @@ export function marshalPrivateKey (key: { bytes: Uint8Array }, type?: string): U
 }
 
 /**
+ * Converts an exported private key into its representative object.
  *
- * @param {string} encryptedKey
- * @param {string} password
+ * Supported formats are 'pem' (RSA only) and 'libp2p-key'.
  */
 export async function importKey (encryptedKey: string, password: string): Promise<PrivateKey> {
   try {

package/src/random-bytes.ts

@@ -1,6 +1,9 @@
 import { CodeError } from '@libp2p/interface/errors'
 import { randomBytes as randB } from '@noble/hashes/utils'
 
+/**
+ * Generates a Uint8Array with length `number` populated by random bytes
+ */
 export default function randomBytes (length: number): Uint8Array {
   if (isNaN(length) || length <= 0) {
     throw new CodeError('random bytes length must be a Number bigger than 0', 'ERR_INVALID_LENGTH')

package/dist/typedoc-urls.json

@@ -1,37 +0,0 @@
-{
-  "AESCipher": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_crypto.aes.AESCipher.html",
-  "./aes:AESCipher": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_crypto.aes.AESCipher.html",
-  "create": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.aes.create.html",
-  "./aes:create": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.aes.create.html",
-  "HMAC": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_crypto.hmac.HMAC.html",
-  "./hmac:HMAC": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_crypto.hmac.HMAC.html",
-  "./hmac:create": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.hmac.create.html",
-  "pbkdf2": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.index.pbkdf2.html",
-  "randomBytes": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.index.randomBytes.html",
-  "codec": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.keysPBM.KeyType.codec.html",
-  "decode": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.keysPBM.PrivateKey.decode.html",
-  "encode": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.keysPBM.PrivateKey.encode.html",
-  "KeyType": "https://libp2p.github.io/js-libp2p/enums/_libp2p_crypto.keys.keysPBM.KeyType-1.html",
-  "PrivateKey": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_crypto.keys.keysPBM.PrivateKey-1.html",
-  "PublicKey": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_crypto.keys.keysPBM.PublicKey-1.html",
-  "KeyTypes": "https://libp2p.github.io/js-libp2p/types/_libp2p_crypto.keys.KeyTypes.html",
-  "./keys:KeyTypes": "https://libp2p.github.io/js-libp2p/types/_libp2p_crypto.keys.KeyTypes.html",
-  "supportedKeys": "https://libp2p.github.io/js-libp2p/variables/_libp2p_crypto.keys.supportedKeys.html",
-  "./keys:supportedKeys": "https://libp2p.github.io/js-libp2p/variables/_libp2p_crypto.keys.supportedKeys.html",
-  "generateEphemeralKeyPair": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.generateEphemeralKeyPair.html",
-  "generateKeyPair": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.generateKeyPair.html",
-  "./keys:generateKeyPair": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.generateKeyPair.html",
-  "generateKeyPairFromSeed": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.generateKeyPairFromSeed.html",
-  "./keys:generateKeyPairFromSeed": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.generateKeyPairFromSeed.html",
-  "importKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.importKey.html",
-  "./keys:importKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.importKey.html",
-  "keyStretcher": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.keyStretcher.html",
-  "marshalPrivateKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.marshalPrivateKey.html",
-  "./keys:marshalPrivateKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.marshalPrivateKey.html",
-  "marshalPublicKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.marshalPublicKey.html",
-  "./keys:marshalPublicKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.marshalPublicKey.html",
-  "unmarshalPrivateKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.unmarshalPrivateKey.html",
-  "./keys:unmarshalPrivateKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.unmarshalPrivateKey.html",
-  "unmarshalPublicKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.unmarshalPublicKey.html",
-  "./keys:unmarshalPublicKey": "https://libp2p.github.io/js-libp2p/functions/_libp2p_crypto.keys.unmarshalPublicKey.html"
-}