libssh 0.12.1 The SSH library

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

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

Note that comparing private keys is almost never needed. The private key is cryptographically bound to the public key and comparing public keys should always be preferred.

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.

Note that the certificate is just the base64 part (without the key type prefix and comment suffix you can find in the OpenSSH certificate file).

Parameters

  [in] | b64_cert | The base64 cert to import.
  [in] | type | The type of the cert to import.
  [out] | pkey | A pointer where the allocated certificate 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.

Note that the public key is just the base64 part (without the key type prefix and comment suffix you can find in the OpenSSH public key file or known_hosts file).

Parameters

  [in] | b64_key | The base64 key to import.
  [in] | type | The type of the key to import.
  [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