libssh: The SSH Public Key Infrastructure

libssh 0.7.3

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

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

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().

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().

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_bind_listen(), ssh_bind_new(), ssh_bind_options_set(), ssh_free(), ssh_message_free(), ssh_pki_export_privkey_file(), ssh_pki_generate(), ssh_userauth_agent(), ssh_userauth_password(), ssh_userauth_publickey_auto(), and ssh_write_knownhost().

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(), ssh_pki_export_pubkey_base64(), and ssh_userauth_publickey().

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 ssh_key_new | ( | void |  | ) |

creates a new empty SSH key

Returns
  an empty ssh_key handle, or NULL on error.

Referenced by ssh_pki_export_privkey_file(), ssh_pki_generate(), and ssh_userauth_password().

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

Referenced by ssh_bind_new(), and ssh_bind_options_set().

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_export_pubkey_base64(), ssh_pki_import_pubkey_base64(), and ssh_pki_import_pubkey_file().

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_export_privkey_file(), ssh_pki_generate(), and ssh_userauth_password().

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_free(), ssh_key_is_private(), ssh_key_new(), ssh_key_type_to_char(), SSH_LOG_FUNCTIONS, ssh_pki_key_ecdsa_name(), ssh_print_hexa(), ssh_string_burn(), ssh_string_data(), ssh_string_free(), ssh_string_get_char(), and ssh_string_len().

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().

Referenced by ssh_userauth_publickey_auto().

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_buffer_free(), ssh_buffer_get_begin(), ssh_buffer_get_len(), ssh_buffer_new(), ssh_buffer_set_secure(), ssh_key_is_private(), ssh_key_type_from_name(), SSH_LOG_FUNCTIONS, ssh_print_hexa(), ssh_string_data(), ssh_string_fill(), ssh_string_free(), ssh_string_from_char(), ssh_string_get_char(), ssh_string_len(), and ssh_string_new().

Referenced by ssh_write_knownhost().

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().

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().

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().

Referenced by ssh_bind_new(), ssh_bind_options_set(), and ssh_userauth_publickey_auto().

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()

References ssh_buffer_free(), ssh_buffer_new(), ssh_key_type_from_name(), ssh_string_data(), ssh_string_free(), ssh_string_get_char(), and ssh_string_len().

Referenced by 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().

Referenced by ssh_userauth_publickey_auto().

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_export_privkey_file(), and ssh_pki_generate().