libssh  0.8.3
The SSH library
Functions
The SSH Public Key Infrastructure
Collaboration diagram for The SSH Public Key Infrastructure:

Functions

enum ssh_keytypes_e pki_privatekey_type_from_string (const char *privkey)
 
const char * ssh_pki_key_ecdsa_name (const ssh_key key)
 returns the ECDSA key name ("ecdsa-sha2-nistp256" for example) More...
 
ssh_key ssh_key_new (void)
 creates a new empty SSH key More...
 
ssh_key ssh_key_dup (const ssh_key key)
 
void ssh_key_clean (ssh_key key)
 clean up the key and deallocate all existing keys More...
 
void ssh_key_free (ssh_key key)
 deallocate a SSH key More...
 
enum ssh_keytypes_e ssh_key_type (const ssh_key key)
 returns the type of a ssh key More...
 
const char * ssh_key_signature_to_char (enum ssh_keytypes_e type, enum ssh_digest_e hash_type)
 Convert a signature type to a string. More...
 
const char * ssh_key_type_to_char (enum ssh_keytypes_e type)
 Convert a key type to a string. More...
 
int ssh_key_algorithm_allowed (ssh_session session, const char *type)
 Checks the given key against the configured allowed public key algorithm types. More...
 
enum ssh_digest_e ssh_key_type_to_hash (ssh_session session, enum ssh_keytypes_e type)
 Convert a key type to a hash type. This is usually unambiguous for all the key types, unless the SHA2 extension (RFC 8332) is negotiated during key exchange. More...
 
const char * ssh_key_get_signature_algorithm (ssh_session session, enum ssh_keytypes_e type)
 Gets signature algorithm name to be used with the given key type. More...
 
enum ssh_keytypes_e ssh_key_type_from_signature_name (const char *name)
 Convert a ssh key algorithm name to a ssh key algorithm type. More...
 
enum ssh_keytypes_e ssh_key_type_from_name (const char *name)
 Convert a ssh key name to a ssh key type. More...
 
int ssh_key_is_public (const ssh_key k)
 Check if the key has/is a public key. More...
 
int ssh_key_is_private (const ssh_key k)
 Check if the key is a private key. 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...
 
ssh_signature ssh_signature_new (void)
 
void ssh_signature_free (ssh_signature sig)
 
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_export_privkey_base64 (const ssh_key privkey, const char *passphrase, ssh_auth_callback auth_fn, void *auth_data, char **b64_key)
 Convert a private key to a pem base64 encoded key, or OpenSSH format for keytype ssh-ed25519. 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_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...
 
ssh_public_key ssh_pki_convert_key_to_publickey (const ssh_key key)
 
ssh_private_key ssh_pki_convert_key_to_privatekey (const ssh_key key)
 
int pki_import_privkey_buffer (enum ssh_keytypes_e type, ssh_buffer buffer, ssh_key *pkey)
 
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_blob (const ssh_string key_blob, ssh_key *pkey)
 
int ssh_pki_import_pubkey_file (const char *filename, ssh_key *pkey)
 Import a public key from the given filename. More...
 
int ssh_pki_import_cert_base64 (const char *b64_cert, enum ssh_keytypes_e type, ssh_key *pkey)
 Import a base64 formated certificate from a memory c-string. More...
 
int ssh_pki_import_cert_blob (const ssh_string cert_blob, ssh_key *pkey)
 
int ssh_pki_import_cert_file (const char *filename, ssh_key *pkey)
 Import a certificate from the given filename. More...
 
int ssh_pki_generate (enum ssh_keytypes_e type, int parameter, ssh_key *pkey)
 Generates a keypair. 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_blob (const ssh_key key, ssh_string *pblob)
 
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_export_pubkey_file (const ssh_key key, const char *filename)
 
int ssh_pki_copy_cert_to_privkey (const ssh_key certkey, ssh_key privkey)
 Copy the certificate part of a public key into a private key. More...
 
int ssh_pki_export_signature_blob (const ssh_signature sig, ssh_string *sig_blob)
 
int ssh_pki_import_signature_blob (const ssh_string sig_blob, const ssh_key pubkey, ssh_signature *psig)
 
int ssh_pki_signature_verify_blob (ssh_session session, ssh_string sig_blob, const ssh_key key, unsigned char *digest, size_t dlen)
 
ssh_string ssh_pki_do_sign (ssh_session session, ssh_buffer sigbuf, const ssh_key privkey)
 
ssh_string ssh_pki_do_sign_agent (ssh_session session, struct ssh_buffer_struct *buf, const ssh_key pubkey)
 
ssh_key ssh_pki_openssh_privkey_import (const char *text_key, const char *passphrase, ssh_auth_callback auth_fn, void *auth_data)
 
ssh_key ssh_pki_openssh_pubkey_import (const char *text_key)
 
ssh_string ssh_pki_openssh_privkey_export (const ssh_key privkey, const char *passphrase, ssh_auth_callback auth_fn, void *auth_data)
 

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

int ssh_key_algorithm_allowed ( ssh_session  session,
const char *  type 
)

Checks the given key against the configured allowed public key algorithm types.

Parameters
[in]sessionThe SSH session [in] type The key algorithm to check
Returns
1 if the key algorithm is allowed 0 otherwise

◆ ssh_key_clean()

void ssh_key_clean ( ssh_key  key)

clean up the key and deallocate all existing keys

Parameters
[in]keyssh_key to clean

◆ 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]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.

◆ ssh_key_free()

void ssh_key_free ( ssh_key  key)

deallocate a SSH key

Parameters
[in]keyssh_key handle to free

◆ ssh_key_get_signature_algorithm()

const char* ssh_key_get_signature_algorithm ( ssh_session  session,
enum ssh_keytypes_e  type 
)

Gets signature algorithm name to be used with the given key type.

Parameters
[in]sessionSSH session.
[in]typeThe algorithm type to convert.
Returns
A string for the keytype or NULL if unknown.

◆ ssh_key_is_private()

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.

◆ ssh_key_is_public()

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.

◆ 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.

◆ ssh_key_signature_to_char()

const char* ssh_key_signature_to_char ( enum ssh_keytypes_e  type,
enum ssh_digest_e  hash_type 
)

Convert a signature type to a string.

Parameters
[in]typeThe algorithm type to convert.
Returns
A string for the keytype or NULL if unknown.

◆ ssh_key_type()

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_ECDSA, SSH_KEYTYPE_ED25519, SSH_KEYTYPE_DSS_CERT01, SSH_KEYTYPE_RSA_CERT01
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]nameThe name to convert.
Returns
The enum ssh key type.

◆ ssh_key_type_from_signature_name()

enum ssh_keytypes_e ssh_key_type_from_signature_name ( const char *  name)

Convert a ssh key algorithm name to a ssh key algorithm type.

Parameters
[in]nameThe name to convert.
Returns
The enum ssh key algorithm type.

◆ 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]typeThe type to convert.
Returns
A string for the keytype or NULL if unknown.

◆ ssh_key_type_to_hash()

enum ssh_digest_e ssh_key_type_to_hash ( ssh_session  session,
enum ssh_keytypes_e  type 
)

Convert a key type to a hash type. This is usually unambiguous for all the key types, unless the SHA2 extension (RFC 8332) is negotiated during key exchange.

Parameters
[in]sessionSSH Session.
[in]typeThe type to convert.
Returns
A hash type to be used.

◆ ssh_pki_copy_cert_to_privkey()

int ssh_pki_copy_cert_to_privkey ( const ssh_key  certkey,
ssh_key  privkey 
)

Copy the certificate part of a public key into a private key.

Parameters
[in]certkeyThe certificate key.
[in]privkeyThe target private key to copy the certificate to.
Returns
SSH_OK on success, SSH_ERROR otherwise.

◆ ssh_pki_export_privkey_base64()

int ssh_pki_export_privkey_base64 ( const ssh_key  privkey,
const char *  passphrase,
ssh_auth_callback  auth_fn,
void *  auth_data,
char **  b64_key 
)

Convert a private key to a pem base64 encoded key, 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.
[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.

◆ 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]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.

◆ 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]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
SSH_OK on success, SSH_ERROR on error.
See also
ssh_key_free()

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

◆ ssh_pki_generate()

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.

◆ ssh_pki_import_cert_base64()

int ssh_pki_import_cert_base64 ( const char *  b64_cert,
enum ssh_keytypes_e  type,
ssh_key pkey 
)

Import a base64 formated certificate from a memory c-string.

Parameters
[in]b64_certThe base64 cert to format.
[in]typeThe type of the cert 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()

◆ ssh_pki_import_cert_file()

int ssh_pki_import_cert_file ( const char *  filename,
ssh_key pkey 
)

Import a certificate from the given filename.

Parameters
[in]filenameThe path to the certificate.
[out]pkeyA pointer to store the allocated certificate. 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()

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

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

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

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

◆ 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]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