epa

package module
v0.20.3 Latest Latest
Warning

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

Go to latest
Published: Jun 28, 2026 License: EUPL-1.2 Imports: 40 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var UserAgent = fmt.Sprintf("zero-epa-client/%s", Version)
View Source
var Version = "dev"

Version is the zero-epa release version. It defaults to "dev" and is overridden at build time via -ldflags "-X github.com/gematik/zero-lab/go/epa.Version=<v>".

Functions

func CalculateHCV

func CalculateHCV(coverageBegin, streetAddress string) ([]byte, error)

func HandleReadmeFunc

func HandleReadmeFunc(proxyInfos []*ProxyInfo) http.HandlerFunc

func IDPEnvironment

func IDPEnvironment(env Env) gemidp.Environment

func LoadIdentityP12 added in v0.20.3

func LoadIdentityP12(path, password string) (*ecdsa.PrivateKey, *x509.Certificate, error)

LoadIdentityP12 loads the SMC-B authentication (AUT) identity from a PKCS#12 file: the EC certificate with KeyUsage digitalSignature set (and contentCommitment unset, which marks the OSIG cert) plus its matching Brainpool private key. The repo's brainpool parsers are used because stdlib crypto/x509 does not know the Brainpool curves. Legacy BER-encoded PKCS#12 (older gematik test cards) is converted via OpenSSL first.

func ResolveBaseURL

func ResolveBaseURL(env Env, provider ProviderNumber) string

func ResolveVersion

func ResolveVersion() string

ResolveVersion returns the ldflags-injected Version when set, otherwise the module version embedded by `go install …@vX.Y.Z` (read from the build info).

Types

type Client

type Client struct {
	Env            Env
	ProviderNumber ProviderNumber
	BaseURL        string
	HttpClient     *http.Client

	Timeout time.Duration
	// contains filtered or unexported fields
}

Client is a cheap, pre-VAU handle to an aggregator. It owns the HTTP transport and identity material needed for both the unauthenticated /information endpoints and for opening a VAU session.

Methods that hit /information endpoints (e.g. GetRecordStatus, GetConsentDecisionInformation) live on *Client and do NOT require an open VAU channel. Use OpenSession to upgrade to a *Session for VAU-bound calls.

func NewClient

func NewClient(env Env, provider ProviderNumber, sf *SecurityFunctions, options ...ClientOption) (*Client, error)

NewClient builds a Client for the given aggregator. It does not perform any network calls; the returned Client is ready to use for /information endpoints, and may be promoted to a *Session via OpenSession when a VAU channel is needed.

func (*Client) Close

func (c *Client) Close()

Close releases idle HTTP connections held by the Client.

func (*Client) GetConsentDecisionInformation

func (c *Client) GetConsentDecisionInformation(insurantId string) (*GetConsentDecisionInformationType, error)

func (*Client) GetRecordStatus

func (c *Client) GetRecordStatus(insurantId string) (bool, error)

func (*Client) OpenSession

func (c *Client) OpenSession() (*Session, error)

OpenSession performs the VAU handshake and returns a Session that can be Authorized for VAU-bound calls. The underlying Client (HTTP transport, identity) is shared with the returned Session via embedding.

type ClientOption

type ClientOption func(*Client)

func WithCertPool

func WithCertPool(certPool *x509.CertPool) ClientOption

func WithHTTPClient added in v0.20.3

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient supplies the base HTTP client. The epa client layers its TLS settings and User-Agent onto a copy of it; when unset, a client with a default timeout is created.

func WithInsecureSkipVerify

func WithInsecureSkipVerify() ClientOption

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOption

type Config

type Config struct {
	BaseDir      string        `yaml:"-"` // set to the base directory of config files when loading
	ProxyConfigs []ProxyConfig `yaml:"proxies" validate:"required,dive,required"`
}

func LoadConfigFile

func LoadConfigFile(path string) (*Config, error)

func (*Config) GetDefaultProxyConfig

func (c *Config) GetDefaultProxyConfig() (*ProxyConfig, bool)

func (*Config) GetProxyConfigByName

func (c *Config) GetProxyConfigByName(name string) (*ProxyConfig, bool)

type ConsentDecisionType

type ConsentDecisionType string
const (
	ConsentDecisionPermit ConsentDecisionType = "permit"
	ConsentDecisionDeny   ConsentDecisionType = "deny"
)

type ConsentDecisionsResponseType

type ConsentDecisionsResponseType struct {
	FunctionId string `json:"functionId"`
	Decision   string `json:"decision"`
}

type EntitlementRequestType

type EntitlementRequestType struct {
	JWT string `json:"jwt"`
}

type Env

type Env string

enumeration for environment

const (
	EnvDev  Env = "dev"
	EnvTest Env = "test"
	EnvRef  Env = "ref"
	EnvProd Env = "prod"
)

func EnvFromString

func EnvFromString(s string) (Env, error)

func (Env) String

func (e Env) String() string

type ErrorType

type ErrorType struct {
	HttpStatusCode int    `json:"-"`
	ErrorCode      string `json:"errorCode"`
	ErrorDetail    string `json:"errorDetail,omitempty"`
}

func (*ErrorType) Error

func (e *ErrorType) Error() string

type GetConsentDecisionInformationType

type GetConsentDecisionInformationType struct {
	Data []ConsentDecisionsResponseType `json:"data"`
}

type MultiProviderError

type MultiProviderError struct {
	Errors []ProvidersError `json:"errors"`
}

func (*MultiProviderError) Error

func (e *MultiProviderError) Error() string

type Nonce

type Nonce struct {
	Nonce string `json:"nonce"`
}

type PatientRecordMetadata

type PatientRecordMetadata struct {
	InsurantID string
	Provider   ProviderNumber
}

type ProvideHCVFunc

type ProvideHCVFunc func(insurantId string) ([]byte, error)

type ProvidePNFunc

type ProvidePNFunc func(insurantId string) (string, error)

func CalculatePNv2

func CalculatePNv2(hmacKeyHex string, hmacKeyKid string, provideHcv ProvideHCVFunc) (ProvidePNFunc, error)

func ProvidePNByHMAC

func ProvidePNByHMAC(hmacKeyHex string, hmacKeyKid string) (ProvidePNFunc, error)

type ProviderNumber

type ProviderNumber int
const (
	ProviderNumber1 ProviderNumber = 1
	ProviderNumber2 ProviderNumber = 2
	ProviderNumber3 ProviderNumber = 3
)

type ProvidersError

type ProvidersError struct {
	Code           string         `json:"error"`
	Description    string         `json:"error_description"`
	ProviderNumber ProviderNumber `json:"provider"`
}

func (*ProvidersError) Error

func (e *ProvidersError) Error() string

type Proxy

type Proxy struct {
	Env Env

	Authenticator *gemidp.Authenticator
	// contains filtered or unexported fields
}

func NewProxy

func NewProxy(config *ProxyConfig) (*Proxy, error)

func NewProxyWithSecurityFunctions

func NewProxyWithSecurityFunctions(env Env, sf *SecurityFunctions, name string, timeout time.Duration, certPool *x509.CertPool) (*Proxy, error)

NewProxyWithSecurityFunctions builds a Proxy from a pre-assembled SecurityFunctions, skipping ProxyConfig.Init() (which reads cert+key files from disk and assembles a VSDM-HMAC ProvidePN). Use this from callers that already produced SecurityFunctions through some other identity backend (e.g. a Konnektor-backed signer or a PKCS#12 loaded in another process).

ProvidePN / ProvideHCV may be left nil on sf when the caller is only interested in /information endpoints and the VAU handshake; VAU-bound calls that need entitlement will fail at the first call with a clear nil-deref error from the consuming code.

func (*Proxy) Close

func (p *Proxy) Close()

func (*Proxy) GetInsurants

func (p *Proxy) GetInsurants(w http.ResponseWriter, r *http.Request)

func (*Proxy) GetProviders

func (p *Proxy) GetProviders(w http.ResponseWriter, r *http.Request)

func (*Proxy) GetProxyInfo

func (p *Proxy) GetProxyInfo() (*ProxyInfo, error)

func (*Proxy) HandleForwardToProvider

func (p *Proxy) HandleForwardToProvider(w http.ResponseWriter, r *http.Request)

func (*Proxy) HandleForwardToVAUInsurant

func (p *Proxy) HandleForwardToVAUInsurant(w http.ResponseWriter, r *http.Request)

func (*Proxy) HandleForwardToVAUProvider

func (p *Proxy) HandleForwardToVAUProvider(w http.ResponseWriter, r *http.Request)

func (*Proxy) HandleProxyInfo

func (p *Proxy) HandleProxyInfo(w http.ResponseWriter, r *http.Request)

func (*Proxy) ServeHTTP

func (p *Proxy) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ProxyConfig

type ProxyConfig struct {
	BaseDir string        `yaml:"-"`
	Name    string        `yaml:"name" validate:"required"`
	Env     Env           `yaml:"env" validate:"required,oneof=dev test ref prod"`
	Timeout time.Duration `yaml:"timeout" validate:"required,gt=0"`

	// SMC-B identity: either a PKCS#12 (authn_p12_path) or a PEM cert+key pair
	// (authn_cert_path + authn_key_path). PKCS#12 takes precedence when set.
	AuthnP12Path     string `yaml:"authn_p12_path"`
	AuthnP12Password string `yaml:"authn_p12_password"`
	AuthnCertPath    string `yaml:"authn_cert_path"`
	AuthnKeyPath     string `yaml:"authn_key_path"`

	VsdmHmacKeyHex string `yaml:"vsdm_hmac_key_hex" validate:"required"`
	VsdmHmacKeyId  string `yaml:"vsdm_hmac_key_id" validate:"required"`

	SecurityFunctions *SecurityFunctions `yaml:"-"`

	// CertPool is the TLS root pool used when connecting to ePA aggregators.
	// When nil, the session manager falls back to InsecureSkipVerify — fine for
	// demos, wrong for anything real. Callers should populate this from the
	// gematik TI roots (e.g. via gempki.EmbeddedLoader{Env}.Load(ctx)).
	CertPool *x509.CertPool `yaml:"-"`
}

func (*ProxyConfig) Init

func (pc *ProxyConfig) Init() error

type ProxyInfo

type ProxyInfo struct {
	Name               string                     `json:"name"`
	Env                Env                        `json:"env"`
	Subject            string                     `json:"subject"`
	AdmissionStatement *gempki.AdmissionStatement `json:"admission_statement"`
}

type ReadmeData

type ReadmeData struct {
	BaseURL    string
	AuthHeader string
	ProxyInfos []*ProxyInfo
}

func (*ReadmeData) Curl

func (d *ReadmeData) Curl(url string, headers ...string) string

Curl renders a curl command for the given URL with optional header values. When any header is present (including a global Authorization header), the command is emitted in multi-line form with backslash continuations.

func (*ReadmeData) URL

func (d *ReadmeData) URL(format string, args ...any) string

URL returns the absolute URL for the given path on this gateway.

type SecurityFunctions

type SecurityFunctions struct {
	AuthnSignFunc           brainpool.SignFunc
	AuthnCertFunc           func() (*x509.Certificate, error)
	ClientAssertionSignFunc brainpool.SignFunc
	ClientAssertionCertFunc func() (*x509.Certificate, error)
	ProvidePN               ProvidePNFunc
	ProvideHCV              func(insurantId string) ([]byte, error)
}

func SecurityFunctionsFromP12 added in v0.20.3

func SecurityFunctionsFromP12(path, password string, provideHCV ProvideHCVFunc, providePN ProvidePNFunc) (*SecurityFunctions, error)

SecurityFunctionsFromP12 builds SecurityFunctions backed by the AUT identity in a PKCS#12 file. ProvidePN/ProvideHCV are supplied by the caller — entitlement needs VSDM material that is not in the p12 — and may be nil when only the VAU handshake, authorization, and /information endpoints are exercised.

type SendAuthCodeSCtype

type SendAuthCodeSCtype struct {
	AuthorizationCode string `json:"authorizationCode"`
	ClientAttest      string `json:"clientAttest"`
}

type Session

type Session struct {
	*Client
	VAUChannel *vau.Channel
	OpenedAt   time.Time
}

Session is a Client with an open VAU channel. Authorize must be called before VAU-bound operations like Entitle.

func (*Session) Authorize

func (s *Session) Authorize(authenticator *gemidp.Authenticator) error

func (*Session) CreateClientAttest

func (s *Session) CreateClientAttest() (string, error)

func (*Session) Entitle

func (s *Session) Entitle(insurantId string) error

Entitle the current SMC-B (provided by SecuriotyFunctions) to access the data of the insurant with the given insurant.

func (*Session) GetNonce

func (c *Session) GetNonce() (string, error)

func (*Session) GetStatus

func (s *Session) GetStatus() (*vau.Status, error)

func (*Session) HealthCheck

func (s *Session) HealthCheck() error

func (*Session) SendAuthCodeSC

func (s *Session) SendAuthCodeSC(authCode SendAuthCodeSCtype) error

func (*Session) SendAuthorizationRequestSC

func (s *Session) SendAuthorizationRequestSC() (string, error)

func (*Session) SetEntitlementPS

func (s *Session) SetEntitlementPS(insurantId string, auditEvidence string, hcv []byte) error

Directories

Path Synopsis
cmd
zero-epa command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL