Webfuse API introduction

This introduction provides a general overview to webfuse API. Please refer to the build instructions to generate API reference documentation.

Authentication
[Adapter Client](#Adapter Client)

Authentication (Adapter Server)

By default, webfuse daemon will redirect each filesystem call to the first connected provider without any authentication. This might be good for testing purposes or when an external authentication mechanism is used. In some use cases, explicit authentication is needed. Therefore, authentication can be enabled within webfuse daemon.

When authentication is enabled, filesystem calls are only redirected to a connected provider, after authenticate has succeeded.

Enable authentication

Authentication is enabled, if one or more authenticators are registered via wf_server_config.

static bool authenticate(struct wf_credentials * creds, void * user_data)
{
    char const * username = wf_credentials_get(creds, "username");
    char const * password = wf_credentials_get(creds, "password");

   return ((NULL != username) && (0 == strcmp(username, "bob")) &&
           (NULL != password) && (0 == strcmp(password, "???")));
}

wf_server_config * config = wf_server_config_create();
wf_server_config_add_authenticator(config, "username", &authenticate, NULL);

wf_server * server = wf_server_create(config);
//...

Authenticator types and credentidals

Each authenticator is identified by a user defined string, called type. The type is provided by the authenticate request, so you can define different authenticators for different authentication types, e.g. username, certificate, token.

Actually, only one type is used: username
It is strongly recommended to prefix custom authenticator types with an underscore (_) to avoid name clashes.

The wf_credentialsstruct represents a map to access credentials as key-value pairs, where both, key and value, are of type string.

username

The authenticator type username is used to authenticate via username and password. Valid credentials should contain two keys.

username refers to the name of the user
password refers to the password of the user

Note that no further encryption is done, so this authenticator type should not be used over unencrypted websocket connections.

Adapter Client

Webfuse also supports a client version of an adapter. This might be useful to connect to a cloud based provider server and request a filesystem.

The adapter client is driven by a callback function, which is triggered whenever an event occurs, an adapter should take care of.

static void client_callback(
   struct wf_client * client,
   int reason,
   void * arg)
{
    switch (reason)
    {
        // ... handle events
        default:
            break;
    }
}

// ...
void * user_data = ...
struct wf_client * client = wf_client_create(&client_callback, user_data);

Init and Cleanup

There are two events definied to handle init and cleanup of clients:

WF_CLIENT_INIT
WF_CLIENT_CLEANUP

These two are the outer-most events and can be used for custom initialization and cleanup.

A thrid event, WF_CLIENT_CREATED, is triggered, when the client is fully created. You might use this event to connect to a foreign provider.

Connection Status

The connection status is relected by two events:

WF_CLIENT_CONNECTED
WF_CLIENT_DISCONNECTED

The disconnected event is also triggerd, when an attempt to connect fails.

Transport Layer Security

During startup, the event WF_CLIENT_GET_TLS_CONFIG is triggered. In this case, the arg parameter points to an instance of struct wf_client_tlsconfig.

To enable TLS, set this struct. If the callback is ignorted or the struct is not set, TLS is not active.

static void client_callback(
    struct wf_client * client,
    int reason,
    void * arg)
{
    switch (reason)
    {
        // ...
        case WF_CLIENT_GET_TLS_CONFIG:
            {
                struct wf_client_tlsconfig * tls = arg;
                wf_client_tslconfig_set_keypath(tls, "/path/to/key.pem");
                wf_client_tslconfig_set_certpath(tls, "/path/to/cert.pem");
                wf_client_tslconfig_set_cafilepath(tls, "/path/to/ca_file.pem");
            }
            break;
        default:
            break;
    }
}

Authentication (Adapter Client)

During wf_client_authenticate the event WF_CLIENT_AUTHENTICATE_GET_CREDENTIALS is triggered to query credentials for authentication.

In this case, the arg paramter point to an instance of struct wf_credentials.

static void client_callback(
    struct wf_client * client,
    int reason,
    void * arg)
{
    switch (reason)
    {
        // ...
        case WF_CLIENT_AUTHENTICATE_GET_CREDENTIALS:
            {
                struct wf_credentials * creds = arg;
                wf_credentials_set_type(creds, "username");
                wf_credentials_add(creds, "username", "Bob");
                wf_credentials_add(creds, "password", "secret");
            }
            break;
        default:
            break;
    }
}

5.4 KiB Raw Blame History