The SSH Public Key Infrastructure

Overview

Functions for the creation, importation and manipulation of public and private keys in the context of the SSH protocol. More…

// global functions

int
ssh_key_cmp(
    const ssh_key k1,
    const ssh_key k2,
    enum ssh_keycmp_e what
);

void
ssh_key_free(ssh_key key);

int
ssh_key_is_private(const ssh_key k);

int
ssh_key_is_public(const ssh_key k);

ssh_key
ssh_key_new(void);

enum ssh_keytypes_e
ssh_key_type(const ssh_key key);

enum ssh_keytypes_e
ssh_key_type_from_name(const char* name);

const char*
ssh_key_type_to_char(enum ssh_keytypes_e type);

int
ssh_pki_export_privkey_file(
    const ssh_key privkey,
    const char* passphrase,
    ssh_auth_callback auth_fn,
    void* auth_data,
    const char* filename
);

int
ssh_pki_export_privkey_to_pubkey(
    const ssh_key privkey,
    ssh_key* pkey
);

int
ssh_pki_export_pubkey_base64(
    const ssh_key key,
    char** b64_key
);

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

int
ssh_pki_import_privkey_base64(
    const char* b64_key,
    const char* passphrase,
    ssh_auth_callback auth_fn,
    void* auth_data,
    ssh_key* pkey
);

int
ssh_pki_import_privkey_file(
    const char* filename,
    const char* passphrase,
    ssh_auth_callback auth_fn,
    void* auth_data,
    ssh_key* pkey
);

int
ssh_pki_import_pubkey_base64(
    const char* b64_key,
    enum ssh_keytypes_e type,
    ssh_key* pkey
);

int
ssh_pki_import_pubkey_file(
    const char* filename,
    ssh_key* pkey
);

const char*
ssh_pki_key_ecdsa_name(const ssh_key key);

void
ssh_key_clean(ssh_key key);

void
_ssh_pki_log(
    const char* function,
    const char* format,
    ...
);

static
int
pki_import_pubkey_buffer(
    ssh_buffer buffer,
    enum ssh_keytypes_e type,
    ssh_key* pkey
);

enum ssh_keytypes_e
pki_privatekey_type_from_string(const char* privkey);

ssh_key
ssh_key_dup(const ssh_key key);

ssh_private_key
ssh_pki_convert_key_to_privatekey(const ssh_key key);

ssh_public_key
ssh_pki_convert_key_to_publickey(const ssh_key key);

ssh_string
ssh_pki_do_sign(
    ssh_session session,
    ssh_buffer sigbuf,
    const ssh_key privkey
);

ssh_string
ssh_pki_do_sign_agent(
    ssh_session session,
    struct ssh_buffer_struct* buf,
    const ssh_key pubkey
);

int
ssh_pki_export_pubkey_blob(
    const ssh_key key,
    ssh_string* pblob
);

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

int
ssh_pki_export_pubkey_rsa1(
    const ssh_key key,
    const char* host,
    char* rsa1,
    size_t rsa1_len
);

int
ssh_pki_export_signature_blob(
    const ssh_signature sig,
    ssh_string* sig_blob
);

int
ssh_pki_import_pubkey_blob(
    const ssh_string key_blob,
    ssh_key* pkey
);

int
ssh_pki_import_signature_blob(
    const ssh_string sig_blob,
    const ssh_key pubkey,
    ssh_signature* psig
);

int
ssh_pki_signature_verify_blob(
    ssh_session session,
    ssh_string sig_blob,
    const ssh_key key,
    unsigned char* digest,
    size_t dlen
);

void
ssh_signature_free(ssh_signature sig);

ssh_signature
ssh_signature_new(void);

ssh_string
ssh_srv_pki_do_sign_sessionid(
    ssh_session session,
    const ssh_key privkey
);

static
int
pki_openssh_import_privkey_blob(
    ssh_buffer key_blob_buffer,
    ssh_key* pkey
);

static
int
pki_private_key_decrypt(
    ssh_string blob,
    const char* passphrase,
    const char* ciphername,
    const char* kdfname,
    ssh_string kdfoptions,
    ssh_auth_callback auth_fn,
    void* auth_data
);

ssh_key
ssh_pki_openssh_privkey_import(
    const char* text_key,
    const char* passphrase,
    ssh_auth_callback auth_fn,
    void* auth_data
);

static
int
pki_openssh_export_privkey_blob(
    const ssh_key privkey,
    ssh_buffer buffer
);

static
int
pki_private_key_encrypt(
    ssh_buffer privkey_buffer,
    const char* passphrase,
    const char* ciphername,
    const char* kdfname,
    ssh_auth_callback auth_fn,
    void* auth_data,
    uint32_t rounds,
    ssh_string salt
);

ssh_string
ssh_pki_openssh_privkey_export(
    const ssh_key privkey,
    const char* passphrase,
    ssh_auth_callback auth_fn,
    void* auth_data
);

Detailed Documentation

Functions for the creation, importation and manipulation of public and private keys in the context of the SSH protocol.

Global Functions

int
ssh_key_cmp(
    const ssh_key k1,
    const ssh_key k2,
    enum ssh_keycmp_e what
)

Compare keys if they are equal.

Parameters:

k1	The first key to compare.
k2	The second key to compare.
what	What part or type of the key do you want to compare.

Returns:

0 if equal, 1 if not.

void
ssh_key_free(ssh_key key)

deallocate a SSH key

Parameters:

key	ssh_key handle to free

int
ssh_key_is_private(const ssh_key k)

Check if the key is a private key.

Parameters:

k	The key to check.

Returns:

1 if it is a private key, 0 if not.

int
ssh_key_is_public(const ssh_key k)

Check if the key has/is a public key.

Parameters:

k	The key to check.

Returns:

1 if it is a public key, 0 if not.

ssh_key
ssh_key_new(void)

creates a new empty SSH key

Returns:

an empty ssh_key handle, or NULL on error.

enum ssh_keytypes_e
ssh_key_type(const ssh_key key)

returns the type of a ssh key

Parameters:

key	the ssh_key handle

Returns:

one of SSH_KEYTYPE_RSA,SSH_KEYTYPE_DSS,SSH_KEYTYPE_RSA1

SSH_KEYTYPE_UNKNOWN if the type is unknown

enum ssh_keytypes_e
ssh_key_type_from_name(const char* name)

Convert a ssh key name to a ssh key type.

Parameters:

name	The name to convert.

Returns:

The enum ssh key type.

const char*
ssh_key_type_to_char(enum ssh_keytypes_e type)

Convert a key type to a string.

Parameters:

type	The type to convert.

Returns:

A string for the keytype or NULL if unknown.

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:

privkey	The private key to export.
passphrase	The passphrase to use to encrypt the key with or NULL. An empty string means no passphrase.
auth_fn	An auth function you may want to use or NULL.
auth_data	Private data passed to the auth function.
filename	The path where to store the pem file.

Returns:

SSH_OK on success, SSH_ERROR on error.

int
ssh_pki_export_privkey_to_pubkey(
    const ssh_key privkey,
    ssh_key* pkey
)

Create a public key from a private key.

Parameters:

privkey	The private key to get the public key from.
pkey	A pointer to store the newly allocated public key. You NEED to free the key.

Returns:

SSH_OK on success, SSH_ERROR on error.

See also:

ssh_key_free()

int
ssh_pki_export_pubkey_base64(
    const ssh_key key,
    char** b64_key
)

Convert a public key to a base64 encoded key.

Parameters:

key	The key to hash
b64_key	A pointer to store the allocated base64 encoded key. You need to free the buffer.

Returns:

SSH_OK on success, SSH_ERROR on error.

See also:

ssh_string_free_char()

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

Generates a keypair.

Warning

Generating a key pair may take some time.

Parameters:

type	Type of key to create
parameter	Parameter to the creation of key: rsa : length of the key in bits (e.g. 1024, 2048, 4096) dsa : length of the key in bits (e.g. 1024, 2048, 3072) ecdsa : bits of the key (e.g. 256, 384, 512)
pkey	A pointer to store the allocated private key. You need to free the memory.

Returns:

SSH_OK on success, SSH_ERROR on error.

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 formated key from a memory c-string

Parameters:

b64_key	The c-string holding the base64 encoded key
passphrase	The passphrase to decrypt the key, or NULL
auth_fn	An auth function you may want to use or NULL.
auth_data	Private data passed to the auth function.
pkey	A pointer where the allocated key can be stored. You need to free the memory.

Returns:

SSH_ERROR in case of error, SSH_OK otherwise.

See also:

ssh_key_free()

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 key from a file.

Parameters:

filename	The filename of the the private key.
passphrase	The passphrase to decrypt the private key. Set to NULL if none is needed or it is unknown.
auth_fn	An auth function you may want to use or NULL.
auth_data	Private data passed to the auth function.
pkey	A pointer to store the allocated ssh_key. You need to free the key.

Returns:

SSH_OK on success, SSH_EOF if the file doesn’t exist or permission denied, SSH_ERROR otherwise.

See also:

ssh_key_free()

int
ssh_pki_import_pubkey_base64(
    const char* b64_key,
    enum ssh_keytypes_e type,
    ssh_key* pkey
)

Import a base64 formated public key from a memory c-string.

Parameters:

b64_key	The base64 key to format.
type	The type of the key to format.
pkey	A pointer where the allocated key can be stored. You need to free the memory.

Returns:

SSH_OK on success, SSH_ERROR on error.

See also:

ssh_key_free()

int
ssh_pki_import_pubkey_file(
    const char* filename,
    ssh_key* pkey
)

Import a public key from the given filename.

Parameters:

filename	The path to the public key.
pkey	A pointer to store the allocated public key. You need to free the memory.

Returns:

SSH_OK on success, SSH_EOF if the file doesn’t exist or permission denied, SSH_ERROR otherwise.

See also:

ssh_key_free()

const char*
ssh_pki_key_ecdsa_name(const ssh_key key)

returns the ECDSA key name (“ecdsa-sha2-nistp256” for example)

Parameters:

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

void
ssh_key_clean(ssh_key key)

clean up the key and deallocate all existing keys

Parameters:

key	ssh_key to clean

static
int
pki_openssh_import_privkey_blob(
    ssh_buffer key_blob_buffer,
    ssh_key* pkey
)

static
int
pki_private_key_decrypt(
    ssh_string blob,
    const char* passphrase,
    const char* ciphername,
    const char* kdfname,
    ssh_string kdfoptions,
    ssh_auth_callback auth_fn,
    void* auth_data
)

decrypts an encrypted ed25519 private key blob