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	pki_key_dup_common_init (const ssh_key key, int demote)
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
uint32_t	ssh_key_get_sk_flags (const ssh_key key)
	Get security key (FIDO2) flags for a security key backed ssh_key.
ssh_string	ssh_key_get_sk_application (const ssh_key key)
	Get the application (RP ID) associated with a security key.
ssh_string	ssh_key_get_sk_user_id (const ssh_key key)
	Get a copy of the user ID associated with a resident security key credential.
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_generate_key (enum ssh_keytypes_e type, ssh_pki_ctx pki_context, 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	pki_buffer_pack_sk_priv_data (ssh_buffer buffer, ssh_key key)
int	pki_buffer_unpack_sk_priv_data (ssh_buffer buffer, ssh_key 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	pki_sk_signature_buffer_prepare (const ssh_key key, const ssh_signature sig, const unsigned char input, size_t input_len, ssh_buffer sk_buffer_out)
	Prepare buffer for FIDO2/U2F security key signature verification.
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)
int	sshsig_sign (const void data, size_t data_length, ssh_key privkey, ssh_pki_ctx pki_context, const char sig_namespace, enum sshsig_digest_e hash_alg, char **signature)
	Signs data in sshsig compatible format.
int	sshsig_verify (const void data, size_t data_length, const char signature, const char sig_namespace, ssh_key sign_key)
	Verifies an sshsig formatted signature against data.
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_pki_ctx	ssh_pki_ctx_new (void)
	Allocate a new generic PKI context container.
void	ssh_pki_ctx_free (ssh_pki_ctx context)
	Free a generic PKI context container.
int	ssh_pki_ctx_options_set (ssh_pki_ctx context, enum ssh_pki_options_e option, const void *value)
	Set various options for a PKI context.
int	ssh_pki_ctx_set_sk_pin_callback (ssh_pki_ctx context, ssh_auth_callback pin_callback, void *userdata)
	Set the PIN callback function to get the PIN for security key authenticator access.
int	ssh_pki_ctx_sk_callbacks_option_set (ssh_pki_ctx context, const char name, const char value, bool required)
	Set a security key (FIDO2/U2F) callback option in the context. These options are passed to the sk_callbacks during enroll/sign/load_resident_keys operations.
int	ssh_pki_ctx_sk_callbacks_options_clear (ssh_pki_ctx context)
	Clear all sk_callbacks options.
int	ssh_pki_ctx_get_sk_attestation_buffer (const struct ssh_pki_ctx_struct context, ssh_buffer attestation_buffer)
	Get a copy of the attestation buffer from a PKI context.
ssh_pki_ctx	ssh_pki_ctx_dup (const ssh_pki_ctx context)
	Duplicate an existing PKI context.
int	pki_sk_enroll_key (ssh_pki_ctx context, enum ssh_keytypes_e key_type, ssh_key *enrolled_key_result)
	Enroll a new security key using a U2F/FIDO2 authenticator.
ssh_signature	pki_sk_do_sign (ssh_pki_ctx context, const ssh_key key, const unsigned char *data, size_t data_len)
int	ssh_sk_resident_keys_load (const struct ssh_pki_ctx_struct pki_context, ssh_key resident_keys_result, size_t num_keys_found_result)
	Load resident keys from FIDO2 security keys.
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

◆ pki_sk_enroll_key()

int pki_sk_enroll_key	(	ssh_pki_ctx	context,
		enum ssh_keytypes_e	key_type,
		ssh_key *	enrolled_key_result )

Enroll a new security key using a U2F/FIDO2 authenticator.

Creates a new security key credential configured according to the parameters in the PKI context. This function handles key enrollment for both ECDSA and Ed25519 algorithms, generates appropriate challenges, and returns the enrolled key with optional attestation data.

The PKI context must be configured with appropriate security key parameters using ssh_pki_ctx_options_set() before calling this function. Required options include SSH_PKI_OPTION_SK_APPLICATION, SSH_PKI_OPTION_SK_USER_ID, and SSH_PKI_OPTION_SK_CALLBACKS.

Parameters

[in]	context	The PKI context containing security key configuration and parameters
[in]	key_type	The type of key to enroll (SSH_KEYTYPE_SK_ECDSA or SSH_KEYTYPE_SK_ED25519)
[out]	enrolled_key_result	Pointer to store the enrolled ssh_key

Returns: SSH_OK on success, SSH_ERROR on failure

See also: ssh_pki_ctx_new(); ssh_pki_ctx_options_set(); ssh_pki_ctx_get_sk_attestation_buffer()

◆ pki_sk_signature_buffer_prepare()

int pki_sk_signature_buffer_prepare	(	const ssh_key	key,
		const ssh_signature	sig,
		const unsigned char *	input,
		size_t	input_len,
		ssh_buffer *	sk_buffer_out )

Prepare buffer for FIDO2/U2F security key signature verification.

This function creates a buffer containing the application hash, flags, counter, and input hash for FIDO/U2F key signature verification.

Parameters

key	The SSH key containing sk_application
sig	The signature containing sk_flags and sk_counter
input	The input data to hash
input_len	Length of the input data
sk_buffer_out	Pointer to store the created buffer

Returns: SSH_OK on success, SSH_ERROR on error

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

ssh_string ssh_key_get_sk_application ( const ssh_key key )

Get the application (RP ID) associated with a security key.

This function returns a freshly allocated ssh_string containing a copy of the application (RP ID). The caller owns the returned ssh_string and must free it with SSH_STRING_FREE() when no longer needed.

Returns NULL if the key is NULL, not a security key type or if the field is not set.

Parameters

[in] key The ssh_key handle.

Returns: ssh_string copy of the application (RP ID) or NULL if not available.

◆ ssh_key_get_sk_flags()

uint32_t ssh_key_get_sk_flags ( const ssh_key key )

Get security key (FIDO2) flags for a security key backed ssh_key.

The returned value contains a bitmask of SSH_SK_* flags (e.g. SSH_SK_USER_PRESENCE_REQD, SSH_SK_USER_VERIFICATION_REQD, etc.). If NULL is passed, then 0 is returned.

Parameters

[in] key The ssh_key handle.

Returns: Bitmask of security key flags, or 0 if not applicable.

◆ ssh_key_get_sk_user_id()

ssh_string ssh_key_get_sk_user_id ( const ssh_key key )

Get a copy of the user ID associated with a resident security key credential.

For resident (discoverable) credentials, authenticators may provide a user id which can be arbitrary binary data to allow for storing multiple keys for the same Relying Party. This function returns a freshly allocated ssh_string containing a copy of that user id. The caller owns the returned ssh_string and must free it with SSH_STRING_FREE() when no longer needed.

Note: This function will only return useful information if the ssh_key passed represents a resident key loaded using the ssh_sk_resident_keys_load() function.

Parameters

[in] key The ssh_key handle.

Returns: ssh_string copy of user id or NULL if not available.

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

ssh_pki_ctx ssh_pki_ctx_dup ( const ssh_pki_ctx context )

Duplicate an existing PKI context.

Creates a new PKI context and copies all fields from the source context. This function performs deep copying for all dynamically allocated fields to ensure independent ownership between source and destination contexts.

Parameters

[in] context The PKI context to copy from

Returns: New PKI context with copied data on success, NULL on failure or if src_context is NULL

◆ ssh_pki_ctx_free()

void ssh_pki_ctx_free ( ssh_pki_ctx context )

Free a generic PKI context container.

Parameters

[in] context The PKI context to free (may be NULL).

See also: ssh_pki_ctx_new()

◆ ssh_pki_ctx_get_sk_attestation_buffer()

int ssh_pki_ctx_get_sk_attestation_buffer	(	const struct ssh_pki_ctx_struct *	context,
		ssh_buffer *	attestation_buffer )

Get a copy of the attestation buffer from a PKI context.

Retrieves a copy of the attestation buffer stored in the context after a key enrollment operation. The attestation buffer contains serialized attestation information in the "ssh-sk-attest-v01" format.

Parameters

[in]	context	The PKI context. Must not be NULL.
[out]	attestation_buffer	Pointer to store a copy of the attestation buffer. Will be set to NULL if no attestation data is available (e.g., authenticator doesn't support attestation, or attestation data was invalid/incomplete).

Returns: SSH_OK on success, SSH_ERROR if context or attestation_buffer is NULL, or if buffer duplication fails.

Note: The caller is responsible for freeing the returned buffer using SSH_BUFFER_FREE().

◆ ssh_pki_ctx_new()

ssh_pki_ctx ssh_pki_ctx_new ( void )

Allocate a new generic PKI context container.

Allocates and default-initializes a new ssh_pki_ctx instance.

Returns: Newly allocated context on success, or NULL on allocation failure.

See also: ssh_pki_ctx_free()

◆ ssh_pki_ctx_options_set()

int ssh_pki_ctx_options_set	(	ssh_pki_ctx	context,
		enum ssh_pki_options_e	option,
		const void *	value )

Set various options for a PKI context.

This function can set all possible PKI context options.

Parameters

[in] context Target PKI context.

option

The option type to set. This could be one of the following:

           - SSH_PKI_OPTION_RSA_KEY_SIZE (int):
             Set the RSA key size in bits for key generation.
             Typically 2048, 3072, or 4096 bits. Must be greater
             than or equal to 1024, as anything below is considered
             insecure.

           - SSH_PKI_OPTION_SK_APPLICATION (const char *):
             The Relying Party identifier (application string) that
             determines which service/domain this security key
             credential will be associated with. This is a required
             field for all security key generation operations.
             The application string typically starts with "ssh:" for
             SSH keys. It is copied internally and can be freed
             after setting.

           - SSH_PKI_SK_OPTION_FLAGS (uint8_t):
             Set FIDO2/U2F operation flags that control how the FIDO2/U2F
             authenticator behaves during generation operations. Multiple
             flags can be combined using bitwise OR operations. The
             pointer must not be NULL.

             Available flags:

             SSH_SK_USER_PRESENCE_REQD: Requires user presence

             SSH_SK_USER_VERIFICATION_REQD: Requires user verification

             SSH_SK_FORCE_OPERATION: Forces generation even if a
             resident key already exists.

             SSH_SK_RESIDENT_KEY: Creates a resident
             key stored on the authenticator.

           - SSH_PKI_OPTION_SK_USER_ID (const char *):
             Sets the user identifier to associate with a resident
             credential during enrollment. When a resident key is
             requested (SSH_SK_RESIDENT_KEY), this ID is stored on the
             authenticator and later used to look up or prevent duplicate
             credentials. Maximum length is SK_MAX_USER_ID_LEN bytes;
             longer values will cause the operation to fail.

           - SSH_PKI_OPTION_SK_CHALLENGE (ssh_buffer):
             Set custom cryptographic challenge data to be included in
             the generation operation. The challenge is signed by the
             authenticator during key generation. If not provided,
             a random 32-byte challenge will be automatically generated.
             The challenge data is copied internally and the caller
             retains ownership of the provided buffer.

           - SSH_PKI_OPTION_SK_CALLBACKS (ssh_sk_callbacks):
             Set the security key callback structure to use custom
             callback functions for FIDO2/U2F operations like enrollment,
             signing, and loading resident keys. The structure is not
             copied so it needs to be valid for the whole context
             lifetime or until replaced.

value The value to set. This is a generic pointer and the datatype which is used should be set according to the option type.

Returns: SSH_OK on success, SSH_ERROR on error.

Warning: When the option value to set is represented via a pointer (e.g const char *, ssh_buffer), the value parameter should be that pointer. Do NOT pass a pointer to a pointer.; When the option value to set is not a pointer (e.g int, uint8_t), the value parameter should be a pointer to the location storing the value to set (int *, uint8_t *).

◆ ssh_pki_ctx_set_sk_pin_callback()

int ssh_pki_ctx_set_sk_pin_callback	(	ssh_pki_ctx	context,
		ssh_auth_callback	pin_callback,
		void *	userdata )

Set the PIN callback function to get the PIN for security key authenticator access.

Parameters

context	The PKI context to modify.
pin_callback	The callback used when the authenticator requires PIN entry for verification.
userdata	A generic pointer that is passed as the userdata argument to the callback function. Can be NULL.

Returns: SSH_OK on success, SSH_ERROR if context is NULL.

Note: The callback and userdata are stored internally in the context structure and must remain valid until the context is freed or replaced.

See also: ssh_auth_callback

◆ ssh_pki_ctx_sk_callbacks_option_set()

int ssh_pki_ctx_sk_callbacks_option_set	(	ssh_pki_ctx	context,
		const char *	name,
		const char *	value,
		bool	required )

Set a security key (FIDO2/U2F) callback option in the context. These options are passed to the sk_callbacks during enroll/sign/load_resident_keys operations.

Both the name and value strings are duplicated internally so the caller retains ownership of the original pointers.

Parameters

[in]	context	The PKI context. Must not be NULL.
[in]	name	option name string. Must not be NULL.
[in]	value	option value string. Must not be NULL.
[in]	required	Set to true if the option is mandatory. If set and the ssh_sk_callbacks do not recognize the option, the operation should fail.

Returns: SSH_OK on success, SSH_ERROR on allocation failure or invalid args.

Note: The option objects are freed automatically when the context is freed via ssh_pki_sk_ctx_free().

See also: ssh_sk_callbacks_struct

◆ ssh_pki_ctx_sk_callbacks_options_clear()

int ssh_pki_ctx_sk_callbacks_options_clear ( ssh_pki_ctx context )

Clear all sk_callbacks options.

Removes and frees all previously set sk_callbacks options from the context.

Parameters

[in] context The PKI context to modify.

Returns: SSH_OK on success, SSH_ERROR if context is NULL.

◆ 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) If parameter is 0, then the default size will be used.
[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_generate_key()

int ssh_pki_generate_key	(	enum ssh_keytypes_e	type,
		ssh_pki_ctx	pki_context,
		ssh_key *	pkey )

Generates a key pair.

Parameters

[in]	type	Type of key to create
[in]	pki_context	PKI context containing various configuration parameters and sub-contexts. Can be NULL for standard SSH key types (RSA, ECDSA, ED25519) where defaults will be used. Can also be NULL for security key types (SK_*), in which case default callbacks and settings will be used automatically.
[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.

See also: ssh_pki_ctx_new(); 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

◆ ssh_sk_resident_keys_load()

int ssh_sk_resident_keys_load	(	const struct ssh_pki_ctx_struct *	pki_context,
		ssh_key **	resident_keys_result,
		size_t *	num_keys_found_result )

Load resident keys from FIDO2 security keys.

This function loads all resident keys (discoverable credentials) stored on FIDO2 security keys using the context's security key callbacks. Resident keys are credentials stored directly on the security key device and can be discovered without prior knowledge of key handles.

Only resident keys with SSH application identifiers (starting with "ssh:") are returned.

Parameters

[in]	pki_context	The PKI context containing security key callbacks. Can be NULL, in which case a default context with default callbacks will be used. If provided, the context must have valid sk_callbacks configured.
[out]	resident_keys_result	Array of ssh_key structs representing the resident keys found and loaded
[out]	num_keys_found_result	Number of resident keys found and loaded

Returns: SSH_OK on success, SSH_ERROR on error

Note: The resident_keys_result array and its contents must be freed by the caller using ssh_sk_resident_key_free() for each key and then freeing the array itself when no longer needed.

◆ sshsig_sign()

int sshsig_sign	(	const void *	data,
		size_t	data_length,
		ssh_key	privkey,
		ssh_pki_ctx	pki_context,
		const char *	sig_namespace,
		enum sshsig_digest_e	hash_alg,
		char **	signature )

Signs data in sshsig compatible format.

Parameters

data	The data to sign
data_length	The length of the data
privkey	The private key to sign with
pki_context	The PKI context. For non-SK keys, this parameter is ignored and can be NULL. For SK keys, can be NULL in which case a default context with default callbacks will be used. If provided, the context must have sk_callbacks set with a valid sign callback implementation. See ssh_pki_ctx_set_sk_callbacks().
sig_namespace	The signature namespace (e.g. "file", "email", etc.)
hash_alg	The hash algorithm to use (SSHSIG_DIGEST_SHA2_256 or SSHSIG_DIGEST_SHA2_512)
signature	Pointer to store the allocated signature string in the armored format. Must be freed with ssh_string_free_char()

Returns: SSH_OK on success, SSH_ERROR on error

◆ sshsig_verify()

int sshsig_verify	(	const void *	data,
		size_t	data_length,
		const char *	signature,
		const char *	sig_namespace,
		ssh_key *	sign_key )

Verifies an sshsig formatted signature against data.

Parameters

data	The data to verify
data_length	The length of the data
signature	The armored sshsig signature
sig_namespace	The expected signature namespace
sign_key	If not NULL, returns the allocated public key that was used for signing this data. Must be freed with ssh_key_free(). Note that this is an output parameter and is not checked against "allowed signers". The caller needs to compare it with expected signer key using ssh_key_cmp().

Returns: SSH_OK on success, SSH_ERROR on verification failure