rpc

Documentation

Overview

Package rpc is a provider that defines an HTTP request/response contract for handling BMC interactions. It allows users a simple way to interoperate with an existing/bespoke out-of-band management solution.

The rpc provider request/response payloads are modeled after JSON-RPC 2.0, but are not JSON-RPC 2.0 compliant so as to allow for more flexibility and interoperability with existing systems.

The rpc provider has options that can be set to include an HMAC signature in the request header. It follows the features found at https://webhooks.fyi/security/hmac, this includes hash algorithms sha256 and sha512, replay prevention, versioning, and key rotation.

Index

• Variables
• func CreateHashes(s Secrets) map[Algorithm][]hash.Hash
• type Algorithm
  • func (a Algorithm) ToShort() Algorithm
• type BootDeviceParams
• type Experimental
• type HMACOpts
• type Hashes
  • func NewSHA256(secret ...string) Hashes
  • func NewSHA512(secret ...string) Hashes
• type Method
• type Opts
• type PowerGetResult
  • func (p PowerGetResult) String() string
• type PowerSetParams
• type Provider
  • func New(consumerURL string, host string, secrets Secrets) *Provider
  • func (p *Provider) BootDeviceSet(ctx context.Context, bootDevice string, setPersistent, efiBoot bool) (ok bool, err error)
  • func (p *Provider) Close(_ context.Context) (err error)
  • func (p *Provider) Name() string
  • func (p *Provider) Open(ctx context.Context) error
  • func (p *Provider) PowerSet(ctx context.Context, state string) (ok bool, err error)
  • func (p *Provider) PowerStateGet(ctx context.Context) (state string, err error)
  • func (p *Provider) Transformer(typ reflect.Type) func(dst, src reflect.Value) error
• type RequestOpts
• type RequestPayload
• type ResponseError
  • func (r *ResponseError) String() string
• type ResponsePayload
• type Secrets
• type SignatureOpts
• type Signatures
• type VirtualMediaParams

Variables

var Features = registrar.Features{
	providers.FeaturePowerSet,
	providers.FeaturePowerState,
	providers.FeatureBootDeviceSet,
}

Features implemented by the RPC provider.

Functions

func CreateHashes

func CreateHashes(s Secrets) map[Algorithm][]hash.Hash

CreateHashes creates a new hash for all secrets provided.

Types

type Algorithm

type Algorithm string

Algorithm is the type for HMAC algorithms.

const (
	// ProviderName for the RPC implementation.
	ProviderName = "rpc"
	// ProviderProtocol for the rpc implementation.
	ProviderProtocol = "http"

	// SHA256 is the SHA256 algorithm.
	SHA256 Algorithm = "sha256"
	// SHA256Short is the short version of the SHA256 algorithm.
	SHA256Short Algorithm = "256"
	// SHA512 is the SHA512 algorithm.
	SHA512 Algorithm = "sha512"
	// SHA512Short is the short version of the SHA512 algorithm.
	SHA512Short Algorithm = "512"
)

func (Algorithm) ToShort

func (a Algorithm) ToShort() Algorithm

ToShort returns the short version of an algorithm.

type BootDeviceParams

type BootDeviceParams struct {
	Device     string `json:"device"`
	Persistent bool   `json:"persistent"`
	EFIBoot    bool   `json:"efiBoot"`
}

BootDeviceParams are the parameters options used when setting a boot device.

type Experimental

type Experimental struct {
	// CustomRequestPayload must be in json.
	CustomRequestPayload []byte
	// DotPath is the path to where the bmclib RequestPayload{} will be embedded. For example: object.data.body
	DotPath string
}

type HMACOpts

type HMACOpts struct {
	// Hashes is a map of algorithms to a slice of hash.Hash (these are the hashed secrets). The slice is used to support multiple secrets.
	Hashes map[Algorithm][]hash.Hash
	// PrefixSigDisabled determines whether the algorithm will be prefixed to the signature. Example: sha256=abc123
	PrefixSigDisabled bool
	// Secrets are a map of algorithms to secrets used for signing.
	Secrets Secrets
}

type Hashes

type Hashes map[Algorithm][]hash.Hash

func NewSHA256

func NewSHA256(secret ...string) Hashes

NewSHA256 returns a map of SHA256 HMACs from the given secrets.

func NewSHA512

func NewSHA512(secret ...string) Hashes

NewSHA512 returns a map of SHA512 HMACs from the given secrets.

type Method

type Method string

const (
	BootDeviceMethod   Method = "setBootDevice"
	PowerSetMethod     Method = "setPowerState"
	PowerGetMethod     Method = "getPowerState"
	VirtualMediaMethod Method = "setVirtualMedia"
	PingMethod         Method = "ping"
)

type Opts

type Opts struct {
	// Request is the options used to create the rpc HTTP request.
	Request RequestOpts
	// Signature is the options used for adding an HMAC signature to an HTTP request.
	Signature SignatureOpts
	// HMAC is the options used to create a HMAC signature.
	HMAC HMACOpts
	// Experimental options.
	Experimental Experimental
}

type PowerGetResult

type PowerGetResult string

const (
	PoweredOn  PowerGetResult = "on"
	PoweredOff PowerGetResult = "off"
)

func (PowerGetResult) String

func (p PowerGetResult) String() string

type PowerSetParams

type PowerSetParams struct {
	State string `json:"state"`
}

PowerSetParams are the parameters options used when setting the power state.

type Provider

type Provider struct {
	// ConsumerURL is the URL where an rpc consumer/listener is running
	// and to which we will send and receive all notifications.
	ConsumerURL string
	// Host is the BMC ip address or hostname or identifier.
	Host string
	// HTTPClient is the http client used for all HTTP calls.
	HTTPClient *http.Client
	// Logger is the logger to use for logging.
	Logger logr.Logger
	// LogNotificationsDisabled determines whether responses from rpc consumer/listeners will be logged or not.
	LogNotificationsDisabled bool
	// Opts are the options for the rpc provider.
	Opts Opts
	// contains filtered or unexported fields
}

Provider defines the configuration for sending rpc notifications.

func New

func New(consumerURL string, host string, secrets Secrets) *Provider

New returns a new Config containing all the defaults for the rpc provider.

func (*Provider) BootDeviceSet

func (p *Provider) BootDeviceSet(ctx context.Context, bootDevice string, setPersistent, efiBoot bool) (ok bool, err error)

BootDeviceSet sends a next boot device rpc notification.

func (*Provider) Close

func (p *Provider) Close(_ context.Context) (err error)

Close a connection to the rpc consumer.

func (*Provider) Name

func (p *Provider) Name() string

Name returns the name of this rpc provider. Implements bmc.Provider interface

func (*Provider) Open

func (p *Provider) Open(ctx context.Context) error

Open a connection to the rpc consumer. For the rpc provider, Open means validating the Config and that communication with the rpc consumer can be established.

func (*Provider) PowerSet

func (p *Provider) PowerSet(ctx context.Context, state string) (ok bool, err error)

PowerSet sets the power state of a BMC machine.

func (*Provider) PowerStateGet

func (p *Provider) PowerStateGet(ctx context.Context) (state string, err error)

PowerStateGet gets the power state of a BMC machine.

func (*Provider) Transformer

func (p *Provider) Transformer(typ reflect.Type) func(dst, src reflect.Value) error

Transformer implements the mergo interfaces for merging custom types.

type RequestOpts

type RequestOpts struct {
	// HTTPContentType is the content type to use for the rpc request notification.
	HTTPContentType string
	// HTTPMethod is the HTTP method to use for the rpc request notification.
	HTTPMethod string
	// StaticHeaders are predefined headers that will be added to every request.
	StaticHeaders http.Header
	// TimestampFormat is the time format for the timestamp header.
	TimestampFormat string
	// TimestampHeader is the header name that should contain the timestamp. Example: X-BMCLIB-Timestamp
	TimestampHeader string
}

type RequestPayload

type RequestPayload struct {
	ID     int64  `json:"id"`
	Host   string `json:"host"`
	Method Method `json:"method"`
	Params any    `json:"params,omitempty"`
}

RequestPayload is the payload sent to the ConsumerURL.

type ResponseError

type ResponseError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

func (*ResponseError) String

func (r *ResponseError) String() string

type ResponsePayload

type ResponsePayload struct {
	// ID is the ID of the response. It should match the ID of the request but is not enforced.
	ID     int64          `json:"id"`
	Host   string         `json:"host"`
	Result any            `json:"result,omitempty"`
	Error  *ResponseError `json:"error,omitempty"`
}

ResponsePayload is the payload received from the ConsumerURL. The Result field is an interface{} so that different methods can define the contract according to their needs.

type Secrets

type Secrets map[Algorithm][]string

Secrets hold per algorithm slice secrets. These secrets will be used to create HMAC signatures.

type SignatureOpts

type SignatureOpts struct {
	// HeaderName is the header name that should contain the signature(s). Example: X-BMCLIB-Signature
	HeaderName string
	// AppendAlgoToHeaderDisabled decides whether to append the algorithm to the signature header or not.
	// Example: X-BMCLIB-Signature becomes X-BMCLIB-Signature-256
	// When set to true, a header will be added for each algorithm. Example: X-BMCLIB-Signature-256 and X-BMCLIB-Signature-512
	AppendAlgoToHeaderDisabled bool
	// IncludedPayloadHeaders are headers whose values will be included in the signature payload. Example: given these headers in a request:
	// X-My-Header=123,X-Another=456, and IncludedPayloadHeaders := []string{"X-Another"}, the value of "X-Another" will be included in the signature payload.
	// All headers will be deduplicated.
	IncludedPayloadHeaders []string
}

type Signatures

type Signatures map[Algorithm][]string

Signatures hold per algorithm slice of signatures.

type VirtualMediaParams

type VirtualMediaParams struct {
	MediaURL string `json:"mediaUrl"`
	Kind     string `json:"kind"`
}

PowerGetParams are the parameters options used when getting the power state.