Skip to content

Latest commit

 

History

History
292 lines (208 loc) · 7.37 KB

KEY.md

File metadata and controls

292 lines (208 loc) · 7.37 KB
Raw

Key API

ipfs.key.gen(name, [options])

Generate a new key

Parameters

Name Type Description
name String The name to give the key

Options

An optional object which may have the following keys:

Name Type Default Description
type String 'rsa' The key type, one of 'rsa' or 'ed25519'
size Number 2048 The key size in bits
timeout Number undefined A timeout in ms
signal AbortSignal undefined Can be used to cancel any long running requests started as a result of this call

Returns

Type Description
Promise<Object> An object that describes the key; name and id

Example

const key = await ipfs.key.gen('my-key', {
    type: 'rsa',
    size: 2048
})

console.log(key)
// { id: 'QmYWqAFvLWb2G5A69JGXui2JJXzaHXiUEmQkQgor6kNNcJ',
//  name: 'my-key' }

A great source of examples can be found in the tests for this API.

ipfs.key.list([options])

List all the keys

Parameters

None

Options

An optional object which may have the following keys:

Name Type Default Description
timeout Number undefined A timeout in ms
signal AbortSignal undefined Can be used to cancel any long running requests started as a result of this call

Returns

Type Description
Promise<Array> An array representing all the keys

example of the returned array:

{
  id: 'hash',   // string - the hash of the key
  name: 'self'  // string - the name of the key
}

Example

const keys = await ipfs.key.list()

console.log(keys)
// [
//   { id: 'QmTe4tuceM2sAmuZiFsJ9tmAopA8au71NabBDdpPYDjxAb',
//     name: 'self' },
//   { id: 'QmWETF5QvzGnP7jKq5sPDiRjSM2fzwzNsna4wSBEzRzK6W',
//     name: 'my-key' }
// ]

A great source of examples can be found in the tests for this API.

ipfs.key.rm(name, [options])

Remove a key

Parameters

Name Type Description
name String The name of the key to remove

Options

An optional object which may have the following keys:

Name Type Default Description
timeout Number undefined A timeout in ms
signal AbortSignal undefined Can be used to cancel any long running requests started as a result of this call

Returns

Type Description
Promise<Object> An object that describes the removed key

example of the returned object:

{
  id: 'hash',   // string - the hash of the key
  name: 'self'  // string - the name of the key
}

Example

const key = await ipfs.key.rm('my-key')

console.log(key)
// { id: 'QmWETF5QvzGnP7jKq5sPDiRjSM2fzwzNsna4wSBEzRzK6W',
//   name: 'my-key' }

A great source of examples can be found in the tests for this API.

ipfs.key.rename(oldName, newName, [options])

Rename a key

Parameters

Name Type Description
oldName String The current key name
newName String The desired key name

Options

An optional object which may have the following keys:

Name Type Default Description
timeout Number undefined A timeout in ms
signal AbortSignal undefined Can be used to cancel any long running requests started as a result of this call

Returns

Type Description
Promise<Object> An object that describes the renamed key

Example

const key = await ipfs.key.rename('my-key', 'my-new-key')

console.log(key)
// { id: 'Qmd4xC46Um6s24MradViGLFtMitvrR4SVexKUgPgFjMNzg',
//   was: 'my-key',
//   now: 'my-new-key',
//   overwrite: false }

A great source of examples can be found in the tests for this API.

ipfs.key.export(name, password, [options])

Export a key in a PEM encoded password protected PKCS #8

Parameters

Name Type Description
name String The name of the key to export
password String Password to set on the PEM output

Options

An optional object which may have the following keys:

Name Type Default Description
timeout Number undefined A timeout in ms
signal AbortSignal undefined Can be used to cancel any long running requests started as a result of this call

Returns

Type Description
Promise<String> The string representation of the key

Example

const pem = await ipfs.key.export('self', 'password')

console.log(pem)
// -----BEGIN ENCRYPTED PRIVATE KEY-----
// MIIFDTA/BgkqhkiG9w0BBQ0wMjAaBgkqhkiG9w0BBQwwDQQIpdO40RVyBwACAWQw
// ...
// YA==
// -----END ENCRYPTED PRIVATE KEY-----

A great source of examples can be found in the tests for this API.

ipfs.key.import(name, pem, password, [options])

Import a PEM encoded password protected PKCS #8 key

Parameters

Name Type Description
name String The name of the key to export
pem String The PEM encoded key
password String The password that protects the PEM key

Options

An optional object which may have the following keys:

Name Type Default Description
timeout Number undefined A timeout in ms
signal AbortSignal undefined Can be used to cancel any long running requests started as a result of this call

Returns

Type Description
Promise<Object> An object that describes the new key

Example

const key = await ipfs.key.import('clone', 'password')

console.log(key)
// { id: 'QmQRiays958UM7norGRQUG3tmrLq8pJdmJarwYSk2eLthQ',
//   name: 'clone' }

A great source of examples can be found in the tests for this API.