encryption

Documentation

Index

• type Client
  • func New(webexClient *webexsdk.Client, config *Config) *Client
  • func (c *Client) CacheKey(key *Key)
  • func (c *Client) DecryptMessageContent(encryptionKeyURL string, encryptedContent string) (string, error)
  • func (c *Client) DecryptText(keyURI string, ciphertext string) (string, error)
  • func (c *Client) GetKey(keyURI string) (*Key, error)
  • func (c *Client) ProcessKMSMessages(jweStrings []string)
  • func (c *Client) SetDeviceInfo(deviceURL, userID string)
• type Config
  • func DefaultConfig() *Config
• type ECDHContext
• type JWK
  • func (j *JWK) SymmetricKey() ([]byte, error)
• type KMSClient
• type KMSCredential
• type KMSEnvelope
• type KMSInfo
• type KMSMessage
  • func (m *KMSMessage) IsSuccess() bool
• type KMSRequestPayload
• type Key

Types

type Client

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

Client is the Encryption API client

func New

func New(webexClient *webexsdk.Client, config *Config) *Client

New creates a new Encryption plugin

func (*Client) CacheKey

func (c *Client) CacheKey(key *Key)

CacheKey manually caches a key. This is used when keys arrive via Mercury WebSocket events (e.g., encryption.kmsMessages).

func (*Client) DecryptMessageContent

func (c *Client) DecryptMessageContent(encryptionKeyURL string, encryptedContent string) (string, error)

DecryptMessageContent attempts to decrypt message content using encryption key URL

func (*Client) DecryptText

func (c *Client) DecryptText(keyURI string, ciphertext string) (string, error)

DecryptText decrypts JWE-encrypted text using a KMS key. The ciphertext must be in JWE compact serialization format (5 dot-separated parts). Supports alg:dir + enc:A256GCM as used by Webex end-to-end encryption.

func (*Client) GetKey

func (c *Client) GetKey(keyURI string) (*Key, error)

GetKey retrieves a key from KMS. It uses a singleflight pattern: if multiple goroutines request the same key URI concurrently, only one KMS round-trip is made and the result is shared with all waiters. This prevents thundering-herd flooding of KMS when many encrypted messages arrive at once referencing the same key.

func (*Client) ProcessKMSMessages

func (c *Client) ProcessKMSMessages(jweStrings []string)

ProcessKMSMessages processes KMS messages received via Mercury WebSocket events. These messages are JWE-encrypted and may contain: - ECDH exchange responses (encrypted with client's ECDH public key) - Key retrieval responses (encrypted with the ECDH shared secret) - Key rotation notifications

Messages matching a pending request (via requestId) are delivered to the waiting goroutine. Others are processed for key caching.

func (*Client) SetDeviceInfo

func (c *Client) SetDeviceInfo(deviceURL, userID string)

SetDeviceInfo sets the device URL and user ID for KMS communication. The device URL is used as the client ID in KMS requests. The user ID is used to look up the KMS cluster info.

type Config

type Config struct {
	// HTTPTimeout is the timeout for HTTP requests to the KMS service
	HTTPTimeout time.Duration
	// DefaultCluster is the default KMS cluster to use when not specified
	DefaultCluster string
	// DisableCache disables the key caching mechanism
	DisableCache bool
}

Config holds the configuration for the Encryption plugin

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns the default configuration for the Encryption plugin

type ECDHContext

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

ECDHContext holds the ECDH key exchange state for KMS communication. After a successful key exchange, the shared secret is used to wrap/unwrap all subsequent KMS requests and responses using dir+A256GCM.

type JWK

type JWK struct {
	Kty string `json:"kty"`           // Key type (oct, EC, RSA)
	K   string `json:"k,omitempty"`   // Key value (for symmetric/oct keys, base64url-encoded)
	Crv string `json:"crv,omitempty"` // Curve (for EC keys)
	X   string `json:"x,omitempty"`   // X coordinate (for EC keys)
	Y   string `json:"y,omitempty"`   // Y coordinate (for EC keys)
	D   string `json:"d,omitempty"`   // Private key (for EC keys)
	N   string `json:"n,omitempty"`   // Modulus (for RSA keys)
	E   string `json:"e,omitempty"`   // Exponent (for RSA keys)
	Kid string `json:"kid,omitempty"` // Key ID
	Alg string `json:"alg,omitempty"` // Algorithm
}

JWK represents a JSON Web Key

func (*JWK) SymmetricKey

func (j *JWK) SymmetricKey() ([]byte, error)

SymmetricKey extracts the raw symmetric key bytes from an oct-type JWK. Returns an error if the key type is not "oct" or the key value is empty.

type KMSClient

type KMSClient struct {
	ClientID   string         `json:"clientId"`
	Credential *KMSCredential `json:"credential"`
}

KMSClient identifies the client making a KMS request.

type KMSCredential

type KMSCredential struct {
	UserID string `json:"userId"`
	Bearer string `json:"bearer"`
}

KMSCredential holds authentication info for KMS requests.

type KMSEnvelope

type KMSEnvelope struct {
	KMSMessages []string `json:"kmsMessages"`
	Destination string   `json:"destination,omitempty"`
}

KMSEnvelope is the HTTP request/response envelope for POST /encryption/api/v1/kms/messages

type KMSInfo

type KMSInfo struct {
	KMSCluster   string          `json:"kmsCluster"`
	RSAPublicKey json.RawMessage `json:"rsaPublicKey"`
}

KMSInfo represents the response from GET /encryption/api/v1/kms/{userId}

type KMSMessage

type KMSMessage struct {
	Method      string                 `json:"method,omitempty"`      // Method to perform (retrieve, create, etc.)
	URI         string                 `json:"uri,omitempty"`         // URI of the key
	ResourceURI string                 `json:"resourceUri,omitempty"` // URI of the resource
	RequestID   string                 `json:"requestId,omitempty"`   // ID of the request
	Status      interface{}            `json:"status,omitempty"`      // Status of the response (string or int)
	Key         *Key                   `json:"key,omitempty"`         // Key in the response
	Keys        []*Key                 `json:"keys,omitempty"`        // Multiple keys in the response
	UserIDs     []string               `json:"userIds,omitempty"`     // User IDs for key creation
	KeyURIs     []string               `json:"keyUris,omitempty"`     // Key URIs for batch operations
	Resource    map[string]interface{} `json:"resource,omitempty"`    // Resource data
	JWK         *JWK                   `json:"jwk,omitempty"`         // JWK for ECDH key exchange
}

KMSMessage represents a message to/from the KMS service

func (*KMSMessage) IsSuccess

func (m *KMSMessage) IsSuccess() bool

IsSuccess checks if the KMS response indicates success. Handles both string ("success") and numeric (200/201) status values.

type KMSRequestPayload

type KMSRequestPayload struct {
	Client    *KMSClient `json:"client"`
	RequestID string     `json:"requestId"`
	Method    string     `json:"method"`
	URI       string     `json:"uri"`
	JWK       *JWK       `json:"jwk,omitempty"` // For ECDH exchange
}

KMSRequestPayload is the full KMS request payload (inside the JWE). This includes the client credentials needed for KMS authentication.

type Key

type Key struct {
	URI string `json:"uri"` // URI of the key
	JWK JWK    `json:"jwk"` // JSON Web Key
}

Key represents a KMS key