libssh_pki(3)

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

SYNOPSIS

  Functions
void ssh_key_clean (ssh_key key)
clean up the key and deallocate all existing keys
int ssh_key_cmp (const ssh_key k1, const ssh_key k2, enum ssh_keycmp_e what)
Compare keys if they are equal.
void ssh_key_free (ssh_key key)
deallocate a SSH key
int ssh_key_is_private (const ssh_key k)
Check if the key is a private key.
int ssh_key_is_public (const ssh_key k)
Check if the key has/is a public key.
ssh_key ssh_key_new (void)
creates a new empty SSH key
enum ssh_keytypes_e ssh_key_type (const ssh_key key)
returns the type of a ssh key
enum ssh_keytypes_e ssh_key_type_from_name (const char *name)
Convert a ssh key name to a ssh key type.
const char * ssh_key_type_to_char (enum ssh_keytypes_e type)
Convert a key type to a string.
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.
int ssh_pki_export_privkey_to_pubkey (const ssh_key privkey, ssh_key *pkey)
Create a public key from a private key.
int ssh_pki_export_pubkey_base64 (const ssh_key key, char **b64_key)
Convert a public key to a base64 encoded key.
int ssh_pki_generate (enum ssh_keytypes_e type, int parameter, ssh_key *pkey)
Generates a keypair.
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
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.
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.
int ssh_pki_import_pubkey_file (const char *filename, ssh_key *pkey)
Import a public key from the given filename.
const char * ssh_pki_key_ecdsa_name (const ssh_key key)
returns the ECDSA key name ('ecdsa-sha2-nistp256' for example)

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:
    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:
    k1 The first key to compare.
    k2 The second key to compare.
    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:
    key ssh_key handle to free

References ssh_key_clean().

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

  int ssh_key_is_private (const ssh_key k)

Check if the key is a private key.

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

  int ssh_key_is_public (const ssh_key k)

Check if the key has/is a public key.

Parameters:
    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_generate().

  enum ssh_keytypes_e ssh_key_type (const ssh_key key)

returns the type of a ssh key

Parameters:
    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

  enum ssh_keytypes_e ssh_key_type_from_name (const char * name)

Convert a ssh key name to a ssh key type.

Parameters:
    name The name to convert.

Returns:
    The enum ssh key type.

Referenced by 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:
    type The type to convert.

Returns:
    A string for the keytype or NULL if unknown.

Referenced by ssh_pki_generate().

  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:
    privkey The private key to export.
    passphrase The passphrase to use to encrypt the key with or NULL. An empty string means no passphrase.
    auth_fn An auth function you may want to use or NULL.
    auth_data Private data passed to the auth function.
    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.

  int ssh_pki_export_privkey_to_pubkey (const ssh_key privkey, ssh_key * pkey)

Create a public key from a private key.

Parameters:
    privkey The private key to get the public key from.
    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().

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

Convert a public key to a base64 encoded key.

Parameters:
    key The key to hash
    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().

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

Generates a keypair.

Parameters:
    type Type of key to create
    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)
    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:
    b64_key The c-string holding the base64 encoded key
    passphrase The passphrase to decrypt the key, or NULL
    auth_fn An auth function you may want to use or NULL.
    auth_data Private data passed to the auth function.
    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:
    filename The filename of the the private key.
    passphrase The passphrase to decrypt the private key. Set to NULL if none is needed or it is unknown.
    auth_fn An auth function you may want to use or NULL.
    auth_data Private data passed to the auth function.
    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().

  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:
    b64_key The base64 key to format.
    type The type of the key to format.
    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().

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

Import a public key from the given filename.

Parameters:
    filename The path to the public key.
    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().

  const char* ssh_pki_key_ecdsa_name (const ssh_key key)

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

Parameters:
    key the ssh_key whose ECDSA name to get

Returns:
    the ECDSA key name ('ecdsa-sha2-nistp256' for example)

Referenced by ssh_pki_generate().

Author

Generated automatically by Doxygen for libssh from the source code.