---
name: "knet_handle_crypto_set_config"
section: "3"
platform: "linux"
package: "libknet-doc"
version: "1.31-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/knet_handle_crypto_set_config"
---

# knet\_handle\_crypto\_set\_config(3)

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)](/knet_handle_crypto_rx_clear_traffic/3.md) 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)](/knet_handle_crypto_use_config/3.md). 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)](/knet_handle_crypto_set_config/3.md) 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)](/knet_handle_crypto_use_config/3.md). 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)](/knet_handle_crypto_set_config/3.md). 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_remove_datafd/3.md), [*knet\_handle\_get\_stats*(3)](/knet_handle_get_stats/3.md), [*knet\_host\_add*(3)](/knet_host_add/3.md), [*knet\_handle\_pmtud\_setfreq*(3)](/knet_handle_pmtud_setfreq/3.md), [*knet\_handle\_pmtud\_get*(3)](/knet_handle_pmtud_get/3.md), [*knet\_handle\_crypto\_use\_config*(3)](/knet_handle_crypto_use_config/3.md), [*knet\_host\_get\_id\_by\_host\_name*(3)](/knet_host_get_id_by_host_name/3.md), [*knet\_host\_get\_status*(3)](/knet_host_get_status/3.md), [*knet\_link\_add\_acl*(3)](/knet_link_add_acl/3.md), [*knet\_link\_get\_pong\_count*(3)](/knet_link_get_pong_count/3.md), [*knet\_link\_get\_priority*(3)](/knet_link_get_priority/3.md), [*knet\_handle\_free*(3)](/knet_handle_free/3.md), [*knet\_handle\_enable\_sock\_notify*(3)](/knet_handle_enable_sock_notify/3.md), [*knet\_handle\_get\_datafd*(3)](/knet_handle_get_datafd/3.md), [*knet\_recv*(3)](/knet_recv/3.md), [*knet\_link\_get\_ping\_timers*(3)](/knet_link_get_ping_timers/3.md), [*knet\_log\_get\_subsystem\_id*(3)](/knet_log_get_subsystem_id/3.md), [*knet\_host\_remove*(3)](/knet_host_remove/3.md), [*knet\_host\_enable\_status\_change\_notify*(3)](/knet_host_enable_status_change_notify/3.md), [*knet\_strtoaddr*(3)](/knet_strtoaddr/3.md), [*knet\_link\_rm\_acl*(3)](/knet_link_rm_acl/3.md), [*knet\_send*(3)](/knet_send/3.md), [*knet\_handle\_enable\_pmtud\_notify*(3)](/knet_handle_enable_pmtud_notify/3.md), [*knet\_handle\_get\_transport\_reconnect\_interval*(3)](/knet_handle_get_transport_reconnect_interval/3.md), [*knet\_link\_get\_enable*(3)](/knet_link_get_enable/3.md), [*knet\_link\_set\_priority*(3)](/knet_link_set_priority/3.md), [*knet\_log\_set\_loglevel*(3)](/knet_log_set_loglevel/3.md), [*knet\_handle\_get\_channel*(3)](/knet_handle_get_channel/3.md), [*knet\_link\_get\_config*(3)](/knet_link_get_config/3.md), [*knet\_link\_get\_link\_list*(3)](/knet_link_get_link_list/3.md), [*knet\_get\_transport\_list*(3)](/knet_get_transport_list/3.md), [*knet\_get\_transport\_id\_by\_name*(3)](/knet_get_transport_id_by_name/3.md), [*knet\_log\_get\_loglevel\_id*(3)](/knet_log_get_loglevel_id/3.md), [*knet\_handle\_new\_ex*(3)](/knet_handle_new_ex/3.md), [*knet\_host\_set\_name*(3)](/knet_host_set_name/3.md), [*knet\_addrtostr*(3)](/knet_addrtostr/3.md), [*knet\_handle\_setfwd*(3)](/knet_handle_setfwd/3.md), [*knet\_get\_compress\_list*(3)](/knet_get_compress_list/3.md), [*knet\_host\_set\_policy*(3)](/knet_host_set_policy/3.md), [*knet\_get\_transport\_name\_by\_id*(3)](/knet_get_transport_name_by_id/3.md), [*knet\_handle\_enable\_filter*(3)](/knet_handle_enable_filter/3.md), [*knet\_handle\_crypto\_rx\_clear\_traffic*(3)](/knet_handle_crypto_rx_clear_traffic/3.md), [*knet\_handle\_compress*(3)](/knet_handle_compress/3.md), [*knet\_link\_get\_status*(3)](/knet_link_get_status/3.md), [*knet\_handle\_add\_datafd*(3)](/knet_handle_add_datafd/3.md), [*knet\_send\_sync*(3)](/knet_send_sync/3.md), [*knet\_log\_get\_loglevel\_name*(3)](/knet_log_get_loglevel_name/3.md), [*knet\_handle\_enable\_access\_lists*(3)](/knet_handle_enable_access_lists/3.md), [*knet\_host\_get\_host\_list*(3)](/knet_host_get_host_list/3.md), [*knet\_host\_get\_policy*(3)](/knet_host_get_policy/3.md), [*knet\_link\_set\_enable*(3)](/knet_link_set_enable/3.md), [*knet\_link\_set\_pong\_count*(3)](/knet_link_set_pong_count/3.md), [*knet\_log\_get\_subsystem\_name*(3)](/knet_log_get_subsystem_name/3.md), [*knet\_host\_get\_name\_by\_host\_id*(3)](/knet_host_get_name_by_host_id/3.md), [*knet\_link\_clear\_config*(3)](/knet_link_clear_config/3.md), [*knet\_log\_get\_loglevel*(3)](/knet_log_get_loglevel/3.md), [*knet\_handle\_new*(3)](/knet_handle_new/3.md), [*knet\_handle\_pmtud\_getfreq*(3)](/knet_handle_pmtud_getfreq/3.md), [*knet\_handle\_pmtud\_set*(3)](/knet_handle_pmtud_set/3.md), [*knet\_handle\_clear\_stats*(3)](/knet_handle_clear_stats/3.md), [*knet\_link\_set\_config*(3)](/knet_link_set_config/3.md), [*knet\_handle\_crypto*(3)](/knet_handle_crypto/3.md), [*knet\_get\_crypto\_list*(3)](/knet_get_crypto_list/3.md), [*knet\_handle\_set\_transport\_reconnect\_interval*(3)](/knet_handle_set_transport_reconnect_interval/3.md), [*knet\_link\_clear\_acl*(3)](/knet_link_clear_acl/3.md), [*knet\_link\_set\_ping\_timers*(3)](/knet_link_set_ping_timers/3.md), [*knet\_link\_insert\_acl*(3)](/knet_link_insert_acl/3.md)

## COPYRIGHT

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