Custom implementation
In addition to the basic and advanced encryption methods that you can use in Bitbucket Data Center, you can also choose to create your own SecretStore implementation. This might be especially useful if:
you're required to use a specific vault to store the password
you want to use encryption algorithms beyond those we ship with Bitbucket
Step 1. Create a Maven project and get API dependencies
Navigate to the
<Bitbucket_installation_directory>/atlassian-bitbucket/WEB-INF/libdirectory.Install the
atlassian-secrets-api.jarfile into local maven repository with the following command:mvn install:install-file \ -Dfile=./atlassian-secrets-api-<version>.jar \ -DgroupId=com.atlassian.secrets \ -DartifactId=atlassian-secrets-api \ -Dversion=<version> \ -Dpackaging=jar \ -DgeneratePom=trueInstall the
atlassian-secrets-store.jarfile into local maven repository with the following command:mvn install:install-file \ -Dfile=./atlassian-secrets-store-<version>.jar \ -DgroupId=com.atlassian.secrets \ -DartifactId=atlassian-secrets-store \ -Dversion=<version> \ -Dpackaging=jar \ -DgeneratePom=trueCreate a Maven project with the following pom:
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId><your_group_ID></groupId> <artifactId><your_artifact_ID></artifactId> <version><your_version></version> <properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> </properties> <build> <resources> <resource> <directory>src/main/resources/libs</directory> <excludes> <exclude>*</exclude> </excludes> <filtering>false</filtering> </resource> </resources> </build> <dependencies> <dependency> <groupId>com.atlassian.secrets</groupId> <artifactId>atlassian-secrets-api</artifactId> <version><api_version></version> <scope>provided</scope> </dependency> <dependency> <groupId>com.atlassian.secrets</groupId> <artifactId>atlassian-secrets-store</artifactId> <version><api_version></version> <scope>provided</scope> </dependency> </dependencies> </project>
Step 2. Implement the SecretStore interface
The SecretStore interface contains two methods that you need to implement according to your requirements; store and get. The get method is called during Bitbucket startup, which means that long-running tasks can affect the startup time. The store method is not called by Bitbucket, as it's only used in the encryption tool.
From Bitbucket 8.13, the Cipher interface should be considered deprecated. Instead, you should use the new interface, SecretStore, and its corresponding methods, store and get. These methods supersede the equivalent Cipher interface methods, encrypt and decrypt.
The Cipher interface and its methods can still be used, but will eventually be retired, and should not be used when setting up new encryption functionality.
You can use Base64Cipher and AlgorithmSecretStore as examples.
Step 3. Test your implementation
The encryption tool described in Basic encryption and Advanced encryption uses the same code as Bitbucket to decrypt the password. You can use it to test your implementation.
Assuming that the CLI and your jar is in the same folder:
java -cp "./*" com.atlassian.secrets.cli.db.DbCipherTool -c your.package.here.ClassNameStep 4. Make your library available
Bitbucket must be able to access your library. Your class will be instantiated using reflection. Put the library in the following directory:
<Bitbucket_home_directory>/lib