KEY.md

Key API

• key.gen
• key.list
• key.rm
• key.rename
• key.export
• key.import

key.gen

Generate a new key

ipfs.key.gen(name, options)

Where:

• name is a local name for the key
• options is an object that contains following properties
  • 'type' - the key type, one of 'rsa', 'ed25519' (Note: js-ipfs will not support 'ed25519' until libp2p/js-libp2p-crypto#145 is resolved)
  • 'size' - the key size in bits

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.

key.list

List all the keys

ipfs.key.list()

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.

key.rm

Remove a key

ipfs.key.rm(name)

Where:

• name is the local name for the key

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.

key.rename

Rename a key

ipfs.key.rename(oldName, newName)

Where:

• oldName is the local name for the key
• newName a new name for key

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.

key.export

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

ipfs.key.export(name, password)

Where:

• name is the local name for the key
• password is the password to protect the key

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.

key.import

Import a PEM encoded password protected PKCS #8 key

ipfs.key.import(name, pem, password)

Where:

• name is a local name for the key
• pem is the PEM encoded key
• password is the password that protects the PEM key

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.