1KNET_HANDLE_CRYPTO_SET_CONKFrIoGn(o3s)net Programmer'sKNMEaTn_uHaAlNDLE_CRYPTO_SET_CONFIG(3)
2
3
4

NAME

6       knet_handle_crypto_set_config  -  set up packet cryptographic signing &
7       encryption
8
9

SYNOPSIS

11       #include <libknet.h>
12
13       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

DESCRIPTION

20       knet_handle_crypto_set_config
21
22       knet_h - pointer to knet_handle_t
23
24       knet_handle_crypto_cfg - pointer to a knet_handle_crypto_cfg structure
25
26       crypto_model should contain the model name.  Currently  only  "openssl"
27       and "nss" are supported. Setting to "none" will disable crypto.
28
29       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
35       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
41       private_key  will contain the private shared key. It has to be at least
42       KNET_MIN_KEY_LEN long.
43
44       private_key_len length of the provided private_key.
45
46       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
62       knet_handle_crypto_use_config(..., 1). -> switch TX to config 1
63
64       knet_handle_crypto_set_config(..., 2). -> install config2  and  use  it
65       only for RX
66
67       knet_handle_crypto_use_config(..., 2). -> switch TX to config 2
68
69       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
76       Implementation notes/current limitations:enabling crypto, will increase
77       latency as packets have to processed.
78
79       enabling crypto might reduce the overall throughtput due to crypto data
80       overhead.
81
82       private/public key encryption/hashing is not currently planned.
83
84       crypto key must be the same for all hosts in the same knet  instance  /
85       configX.
86
87       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

STRUCTURES

95       struct knet_handle_crypto_cfg {
96           char           crypto_model[16];
97           char           crypto_cipher_type[16];
98           char           crypto_hash_type[16];
99           unsigned char  private_key[KNET_MAX_KEY_LEN];
100           unsigned int   private_key_len;
101       };
102

RETURN VALUE

104       knet_handle_crypto_set_config returns:
105
106       0          on success
107
108       -1         on error and errno is set.
109
110       -2         on crypto subsystem initialization error. No errno  is  pro‐
111       vided at the moment (yet).
112

SEE ALSO

114       knet_handle_remove_datafd(3), knet_handle_get_stats(3),
115       knet_host_add(3), knet_handle_pmtud_setfreq(3),
116       knet_handle_pmtud_get(3), knet_handle_crypto_use_config(3),
117       knet_host_get_id_by_host_name(3), knet_host_get_status(3),
118       knet_link_add_acl(3), knet_link_get_pong_count(3),
119       knet_link_get_priority(3), knet_handle_free(3),
120       knet_handle_enable_sock_notify(3), knet_handle_get_datafd(3),
121       knet_recv(3), knet_link_get_ping_timers(3),
122       knet_log_get_subsystem_id(3), knet_host_remove(3),
123       knet_host_enable_status_change_notify(3), knet_strtoaddr(3),
124       knet_link_rm_acl(3), knet_send(3), knet_handle_enable_pmtud_notify(3),
125       knet_handle_get_transport_reconnect_interval(3),
126       knet_link_get_enable(3), knet_link_set_priority(3),
127       knet_log_set_loglevel(3), knet_handle_get_channel(3),
128       knet_link_get_config(3), knet_link_get_link_list(3),
129       knet_get_transport_list(3), knet_get_transport_id_by_name(3),
130       knet_log_get_loglevel_id(3), knet_handle_new_ex(3),
131       knet_host_set_name(3), knet_addrtostr(3), knet_handle_setfwd(3),
132       knet_get_compress_list(3), knet_host_set_policy(3),
133       knet_get_transport_name_by_id(3), knet_handle_enable_filter(3),
134       knet_handle_crypto_rx_clear_traffic(3), knet_handle_compress(3),
135       knet_link_get_status(3), knet_handle_add_datafd(3), knet_send_sync(3),
136       knet_log_get_loglevel_name(3), knet_handle_enable_access_lists(3),
137       knet_host_get_host_list(3), knet_host_get_policy(3),
138       knet_link_set_enable(3), knet_link_set_pong_count(3),
139       knet_log_get_subsystem_name(3), knet_host_get_name_by_host_id(3),
140       knet_link_clear_config(3), knet_log_get_loglevel(3),
141       knet_handle_new(3), knet_handle_pmtud_getfreq(3),
142       knet_handle_pmtud_set(3), knet_handle_clear_stats(3),
143       knet_link_set_config(3), knet_handle_crypto(3),
144       knet_get_crypto_list(3),
145       knet_handle_set_transport_reconnect_interval(3),
146       knet_link_clear_acl(3), knet_link_set_ping_timers(3),
147       knet_link_insert_acl(3)
148
150       Copyright (C) 2010-2020 Red Hat, Inc. All rights reserved.
151
152
153
154kronosnet                         2020-10-19  KNET_HANDLE_CRYPTO_SET_CONFIG(3)
Impressum