libssh: The SSH Public Key Infrastructure

libssh 0.7.4

Functions
The SSH Public Key Infrastructure
The libssh API

Functions for the creation, importation and manipulation of public and private keys in the context of the SSH protocol. More...

## Functions
void | ssh_key_clean (ssh_key key)
| clean up the key and deallocate all existing keys More...
int | ssh_key_cmp (const ssh_key k1, const ssh_key k2, enum ssh_keycmp_e what)
| Compare keys if they are equal. More...
void | ssh_key_free (ssh_key key)
| deallocate a SSH key More...
int | ssh_key_is_private (const ssh_key k)
| Check if the key is a private key. More...
int | ssh_key_is_public (const ssh_key k)
| Check if the key has/is a public key. More...
ssh_key | ssh_key_new (void)
| creates a new empty SSH key More...
enum ssh_keytypes_e | ssh_key_type (const ssh_key key)
| returns the type of a ssh key More...
enum ssh_keytypes_e | ssh_key_type_from_name (const char *name)
| Convert a ssh key name to a ssh key type. More...
const char * | ssh_key_type_to_char (enum ssh_keytypes_e type)
| Convert a key type to a string. More...
int | ssh_pki_export_privkey_file (const ssh_key privkey, const char *passphrase, ssh_auth_callback auth_fn, void *auth_data, const char *filename)
| Export a private key to a pem file on disk, or OpenSSH format for keytype ssh-ed25519. More...
int | ssh_pki_export_privkey_to_pubkey (const ssh_key privkey, ssh_key *pkey)
| Create a public key from a private key. More...
int | ssh_pki_export_pubkey_base64 (const ssh_key key, char **b64_key)
| Convert a public key to a base64 encoded key. More...
int | ssh_pki_generate (enum ssh_keytypes_e type, int parameter, ssh_key *pkey)
| Generates a keypair. More...
int | ssh_pki_import_privkey_base64 (const char *b64_key, const char *passphrase, ssh_auth_callback auth_fn, void *auth_data, ssh_key *pkey)
| import a base64 formated key from a memory c-string More...
int | ssh_pki_import_privkey_file (const char *filename, const char *passphrase, ssh_auth_callback auth_fn, void *auth_data, ssh_key *pkey)
| Import a key from a file. More...
int | ssh_pki_import_pubkey_base64 (const char *b64_key, enum ssh_keytypes_e type, ssh_key *pkey)
| Import a base64 formated public key from a memory c-string. More...
int | ssh_pki_import_pubkey_file (const char *filename, ssh_key *pkey)
| Import a public key from the given filename. More...
const char * | ssh_pki_key_ecdsa_name (const ssh_key key)
| returns the ECDSA key name ("ecdsa-sha2-nistp256" for example) More...

## Detailed Description

Functions for the creation, importation and manipulation of public and private keys in the context of the SSH protocol.

## Function Documentation

## ◆ ssh_key_clean()

void ssh_key_clean | ( | ssh_key | key | ) |

clean up the key and deallocate all existing keys

Parameters

  [in] | key | ssh_key to clean

Referenced by ssh_key_free().

## ◆ ssh_key_cmp()

int ssh_key_cmp | ( | const ssh_key | k1,
|  | const ssh_key | k2,
|  | enum ssh_keycmp_e | what
| ) |  |

Compare keys if they are equal.

Parameters

  [in] | k1 | The first key to compare.
  [in] | k2 | The second key to compare.
  [in] | what | What part or type of the key do you want to compare.

Returns
  0 if equal, 1 if not.

References ssh_key_is_private().

## ◆ ssh_key_free()

void ssh_key_free | ( | ssh_key | key | ) |

deallocate a SSH key

Parameters

  [in] | key | ssh_key handle to free

References ssh_key_clean().

Referenced by ssh_bind_free(), ssh_message_free(), and ssh_pki_generate().

## ◆ ssh_key_is_private()

int ssh_key_is_private | ( | const ssh_key | k | ) |

Check if the key is a private key.

Parameters

  [in] | k | The key to check.

Returns
  1 if it is a private key, 0 if not.

Referenced by ssh_key_cmp(), ssh_pki_export_privkey_file(), ssh_pki_export_privkey_to_pubkey(), and ssh_userauth_publickey().

## ◆ ssh_key_is_public()

int ssh_key_is_public | ( | const ssh_key | k | ) |

Check if the key has/is a public key.

Parameters

  [in] | k | The key to check.

Returns
  1 if it is a public key, 0 if not.

Referenced by ssh_userauth_try_publickey().

## ◆ ssh_key_new()

ssh_key ssh_key_new | ( | void |  | ) |

creates a new empty SSH key

Returns
  an empty ssh_key handle, or NULL on error.

Referenced by ssh_pki_generate().

## ◆ ssh_key_type()

enum ssh_keytypes_e ssh_key_type | ( | const ssh_key | key | ) |

returns the type of a ssh key

Parameters

  [in] | key | the ssh_key handle

Returns
  one of SSH_KEYTYPE_RSA,SSH_KEYTYPE_DSS,SSH_KEYTYPE_RSA1
  SSH_KEYTYPE_UNKNOWN if the type is unknown

## ◆ ssh_key_type_from_name()

enum ssh_keytypes_e ssh_key_type_from_name | ( | const char * | name | ) |

Convert a ssh key name to a ssh key type.

Parameters

  [in] | name | The name to convert.

Returns
  The enum ssh key type.

Referenced by ssh_pki_import_pubkey_file().

## ◆ ssh_key_type_to_char()

const char* ssh_key_type_to_char | ( | enum ssh_keytypes_e | type | ) |

Convert a key type to a string.

Parameters

  [in] | type | The type to convert.

Returns
  A string for the keytype or NULL if unknown.

Referenced by ssh_pki_generate().

## ◆ ssh_pki_export_privkey_file()

int ssh_pki_export_privkey_file | ( | const ssh_key | privkey,
|  | const char * | passphrase,
|  | ssh_auth_callback | auth_fn,
|  | void * | auth_data,
|  | const char * | filename
| ) |  |

Export a private key to a pem file on disk, or OpenSSH format for keytype ssh-ed25519.

Parameters

  [in] | privkey | The private key to export.
  [in] | passphrase | The passphrase to use to encrypt the key with or NULL. An empty string means no passphrase.
  [in] | auth_fn | An auth function you may want to use or NULL.
  [in] | auth_data | Private data passed to the auth function.
  [in] | filename | The path where to store the pem file.

Returns
  SSH_OK on success, SSH_ERROR on error.

References ssh_key_is_private(), and SSH_LOG_FUNCTIONS.

## ◆ ssh_pki_export_privkey_to_pubkey()

int ssh_pki_export_privkey_to_pubkey | ( | const ssh_key | privkey,
|  | ssh_key * | pkey
| ) |  |

Create a public key from a private key.

Parameters

  [in] | privkey | The private key to get the public key from.
  [out] | pkey | A pointer to store the newly allocated public key. You NEED to free the key.

Returns
  SSH_OK on success, SSH_ERROR on error.

See also
  ssh_key_free()

References ssh_key_is_private().

## ◆ ssh_pki_export_pubkey_base64()

int ssh_pki_export_pubkey_base64 | ( | const ssh_key | key,
|  | char ** | b64_key
| ) |  |

Convert a public key to a base64 encoded key.

Parameters

  [in] | key | The key to hash
  [out] | b64_key | A pointer to store the allocated base64 encoded key. You need to free the buffer.

Returns
  SSH_OK on success, SSH_ERROR on error.

See also
  ssh_string_free_char()

References ssh_string_data(), ssh_string_free(), and ssh_string_len().

## ◆ ssh_pki_generate()

int ssh_pki_generate | ( | enum ssh_keytypes_e | type,
|  | int | parameter,
|  | ssh_key * | pkey
| ) |  |

Generates a keypair.

Parameters

  [in] | type | Type of key to create
  [in] | parameter | Parameter to the creation of key: rsa : length of the key in bits (e.g. 1024, 2048, 4096) dsa : length of the key in bits (e.g. 1024, 2048, 3072) ecdsa : bits of the key (e.g. 256, 384, 512)
  [out] | pkey | A pointer to store the allocated private key. You need to free the memory.

Returns
  SSH_OK on success, SSH_ERROR on error.

Warning
  Generating a key pair may take some time.

References ssh_key_free(), ssh_key_new(), ssh_key_type_to_char(), and ssh_pki_key_ecdsa_name().

## ◆ ssh_pki_import_privkey_base64()

int ssh_pki_import_privkey_base64 | ( | const char * | b64_key,
|  | const char * | passphrase,
|  | ssh_auth_callback | auth_fn,
|  | void * | auth_data,
|  | ssh_key * | pkey
| ) |  |

import a base64 formated key from a memory c-string

Parameters

  [in] | b64_key | The c-string holding the base64 encoded key
  [in] | passphrase | The passphrase to decrypt the key, or NULL
  [in] | auth_fn | An auth function you may want to use or NULL.
  [in] | auth_data | Private data passed to the auth function.
  [out] | pkey | A pointer where the allocated key can be stored. You need to free the memory.

Returns
  SSH_ERROR in case of error, SSH_OK otherwise.

See also
  ssh_key_free()

Referenced by ssh_pki_import_privkey_file().

## ◆ ssh_pki_import_privkey_file()

int ssh_pki_import_privkey_file | ( | const char * | filename,
|  | const char * | passphrase,
|  | ssh_auth_callback | auth_fn,
|  | void * | auth_data,
|  | ssh_key * | pkey
| ) |  |

Import a key from a file.

Parameters

  [in] | filename | The filename of the the private key.
  [in] | passphrase | The passphrase to decrypt the private key. Set to NULL if none is needed or it is unknown.
  [in] | auth_fn | An auth function you may want to use or NULL.
  [in] | auth_data | Private data passed to the auth function.
  [out] | pkey | A pointer to store the allocated ssh_key. You need to free the key.

Returns
  SSH_OK on success, SSH_EOF if the file doesn't exist or permission denied, SSH_ERROR otherwise.

See also
  ssh_key_free()

References ssh_pki_import_privkey_base64().

## ◆ ssh_pki_import_pubkey_base64()

int ssh_pki_import_pubkey_base64 | ( | const char * | b64_key,
|  | enum ssh_keytypes_e | type,
|  | ssh_key * | pkey
| ) |  |

Import a base64 formated public key from a memory c-string.

Parameters

  [in] | b64_key | The base64 key to format.
  [in] | type | The type of the key to format.
  [out] | pkey | A pointer where the allocated key can be stored. You need to free the memory.

Returns
  SSH_OK on success, SSH_ERROR on error.

See also
  ssh_key_free()

Referenced by ssh_pki_import_pubkey_file().

## ◆ ssh_pki_import_pubkey_file()

int ssh_pki_import_pubkey_file | ( | const char * | filename,
|  | ssh_key * | pkey
| ) |  |

Import a public key from the given filename.

Parameters

  [in] | filename | The path to the public key.
  [out] | pkey | A pointer to store the allocated public key. You need to free the memory.

Returns
  SSH_OK on success, SSH_EOF if the file doesn't exist or permission denied, SSH_ERROR otherwise.

See also
  ssh_key_free()

References ssh_key_type_from_name(), and ssh_pki_import_pubkey_base64().

## ◆ ssh_pki_key_ecdsa_name()

const char* ssh_pki_key_ecdsa_name | ( | const ssh_key | key | ) |

returns the ECDSA key name ("ecdsa-sha2-nistp256" for example)

Parameters

  [in] | key | the ssh_key whose ECDSA name to get

Returns
  the ECDSA key name ("ecdsa-sha2-nistp256" for example)
  "unknown" if the ECDSA key name is not known

Referenced by ssh_pki_generate().