NMSettingWireGuard: libnm Reference Manual

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 ()
NMTernary	nm_setting_wireguard_get_ip4_auto_default_route ()
NMTernary	nm_setting_wireguard_get_ip6_auto_default_route ()

Types and Values

#define	NM_WIREGUARD_PUBLIC_KEY_LEN
#define	NM_WIREGUARD_SYMMETRIC_KEY_LEN
#define	NM_SETTING_WIREGUARD_SETTING_NAME
#define	NM_SETTING_WIREGUARD_FWMARK
#define	NM_SETTING_WIREGUARD_LISTEN_PORT
#define	NM_SETTING_WIREGUARD_PRIVATE_KEY
#define	NM_SETTING_WIREGUARD_PRIVATE_KEY_FLAGS
#define	NM_SETTING_WIREGUARD_PEERS
#define	NM_SETTING_WIREGUARD_MTU
#define	NM_SETTING_WIREGUARD_PEER_ROUTES
#define	NM_SETTING_WIREGUARD_IP4_AUTO_DEFAULT_ROUTE
#define	NM_SETTING_WIREGUARD_IP6_AUTO_DEFAULT_ROUTE
#define	NM_WIREGUARD_PEER_ATTR_ALLOWED_IPS
#define	NM_WIREGUARD_PEER_ATTR_ENDPOINT
#define	NM_WIREGUARD_PEER_ATTR_PERSISTENT_KEEPALIVE
#define	NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY
#define	NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY_FLAGS
#define	NM_WIREGUARD_PEER_ATTR_PUBLIC_KEY

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);

Parameters

self

the NMWireGuardPeer instance.

[nullable]

Returns

returns the input argument self after incrementing the reference count.

Since 1.42, ref-counting of NMWireGuardPeer is thread-safe.

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 associate data released.

Since 1.42, ref-counting of NMWireGuardPeer is thread-safe.

Parameters

self

the NMWireGuardPeer instance.

[nullable]

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.	[nullable][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.	[nullable][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. This parameter is wrongly not marked as (out) argument, it is thus not accessible via introspection. This cannot be fixed without breaking API for introspection users.	[nullable]

Returns

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

[transfer none][nullable]

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.	[nullable]
b	the other NMWireGuardPeer to compare.	[nullable]
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][optional]

Returns

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

[transfer none][nullable]

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);

Parameters

self

the NMSettingWireGuard instance

Returns

the number of cleared peers.

Since: 1.16

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

nm_setting_wireguard_get_ip4_auto_default_route ()

NMTernary
nm_setting_wireguard_get_ip4_auto_default_route
                               (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard setting.

Returns

the "ip4-auto-default-route" property of the setting.

Since: 1.20

nm_setting_wireguard_get_ip6_auto_default_route ()

NMTernary
nm_setting_wireguard_get_ip6_auto_default_route
                               (NMSettingWireGuard *self);

Parameters

self

the NMSettingWireGuard setting.

Returns

the "ip6-auto-default-route" property of the setting.

Since: 1.20

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_SETTING_WIREGUARD_IP4_AUTO_DEFAULT_ROUTE

#define NM_SETTING_WIREGUARD_IP4_AUTO_DEFAULT_ROUTE "ip4-auto-default-route"

NM_SETTING_WIREGUARD_IP6_AUTO_DEFAULT_ROUTE

#define NM_SETTING_WIREGUARD_IP6_AUTO_DEFAULT_ROUTE "ip6-auto-default-route"

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"