This page describes how the Octopus Server and the Tentacle deployment agents communicate in a secure way.
Background
Some deployment technologies are designed for the LAN and have no security at all. Some require machines to be on the same Active Directory domain. Others require you to set up usernames and passwords, and to store them in configuration files.
When designing Octopus, we wanted to make it easy to have secure deployments out of the box, without expecting machines to be on the same domain and without sharing passwords. Octopus needed to work in scenarios where the Octopus Server is running in your local LAN, close to your developers, while your production servers are running in the cloud or at a remote data center.
We achieve this security using public-key cryptography.
Octopus/Tentacle trust relationship
Regardless of whether Tentacle is in listening mode or polling mode, all communication between the Tentacle and Octopus is performed over a secure (TLS) connection. Octopus and Tentacle both have a public/private key pair that they use to establish the TLS connection and verify the identity of the other party.
When Tentacle is configured, you give it the thumbprint (which uniquely identifies the public key) of the Octopus Server. Likewise, you tell Octopus the thumbprint of the Tentacle. This establishes a trust relationship between the two machines:
- Your Octopus Server will only issue commands to the Tentacles that it trusts.
- Your Tentacles only accept commands from an Octopus they trust.
The only way another system can impersonate either party is by getting hold of the private key, which are kept safe and never leave the Octopus/Tentacle server (unless you export them from the certificate store). This makes it much more secure than exchanging passwords. Since this is all based on public-key cryptography, it creates a highly secure way for the two machines to communicate without exchanging passwords, and works much like an SSH connection in the UNIX world.
If necessary you can further restrict access using IPSec or VPNs.
Octopus certificates
The X.509 certificates used by Octopus and Tentacle are generated on installation and use 2048-bit private keys. There is an insightful discussion of why Octopus uses self-signed certificates by default.
Instead of having Tentacle generate its own certificate, you can import a Tentacle certificate which is helpful when automating Tentacle installation.
Scenario: Listening Tentacles
Tentacle plays the role of server and Octopus as the client:
- Octopus establishes the TLS connection with the Tentacle.
- The Tentacle presents its certificate as the server certificate allowing Octopus to verify the identity of the Tentacle.
- Octopus presents its certificate as a client certificate so the Tentacle can verify the identity of Octopus.
- Once the identity of the Octopus and Tentacle have been established the connection is held open and Octopus will start issuing commands to the Tentacle.
Scenario: Polling Tentacles
Octopus plays the role of server and Tentacle as the client:
- The Tentacle establishes the TLS connection with Octopus.
- Octopus presents its certificate as the server certificate allowing the Tentacle to verify the identity of Octopus.
- The Tentacle presents its certificate as a client certificate so Octopus can verify the identity of the Tentacle.
- Once the identity of the Octopus and Tentacle have been established the connection is held open and Octopus will start issuing commands to the Tentacle.
Data transport
Octopus uses Halibut to communicate. This is based on TCP, not HTTP, it is not possible to add HTTP headers to this communication channel.
Both Tentacle and Server expose a simple page on the listening port to web browsers to allow you to confirm your configuration. Some security scanners detect this page and incorrectly assume that it’s a web server or a web app and warn about self-signed certificates.
Transport Layer Security (TLS) implementation
Octopus Server and Tentacle rely on the host OS for the available TLS version to use when establishing a secure TLS connection when communicating.
The TLS implementation uses the .NET SslStream class, and uses the best available of TLS 1.2, TLS 1.1 or TLS 1.0. Fallback to SSL is disallowed.
TLS 1.2 requires .NET 4.5 which was introduced as a requirement in Octopus 3.1. Earlier versions of Octopus use TLS 1.0.
To harden the TLS implementation used, review our documentation on Disabling weak TLS protocols.
Troubleshooting Tentacle communication problems
We have built comprehensive troubleshooting guides for both Listening and Polling Tentacles.
If you are seeing error messages like below, try Troubleshooting Schannel and TLS:
Client-side:System.Security.Authentication.AuthenticationException: A call to SSPI failed, see inner exception. ---> System.ComponentModel.Win32Exception: One or more of the parameters passed to the function was invalid
Server-side:System.IO.IOException: Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Sunday, January 1, 2023