net

Documentation

Index

• Variables
• func CreateMtlsClient(source *workloadapi.X509Source) (*http.Client, error)
• func CreateMtlsClientWithPredicate(source *workloadapi.X509Source, predicate func(string) bool) (*http.Client, error)
• func CreateMtlsServer(source *workloadapi.X509Source, tlsPort string, predicate func(string) bool) (*http.Server, error)
• func Post(client *http.Client, path string, mr []byte) ([]byte, error)
• func Serve(source *workloadapi.X509Source, initializeRoutes func(), ...) error

Variables

var ErrNotFound = errors.New("not found")

var ErrUnauthorized = errors.New("unauthorized")

Functions

func CreateMtlsClient

func CreateMtlsClient(source *workloadapi.X509Source) (*http.Client, error)

CreateMtlsClient creates an HTTP client configured for mutual TLS authentication using SPIFFE workload identities. It uses the provided X.509 source for client certificates and validates peer certificates against a predicate function.

Parameters:

• source: An X509Source that provides the client's identity certificates and trusted roots

Returns:

• *http.Client: A configured HTTP client that will use mTLS for all connections
• error: An error if the client creation fails

The returned client will:

• Present client certificates from the provided X509Source
• Validate peer certificates using the same X509Source
• Only accept peer certificates with SPIFFE IDs that pass the predicate function

func CreateMtlsClientWithPredicate

func CreateMtlsClientWithPredicate(
	source *workloadapi.X509Source,
	predicate func(string) bool,
) (*http.Client, error)

CreateMtlsClientWithPredicate creates an HTTP client configured for mutual TLS authentication using SPIFFE workload identities. It uses the provided X.509 source for client certificates and validates peer certificates against a predicate function.

Parameters:

• source: An X509Source that provides the client's identity certificates and trusted roots
• predicate: A function that evaluates SPIFFE IDs (as strings) and returns true if the ID should be trusted

Returns:

• *http.Client: A configured HTTP client that will use mTLS for all connections
• error: An error if the client creation fails

The returned client will:

• Present client certificates from the provided X509Source
• Validate peer certificates using the same X509Source
• Only accept peer certificates with SPIFFE IDs that pass the predicate function

func CreateMtlsServer

func CreateMtlsServer(source *workloadapi.X509Source,
	tlsPort string,
	predicate func(string) bool) (*http.Server, error)

CreateMtlsServer creates an HTTP server configured for mutual TLS (mTLS) authentication using SPIFFE X.509 certificates. It sets up the server with a custom authorizer that validates client SPIFFE IDs against a provided predicate function.

Parameters:

• source: An X509Source that provides the server's identity credentials and validates client certificates. It must be initialized and valid.
• tlsPort: The network address and port for the server to listen on (e.g., ":8443").
• predicate: A function that takes a SPIFFE ID string and returns true if the client should be allowed access, false otherwise.

Returns:

• *http.Server: A configured HTTP server ready to be started with TLS enabled.
• error: An error if the server configuration fails.

The server uses the provided X509Source for both its own identity and for validating client certificates. Client connections are only accepted if their SPIFFE ID passes the provided predicate function.

func Post

func Post(client *http.Client, path string, mr []byte) ([]byte, error)

Post performs an HTTP POST request with a JSON payload and returns the response body. It handles the common cases of connection errors, non-200 status codes, and proper response body handling.

Parameters:

• client: An *http.Client used to make the request, typically configured with TLS settings.
• path: The URL path to send the POST request to.
• mr: A byte slice containing the marshaled JSON request body.

Returns:

• []byte: The response body if the request is successful.
• error: An error if any of the following occur:
• Connection failure during POST request
• Non-200 status code in response
• Failure to read response body
• Failure to close response body

The function ensures proper cleanup by always attempting to close the response body, even if an error occurs during reading. Any error from closing the body is joined with any existing error using errors.Join.

Example:

client := &http.Client{}
data := []byte(`{"key": "value"}`)
response, err := Post(client, "https://api.example.com/endpoint", data)
if err != nil {
    log.Fatalf("failed to post: %v", err)
}

func Serve

func Serve(source *workloadapi.X509Source,
	initializeRoutes func(),
	predicate func(string) bool,
	tlsPort string) error

Serve initializes and starts an HTTPS server using mTLS authentication with SPIFFE X.509 certificates. It sets up the server routes using the provided initialization function and listens for incoming connections on the specified port.

Parameters:

• source: An X509Source that provides the server's identity credentials and validates client certificates. Must not be nil.
• initializeRoutes: A function that sets up the HTTP route handlers for the server. This function is called before the server starts.
• tlsPort: The network address and port for the server to listen on (e.g., ":8443").

Returns:

• error: Returns nil if the server starts successfully, otherwise returns an error explaining the failure. Specific error cases include:
• If source is nil
• If server creation fails
• If the server fails to start or encounters an error while running

The function uses empty strings for the certificate and key file parameters in ListenAndServeTLS as the certificates are provided by the X509Source. The server's mTLS configuration is determined by the CreateMtlsServer function.