sdkey

README

sdkey-go

Official Go client for SDKey license authentication.

Implements the sealed session protocol: Ed25519-verified handshake, HKDF session keys, and AES-256-GCM validate envelopes. See PROTOCOL.md.

Install

go get github.com/SDKeyDev/sdkey-go@v0.1.0

Requires Go 1.22+.

Quick start

Embed these values from the SDKey dashboard when you ship your app:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/SDKeyDev/sdkey-go"
)

func main() {
	client := sdkey.NewClient(sdkey.ClientOptions{
		APIBaseURL:      "https://api.sdkey.dev",
		AppID:           "YOUR_APP_ID",
		AppPublicKeyB64: "YOUR_APP_PUBLIC_KEY_BASE64",
	})

	result, err := client.Validate(context.Background(), "SDKY-XXXX-XXXX-XXXX-XXXX", "machine-hwid")
	if err != nil {
		if se, ok := err.(*sdkey.Error); ok {
			log.Fatalf("%s %s", se.Code, se.Message)
		}
		log.Fatal(err)
	}
	if result.Success {
		fmt.Println("licensed", result.Status, result.ExpiresAt)
	} else {
		fmt.Println("denied", result.Code, result.Message)
	}
}

Validate calls Init automatically when no session exists. Sessions last ~15 minutes server-side; on SESSION_EXPIRED the client clears local state so the next call re-handshakes.

API

sdkey.NewClient(opts)

Option	Type	Description
APIBaseURL	string	API origin (no trailing slash)
AppID	string	Application UUID
AppPublicKeyB64	string	Raw Ed25519 public key (32 bytes), base64
HTTPPost	HTTPPost	Optional HTTP POST override (tests / custom transport)

Methods

• Init(ctx) — challenge handshake; verifies the signed hello; derives the AES session key
• Validate(ctx, licenseKey, hwid) — sealed validate; always decrypts then verifies the Ed25519 signature before trusting success
• Session() / GetSession() / ClearSession() — inspect or drop the local session

Errors

Protocol / transport failures return *sdkey.Error with a Code:

INIT_FAILED · HELLO_SIGNATURE_INVALID · VALIDATE_RESPONSE_INVALID · RESPONSE_SIGNATURE_INVALID · SESSION_MISMATCH · CLOCK_SKEW · NETWORK

License denials (banned, HWID mismatch, etc.) return a normal ValidateResult with Success=false — they are not errors.

Security notes

• Never ship app private keys in a client.
• Do not skip signature verification — that is the anti-spoof binding.
• This package is open source; the SDKey server remains a separate product.

Development

go test ./...

License

MIT

Documentation

Overview

Package sdkey is the official Go client for SDKey license authentication.

It implements the sealed session protocol (Ed25519-verified handshake, HKDF session keys, AES-256-GCM validate envelopes). See PROTOCOL.md.

Index

• type Client
  • func NewClient(opts ClientOptions) *Client
  • func (c *Client) ClearSession()
  • func (c *Client) GetSession() *SessionState
  • func (c *Client) Init(ctx context.Context) (*SessionState, error)
  • func (c *Client) Session() *SessionState
  • func (c *Client) Validate(ctx context.Context, licenseKey, hwid string) (*ValidateResult, error)
• type ClientOptions
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorCode
• type HTTPPost
• type SessionState
• type ValidateResult

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the SDKey license client.

Flow: Init (session handshake) → Validate (sealed request). Validate calls Init automatically when no session exists.

func NewClient

func NewClient(opts ClientOptions) *Client

NewClient constructs a Client from options.

func (*Client) ClearSession

func (c *Client) ClearSession()

ClearSession drops the current session (next Validate will re-init).

func (*Client) GetSession

func (c *Client) GetSession() *SessionState

GetSession is an alias for Session (API parity with Python get_session).

func (*Client) Init

func (c *Client) Init(ctx context.Context) (*SessionState, error)

Init performs the challenge handshake, verifies the signed hello, and derives the AES session key.

func (*Client) Session

func (c *Client) Session() *SessionState

Session returns the active session, if any.

func (*Client) Validate

func (c *Client) Validate(ctx context.Context, licenseKey, hwid string) (*ValidateResult, error)

Validate sealed-validates a license key for hwid. Always decrypts then verifies the Ed25519 signature before trusting success.

type ClientOptions

type ClientOptions struct {
	// APIBaseURL is the API origin (trailing slashes are stripped).
	APIBaseURL string
	// AppID is the application UUID from the SDKey dashboard.
	AppID string
	// AppPublicKeyB64 is the raw Ed25519 public key (32 bytes), standard or URL-safe base64.
	AppPublicKeyB64 string
	// HTTPPost optionally overrides the default HTTPS JSON transport (tests / custom agents).
	HTTPPost HTTPPost
}

ClientOptions configures NewClient.

type Error

type Error struct {
	Code    ErrorCode
	Message string
	Cause   error
}

Error is a protocol or transport failure. License denials (banned, HWID mismatch, etc.) return ValidateResult, not Error.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorCode

type ErrorCode string

ErrorCode identifies protocol / transport failures (not license denials).

const (
	ErrInitFailed               ErrorCode = "INIT_FAILED"
	ErrHelloSignatureInvalid    ErrorCode = "HELLO_SIGNATURE_INVALID"
	ErrValidateResponseInvalid  ErrorCode = "VALIDATE_RESPONSE_INVALID"
	ErrResponseSignatureInvalid ErrorCode = "RESPONSE_SIGNATURE_INVALID"
	ErrSessionMismatch          ErrorCode = "SESSION_MISMATCH"
	ErrClockSkew                ErrorCode = "CLOCK_SKEW"
	ErrNetwork                  ErrorCode = "NETWORK"
	ErrUnknown                  ErrorCode = "UNKNOWN"
)

type HTTPPost

type HTTPPost func(ctx context.Context, url string, body map[string]any) (status int, response map[string]any, err error)

HTTPPost posts a JSON body and returns status code plus parsed JSON object. Used for injectable transport in tests and custom HTTP stacks.

type SessionState

type SessionState struct {
	SessionID      string
	AESKey         []byte
	ServerNonceB64 string
	HKDFSaltB64    string
}

SessionState is the active sealed session after a successful Init.

type ValidateResult

type ValidateResult struct {
	Success   bool
	Code      string
	Message   string
	Status    *string
	ExpiresAt *string
	Timestamp int64
}

ValidateResult is a decrypted, signature-verified license validate response. License denials use Success=false with a code; they are not SdkeyError.