jammy (3) knet_handle_crypto_set_config.3.gz

Provided by: libknet-doc_1.23-2build1_all bug

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


SEE ALSO
       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 (C) 2010-2021 Red Hat, Inc. All rights reserved.