knet_handle_crypto_set_config - Man Page

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