libssh  0.7
Functions
The SSH Public Key Infrastructure

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]keyssh_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]k1The first key to compare.
[in]k2The second key to compare.
[in]whatWhat 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)
int ssh_key_is_private ( const ssh_key  k)

Check if the key is a private key.

Parameters
[in]kThe 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
[in]kThe 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
[in]keythe 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_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]nameThe 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
[in]typeThe 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
[in]privkeyThe private key to export.
[in]passphraseThe passphrase to use to encrypt the key with or NULL. An empty string means no passphrase.
[in]auth_fnAn auth function you may want to use or NULL.
[in]auth_dataPrivate data passed to the auth function.
[in]filenameThe path where to store the pem file.
Returns
SSH_OK on success, SSH_ERROR on error.

References ssh_key_is_private(), SSH_LOG_FUNCTIONS, ssh_string_data(), ssh_string_free(), 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]privkeyThe private key to get the public key from.
[out]pkeyA pointer to store the newly allocated public key. You NEED to free the key.
Returns
A public key, NULL 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]keyThe key to hash
[out]b64_keyA 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().

Referenced by ssh_write_knownhost().

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

Generates a keypair.

Parameters
[in]typeType of key to create
[in]parameterParameter 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]pkeyA 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_keyThe c-string holding the base64 encoded key
[in]passphraseThe passphrase to decrypt the key, or NULL
[in]auth_fnAn auth function you may want to use or NULL.
[in]auth_dataPrivate data passed to the auth function.
[out]pkeyA 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]filenameThe filename of the the private key.
[in]passphraseThe passphrase to decrypt the private key. Set to NULL if none is needed or it is unknown.
[in]auth_fnAn auth function you may want to use or NULL.
[in]auth_dataPrivate data passed to the auth function.
[out]pkeyA 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_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_keyThe base64 key to format.
[in]typeThe type of the key to format.
[out]pkeyA 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(), and ssh_string_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
[in]filenameThe path to the public key.
[out]pkeyA 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]keythe 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().