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)

ssh_key	ssh_key_new (void)
	creates a new empty SSH key

ssh_key	ssh_key_dup (const ssh_key key)
	duplicates the key

void	ssh_key_clean (ssh_key key)
	clean up the key and deallocate all existing keys

void	ssh_key_free (ssh_key key)
	deallocate a SSH key

enum ssh_keytypes_e	ssh_key_type (const ssh_key key)
	returns the type of a ssh key

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.

const char *	ssh_key_type_to_char (enum ssh_keytypes_e type)
	Convert a key type to a string.

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.

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.

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.

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.

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.

enum ssh_keytypes_e	ssh_key_type_from_name (const char *name)
	Convert a ssh key name to a ssh key type.

enum ssh_keytypes_e	ssh_key_type_plain (enum ssh_keytypes_e type)
	Get the public key type corresponding to a certificate type.

int	ssh_key_is_public (const ssh_key k)
	Check if the key has/is a public key.

int	ssh_key_is_private (const ssh_key k)
	Check if the key is a private key.

int	ssh_key_cmp (const ssh_key k1, const ssh_key k2, enum ssh_keycmp_e what)
	Compare keys if they are equal.

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

int	ssh_pki_export_privkey_base64_format (const ssh_key privkey, const char passphrase, ssh_auth_callback auth_fn, void auth_data, char **b64_key, enum ssh_file_format_e format)
	Convert a private key to a base64 encoded key in given format.

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.

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.

int	ssh_pki_export_privkey_file_format (const ssh_key privkey, const char passphrase, ssh_auth_callback auth_fn, void auth_data, const char *filename, enum ssh_file_format_e format)
	Export a private key to a file in format specified in the argument.

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.

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.

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

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.

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.

int	ssh_pki_generate (enum ssh_keytypes_e type, int parameter, ssh_key *pkey)
	Generates a key pair.

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_blob (const ssh_key key, ssh_string *pblob)

int	ssh_pki_export_privkey_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.

int	ssh_pki_export_pubkey_file (const ssh_key key, const char *filename)
	Export public key to file.

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.

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

ssh_key ssh_key_dup ( const ssh_key key )

duplicates the key

Parameters

key	An ssh_key to duplicate

Returns: A duplicated ssh_key key

◆ 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.
[in]	hash_type	The hash 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_ECDSA_P256, SSH_KEYTYPE_ECDSA_P384, SSH_KEYTYPE_ECDSA_P521, SSH_KEYTYPE_ED25519, 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 public 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_base64_format()

int ssh_pki_export_privkey_base64_format	(	const ssh_key	privkey,
		const char *	passphrase,
		ssh_auth_callback	auth_fn,
		void *	auth_data,
		char **	b64_key,
		enum ssh_file_format_e	format )

Convert a private key to a base64 encoded key in given format.

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().
[in]	format	The file format (OpenSSH, PEM, or default)

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

int ssh_pki_export_privkey_file_format	(	const ssh_key	privkey,
		const char *	passphrase,
		ssh_auth_callback	auth_fn,
		void *	auth_data,
		const char *	filename,
		enum ssh_file_format_e	format )

Export a private key to a file in format specified in the argument.

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.
[in]	format	The file format (OpenSSH, PEM, or default)

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

int ssh_pki_export_pubkey_file	(	const ssh_key	key,
		const char *	filename )

Export public key to file.

Exports the public key in AuthorizedKeysFile acceptable format. For more information see man sshd

Parameters

key	A key to export
filename	The name of the output file

Returns: SSH_OK on success, SSH_ERROR otherwise.

◆ ssh_pki_generate()

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

Generates a key pair.

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)
[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_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