tls
Transport Layer Security (TLS) is a protocol that ensures privacy between communicating applications and their users on the Internet. When a server and client communicate, TLS ensures that no third party may eavesdrop or tamper with any message. TLS is the successor to the Secure Sockets Layer (SSL).
Deployment
Charms using the tls layer can be deployed with multiple units using the peer relation to create signed certificates.
juju deploy trusty/tls
juju add-unit tls -n 2
Using the tls layer
The tls layer uses easy-rsa to generate the public key infrastructure (PKI). The tls layer knows where the certificates and keys are located. Upper layers do not need to know the underlying implementation, they simple need the keys and certificates saved in service specific locations.
tlslib
This layer contains a python library named tlslib
that has methods to copy
the keys and certificates. Use the methods in tlslib
to copy the tls pki
to directories that that other layers can use.
server_cert
Copy the server certificate to the destination, creating directories if needed and assign ownership if set.
import tlslib
# Copy the server certificate from the default location to swarm directory.
tlslib.server_cert(None, '/etc/swarm/server.crt', user='ubuntu', group='docker')
server_key
Copy the server key to the destination, creating directories if needed and assign ownership if set.
import tlslib
# Copy the server key from the default location to the swarm directory.
tlslib.server_key(None, '/etc/swarm/server.key', user='ubuntu', group='docker')
client_cert
Copy the client certificate to the destination creating directories if needed and assign ownership if set.
import tlslib
# Save the client certificate from the default location to the kubernetes directory.
tlslib.client_cert(None, '/srv/kubernetes/client.crt', user='ubuntu', group='ubuntu')
client_key
Copy the client key to the destination, creating directories if needed and assign ownership if set.
import tlslib
# Copy the client key from the default location to the kubernetes directory.
tlslib.client_key(None, '/srv/kubernetes/client.key', user='ubuntu', group='ubuntu')
ca
Copy the Certificate Authority (CA) to the destination, creating parent directories if needed and assign owner if set. The tls layer installs the CA on all the peers in /usr/local/share/ca-certificates/.
import tlslib
# Copy the CA from the default location to the swarm directory.
tlslib.ca(None, '/etc/swarm/ca.crt', user='ubuntu', group='docker')
State Events
This charm makes use of the reactive framework where states are set or removed. The charm code can respond to these layers appropriately. Some states are meant to be internal to the tls layer all the external states start with "tls."
tls.client.authorization.required
By default the tls layer does not generate server certificate that can be used
with client authentication. If your layer needs certificates configured with
clientAuth
then the layer should set the tls.client.authorization.required
state.
from charms.reactive import set_state
# My service requires clientAuth set when generating the server certificate.
set_state('tls.client.authorization.required')
tls.server.certificate available
The server certificate is available in the unitdata of this charm using the
tls.server.certificate
key.
@when('tls.server.certificate available')
def secure_my_sevice():
from charmhelpers.core import unitdata
database = unitdata.kv()
server_cert = database.get('tls.server.certificate')
tls.client.certificate available
The client certificates are available in the unitdata of this charm using the
tls.client.certificate
key.
@when('tls.client.certificate available')
def client_certificate():
from charmhelpers.core import unitdata
database = unitdata.kv()
client_cert = database.get('tls.client.certificate')
Contact
- Author: Matthew Bruzek <Matthew.Bruzek@canonical.com>
- Contributor: Charles Butler <Charles.Butler@canonical.com>
- Contributor: Cory Johns <Cory.Johns@canonical.com>