Aller au contenu
Bibliothèque client

Bibliothèque client

claimward-vpn-client : la bibliothèque Go que partagent les applications et le serveur — connexion, protocole réseau, tunnel, helper privilégié et cœur des applications. Elle ne fournit aucun binaire.

claimward-vpn-client v0.3.1 est une bibliothèque Go. Elle ne fournit aucun binaire : les programmes exécutables sont ceux des applications (cmd/claimward-app et cmd/claimward-helper dans le dépôt de chaque application). Le serveur l’importe aussi, pour les types réseau et les stubs gRPC.

Il n’existe pas de client en ligne de commande claimward. Les versions antérieures de ce module en avaient un (cmd/claimward, avec login et connect) ; il a été supprimé, et c’est sur le module réduit à la bibliothèque que s’appuient les applications.

Paquets

PaquetRôle
pkg/protocolle contrat réseau (/enroll, /tenants, /heartbeat, /deregister), partagé avec le serveur
pkg/routespbles stubs gRPC/protobuf générés du RouteService, partagés avec le serveur
pkg/authla connexion interactive derrière un Provider : device flow GitHub (par défaut), code d’autorisation OIDC + PKCE, ou device flow go-authn, dont le fournisseur enregistre aussi la clé de l’appareil (KeyRegistrar)
pkg/oidcle flux OIDC code d’autorisation + PKCE : découverte, redirection en boucle locale (loopback)
pkg/browserouvre une URL dans le navigateur par défaut avec des chemins d’ouverture absolus, pour fonctionner depuis des applications graphiques
pkg/clientEnroll, Tenants, Heartbeat, Deregister auprès du serveur, et TunnelConfig pour transformer une EnrollResponse en wgtun.Config
pkg/wgkeygénération et analyse des clés WireGuard
pkg/wgtuntunnel WireGuard en espace utilisateur avec wireguard-go, plus l’adresse et les routes : ifconfig/route sur macOS, ip sur Linux, un adaptateur Wintun via winipcfg sur Windows (avec DNS et MTU) ; nécessite des privilèges
pkg/routeclientsurveille le RouteService du serveur et signale les mises à jour de routes ; TLS sauf vers la boucle locale
pkg/appcorela logique des applications, commune aux trois : connexion, locataire choisi pour la session, connexion et déconnexion via le helper, état pour l’interface
pkg/helperle helper privilégié, commun aux trois applications : enrôle, possède le tunnel, surveille les envois de routes
pkg/hproto, pkg/helperclientle protocole de socket du helper, et le client de l’application pour ce protocole
pkg/tokenstorela session (bearer, jeton de rafraîchissement, clé privée de l’appareil, locataire choisi) dans un fichier JSON 0600

Fichiers sur l’appareil

FichierContenu
<config dir>/Claimward/config.jsonla configuration de l’application (appcore.Config), 0600, surchargée par les variables CLAIMWARD_*
<config dir>/claimward/session.jsonla session (pkg/tokenstore), 0600

<config dir> est le os.UserConfigDir() de Go : ~/Library/Application Support sur macOS, ~/.config sur Linux, %AppData% sur Windows.

Clé de config.jsonVariable
server_urlCLAIMWARD_SERVERl’URL de base du serveur ; doit faire partie de celles pour lesquelles le helper est configuré
providerCLAIMWARD_AUTH_PROVIDERgithub (par défaut), oidc ou go-authn
github_client_idCLAIMWARD_GITHUB_CLIENT_IDl’identifiant client de l’application OAuth GitHub
oidc_issuerCLAIMWARD_OIDC_ISSUERoidc et go-authn
oidc_client_idCLAIMWARD_OIDC_CLIENT_IDoidc et go-authn
socket_pathCLAIMWARD_HELPER_SOCKETla socket du helper, si ce n’est pas celle par défaut

Utilisation dans vos propres outils

ctx := context.Background()

// 1. Sign in. GitHub is the default provider (device flow).
provider, err := auth.New(auth.Config{Provider: "github", GitHubClientID: "Iv1.0123456789abcdef"})
if err != nil {
	log.Fatal(err)
}
tok, err := provider.Login(ctx, func(p auth.DevicePrompt) {
	fmt.Printf("visit %s and enter code %s\n", p.VerificationURI, p.UserCode)
})
if err != nil {
	log.Fatal(err)
}

// 2. A key pair, and with go-authn the PUBLIC key registered first: the
//    token for the server is the one RegisterKey returns.
keys, err := wgkey.Generate()
if err != nil {
	log.Fatal(err)
}
if reg, ok := provider.(auth.KeyRegistrar); ok {
	if tok, err = reg.RegisterKey(ctx, tok, keys.Public.String(), "laptop"); err != nil {
		log.Fatal(err)
	}
}

// 3. Enroll; "" lets the server use the person's only tenant.
c := client.New("https://vpn.example.com")
resp, err := c.Enroll(ctx, tok.Value, keys.Public,
	protocol.DeviceInfo{Name: "laptop", OS: "linux", Platform: "my-tool"}, "")
if err != nil {
	log.Fatal(err)
}

// 4. The tunnel (needs privileges), and optionally live routes.
cfg, err := client.TunnelConfig(resp, keys.Private)
if err != nil {
	log.Fatal(err)
}
tun, err := wgtun.Up(cfg)
if err != nil {
	log.Fatal(err)
}
defer tun.Close()
if resp.GRPCEndpoint != "" {
	go routeclient.Watch(ctx, resp.GRPCEndpoint, tok.Value, keys.Public.String(),
		func(u routeclient.Update) { _ = tun.UpdateRoutes(u.AllowedIPs) })
}

Un client de longue durée renouvelle son bail avec c.Heartbeat avant resp.LeaseExpiresAt, et supprime son pair avec c.Deregister lorsqu’il a terminé.

Notes par plateforme

  • DNS. Les serveurs DNS du serveur ne sont appliqués que sur Windows ; sur macOS et Linux, ils sont transportés par le protocole mais pkg/wgtun ne les applique pas encore.
  • Les envois de routes remplacent les IP autorisées et les routes ; les changements DNS contenus dans un envoi ne sont pas appliqués.
  • Windows. Le périphérique est un adaptateur Wintun nommé Claimward : wintun.dll (provenant de https://www.wintun.net, signé par WireGuard LLC) doit se trouver à côté de l’exécutable qui appelle wgtun.Up, ce dont se charge le packaging de l’application Windows. L’adresse, les routes, le DNS et le MTU sont configurés via winipcfg (l’API IP Helper, en Go pur, CGO_ENABLED=0).
  • Stockage de la session. Un fichier 0600 ; son déplacement vers le magasin de secrets de la plateforme reste à venir.

Créée le par tannevaled

Modifiée le par tannevaled