Advanced Integration

Introduction

VeilNet Conflux is a gRPC sub-process that lives with your main application. In the previous quick start guide, we demonstrated the minimal configuration. Here we will demonstrate how to start the plugin with proper configurations.

Prerequisites

First, you need to add the VeilNet Conflux dependency to your project:

go get github.com/veil-net/conflux

Anchor Module

The Anchor module includes all functions and structs your need to start and control VeilNet Conflux plug in. The additional modules are used for packaging VeilNet Conflux as system services for independent deployment without an application.

Manage VeilNet Conflux Lifecycle

package main

import "github.com/veil-net/conflux/anchor"

func main() {

    // Initialize the anchor plugin
    subprocess, err := anchor.NewAnchor()
    if err != nil {
        return err
    }

    // defer subprocess.Process.Kill()
}

This will start the VeilNet Conflux as a subprocess. You can control its life-cycle via subprocess.Process.Kill()

Reuqets Credentials from VeilNet Guardian

You need to request credentials from VeilNet Guardian to start the VeilNet Conflux plugin. You will need to provide the following information:

• Registration Token: A registration token from your VeilNet management console at https://console.veilnet.com
• Guardian: The guardian URL, currently it is https://guardian.veilnet.app
• Tag: The tag of this conflux node, it will be converted to a DNS name <tag>.veilnet.

Integrate with IDP

You could also provide additional information from your identity provider to create network isolation automatically based on the JWT token:

• JWT: The JWT token from your identity provider
• JWKS_url: The JWKS URL from your identity provider
• Audience: The audience of the JWT token
• Issuer: The issuer of the JWT token

Note: VeilNet Guardian will validate the JWT token via the JWKS URL. VeilNet Guardian will create a unique cryptographic signature by Dilithium DSA algorithm for each scope defined in the JWT token claims. These signatures are used in Packet-Level Authentication to verify if communication is allowed between the conflux node and other nodes.

package main

import "github.com/veil-net/conflux/anchor"

func main() {

  // Create a registration request
    registrationRequest := &anchor.ResgitrationRequest{
        RegistrationToken: "your-registration-token",
        Guardian:          "https://guardian.veilnet.app",
        Tag:               "your-tag",
        JWT:               "your-jwt",
        JWKS_url:          "your-jwks-url",
        Audience:          "your-audience",
        Issuer:            "your-issuer",
    }

    // Register the conflux
    registrationResponse, err := anchor.RegisterConflux(registrationRequest)
    if err != nil {
        Logger.Sugar().Errorf("failed to register conflux: %v", err)
        return err
    }
  
}

Start and config the Anchor Protocol

The registrationResponse is the response from VeilNet Guardian. You can use it to start the Anchor protocol, the communication fabric of VeilNet. These response contains a new short-lived token for the conflux node to authenticate with VeilNet Guardian.

Note: The token is only valid for a short period of time. You should start the conflux plugin with the new token immediately after receiving the response.

package main

import (
    "context"

    "github.com/veil-net/conflux/anchor"
  pb "github.com/veil-net/conflux/proto"
)

func main() {

  // Start the Anchor protocol
    _, err = anchor.StartAnchor(context.Background(), &pb.StartAnchorRequest{
        GuardianUrl: "https://guardian.veilnet.app",
        AnchorToken: registrationResponse.Token,
        Ip:          "10.128.0.1",
        Rift:        false,
        Portal:      false,
    })
    if err != nil {
        Logger.Sugar().Errorf("failed to start anchor: %v", err)
        return err
    }
}

There are two additonal attributes you need to pass to the StartAnchor function:

• IP: The IP address of the conflux node, it should be a private IP address within the subnet of the Realm. If the IP is not provided, the conflux node will be assigned a random IP address within the subnet. If the IP is not available, the function will return an error.
• Portal: Set to true will enable the portal mode of this VeilNet Conflux node. Reachable local network will be actively scaned and advertised to other trusted nodes. Other nodes will be able to use this node as a "mini router" to access reachable local network.
• Rift: Set to true will enable the rift mode of this VeilNet Conflux node. The host default route will be overwritten by the VeilNet TUN interface. All traffic from the host will be carried through VeilNet.

Warning: It is not recommended to enable either Rift or Portal mode when integrate VeilNet Conflux directly into your application.

Stop the Anchor Protocol

You can stop the Anchor protocol by calling the StopAnchor function:

package main

import (
    "context"

    "github.com/veil-net/conflux/anchor"
    "google.golang.org/protobuf/types/known/emptypb"
)

func main() {

  // ... start the anchor protocol ...

  // Stop the anchor
    _, err = anchor.StopAnchor(context.Background(), &emptypb.Empty{})
    if err != nil {
        Logger.Sugar().Errorf("failed to stop anchor: %v", err)
    }
}

Force Stop the Anchor Protocol

You can force stop the Anchor protocol by kill the subprocess:

package main

import "github.com/veil-net/conflux/anchor"

func main() {

  // ... start the anchor protocol ...

  // Force stop the anchor
    subprocess.Process.Kill()
}