Ubuntu Manpage: knet_handle_crypto_set_config - set up packet cryptographic signing & encryption

NAME

       knet_handle_crypto_set_config - set up packet cryptographic signing & encryption

SYNOPSIS

       #include <libknet.h>

       int knet_handle_crypto_set_config(
           knet_handle_t                    knet_h,
           struct knet_handle_crypto_cfg   *knet_handle_crypto_cfg,
           uint8_t                          config_num
       );

DESCRIPTION

knet_handle_crypto_set_config

knet_h - pointer to knet_handle_t

knet_handle_crypto_cfg - pointer to a knet_handle_crypto_cfg structure

crypto_model should contain the model name. Currently only "openssl" and "nss" are
supported. Setting to "none" will disable crypto.

crypto_cipher_type should contain the cipher algo name. It can be set to "none" to disable
encryption. Currently supported by "nss" model: "aes128", "aes192" and "aes256". "openssl"
model supports more modes and it strictly depends on the openssl build. See:
EVP_get_cipherbyname openssl API call for details.

crypto_hash_type should contain the hashing algo name. It can be set to "none" to disable
hashing. Currently supported by "nss" model: "md5", "sha1", "sha256", "sha384" and
"sha512". "openssl" model supports more modes and it strictly depends on the openssl
build. See: EVP_get_digestbyname openssl API call for details.

private_key will contain the private shared key. It has to be at least KNET_MIN_KEY_LEN
long.

private_key_len length of the provided private_key.

config_num - knet supports 2 concurrent sets of crypto configurations, to allow runtime
change of crypto config and keys. On RX both configurations will be used sequentially in
an attempt to decrypt/validate a packet (when 2 are available). Note that this might slow
down performance during a reconfiguration. See also knet_handle_crypto_rx_clear_traffic(3)
to enable / disable processing of clear (unencrypted) traffic. For TX, the user needs to
specify which configuration to use via knet_handle_crypto_use_config(3). config_num
accepts 0, 1 or 2 as the value. 0 should be used when all crypto is being disabled.
Calling knet_handle_crypto_set_config(3) twice with the same config_num will REPLACE the
configuration and NOT activate the second key. If the configuration is currently in use
EBUSY will be returned. See also knet_handle_crypto_use_config(3). The correct sequence to
perform a runtime rekey / reconfiguration is:knet_handle_crypto_set_config(..., 1). ->
first time config, will use config1

knet_handle_crypto_use_config(..., 1). -> switch TX to config 1

knet_handle_crypto_set_config(..., 2). -> install config2 and use it only for RX

knet_handle_crypto_use_config(..., 2). -> switch TX to config 2

knet_handle_crypto_set_config(..., 1). -> with a "none"/"none"/"none" configuration to
release the resources previously allocated The application is responsible for
synchronizing calls on the nodes to make sure the new config is in place before switching
the TX configuration. Failure to do so will result in knet being unable to talk to some of
the nodes.

Implementation notes/current limitations:enabling crypto, will increase latency as packets
have to processed.

enabling crypto might reduce the overall throughtput due to crypto data overhead.

private/public key encryption/hashing is not currently planned.

crypto key must be the same for all hosts in the same knet instance / configX.

it is safe to call knet_handle_crypto_set_config multiple times at runtime. The last
config will be used. IMPORTANT: a call to knet_handle_crypto_set_config can fail due to:
1) failure to obtain locking 2) errors to initializing the crypto level. This can happen
even in subsequent calls to knet_handle_crypto_set_config(3). A failure in crypto init
will restore the previous crypto configuration if any.

STRUCTURES

       Structure passed into knet_handle_set_crypto_config() to determine the crypto options to use for the current communications handle

       struct knet_handle_crypto_cfg {
           char           crypto_model[16];              /* Model to use. nss, openssl, etc */
           char           crypto_cipher_type[16];        /* Cipher type name for encryption. aes 256 etc */
           char           crypto_hash_type[16];          /* Hash type for digest. sha512 etc */
           unsigned char  private_key[KNET_MAX_KEY_LEN]; /* Private key */
           unsigned int   private_key_len;               /* Length of private key */
       };

RETURN VALUE

       knet_handle_crypto_set_config returns:

       0          on success

       -1         on error and errno is set.

       -2          on  crypto  subsystem initialization error. No errno is provided at the moment
       (yet).

       knet_handle_remove_datafd(3), knet_handle_get_stats(3), knet_host_add(3),
       knet_handle_pmtud_setfreq(3), knet_handle_pmtud_get(3), knet_handle_crypto_use_config(3),
       knet_host_get_id_by_host_name(3), knet_host_get_status(3), knet_link_add_acl(3),
       knet_link_get_pong_count(3), knet_link_get_priority(3), knet_handle_free(3),
       knet_handle_enable_sock_notify(3), knet_handle_get_datafd(3), knet_recv(3),
       knet_link_get_ping_timers(3), knet_log_get_subsystem_id(3), knet_host_remove(3),
       knet_host_enable_status_change_notify(3), knet_strtoaddr(3), knet_link_rm_acl(3),
       knet_send(3), knet_handle_enable_pmtud_notify(3),
       knet_handle_get_transport_reconnect_interval(3), knet_link_get_enable(3),
       knet_link_set_priority(3), knet_log_set_loglevel(3), knet_handle_get_channel(3),
       knet_link_get_config(3), knet_link_get_link_list(3), knet_get_transport_list(3),
       knet_get_transport_id_by_name(3), knet_log_get_loglevel_id(3), knet_handle_new_ex(3),
       knet_host_set_name(3), knet_addrtostr(3), knet_handle_setfwd(3),
       knet_get_compress_list(3), knet_host_set_policy(3), knet_get_transport_name_by_id(3),
       knet_handle_enable_filter(3), knet_handle_crypto_rx_clear_traffic(3),
       knet_handle_compress(3), knet_link_get_status(3), knet_handle_add_datafd(3),
       knet_send_sync(3), knet_log_get_loglevel_name(3), knet_handle_enable_access_lists(3),
       knet_host_get_host_list(3), knet_host_get_policy(3), knet_link_set_enable(3),
       knet_link_set_pong_count(3), knet_log_get_subsystem_name(3),
       knet_host_get_name_by_host_id(3), knet_link_clear_config(3), knet_log_get_loglevel(3),
       knet_handle_new(3), knet_handle_pmtud_getfreq(3), knet_handle_pmtud_set(3),
       knet_handle_clear_stats(3), knet_link_set_config(3), knet_handle_crypto(3),
       knet_get_crypto_list(3), knet_handle_set_transport_reconnect_interval(3),
       knet_link_clear_acl(3), knet_link_set_ping_timers(3), knet_link_insert_acl(3)

COPYRIGHT