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

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

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_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_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_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] 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(), 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] 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:
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] 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().

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_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(), 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] 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_generate().


Generated on 24 Jun 2015 for libssh by  doxygen 1.6.1