Learn how to evaluate and integrate the VNC SDK

We're here if you need help.

RsaKey.h

Manage the RSA key used to securely identify this endpoint. (more...)

Data structures

Modifier and Type Name and Description
struct

vnc_RsaKey_Callback

Callback which receives RSA key details.

Functions

Modifier and Type Name and Description
function vnc_status_t

vnc_RsaKey_getDetails(const vnc_RsaKey_Callback *callback, void *userData, vnc_bool_t generateIfMissing)

Requests the details for the machine’s identifying RSA public key.
function void

vnc_RsaKey_cancelDetails(void *userData)

Cancels any outstanding notifications for the given callback.
function vnc_status_t

vnc_RsaKey_clear()

Removes any stored RSA key from the data store.

Detailed description

Manage the RSA key used to securely identify this endpoint.

Each endpoint is identified securely with an RSA key, used for providing end- to-end verification of the peer’s identity during connections. The RSA key is generated automatically when needed by incoming or outgoing connections.

The vnc_RsaKey_getDetails() function is used to make an asynchronous request for the fingerprint of the local key, and the results are returned via a vnc_RsaKey_Callback::detailsReady callback. Note you can call this function at app start-up to force key generation, which might be useful on slower platforms such as the Raspberry Pi to help prevent connection failures.

Functions

vnc_status_t vnc_RsaKey_getDetails(const vnc_RsaKey_Callback *callback, void *userData, vnc_bool_t generateIfMissing)

Requests the details for the machine’s identifying RSA public key.

The results are returned asynchronously via the vnc_RsaKey_Callback::detailsReady callback.

The key is read from and stored in the data store.

If a callback is already queued with identical userData, a second callback will not be queued (that is, the callback will not be invoked twice).

Return
vnc_success is returned on success, and the callback will be invoked later. In the case of an error, vnc_failure is returned, the callback not be called, and vnc_getLastError() can be used to get the error code.
Parameters
  • callback -

    The callback to be invoked when the key details are ready.

  • generateIfMissing -

    This will normally be vnc_true, so that a key is generated on-demand. If set to vnc_false and a key does not yet exist, a key will not be generated and vnc_RsaKey_getDetails() will return with a NoRsaKeyError error.

Return Value
  • NoRsaKeyError -

    generateIfMissing was set to vnc_false, and no key was found

  • RsaKeyError -

    The loaded key is invalid

  • DataStoreError -

    There was an error reading from the data store or there is no data store

void vnc_RsaKey_cancelDetails(void *userData)

Cancels any outstanding notifications for the given callback.

Has no effect if no callbacks with the given userData are outstanding.

Parameters
  • userData -

    The callback to be cancelled.

vnc_status_t vnc_RsaKey_clear(void)

Removes any stored RSA key from the data store.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Return Value
  • DataStoreError -

    There was an error writing to the data store, or there is no data store

struct vnc_RsaKey_Callback
#include <RsaKey.h>

Callback which receives RSA key details.

Public Members

void(* vnc_RsaKey_Callback::detailsReady) (void *userData, const vnc_DataBuffer *rsaPublic, const char *hexFingerprint, const char *catchphraseFingerprint)

Notification that the SDK’s RSA key has been retrieved.

This callback is required for retrieving the RSA key details.

Parameters
  • rsaPublic -

    The RSA public part, encoded using the RFB data format (N’s bit-length as a four-byte big-endian number, followed by N and e in unsigned big-endian bytes, with e padded to N’s byte-length). This public part is suitable for hashing with SHA-256 and using for key verification, if the 64-bit hexFingerprint does not meet security requirements.

  • hexFingerprint -

    The SHA-1 hash of the RSA public part, truncated to 64 bits and written as a hexadecimal string.

  • catchphraseFingerprint -

    The SHA-1 hash of the RSA public part, truncated to 64 bits and written using words from a dictionary (this is a reversible encoding of the hexFingerprint string).

×