KNET_HAN...ET_CONFIG(3)

📦
version 1.35 · 8 versions
, in fedora 43, fedora 44

💖 KNET_HAN...ET_CONFIG(3) 💖

okay bestie, so this is a page out of the Kronosnet Programmer's Manual (yes, the real one, section 3, programmers' corner) and we're about to make cryptography make sense. buckle up, it's giving secure packet energy. 🔐✨

🌸 NAME 🌸

knet_handle_crypto_set_config — set up packet cryptographic signing & encryption. literally the glow-up button for your packets. 💅

✨ 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 🦋

so we're calling knet_handle_crypto_set_config and here's the whole vibe check on every single argument, no skips, no skimming, i got you 🫶

  • knet_h — pointer to knet_handle_t. that's your handle, your main character. 👑
  • knet_handle_crypto_cfg — pointer to a knet_handle_crypto_cfg structure. the whole tea on that struct is down in STRUCTURES, don't worry.

then inside that struct, here's what each field is doing:

  • crypto_model — should contain the model name. rn only "openssl" and "nss" are supported. setting it to "none" will disable crypto. periodt.
  • crypto_cipher_type — should contain the cipher algo name. it can be set to "none" to disable encryption. currently supported by the "nss" model: "aes128", "aes192" and "aes256". the "openssl" model supports more modes and it strictly depends on the openssl build. see: EVP_get_cipherbyname openssl API call for details. (iykyk 🌈)
  • crypto_hash_type — should contain the hashing algo name. it can be set to "none" to disable hashing. currently supported by the "nss" model: "md5", "sha1", "sha256", "sha384" and "sha512". the "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. no baby keys allowed bestie. 🍼✋
  • private_key_len — length of the provided private_key.
  • config_num — okay this one's the big one, sit down. 🪑

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 */
};

look at her. so organized. so iconic. ⭐

💜 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_get_crypto_cipher_list(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_crypto_hash_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_handle_setprio_dscp(3), knet_link_insert_acl(3)

that's the whole friend group, go say hi. 🫶✨

Copyright (C) 2010-2026 Red Hat, Inc. All rights reserved.

and that's the whole page bestie, no cap. this one came from kronosnet, dated 2026-07-20, and yeah the man page title is a whole keyboard smash (KNET_HAN...ET_CONFIG(3)) but we love her anyway. go forth and encrypt. 💖🔐🌈

📦 where this page comes from