Setting up TLSv1.3 in Bitbucket Server

Still need help?

The Atlassian Community is here for you.

Ask the community


Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Purpose

Sometimes security policy requires Bitbucket Server to use TLSv1.3

Solution

  1. TLSv1.3 works with Zulu OpenJDK8 versions 8.40 and above, provided the JVM runs with the additional argument as documented here.

    Edit _start-webapp.sh (Linux) or  _start-webapp.bat (Windows). It can be found in <bitbucket-installation-directory>/bin
    Find the line containing:

    JVM_SUPPORT_RECOMMENDED_ARGS=

    and append the following argument: -XX:+UseOpenJSSE

    If you didn't have any JVM arguments already listed, this line should now look as follows: 

    JVM_SUPPORT_RECOMMENDED_ARGS=-XX:+UseOpenJSSE
  2. Please make sure you are using a version of Bitbucket Server that is not affected by  BSERV-12135 - Getting issue details... STATUS

  3. Also, the TLS protocol version has to be defined in the bitbucket.properties by adding the following line:

    server.ssl.protocol=TLSv1.3
  4. If required, add other SSL configuration settings that can be found here.

  5. Restart Bitbucket Server (or all nodes of your Bitbucket Data Center) after saving the modified configuration files.

Additional Details gathered about Zulu OpenJDK8

Starting with Zulu 8.48, Zulu 8 supports TLSv1.3 by default and follows the API changes
introduced by Maintenance Release 3 to the Java SE 8 specification. For more details,
refer to JDK-8248721: Backport TLSv1.3 protocol implementation.

TLSv1.3 support is now included in the default (SunJSSE) JSSE provider in Zulu 8. In
addition to the default JSSE provider, Zulu 8 releases also include a non-default
Legacy8uJSSE provider containing the prior, 8u252 JSSE provider implementation (with
no TLSv1.3 support) as a fallback measure, as well as the non-default OpenJSSE
provider previously included in Zulu packages for non-default support for TLSv1.3.

Zulu 8 currently supports the following bundled modes for JSSE:

Default mode: SunJSSE provider, including SSLv3.0, TLSv1, TLSv1.1, TLSv1.2, and
TLSv1.3 protocols support. This mode is enabled by default.

Fallback mode: using the bundled Legacy8uJSSE provider, which includes the prior, 8u252 JSSE provider implementation (with no TLSv1.3 support). This mode may be useful if any application issues are introduced by the new TLS 1.3 support in the default JSSE provider. To enable the fallback mode, set the -XX:+UseLegacy8uJSSE flag in the Java options.

OpenJSSE mode: using the OpenJSSE provider, which includes a TLSv1.3 protocol implementation. This mode has been included in Zulu 8 since Zulu 8.40. and may be useful for prior users of the OpenJSSE provider who wish to keep using it in place of the new default SunJSSE provider (even tho the new default provider now includes all functionality previously covered by the OpenJSSE provider). For example, applications that chose to use org.openjsse APIs directly may want to keep using the OpenJSSE mode. To enable the OpenJSSE mode, set the -XX:+UseOpenJSSE flag in the Java options.


TLS 1.3 and Smart Mirroring

Please note that all the visions of Smart Mirroring do not support TLSv1.3 for synchronization until BSERV-13366 - Getting issue details... STATUS  is implemented.

DescriptionHow to use TLSv1.3 with Bitbucket Server
ProductBitbucket Server, Bitbucket Data Center

Last modified on Jan 23, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.