NMSettingWireGuard

NMSettingWireGuard — Describes connection properties for wireguard related options

Functions

NMWireGuardPeer * nm_wireguard_peer_new ()
NMWireGuardPeer * nm_wireguard_peer_new_clone ()
NMWireGuardPeer * nm_wireguard_peer_ref ()
void nm_wireguard_peer_unref ()
void nm_wireguard_peer_seal ()
gboolean nm_wireguard_peer_is_sealed ()
const char * nm_wireguard_peer_get_public_key ()
gboolean nm_wireguard_peer_set_public_key ()
const char * nm_wireguard_peer_get_preshared_key ()
gboolean nm_wireguard_peer_set_preshared_key ()
NMSettingSecretFlags nm_wireguard_peer_get_preshared_key_flags ()
void nm_wireguard_peer_set_preshared_key_flags ()
guint16 nm_wireguard_peer_get_persistent_keepalive ()
void nm_wireguard_peer_set_persistent_keepalive ()
const char * nm_wireguard_peer_get_endpoint ()
gboolean nm_wireguard_peer_set_endpoint ()
guint nm_wireguard_peer_get_allowed_ips_len ()
const char * nm_wireguard_peer_get_allowed_ip ()
void nm_wireguard_peer_clear_allowed_ips ()
gboolean nm_wireguard_peer_append_allowed_ip ()
gboolean nm_wireguard_peer_remove_allowed_ip ()
gboolean nm_wireguard_peer_is_valid ()
int nm_wireguard_peer_cmp ()
NMSetting * nm_setting_wireguard_new ()
const char * nm_setting_wireguard_get_private_key ()
NMSettingSecretFlags nm_setting_wireguard_get_private_key_flags ()
guint16 nm_setting_wireguard_get_listen_port ()
guint32 nm_setting_wireguard_get_fwmark ()
guint nm_setting_wireguard_get_peers_len ()
NMWireGuardPeer * nm_setting_wireguard_get_peer ()
NMWireGuardPeer * nm_setting_wireguard_get_peer_by_public_key ()
void nm_setting_wireguard_set_peer ()
void nm_setting_wireguard_append_peer ()
gboolean nm_setting_wireguard_remove_peer ()
guint nm_setting_wireguard_clear_peers ()
gboolean nm_setting_wireguard_get_peer_routes ()
guint32 nm_setting_wireguard_get_mtu ()

Object Hierarchy

    GBoxed
    ╰── NMWireGuardPeer

Description

The NMSettingWireGuard object is a NMSetting subclass that contains settings for configuring WireGuard.

Functions

nm_wireguard_peer_new ()

NMWireGuardPeer *
nm_wireguard_peer_new (void);

Returns

a new, default, unsealed NMWireGuardPeer instance.

[transfer full]

Since: 1.16


nm_wireguard_peer_new_clone ()

NMWireGuardPeer *
nm_wireguard_peer_new_clone (const NMWireGuardPeer *self,
                             gboolean with_secrets);

Parameters

self

the NMWireGuardPeer instance to copy.

 

with_secrets

if TRUE, the preshared-key secrets are copied as well. Otherwise, they will be removed.

 

Returns

a clone of self . This instance is always unsealed.

[transfer full]

Since: 1.16


nm_wireguard_peer_ref ()

NMWireGuardPeer *
nm_wireguard_peer_ref (NMWireGuardPeer *self);

This is not thread-safe.

Parameters

self

the NMWireGuardPeer instance.

[allow-none]

Returns

returns the input argument self after incrementing the reference count.

Since: 1.16


nm_wireguard_peer_unref ()

void
nm_wireguard_peer_unref (NMWireGuardPeer *self);

Drop a reference to self . If the last reference is dropped, the instance is freed and all accociate data released.

This is not thread-safe.

Parameters

self

the NMWireGuardPeer instance.

[allow-none]

Since: 1.16


nm_wireguard_peer_seal ()

void
nm_wireguard_peer_seal (NMWireGuardPeer *self);

Seal the NMWireGuardPeer instance. Afterwards, it is a bug to call all functions that modify the instance (except ref/unref). A sealed instance cannot be unsealed again, but you can create an unsealed copy with nm_wireguard_peer_new_clone().

Parameters

self

the NMWireGuardPeer instance

 

Since: 1.16


nm_wireguard_peer_is_sealed ()

gboolean
nm_wireguard_peer_is_sealed (const NMWireGuardPeer *self);

Parameters

self

the NMWireGuardPeer instance

 

Returns

whether self is sealed or not.

Since: 1.16


nm_wireguard_peer_get_public_key ()

const char *
nm_wireguard_peer_get_public_key (const NMWireGuardPeer *self);

Parameters

self

the NMWireGuardPeer instance

 

Returns

the public key or NULL if unset.

[transfer none]

Since: 1.16


nm_wireguard_peer_set_public_key ()

gboolean
nm_wireguard_peer_set_public_key (NMWireGuardPeer *self,
                                  const char *public_key,
                                  gboolean accept_invalid);

Reset the public key. Note that if the public key is valid, it will be normalized (which may or may not modify the set value).

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

public_key

the new public key or NULL to clear the public key.

[allow-none][transfer none]

accept_invalid

if TRUE and public_key is not NULL and invalid, then do not modify the instance.

 

Returns

TRUE if the key was valid or NULL. Returns FALSE for invalid keys. Depending on accept_invalid will an invalid key be set or not.

Since: 1.16


nm_wireguard_peer_get_preshared_key ()

const char *
nm_wireguard_peer_get_preshared_key (const NMWireGuardPeer *self);

Parameters

self

the NMWireGuardPeer instance

 

Returns

the preshared key or NULL if unset.

[transfer none]

Since: 1.16


nm_wireguard_peer_set_preshared_key ()

gboolean
nm_wireguard_peer_set_preshared_key (NMWireGuardPeer *self,
                                     const char *preshared_key,
                                     gboolean accept_invalid);

Reset the preshared key. Note that if the preshared key is valid, it will be normalized (which may or may not modify the set value).

Note that the preshared-key is a secret and consequently has corresponding preshared-key-flags property. This is so that secrets can be optional and requested on demand from a secret-agent. Also, an invalid preshared-key may optionally cause nm_wireguard_peer_is_valid() to fail or it may be accepted.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

preshared_key

the new preshared key or NULL to clear the preshared key.

[allow-none][transfer none]

accept_invalid

whether to allow setting the key to an invalid value. If FALSE, self is unchanged if the key is invalid and if FALSE is returned.

 

Returns

TRUE if the preshared-key is valid, otherwise FALSE. NULL is considered a valid value. If the key is invalid, it depends on accept_invalid whether the previous value was reset.

Since: 1.16


nm_wireguard_peer_get_preshared_key_flags ()

NMSettingSecretFlags
nm_wireguard_peer_get_preshared_key_flags
                               (const NMWireGuardPeer *self);

Parameters

self

the NMWireGuardPeer instance

 

Returns

get the secret flags for the preshared-key.

Since: 1.16


nm_wireguard_peer_set_preshared_key_flags ()

void
nm_wireguard_peer_set_preshared_key_flags
                               (NMWireGuardPeer *self,
                                NMSettingSecretFlags preshared_key_flags);

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

preshared_key_flags

the secret flags to set.

 

Since: 1.16


nm_wireguard_peer_get_persistent_keepalive ()

guint16
nm_wireguard_peer_get_persistent_keepalive
                               (const NMWireGuardPeer *self);

Parameters

self

the NMWireGuardPeer instance

 

Returns

get the persistent-keepalive setting in seconds. Set to zero to disable keep-alive.

Since: 1.16


nm_wireguard_peer_set_persistent_keepalive ()

void
nm_wireguard_peer_set_persistent_keepalive
                               (NMWireGuardPeer *self,
                                guint16 persistent_keepalive);

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

persistent_keepalive

the keep-alive value to set.

 

Since: 1.16


nm_wireguard_peer_get_endpoint ()

const char *
nm_wireguard_peer_get_endpoint (const NMWireGuardPeer *self);

Parameters

self

the NMWireGuardPeer instance

 

Returns

the endpoint or NULL if none was set.

[transfer none]

Since: 1.16


nm_wireguard_peer_set_endpoint ()

gboolean
nm_wireguard_peer_set_endpoint (NMWireGuardPeer *self,
                                const char *endpoint,
                                gboolean allow_invalid);

Sets or clears the endpoint of self .

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

endpoint

the socket address endpoint to set or NULL.

 

allow_invalid

if TRUE, also invalid values are set. If FALSE, the function does nothing for invalid endpoint arguments.

 

Returns

TRUE if the endpoint is NULL or valid. For an invalid endpoint argument, FALSE is returned. Depending on allow_invalid , the instance will be modified.

Since: 1.16


nm_wireguard_peer_get_allowed_ips_len ()

guint
nm_wireguard_peer_get_allowed_ips_len (const NMWireGuardPeer *self);

Parameters

self

the NMWireGuardPeer instance

 

Returns

the number of allowed-ips entries.

Since: 1.16


nm_wireguard_peer_get_allowed_ip ()

const char *
nm_wireguard_peer_get_allowed_ip (const NMWireGuardPeer *self,
                                  guint idx,
                                  gboolean *out_is_valid);

Parameters

self

the NMWireGuardPeer instance

 

idx

the index from zero to (allowed-ips-len - 1) to retrieve.

 

out_is_valid

TRUE if the returned value is a valid allowed-ip setting.

[allow-none]

Returns

the allowed-ip setting at index idx . If idx is out of range, NULL will be returned.

[transfer none]

Since: 1.16


nm_wireguard_peer_clear_allowed_ips ()

void
nm_wireguard_peer_clear_allowed_ips (NMWireGuardPeer *self);

Removes all allowed-ip entries.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

Since: 1.16


nm_wireguard_peer_append_allowed_ip ()

gboolean
nm_wireguard_peer_append_allowed_ip (NMWireGuardPeer *self,
                                     const char *allowed_ip,
                                     gboolean accept_invalid);

Appends allowed_ip setting to the list. This does not check for duplicates and always appends allowed_ip to the end of the list. If allowed_ip is valid, it will be normalized and a modified for might be appended. If allowed_ip is invalid, it will still be appended, but later verification will fail.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

allowed_ip

the allowed-ip entry to set.

 

accept_invalid

if TRUE, also invalid allowed_ip value will be appended. Otherwise, the function does nothing in face of invalid values and returns FALSE.

 

Returns

TRUE if the value is a valid allowed-ips value, FALSE otherwise. Depending on accept_invalid , also invalid values are added.

Since: 1.16


nm_wireguard_peer_remove_allowed_ip ()

gboolean
nm_wireguard_peer_remove_allowed_ip (NMWireGuardPeer *self,
                                     guint idx);

Removes the allowed-ip at the given idx . This shifts all following entries one index down.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

Parameters

self

the unsealed NMWireGuardPeer instance

 

idx

the index from zero to (allowed-ips-len - 1) to retrieve. If the index is out of range, FALSE is returned and nothing is done.

 

Returns

TRUE if idx was valid and the allowed-ip was removed. FALSE otherwise, and the peer will not be changed.

Since: 1.16


nm_wireguard_peer_is_valid ()

gboolean
nm_wireguard_peer_is_valid (const NMWireGuardPeer *self,
                            gboolean check_non_secrets,
                            gboolean check_secrets,
                            GError **error);

Parameters

self

the NMWireGuardPeer instance

 

check_secrets

if TRUE, non-secret properties are validated. Otherwise they are ignored for this purpose.

 

check_non_secrets

if TRUE, secret properties are validated. Otherwise they are ignored for this purpose.

 

error

the GError location for returning the failure reason.

 

Returns

TRUE if the peer is valid or fails with an error reason.

Since: 1.16


nm_wireguard_peer_cmp ()

int
nm_wireguard_peer_cmp (const NMWireGuardPeer *a,
                       const NMWireGuardPeer *b,
                       NMSettingCompareFlags compare_flags);

Parameters

a

the NMWireGuardPeer to compare.

[allow-none]

b

the other NMWireGuardPeer to compare.

[allow-none]

compare_flags

NMSettingCompareFlags to affect the comparison.

 

Returns

zero of the two instances are equivalent or a non-zero integer otherwise. This defines a total ordering over the peers. Whether a peer is sealed or not, does not affect the comparison.

Since: 1.16


nm_setting_wireguard_new ()

NMSetting *
nm_setting_wireguard_new (void);

Creates a new NMSettingWireGuard object with default values.

Returns

the new empty NMSettingWireGuard object.

[transfer full]

Since: 1.16


nm_setting_wireguard_get_private_key ()

const char *
nm_setting_wireguard_get_private_key (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard instance

 

Returns

the set private-key or NULL.

[transfer none]

Since: 1.16


nm_setting_wireguard_get_private_key_flags ()

NMSettingSecretFlags
nm_setting_wireguard_get_private_key_flags
                               (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard instance

 

Returns

the secret-flags for “private-key”.

Since: 1.16


nm_setting_wireguard_get_listen_port ()

guint16
nm_setting_wireguard_get_listen_port (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard instance

 

Returns

the set UDP listen port.

Since: 1.16


nm_setting_wireguard_get_fwmark ()

guint32
nm_setting_wireguard_get_fwmark (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard instance

 

Returns

the set firewall mark.

Since: 1.16


nm_setting_wireguard_get_peers_len ()

guint
nm_setting_wireguard_get_peers_len (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard instance

 

Returns

the number of registered peers.

Since: 1.16


nm_setting_wireguard_get_peer ()

NMWireGuardPeer *
nm_setting_wireguard_get_peer (NMSettingWireGuard *self,
                               guint idx);

Parameters

self

the NMSettingWireGuard instance

 

idx

the index to lookup.

 

Returns

the NMWireGuardPeer entry at index idx . If the index is out of range, NULL is returned.

[transfer none]

Since: 1.16


nm_setting_wireguard_get_peer_by_public_key ()

NMWireGuardPeer *
nm_setting_wireguard_get_peer_by_public_key
                               (NMSettingWireGuard *self,
                                const char *public_key,
                                guint *out_idx);

Parameters

self

the NMSettingWireGuard instance

 

public_key

the public key for looking up the peer.

 

out_idx

optional output argument for the index of the found peer. If no index is found, this is set to the nm_setting_wireguard_get_peers_len().

[out][allow-none]

Returns

the NMWireGuardPeer instance with a matching public key. If no such peer exists, NULL is returned.

[transfer none]

Since: 1.16


nm_setting_wireguard_set_peer ()

void
nm_setting_wireguard_set_peer (NMSettingWireGuard *self,
                               NMWireGuardPeer *peer,
                               guint idx);

If idx is one past the last peer, the behavior is the same as nm_setting_wireguard_append_peer(). Otherwise, the peer will be at idx and replace the peer instance at that index. Note that if a peer with the same public-key exists on another index, then that peer will also be replaced. In that case, the number of peers will shrink by one (because the one at idx got replace and then one with the same public-key got removed). This also means, that the resulting index afterwards may be one less than idx (if another peer with a lower index was dropped).

Parameters

self

the NMSettingWireGuard instance

 

peer

the NMWireGuardPeer instance to set. This seals peer and keeps a reference on the instance.

 

idx

the index, in the range of 0 to the number of peers (including). That means, if idx is one past the end of the number of peers, this is the same as nm_setting_wireguard_append_peer(). Otherwise, the peer at this index is replaced.

 

Since: 1.16


nm_setting_wireguard_append_peer ()

void
nm_setting_wireguard_append_peer (NMSettingWireGuard *self,
                                  NMWireGuardPeer *peer);

If a peer with the same public-key already exists, that one is replaced by peer . The new peer is always appended (or moved to) the end, so in case a peer is replaced, the indexes are shifted and the number of peers stays unchanged.

Parameters

self

the NMSettingWireGuard instance

 

peer

the NMWireGuardPeer instance to append. This seals peer and keeps a reference on the instance.

 

Since: 1.16


nm_setting_wireguard_remove_peer ()

gboolean
nm_setting_wireguard_remove_peer (NMSettingWireGuard *self,
                                  guint idx);

Parameters

self

the NMSettingWireGuard instance

 

idx

the index to remove.

 

Returns

TRUE if idx was in range and a peer was removed. Otherwise, self is unchanged.

Since: 1.16


nm_setting_wireguard_clear_peers ()

guint
nm_setting_wireguard_clear_peers (NMSettingWireGuard *self);

nm_setting_wireguard_get_peer_routes ()

gboolean
nm_setting_wireguard_get_peer_routes (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard instance

 

Returns

whether automatically add peer routes.

Since: 1.16


nm_setting_wireguard_get_mtu ()

guint32
nm_setting_wireguard_get_mtu (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard instance

 

Returns

the MTU of the setting.

Since: 1.16

Types and Values

NM_WIREGUARD_PUBLIC_KEY_LEN

#define NM_WIREGUARD_PUBLIC_KEY_LEN     32

NM_WIREGUARD_SYMMETRIC_KEY_LEN

#define NM_WIREGUARD_SYMMETRIC_KEY_LEN  32

NM_SETTING_WIREGUARD_SETTING_NAME

#define NM_SETTING_WIREGUARD_SETTING_NAME "wireguard"

NM_SETTING_WIREGUARD_FWMARK

#define NM_SETTING_WIREGUARD_FWMARK            "fwmark"

NM_SETTING_WIREGUARD_LISTEN_PORT

#define NM_SETTING_WIREGUARD_LISTEN_PORT       "listen-port"

NM_SETTING_WIREGUARD_PRIVATE_KEY

#define NM_SETTING_WIREGUARD_PRIVATE_KEY       "private-key"

NM_SETTING_WIREGUARD_PRIVATE_KEY_FLAGS

#define NM_SETTING_WIREGUARD_PRIVATE_KEY_FLAGS "private-key-flags"

NM_SETTING_WIREGUARD_PEERS

#define NM_SETTING_WIREGUARD_PEERS             "peers"

NM_SETTING_WIREGUARD_MTU

#define NM_SETTING_WIREGUARD_MTU               "mtu"

NM_SETTING_WIREGUARD_PEER_ROUTES

#define NM_SETTING_WIREGUARD_PEER_ROUTES       "peer-routes"

NM_WIREGUARD_PEER_ATTR_ALLOWED_IPS

#define NM_WIREGUARD_PEER_ATTR_ALLOWED_IPS          "allowed-ips"

NM_WIREGUARD_PEER_ATTR_ENDPOINT

#define NM_WIREGUARD_PEER_ATTR_ENDPOINT             "endpoint"

NM_WIREGUARD_PEER_ATTR_PERSISTENT_KEEPALIVE

#define NM_WIREGUARD_PEER_ATTR_PERSISTENT_KEEPALIVE "persistent-keepalive"

NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY

#define NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY        "preshared-key"

NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY_FLAGS

#define NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY_FLAGS  "preshared-key-flags"

NM_WIREGUARD_PEER_ATTR_PUBLIC_KEY

#define NM_WIREGUARD_PEER_ATTR_PUBLIC_KEY           "public-key"