Creating your own Cipher

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

You can also create your own Cipher, which might be especially useful if you’re required to use a specific vault to store the password.

Pre-requisites:

  • Basic knowledge of Maven
  • Knowledge of Java


Step 1: Create a Maven project and get API dependencies

  1. Get 'api' and 'base' dependencies.
    1. Go to <Jira_installation_directory>/atlassian-jira/WEB-INF/lib.
    2. Copy the following jar files:
      • password-cipher-api-<version>.jar: This file contains the API.
      • (optional) password-cipher-base-<version>.jar: This file contains sample implementation. 
  2. Create a Maven project.
  3. Go to resources, and create a new folder libs.
  4. Copy the jar files to the libs folder.
  5. You can then use the following pom

    <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>
    
    <repositories>
    <repository>
    <id>local-maven-repo</id>
    <url>file:///${project.basedir}/libs</url>
    </repository>
    </repositories>
    <build>
    <resources>
    <resource>
    <directory>src/main/resources/libs</directory>
    <excludes>
    <exclude>*</exclude>
    </excludes>
    <filtering>false</filtering>
    </resource>
    </resources>
    </build>
    
    <dependencies>
    <dependency>
    <groupId>com.atlassian.db.config</groupId>
    <artifactId>password-cipher-api</artifactId>
    <version><api_version></version>
    <scope>provided</scope>
    </dependency>
    <dependency>
    <groupId>com.atlassian.db.config</groupId>
    <artifactId>password-cipher-base</artifactId>
    <version><base_version></version>
    <scope>provided</scope>
    </dependency>
    </dependencies>
    
    </project>

Step 2: Implement the Cipher interface

The Cipher interface contains only two methods — encrypt and decrypt. Decrypt will be called during Jira startup, which means that long running tasks can affect the startup time. Encrypt will not be called by Jira, as it's only used in the encryption tool.

You can use Base64Cipher and AlgorithmCipher as examples. 

Step 3: Test your implementation

The encryption tool, described in Basic encryption and Advanced encryption, uses the same code as Jira to decrypt the password. You can use it to test your implementation.

Assuming that CLI and your jar is in the same folder:

java -cp "./*" com.atlassian.db.config.password.tools.CipherTool -c your.package.here.ClassName

Step 4: Make your lib available to Jira

Jira must be able to access your lib. Your class will be initiated using reflection. Put the lib in the following directory:

<Jira_installation_directory>/atlassian-jira/WEB-INF/lib

After upgrading Jira, you'll need to copy your lib to the Jira installation directory again.

Last modified on May 7, 2021

Was this helpful?

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