libssh: The SSH Public Key Infrastructure

libssh 0.10.4 The SSH library

Loading...
Searching...
No Matches
Macros | Functions
The SSH Public Key Infrastructure
The libssh API

## Macros
#define | MAX_LINE_SIZE 4096
#define | PKCS11_URI "pkcs11:"

## 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...
enum ssh_digest_e | ssh_key_hash_from_name (const char *name)
int | ssh_key_algorithm_allowed (ssh_session session, const char *type)
| Checks the given key against the configured allowed public key algorithm types. More...
bool | ssh_key_size_allowed_rsa (int min_size, ssh_key key)
bool | ssh_key_size_allowed (ssh_session session, ssh_key key)
| Check the given key is acceptable in regards to the key size policy specified by the configuration. 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...
enum ssh_keytypes_e | ssh_key_type_plain (enum ssh_keytypes_e type)
| Get the pubic key type corresponding to a certificate 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 formatted 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 private key from a file or a PKCS #11 device. 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 formatted public key from a memory c-string. More...
int | ssh_pki_import_pubkey_blob (const ssh_string key_blob, ssh_key *pkey)
bool | ssh_pki_is_uri (const char *cmp)
| Detect if the pathname in cmp is a PKCS #11 URI. More...
char * | ssh_pki_export_pub_uri_from_priv_uri (const char *priv_uri)
| export a Public PKCS #11 URI from a Private PKCS #11 URI by replacing "type=private" to "type=public". TODO: Improve the parser More...
int | ssh_pki_import_pubkey_file (const char *filename, ssh_key *pkey)
| Import a public key from a file or a PKCS #11 device. More...
int | ssh_pki_import_cert_base64 (const char *b64_cert, enum ssh_keytypes_e type, ssh_key *pkey)
| Import a base64 formatted 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 | pki_key_check_hash_compatible (ssh_key key, enum ssh_digest_e hash_type)
int | ssh_pki_signature_verify (ssh_session session, ssh_signature sig, const ssh_key key, const unsigned char *input, size_t input_len)
ssh_signature | pki_do_sign (const ssh_key privkey, const unsigned char *input, size_t input_len, enum ssh_digest_e hash_type)
ssh_string | ssh_pki_do_sign (ssh_session session, ssh_buffer sigbuf, const ssh_key privkey, enum ssh_digest_e hash_type)
ssh_string | ssh_pki_do_sign_agent (ssh_session session, struct ssh_buffer_struct *buf, const ssh_key pubkey)
ssh_string | ssh_srv_pki_do_sign_sessionid (ssh_session session, const ssh_key privkey, const enum ssh_digest_e digest)
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] | session | The 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] | key | ssh_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] | 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.

## ◆ ssh_key_free()

void ssh_key_free | ( | ssh_key | key | ) |

deallocate a SSH key

Parameters

  [in] | key | ssh_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] | session | SSH session.
  [in] | type | The 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] | k | The 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] | k | The 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] | type | The algorithm type to convert.

Returns
  A string for the keytype or NULL if unknown.

## ◆ ssh_key_size_allowed()

bool ssh_key_size_allowed | ( | ssh_session | session,
|  | ssh_key | key
| ) |  |

Check the given key is acceptable in regards to the key size policy specified by the configuration.

Parameters

  [in] | session | The SSH session
  [in] | key | The SSH key

Returns
  true if the key is allowed, false otherwise

## ◆ ssh_key_type()

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_ECDSA_P256, SSH_KEYTYPE_ECDSA_P384, SSH_KEYTYPE_ECDSA_P521, SSH_KEYTYPE_ED25519, SSH_KEYTYPE_DSS_CERT01, SSH_KEYTYPE_RSA_CERT01, SSH_KEYTYPE_ECDSA_P256_CERT01, SSH_KEYTYPE_ECDSA_P384_CERT01, SSH_KEYTYPE_ECDSA_P521_CERT01, or SSH_KEYTYPE_ED25519_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] | name | The 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] | name | The name to convert.

Returns
  The enum ssh key algorithm type.

## ◆ ssh_key_type_plain()

enum ssh_keytypes_e ssh_key_type_plain | ( | enum ssh_keytypes_e | type | ) |

Get the pubic key type corresponding to a certificate type.

Parameters

  [in] | type | The certificate or public key type.

Returns
  The matching public key 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] | type | The 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] | session | SSH Session.
  [in] | type | The 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] | certkey | The certificate key.
  [in] | privkey | The 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] | 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.
  [out] | b64_key | A pointer to store the allocated base64 encoded key. You need to free the buffer using ssh_string_from_char().

Returns
  SSH_OK on success, SSH_ERROR on error.

See also
  ssh_string_free_char()

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

## ◆ 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] | 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 using ssh_key_free().

Returns
  SSH_OK on success, SSH_ERROR on error.

See also
  ssh_key_free()

## ◆ ssh_pki_export_pub_uri_from_priv_uri()

char * ssh_pki_export_pub_uri_from_priv_uri | ( | const char * | priv_uri | ) |

export a Public PKCS #11 URI from a Private PKCS #11 URI by replacing "type=private" to "type=public". TODO: Improve the parser

Parameters

  [in] | priv_uri | Private PKCS #11 URI.

Returns
  pointer to the public PKCS #11 URI. You need to free the memory using ssh_string_free_char().

See also
  ssh_string_free_char().

## ◆ 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] | key | The key to hash
  [out] | b64_key | A pointer to store the allocated base64 encoded key. You need to free the buffer using ssh_string_free_char()

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] | 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)
  [out] | pkey | A pointer to store the allocated private key. You need to free the memory using ssh_key_free().

Returns
  SSH_OK on success, SSH_ERROR on error.

Warning
  Generating a key pair may take some time.

See also
  ssh_key_free()

## ◆ 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 formatted certificate from a memory c-string.

Parameters

  [in] | b64_cert | The base64 cert to format.
  [in] | type | The type of the cert to format.
  [out] | pkey | A pointer where the allocated key can be stored. You need to free the memory using ssh_key_free().

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] | filename | The path to the certificate.
  [out] | pkey | A pointer to store the allocated certificate. You need to free the memory using ssh_key_free().

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 formatted 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 using ssh_key_free()

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 private key from a file or a PKCS #11 device.

Parameters

  [in] | filename | The filename of the private key or the PKCS #11 URI corresponding to 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 using ssh_key_free().

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 formatted 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 using ssh_key_free().

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 a file or a PKCS #11 device.

Parameters

  [in] | filename | The filename of the public key or the PKCS #11 URI corresponding to the public key.
  [out] | pkey | A pointer to store the allocated public key. You need to free the memory using ssh_key_free().

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

bool ssh_pki_is_uri | ( | const char * | cmp | ) |

Detect if the pathname in cmp is a PKCS #11 URI.

Parameters

  [in] | cmp | The path to the public/private key or a private/public PKCS #11 URI.

Returns
  true if filename is a URI starting with "pkcs11:" false otherwise.

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