<commit_before>Using the transport package
===========================

The transport package is designed to provide automated mutually-
authenticated and server-only TLS security with proper security
settings for Go programs. Mutually-authenticated means that clients
will strictly validate the server's certificate, and servers will
require that clients present a valid client authentication
certificate.

Adding the transport package to a project consists of a few steps:

1. Planning the right communications model.
2. Determining the configuration.
3. Adding the transport package to the project.

Each of these steps will be covered in sequence, with the examples
under transport/example/ used as illustrations. Some terminology:

  certificate provider: an interface to a CA that will sign CSRs and
  return certificates. The only available certificate provider at
  this time is CFSSL.

  key provider: mechanism for providing keys and signing certificate
  signing requests (CSRs). The only available key provider at this
  time is a disk-backed key set.

  root: the public certificate for a certificate authority (CA). This
  certificate is used to verify the certificate of a remote system: a
  client authentication root specifies the CA that a server uses to
  verify clients. The unqualified term root usually refers to a CA
  certificate that a client uses to verify a server's certificate.


Transport package communication models
--------------------------------------

There are three models for communications:

1. A general TLS listener, such as a public HTTPS server. In this
   model, the server does not expect clients to authenticate
   themselves to the server using client authentication
   certificates. This listener doesn't need to configure any roots.

2. A mutually-authenticated TCP server. This can be an HTTPS server
   that requires client authentication, or any other TCP server that
   wants to set up mutually-authenticated communications. A server
   will construct a `Listener` and call the `Listen` method on that
   structure (this will be useful to remember later).

3. A mutually-authenticated TCP client. This can be an HTTPS client
   that supplies a client authentication certificate, or any other TCP
   client setting up a mutually-authenticated connection. A client
   will call `Dial` from a `Transport` structure.

Once the model is determined, the configuration can be built.


Transport package configuration
-------------------------------

In general, the transport package is build around the `core.Identity`
type. This contains several top-level fields:

+ `Request` contains a `CertificateRequest` from the CFSSL csr package
  (e.g. https://godoc.org/github.com/cloudflare/cfssl/csr#CertificateRequest).
  The JSON tag for this field is "request".
+ `Profiles` contains profiles for certificate and key providers. The
  JSON tag for this field is "profiles".
+ `Roots` specifies roots that are used by clients to verify server
  certificates. The JSON tag for this field is "roots".
+ `ClientRoots` specifies roots that are used by servers to verify
  client certificates. The JSON tag for this field is "client_roots".

The `Identity` structure is set up so that it could be integrated into
a current configuration set up, or it can be present as a standalone
configuration. The example programs use the code

        // conf is a string contain the path to a JSON configuration
        // file.
        var id = new(core.Identity)
        data, err := ioutil.ReadFile(conf)
        if err != nil {
                exlib.Err(1, err, "reading config file")
        }

        err = json.Unmarshal(data, id)
        if err != nil {
                exlib.Err(1, err, "parsing config file")
        }

to load a standalone transport configuration file in JSON.

The `Profiles` field configures both key providers and certificate
authorities.

Key providers use the key request in the `Request` field to determine
what sort of key to generate, and the rest of the field to determine
the certificate signing request to generate.

The only key-provider supported right now is the "path" provider,
which would be configured something like

	// id is a core.Identity value.
	id.Profiles["path"] = map[string]string{
		"private_key": "/path/to/key.pem",
		"certificate": "/path/to/cert.pem",
	}<commit_msg>doc: remove mention of deprecated io/ioutil<commit_after>Using the transport package
===========================

The transport package is designed to provide automated mutually-
authenticated and server-only TLS security with proper security
settings for Go programs. Mutually-authenticated means that clients
will strictly validate the server's certificate, and servers will
require that clients present a valid client authentication
certificate.

Adding the transport package to a project consists of a few steps:

1. Planning the right communications model.
2. Determining the configuration.
3. Adding the transport package to the project.

Each of these steps will be covered in sequence, with the examples
under transport/example/ used as illustrations. Some terminology:

  certificate provider: an interface to a CA that will sign CSRs and
  return certificates. The only available certificate provider at
  this time is CFSSL.

  key provider: mechanism for providing keys and signing certificate
  signing requests (CSRs). The only available key provider at this
  time is a disk-backed key set.

  root: the public certificate for a certificate authority (CA). This
  certificate is used to verify the certificate of a remote system: a
  client authentication root specifies the CA that a server uses to
  verify clients. The unqualified term root usually refers to a CA
  certificate that a client uses to verify a server's certificate.


Transport package communication models
--------------------------------------

There are three models for communications:

1. A general TLS listener, such as a public HTTPS server. In this
   model, the server does not expect clients to authenticate
   themselves to the server using client authentication
   certificates. This listener doesn't need to configure any roots.

2. A mutually-authenticated TCP server. This can be an HTTPS server
   that requires client authentication, or any other TCP server that
   wants to set up mutually-authenticated communications. A server
   will construct a `Listener` and call the `Listen` method on that
   structure (this will be useful to remember later).

3. A mutually-authenticated TCP client. This can be an HTTPS client
   that supplies a client authentication certificate, or any other TCP
   client setting up a mutually-authenticated connection. A client
   will call `Dial` from a `Transport` structure.

Once the model is determined, the configuration can be built.


Transport package configuration
-------------------------------

In general, the transport package is build around the `core.Identity`
type. This contains several top-level fields:

+ `Request` contains a `CertificateRequest` from the CFSSL csr package
  (e.g. https://godoc.org/github.com/cloudflare/cfssl/csr#CertificateRequest).
  The JSON tag for this field is "request".
+ `Profiles` contains profiles for certificate and key providers. The
  JSON tag for this field is "profiles".
+ `Roots` specifies roots that are used by clients to verify server
  certificates. The JSON tag for this field is "roots".
+ `ClientRoots` specifies roots that are used by servers to verify
  client certificates. The JSON tag for this field is "client_roots".

The `Identity` structure is set up so that it could be integrated into
a current configuration set up, or it can be present as a standalone
configuration. The example programs use the code

        // conf is a string contain the path to a JSON configuration
        // file.
        var id = new(core.Identity)
        data, err := os.ReadFile(conf)
        if err != nil {
                exlib.Err(1, err, "reading config file")
        }

        err = json.Unmarshal(data, id)
        if err != nil {
                exlib.Err(1, err, "parsing config file")
        }

to load a standalone transport configuration file in JSON.

The `Profiles` field configures both key providers and certificate
authorities.

Key providers use the key request in the `Request` field to determine
what sort of key to generate, and the rest of the field to determine
the certificate signing request to generate.

The only key-provider supported right now is the "path" provider,
which would be configured something like

	// id is a core.Identity value.
	id.Profiles["path"] = map[string]string{
		"private_key": "/path/to/key.pem",
		"certificate": "/path/to/cert.pem",
	}
{'fraction_non_alphanumeric': 0.07162471395881007, 'fraction_numerical': 0.0018306636155606408, 'mean_word_length': 3.540779220779221, 'pattern_counts': {'":': 4, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1600946', 'n_tokens_mistral': 2140, 'n_tokens_neox': 2047, 'n_words': 1171}