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