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       Structure passed into knet_handle_set_crypto_config() to determine the crypto options to use for the current communications handle
96
97       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

RETURN VALUE

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

SEE ALSO

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.
153
154
155
156kronosnet                         2023-01-04  KNET_HANDLE_CRYPTO_SET_CONFIG(3)
Impressum