cxp

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 2, 2026 License: AGPL-3.0 Imports: 2 Imported by: 0

README

go-cxp

Go implementation of the FIDO Alliance Credential Exchange Protocol (CXP) v1.0.

Test

Overview

This package provides Go type definitions for the CXP protocol messages used for secure credential exchange between providers. It implements the types defined in the CXP specification.

For the Credential Exchange Format (CXF) types, see github.com/nvinuesa/go-cxf.

Installation

go get github.com/nvinuesa/go-cxp

Usage

package main

import (
    "encoding/json"
    "fmt"

    "github.com/nvinuesa/go-cxp"
)

func main() {
    // Create an export request
    req := cxp.ExportRequest{
        Version:  cxp.VersionV0,
        Importer: "importer.example.com",
        Hpke: []cxp.HpkeParameters{
            {
                Mode: cxp.HpkeModeBase,
                Kem:  cxp.HpkeKemDhX25519,
                Kdf:  cxp.HpkeKdfHkdfSha256,
                Aead: cxp.HpkeAeadAes256Gcm,
            },
        },
        CredentialTypes: []cxp.CredentialType{
            cxp.CredentialTypePasskey,
            cxp.CredentialTypeBasicAuth,
        },
    }

    // Serialize to JSON
    data, _ := json.MarshalIndent(req, "", "  ")
    fmt.Println(string(data))
}

Types

Protocol Messages
  • ExportRequest - Request sent by the importing provider
  • ExportResponse - Response containing encrypted credentials
  • ErrorResponse - Error response with error code
HPKE Configuration
  • HpkeParameters - HPKE encryption parameters
  • HpkeMode - HPKE operating mode (base, psk, auth, auth-psk)
  • HpkeKem - Key Encapsulation Mechanism identifiers
  • HpkeKdf - Key Derivation Function identifiers
  • HpkeAead - AEAD cipher identifiers
Enums
  • Version - Protocol version (currently V0)
  • CredentialType - Types of credentials (passkey, basic-auth, totp, etc.)
  • KnownExtension - Protocol extensions (shared)
  • ErrorCode - Error codes for failed exchanges

License

See LICENSE file.

Documentation

Overview

Package cxp provides Go types for the FIDO Alliance Credential Exchange Protocol (CXP) v1.0.

This package implements the protocol message types for secure credential exchange between providers. It is designed to be used alongside github.com/nvinuesa/go-cxf for the Credential Exchange Format types.

See: https://fidoalliance.org/specs/cx/cxp-v1.0-wd-20241003.html

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ArchiveAlgorithm added in v0.1.1 

type ArchiveAlgorithm string

ArchiveAlgorithm represents an archiving algorithm for compressing credentials. See: https://fidoalliance.org/specs/cx/cxp-v1.0-wd-20240522.html#dom-archivealgorithm-deflate 

const (
	// ArchiveAlgorithmDeflate uses the DEFLATE algorithm defined in RFC1951.
	ArchiveAlgorithmDeflate ArchiveAlgorithm = "deflate"
)

type CredentialType 

type CredentialType string

CredentialType represents a type of credential that can be exchanged. 

const (
	CredentialTypeBasicAuth        CredentialType = "basic-auth"
	CredentialTypePasskey          CredentialType = "passkey"
	CredentialTypeTotp             CredentialType = "totp"
	CredentialTypeNote             CredentialType = "note"
	CredentialTypeFile             CredentialType = "file"
	CredentialTypeAddress          CredentialType = "address"
	CredentialTypeCreditCard       CredentialType = "credit-card"
	CredentialTypeDriverLicense    CredentialType = "driver-license"
	CredentialTypeItemReference    CredentialType = "item-reference"
	CredentialTypeIdentityDocument CredentialType = "identity-document"
	CredentialTypePassport         CredentialType = "passport"
	CredentialTypePersonName       CredentialType = "person-name"
	CredentialTypeSshKey           CredentialType = "ssh-key"
	CredentialTypeApiKey           CredentialType = "api-key"
)

type ErrorCode 

type ErrorCode string

ErrorCode represents an error that occurred during credential exchange. 

const (
	// ErrorUserCanceled indicates that a user confirmation action was refused.
	ErrorUserCanceled ErrorCode = "user-canceled"
	// ErrorIncompatibleHpkeParameters indicates the exporter doesn't support any requested HPKE parameters.
	ErrorIncompatibleHpkeParameters ErrorCode = "incompatible-hpke-parameters"
	// ErrorMissingImporterKey indicates the importer didn't provide a required key.
	ErrorMissingImporterKey ErrorCode = "missing-importer-key"
	// ErrorIncorrectImporterKeyEncoding indicates the importer provided an invalid key.
	ErrorIncorrectImporterKeyEncoding ErrorCode = "incorrect-importer-key-encoding"
	// ErrorUnsupportedVersion indicates the exporter doesn't support the requested protocol version.
	ErrorUnsupportedVersion ErrorCode = "unsupported-version"
	// ErrorInvalidJson indicates an error occurred while parsing the JSON request.
	ErrorInvalidJson ErrorCode = "invalid-json"
	// ErrorForbiddenAction indicates the exporter refused the export due to policy.
	ErrorForbiddenAction ErrorCode = "forbidden-action"
)

type ErrorResponse 

type ErrorResponse struct {
	Version Version   `json:"version"`
	Error   ErrorCode `json:"error"`
}

ErrorResponse is sent by the exporting provider when an error occurs.

type ExportRequest 

type ExportRequest struct {
	Version         Version            `json:"version"`
	Hpke            []HpkeParameters   `json:"hpke"`
	Importer        string             `json:"importer"`
	Archive         []ArchiveAlgorithm `json:"archive,omitempty"`
	CredentialTypes []CredentialType   `json:"credentialTypes,omitempty"`
	KnownExtensions []KnownExtension   `json:"knownExtensions,omitempty"`
}

ExportRequest is sent by the importing provider to request credentials from an exporting provider.

type ExportResponse 

type ExportResponse struct {
	Version  Version          `json:"version"`
	Hpke     HpkeParameters   `json:"hpke"`
	Exporter string           `json:"exporter"`
	Archive  ArchiveAlgorithm `json:"archive,omitempty"`
	Payload  string           `json:"payload"` // base64url encoded
}

ExportResponse is sent by the exporting provider containing encrypted credentials.

type HpkeAead 

type HpkeAead uint16

HpkeAead represents the HPKE AEAD cipher. 

const (
	HpkeAeadReserved         HpkeAead = 0x0000
	HpkeAeadAes128Gcm        HpkeAead = 0x0001
	HpkeAeadAes256Gcm        HpkeAead = 0x0002
	HpkeAeadChaCha20Poly1305 HpkeAead = 0x0003
	HpkeAeadExportOnly       HpkeAead = 0xFFFF
)

func (HpkeAead) MarshalJSON 

func (a HpkeAead) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for HpkeAead.

func (HpkeAead) String 

func (a HpkeAead) String() string

String returns the string representation of the AEAD.

func (*HpkeAead) UnmarshalJSON 

func (a *HpkeAead) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for HpkeAead.

type HpkeKdf 

type HpkeKdf uint16

HpkeKdf represents the HPKE Key Derivation Function. 

const (
	HpkeKdfReserved   HpkeKdf = 0x0000
	HpkeKdfHkdfSha256 HpkeKdf = 0x0001
	HpkeKdfHkdfSha384 HpkeKdf = 0x0002
	HpkeKdfHkdfSha512 HpkeKdf = 0x0003
)

func (HpkeKdf) MarshalJSON 

func (k HpkeKdf) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for HpkeKdf.

func (HpkeKdf) String 

func (k HpkeKdf) String() string

String returns the string representation of the KDF.

func (*HpkeKdf) UnmarshalJSON 

func (k *HpkeKdf) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for HpkeKdf.

type HpkeKem 

type HpkeKem uint16

HpkeKem represents the HPKE Key Encapsulation Mechanism. 

const (
	HpkeKemReserved              HpkeKem = 0x0000
	HpkeKemDhP256                HpkeKem = 0x0010
	HpkeKemDhP384                HpkeKem = 0x0011
	HpkeKemDhP521                HpkeKem = 0x0012
	HpkeKemDhCP256               HpkeKem = 0x0013
	HpkeKemDhCP384               HpkeKem = 0x0014
	HpkeKemDhCP521               HpkeKem = 0x0015
	HpkeKemDhSecP256K1           HpkeKem = 0x0016
	HpkeKemDhX25519              HpkeKem = 0x0020
	HpkeKemDhX448                HpkeKem = 0x0021
	HpkeKemX25519Kyber768Draft00 HpkeKem = 0x0030
)

func (HpkeKem) MarshalJSON 

func (k HpkeKem) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for HpkeKem.

func (HpkeKem) String 

func (k HpkeKem) String() string

String returns the string representation of the KEM.

func (*HpkeKem) UnmarshalJSON 

func (k *HpkeKem) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for HpkeKem.

type HpkeMode 

type HpkeMode string

HpkeMode represents the HPKE operating mode. 

const (
	HpkeModeBase    HpkeMode = "base"
	HpkeModePsk     HpkeMode = "psk"
	HpkeModeAuth    HpkeMode = "auth"
	HpkeModeAuthPsk HpkeMode = "auth-psk"
)

type HpkeParameters 

type HpkeParameters struct {
	Mode HpkeMode        `json:"mode"`
	Kem  HpkeKem         `json:"kem"`
	Kdf  HpkeKdf         `json:"kdf"`
	Aead HpkeAead        `json:"aead"`
	Key  json.RawMessage `json:"key,omitempty"` // JWK
}

HpkeParameters defines the HPKE configuration for encryption.

func (HpkeParameters) Equal 

func (h HpkeParameters) Equal(other HpkeParameters) bool

Equal compares two HpkeParameters, ignoring the Key field (which is ephemeral).

type KnownExtension 

type KnownExtension string

KnownExtension represents a known protocol extension. 

const (
	// KnownExtensionShared represents the shared credentials extension.
	KnownExtensionShared KnownExtension = "shared"
)

type Version 

type Version uint8

Version represents the protocol version. 

const (
	// VersionV0 is the current protocol version.
	VersionV0 Version = 0
)

func (Version) MarshalJSON 

func (v Version) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for Version.

func (*Version) UnmarshalJSON 

func (v *Version) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for Version.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.