1KNET_HANDLE_CRYPTO_SET_CONKFrIoGn(o3s)net Programmer'sKNMEaTn_uHaAlNDLE_CRYPTO_SET_CONFIG(3)
2
6 knet_handle_crypto_set_config - set up packet cryptographic signing &
7 encryption
8
11 #include <libknet.h>
12 int knet_handle_crypto_set_config(
14 knet_handle_t knet_h,
15 struct knet_handle_crypto_cfg *knet_handle_crypto_cfg,
16 uint8_t config_num
17 );
18
20 knet_handle_crypto_set_config
21 knet_h - pointer to knet_handle_t
23 knet_handle_crypto_cfg - pointer to a knet_handle_crypto_cfg structure
25 crypto_model should contain the model name. Currently only "openssl"
27 and "nss" are supported. Setting to "none" will disable crypto.
28 crypto_cipher_type should contain the cipher algo name. It can be set
30 to "none" to disable encryption. Currently supported by "nss" model:
31 "aes128", "aes192" and "aes256". "openssl" model supports more modes
32 and it strictly depends on the openssl build. See: EVP_get_cipherbyname
33 openssl API call for details.
34 crypto_hash_type should contain the hashing algo name. It can be set to
36 "none" to disable hashing. Currently supported by "nss" model: "md5",
37 "sha1", "sha256", "sha384" and "sha512". "openssl" model supports more
38 modes and it strictly depends on the openssl build. See: EVP_get_di‐
39 gestbyname openssl API call for details.
40 private_key will contain the private shared key. It has to be at least
42 KNET_MIN_KEY_LEN long.
43 private_key_len length of the provided private_key.
45 config_num - knet supports 2 concurrent sets of crypto configurations,
47 to allow runtime change of crypto config and keys. On RX both configu‐
48 rations will be used sequentially in an attempt to decrypt/validate a
49 packet (when 2 are available). Note that this might slow down perfor‐
50 mance during a reconfiguration. See also knet_han‐
51 dle_crypto_rx_clear_traffic(3) to enable / disable processing of clear
52 (unencrypted) traffic. For TX, the user needs to specify which configu‐
53 ration to use via knet_handle_crypto_use_config(3). config_num accepts
54 0, 1 or 2 as the value. 0 should be used when all crypto is being dis‐
55 abled. Calling knet_handle_crypto_set_config(3) twice with the same
56 config_num will REPLACE the configuration and NOT activate the second
57 key. If the configuration is currently in use EBUSY will be returned.
58 See also knet_handle_crypto_use_config(3). The correct sequence to per‐
59 form a runtime rekey / reconfiguration is:knet_handle_crypto_set_con‐
60 fig(..., 1). -> first time config, will use config1
61 knet_handle_crypto_use_config(..., 1). -> switch TX to config 1
63 knet_handle_crypto_set_config(..., 2). -> install config2 and use it
65 only for RX
66 knet_handle_crypto_use_config(..., 2). -> switch TX to config 2
68 knet_handle_crypto_set_config(..., 1). -> with a "none"/"none"/"none"
70 configuration to release the resources previously allocated The appli‐
71 cation is responsible for synchronizing calls on the nodes to make sure
72 the new config is in place before switching the TX configuration. Fail‐
73 ure to do so will result in knet being unable to talk to some of the
74 nodes.
75 Implementation notes/current limitations:enabling crypto, will increase
77 latency as packets have to processed.
78 enabling crypto might reduce the overall throughtput due to crypto data
80 overhead.
81 private/public key encryption/hashing is not currently planned.
83 crypto key must be the same for all hosts in the same knet instance /
85 configX.
86 it is safe to call knet_handle_crypto_set_config multiple times at run‐
88 time. The last config will be used. IMPORTANT: a call to knet_han‐
89 dle_crypto_set_config can fail due to: 1) failure to obtain locking 2)
90 errors to initializing the crypto level. This can happen even in subse‐
91 quent calls to knet_handle_crypto_set_config(3). A failure in crypto
92 init will restore the previous crypto configuration if any.
93
95 Structure passed into knet_handle_set_crypto_config() to determine the crypto options to use for the current communications handle
96 struct knet_handle_crypto_cfg {
98 char crypto_model[16]; /* Model to use. nss, openssl, etc */
99 char crypto_cipher_type[16]; /* Cipher type name for encryption. aes 256 etc */
100 char crypto_hash_type[16]; /* Hash type for digest. sha512 etc */
101 unsigned char private_key[KNET_MAX_KEY_LEN]; /* Private key */
102 unsigned int private_key_len; /* Length of private key */
103 };
104
106 knet_handle_crypto_set_config returns:
107 0 on success
109 -1 on error and errno is set.
111 -2 on crypto subsystem initialization error. No errno is pro‐
113 vided at the moment (yet).
114
116 knet_handle_remove_datafd(3), knet_handle_get_stats(3),
117 knet_host_add(3), knet_handle_pmtud_setfreq(3),
118 knet_handle_pmtud_get(3), knet_handle_crypto_use_config(3),
119 knet_host_get_id_by_host_name(3), knet_host_get_status(3),
120 knet_link_add_acl(3), knet_link_get_pong_count(3),
121 knet_link_get_priority(3), knet_handle_free(3),
122 knet_handle_enable_sock_notify(3), knet_handle_get_datafd(3),
123 knet_recv(3), knet_link_get_ping_timers(3),
124 knet_log_get_subsystem_id(3), knet_host_remove(3),
125 knet_host_enable_status_change_notify(3), knet_strtoaddr(3),
126 knet_link_rm_acl(3), knet_send(3), knet_handle_enable_pmtud_notify(3),
127 knet_handle_get_transport_reconnect_interval(3),
128 knet_link_get_enable(3), knet_link_set_priority(3),
129 knet_log_set_loglevel(3), knet_handle_get_channel(3),
130 knet_link_get_config(3), knet_link_get_link_list(3),
131 knet_get_transport_list(3), knet_get_transport_id_by_name(3),
132 knet_log_get_loglevel_id(3), knet_handle_new_ex(3),
133 knet_host_set_name(3), knet_addrtostr(3), knet_handle_setfwd(3),
134 knet_get_compress_list(3), knet_host_set_policy(3),
135 knet_get_transport_name_by_id(3), knet_handle_enable_filter(3),
136 knet_handle_crypto_rx_clear_traffic(3), knet_handle_compress(3),
137 knet_link_get_status(3), knet_handle_add_datafd(3), knet_send_sync(3),
138 knet_log_get_loglevel_name(3), knet_handle_enable_access_lists(3),
139 knet_host_get_host_list(3), knet_host_get_policy(3),
140 knet_link_set_enable(3), knet_link_set_pong_count(3),
141 knet_log_get_subsystem_name(3), knet_host_get_name_by_host_id(3),
142 knet_link_clear_config(3), knet_log_get_loglevel(3),
143 knet_handle_new(3), knet_handle_pmtud_getfreq(3),
144 knet_handle_pmtud_set(3), knet_handle_clear_stats(3),
145 knet_link_set_config(3), knet_handle_crypto(3),
146 knet_get_crypto_list(3),
147 knet_handle_set_transport_reconnect_interval(3),
148 knet_link_clear_acl(3), knet_link_set_ping_timers(3),
149 knet_link_insert_acl(3)
150
152 Copyright (C) 2010-2023 Red Hat, Inc. All rights reserved.
153kronosnet 2023-01-04 KNET_HANDLE_CRYPTO_SET_CONFIG(3)