testcerts

https://pkg.go.dev/github.com/madflojo/testcerts
Admin
testcerts is a Go package that provides an easy-to-use suite of functions for generating x509 test...
Tokens:3,494
Snippets:30
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Get KeyPair Certificate

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Retrieves the x509.Certificate from a KeyPair. No setup is required.

```go
func (kp *KeyPair) Cert() *x509.Certificate
```

--------------------------------

### Get KeyPair Private Key

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Retrieves the private key of the KeyPair. No setup is required.

```go
func (kp *KeyPair) PrivateKey() []byte
```

--------------------------------

### Get KeyPair Public Key

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Retrieves the public key of the KeyPair. No setup is required.

```go
func (kp *KeyPair) PublicKey() []byte
```

--------------------------------

### Get IP Addresses from KeyPairConfig

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Retrieves a list of IP addresses in Net.IP format from the KeyPairConfig. This is useful for validating or processing IP addresses intended for certificate alternative names.

```go
func (c *KeyPairConfig) IPNetAddresses() ([]net.IP, error)
```

--------------------------------

### Get Certificate Authority Public Key

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Retrieves the public key of a CertificateAuthority. No setup is required.

```go
func (ca *CertificateAuthority) PublicKey() []byte
```

--------------------------------

### Write Certificates to Files

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Creates an x509 certificate and key, writing them to the specified file paths. Existing files at these paths will be overwritten.

```go
err := GenerateCertsToFile("/path/to/cert", "/path/to/key")
if err != nil {
	// handle error
}
```

--------------------------------

### GenerateCertsToFile

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Creates a x509 certificate and key and writes it to the specified file paths. Overwrites existing files if they exist.

```APIDOC
## GenerateCertsToFile

### Description
Creates a x509 certificate and key and writes it to the specified file paths. If the specified file paths already exist, it will overwrite the existing files.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```go
err := GenerateCertsToFile("/path/to/cert", "/path/to/key")
if err != nil {
	// handle error
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### GenerateCertsToTempFile

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Creates a temporary x509 certificate and key in a randomly generated file using the directory path provided. If no directory is specified, the default directory for temporary files will be used.

```APIDOC
## GenerateCertsToTempFile

### Description
Will create a temporary x509 certificate and key in a randomly generated file using the directory path provided. If no directory is specified, the default directory for temporary files as returned by os.TempDir will be used.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```go
cert, key, err := GenerateCertsToTempFile("/tmp/")
if err != nil {
	// handle error
}
```

### Response
#### Success Response (200)
- **certPath** (string) - The path to the temporary certificate file.
- **keyPath** (string) - The path to the temporary key file.

#### Response Example
```json
{
  "certPath": "/tmp/cert12345.pem",
  "keyPath": "/tmp/key67890.pem"
}
```
```

--------------------------------

### Generate Certificates to Temporary Files

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Creates a temporary x509 certificate and key in the specified directory, or the system default if none is provided.

```go
cert, key, err := GenerateCertsToTempFile("/tmp/")
if err != nil {
	// handle error
}
```

--------------------------------

### Generate Certificates as Bytes

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Generates an x509 certificate and key, returning them as byte slices.

```go
cert, key, err := GenerateCerts()
if err != nil {
	// handle error
}
```

--------------------------------

### Save KeyPair to Files

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Saves the KeyPair certificate and private key to specified files. Ensure the file paths are valid and writable.

```go
func (kp *KeyPair) ToFile(certFile, keyFile string) error
```

--------------------------------

### Configure TLSConfig with KeyPair

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Configures a tls.Config with the KeyPair's certificate and private key. The returned tls.Config can be used for both server and client configurations.

```go
func (kp *KeyPair) ConfigureTLSConfig(tlsConfig *tls.Config) (*tls.Config, error)
```

--------------------------------

### KeyPairConfig

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Configuration for creating a KeyPair.

```APIDOC
## KeyPairConfig

### Description
Configuration for creating a KeyPair.

### Type
type KeyPairConfig struct {
	// contains filtered or unexported fields
}

### Methods
#### IPNetAddresses()
- **Description**: Returns the IP addresses from the KeyPairConfig.
- **Returns**:
  - []net.IP - A slice of IP addresses.
  - error

#### Validate()
- **Description**: Validates the KeyPairConfig.
- **Returns**: error
```

--------------------------------

### Generate self-signed certificates for temporary use

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Use GenerateToTempFile to create and write self-signed certificates to temporary storage for use in local HTTP listeners.

```go
func TestFunc(t *testing.T) {
	// Create and write self-signed Certificate and Key to temporary files
	cert, key, err := testcerts.GenerateToTempFile("/tmp/")
	if err != nil {
		// do something
	}
	defer os.Remove(key)
	defer os.Remove(cert)

	// Start HTTP Listener with test certificates
	err = http.ListenAndServeTLS("127.0.0.1:443", cert, key, someHandler)
	if err != nil {
		// do something
	}
}
```

--------------------------------

### GenerateCerts

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Generates a x509 certificate and key. Returns the certificate and key as byte slices, and any error that occurred.

```APIDOC
## GenerateCerts

### Description
Generates a x509 certificate and key. Returns the certificate and key as byte slices, and any error that occurred.

### Method
func

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```go
cert, key, err := GenerateCerts()
if err != nil {
	// handle error
}
```

### Response
#### Success Response (200)
- **certificate** ([]byte) - The generated certificate.
- **key** ([]byte) - The generated private key.

#### Response Example
```json
{
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}
```
```

--------------------------------

### KeyPairConfig Methods

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Methods for validating and processing KeyPair configuration.

```APIDOC
## IPNetAddresses

### Description
Returns a list of IP addresses from the configuration in net.IP format.

## Validate

### Description
Validates the KeyPairConfig to ensure it is not empty and contains valid values.
```

--------------------------------

### Save KeyPair to Temporary Files

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Saves the KeyPair certificate and private key to temporary files in a specified directory. Temporary files will have random names.

```go
func (kp *KeyPair) ToTempFile(dir string) (cfh *os.File, kfh *os.File, err error)
```

--------------------------------

### KeyPair Methods

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Methods for managing KeyPair objects and configuring TLS.

```APIDOC
## Cert

### Description
Returns the x509.Certificate of the KeyPair.

## ConfigureTLSConfig

### Description
Configures a tls.Config object with the KeyPair certificate and private key.

### Parameters
- **tlsConfig** (*tls.Config) - Required - The existing TLS configuration to update.

## PrivateKey / PublicKey

### Description
Returns the private or public key of the KeyPair as a byte slice.

## ToFile

### Description
Saves the KeyPair certificate and private key to the specified files.

## ToTempFile

### Description
Saves the KeyPair certificate and private key to temporary files.
```

--------------------------------

### Create a Certificate Authority for complex test scenarios

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Use NewCA to generate a Certificate Authority and sign key pairs for specific domains, enabling secure HTTPS communication in tests.

```go
func TestFunc(t *testing.T) {
	// Generate Certificate Authority
	ca := testcerts.NewCA()

	go func() {
		// Create a signed Certificate and Key for "localhost"
		certs, err := ca.NewKeyPair("localhost")
		if err != nil {
			// do something
		}

		// Write certificates to a file
		err = certs.ToFile("/tmp/cert", "/tmp/key")
		if err {
			// do something
		}

		// Start HTTP Listener
		err = http.ListenAndServeTLS("localhost:443", "/tmp/cert", "/tmp/key", someHandler)
		if err != nil {
			// do something
		}
	}()

	// Create a client with the self-signed CA
	client := &http.Client{
		Transport: &http.Transport{
			TLSClientConfig: certs.ConfigureTLSConfig(ca.GenerateTLSConfig()),
		},
	}

	// Make an HTTPS request
	r, _ := client.Get("https://localhost")
}
```

--------------------------------

### Save Certificate Authority to Files

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Saves the CertificateAuthority certificate and private key to specified files. Ensure the file paths are valid and writable.

```go
func (ca *CertificateAuthority) ToFile(certFile, keyFile string) error
```

--------------------------------

### Define Package Variables

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Common error variables used throughout the package for configuration and IP validation.

```go
var (
	// ErrEmptyConfig is returned when a KeyPairConfig is empty.
	ErrEmptyConfig = errors.New("empty KeyPairConfig")

	// ErrInvalidIP is returned when an IP address is invalid.
	ErrInvalidIP = errors.New("invalid IP address")
)
```

--------------------------------

### Validate KeyPairConfig

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Validates the KeyPairConfig to ensure it is not empty and that all provided values are valid. Returns an error if the configuration is invalid.

```go
func (c *KeyPairConfig) Validate() error
```

--------------------------------

### Save Certificate Authority to Temporary Files

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Saves the CertificateAuthority certificate and private key to temporary files in a specified directory. Temporary files will have random names.

```go
func (ca *CertificateAuthority) ToTempFile(dir string) (cfh *os.File, kfh *os.File, err error)
```

--------------------------------

### CertificateAuthority Methods

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Methods for interacting with the CertificateAuthority structure.

```APIDOC
## PublicKey

### Description
Returns the public key of the CertificateAuthority.

## ToFile

### Description
Saves the CertificateAuthority certificate and private key to the specified files.

### Parameters
- **certFile** (string) - Required - Path to save the certificate file.
- **keyFile** (string) - Required - Path to save the private key file.

## ToTempFile

### Description
Saves the CertificateAuthority certificate and private key to temporary files in the specified directory.

### Parameters
- **dir** (string) - Required - Directory to create temporary files.
```

--------------------------------

### Define KeyPairConfig Structure

Source: https://pkg.go.dev/github.com/madflojo/testcerts

KeyPairConfig is a configuration struct for generating an X.509 key pair. It includes fields for domains, IP addresses, serial number, common name, and expiration status.

```go
type KeyPairConfig struct {
	// Domains is a list of domains to include in the certificate as Subject
	// Alternative Names.
	Domains []string

	// IPAddresses is a list of IP addresses to include in the certificate
	// as Subject Alternative Names.
	IPAddresses []string

	// SerialNumber is the serial number to use for the certificate.
	SerialNumber *big.Int

	// CommonName is the Common Name to use for the certificate.
	CommonName string

	// Expired creates expired certificates.
	Expired bool
}
```

--------------------------------

### KeyPair

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Represents a key pair (certificate and private key).

```APIDOC
## KeyPair

### Description
Represents a key pair (certificate and private key).

### Type
type KeyPair struct {
	// contains filtered or unexported fields
}

### Methods
#### Cert()
- **Description**: Returns the certificate of the KeyPair.
- **Returns**: *x509.Certificate

#### ConfigureTLSConfig(tlsConfig *tls.Config)
- **Description**: Configures the given tls.Config with the KeyPair's certificate and private key.
- **Parameters**:
  - **tlsConfig** (*tls.Config) - The tls.Config to configure.
- **Returns**:
  - *tls.Config - The configured tls.Config.
  - error

#### PrivateKey()
- **Description**: Returns the private key of the KeyPair.
- **Returns**: []byte

#### ToFile(certFile, keyFile string)
- **Description**: Writes the KeyPair certificate and private key to the specified files.
- **Parameters**:
  - **certFile** (string) - The path to the certificate file.
  - **keyFile** (string) - The path to the private key file.
- **Returns**: error

#### ToTempFile(dir string)
- **Description**: Creates temporary files for the KeyPair certificate and private key in the specified directory.
- **Parameters**:
  - **dir** (string) - The directory to create the temporary files in. If empty, the default temporary directory will be used.
- **Returns**:
  - *os.File - File handle for the certificate.
  - *os.File - File handle for the private key.
  - error
```

--------------------------------

### Define KeyPair Structure

Source: https://pkg.go.dev/github.com/madflojo/testcerts

KeyPair represents a pair of self-signed x509 certificate and private key. It is used to hold certificate and key data.

```go
type KeyPair struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### CertificateAuthority

Source: https://pkg.go.dev/github.com/madflojo/testcerts

Represents a self-signed x509 certificate authority.

```APIDOC
## CertificateAuthority

### Description
Represents a self-signed x509 certificate authority.

### Type
type CertificateAuthority struct {
	// contains filtered or unexported fields
}

### Methods
#### NewCA()
- **Description**: Creates a new CertificateAuthority.
- **Returns**: *CertificateAuthority

#### Cert()
- **Description**: Returns the CertificateAuthority Certificate.
- **Returns**: *x509.Certificate

#### CertPool()
- **Description**: Returns a Certificate Pool of the CertificateAuthority Certificate.
- **Returns**: *x509.CertPool

#### GenerateTLSConfig()
- **Description**: Returns a tls.Config with the CertificateAuthority as the RootCA.
- **Returns**: *tls.Config

#### NewKeyPair(domains ...string)
- **Description**: Generates a new KeyPair signed by the CertificateAuthority for the given domains. The domains are used to populate the Subject Alternative Name field of the certificate.
- **Parameters**:
  - **domains** ([]string) - The domains for the certificate.
- **Returns**:
  - *KeyPair
  - error

#### NewKeyPairFromConfig(config KeyPairConfig)
- **Description**: Generates a new KeyPair signed by the CertificateAuthority from the given configuration. The configuration is used to populate the Subject Alternative Name field of the certificate.
- **Parameters**:
  - **config** (KeyPairConfig) - The configuration for the key pair.
- **Returns**:
  - *KeyPair
  - error

#### PrivateKey()
- **Description**: Returns the private key of the CertificateAuthority.
- **Returns**: []byte

#### ToFile(certFile, keyFile string)
- **Description**: Writes the CertificateAuthority certificate and private key to the specified files.
- **Parameters**:
  - **certFile** (string) - The path to the certificate file.
  - **keyFile** (string) - The path to the private key file.
- **Returns**: error

#### ToTempFile(dir string)
- **Description**: Creates temporary files for the CertificateAuthority certificate and private key in the specified directory.
- **Parameters**:
  - **dir** (string) - The directory to create the temporary files in. If empty, the default temporary directory will be used.
- **Returns**:
  - *os.File - File handle for the certificate.
  - *os.File - File handle for the private key.
  - error
```
Tokens:
Raw