Using Fortanix Data Security Manager with GitLab

1.0 Introduction

The objective of this article is to facilitate a secure and efficient secret management process. It outlines the steps required for generating and importing secrets, as well as for using existing secrets from Fortanix-Data-Security-Manager (DSM) within GitLab build environments.

Follow the instructions to implement this integration effectively, enhancing data security and optimizing CI/CD pipelines.

1.1 Prerequisites

Ensure that you must have the following:

• Access to a Fortanix DSM account with appropriate administrative privileges. For more information, refer to Getting Started with Fortanix Data Security Manager.

• A GitLab account with access to the project where you intend to set up the integration. For more information, refer to Getting Started with GitLab.

• Knowledge about the process of saving secrets in Fortanix DSM, including generating and importing the secret.

• Access to necessary permissions in Fortanix DSM and GitLab for group, application, plugin, variable, and secret management.

2.0 Procedure

Perform the following steps are involved in managing the secrets in a GitLab pipeline through Fortanix DSM:

1. Authentication within Fortanix DSM.

2. Configuring Fortanix DSM, which includes creating groups and applications.

3. Storing secrets securely within Fortanix DSM.

4. Accessing and retrieving secrets from Fortanix DSM for utilization within the GitLab pipeline.

3.0 Use Case 1: Generating & Importing a Secret

3.1 Signing Up

To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

   • Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.

   • Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

3. Click the SAVE button to add the new application.

The new application has been added to the Fortanix DSM successfully.

3.5 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click the VIEW API KEY DETAILS button.

3. From the API Key Details dialog box, copy the API Key of the app to be used later.

3.6 Generating the Plugin

Perform the following steps to generate a plugin in Fortanix DSM:

1. Run the following command to generate a new plugin in Fortanix DSM:
   For more information, refer to User’s Guide: Plugin Library.

   numericAlphabet
   = "0123456789"
   alphanumericAlphabet
   = numericAlphabet .. "abcdefghijklmnopqrstuvwxyz"
   alphanumericCapsAlphabet
   = alphanumericAlphabet .. "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
   alphanumericCapsSymbolsAlphabets
   = alphanumericCapsAlphabet .. "!@#$&*_%="
   function
   genPass(alphabet, len, name, import)
       local alphabetSize = #alphabet
       local password = ''
       for i = 1, len, 1 do
           local random_char =
   math.random(alphabetSize)
           password = password ..
   string.sub(alphabet, random_char, random_char)
       end
       local pass = Blob.from_bytes(password)
       if import == "yes" then
           local sobject = assert(Sobject.import {
   name = name, obj_type = "SECRET", value = pass, key_ops =
   {'APPMANAGEABLE', 'EXPORT'} })
           return password
       end
       return password;
   end
   function
   run(input)
       if input.type == "numeric" then
           return genPass(numericAlphabet,
   input.length, input.name, input.import)
       end
       if input.type == "alphanumeric"
   then
           return genPass(alphanumericAlphabet, input.length,
   input.name, input.import)
       end  
       if input.type ==
   "alphanumeric_caps" then
           return
   genPass(alphanumericCapsAlphabet, input.length, input.name, input.import)
       end  
       if input.type ==
   "alphanumeric_caps_symbols" then
           return
   genPass(alphanumericCapsSymbolsAlphabets, input.length, input.name,
   input.import)      
       end
   end

   • Set the import option to yes if you want to store the secret in Fortanix DSM.

     {
         "type": "alphanumeric_caps",
         "length": 64,
         "name": "GitLab-Secret",
         "import": "yes"
     }
     

   • Set the import option to no if you only want a new value generated for rotation.

     {
         "type": "numeric",
         "length": 64,
         "name": "GitLab-Secret",
         "import": "no"
     }

3.7 Integration Steps

Perform the following steps:

1. Navigate to GitLab and select the project where you want to set up the integration.

2. In GitLab, go to Settings → CI/CD → Variables, and add the following new variables:

   • FORTANIX_API_ENDPOINT

   • FORTANIX_API_KEY

   • FORTANIX_PLUGIN_ID

3. Under the top level of your GitLab project, locate the .gitlab-ci.yaml configuration file and edit this file as following to define the CI/CD pipeline for the integration:

   stages:
     - build
   
   build:
     stage: build
     image: ubuntu
     script:
     - apt-get update
     - apt install jq -y
     - apt install curl -y
     - jq --version
     - curl -V
     - secret=$(curl -s -X POST -H "Authorization:Basic ${FORTANIX_API_KEY}" ${FORTANIX_API_ENDPOINT}/sys/v1/plugins/${FORTANIX_PLUGIN_ID} -d "{\"type\":\"alphanumeric_caps\", \"name\":\"$CI_PIPELINE_ID\",\"import\":\"yes\", \"length\":\"48\"}" | jq -r)
     - echo $CI_PIPELINE_ID
     - echo $secret
     - nsecret=$(curl -s -X POST -H "Authorization:Basic ${FORTANIX_API_KEY}" ${FORTANIX_API_ENDPOINT}/sys/v1/plugins/${FORTANIX_PLUGIN_ID} -d "{\"type\":\"alphanumeric_caps\", \"import\":\"no\", \"length\":\"48\"}" | jq -r)
     - echo $nsecret
     - encodesecret=$(echo $nsecret | base64)
     - rotate=$(curl -s -X POST -H "Authorization:Basic ${FORTANIX_API_KEY}" ${FORTANIX_API_ENDPOINT}/crypto/v1/keys/rekey -d "{\"name\":\"$CI_PIPELINE_ID\", \"value\":\"$encodesecret\"}" | jq -r .kid)
     - echo $rotate

   The pipeline must automatically run after editing the .gitlab-ci.yaml file.
   If not, select Build → Pipelines → Run pipeline to initiate the process.

   

4. On Gitlab UI, navigate to Build → Jobs from the left navigation bar to review the latest output.

4.0 Use Case 2: Using an Existing Secret from Fortanix DSM

Ensure you have a secret in Fortanix DSM that you want to use in the integration and this secret is marked as exportable within Fortanix DSM.

Perform the following steps to utilize an existing secret from Fortanix DSM in your integration with GitLab:

1. Navigate to your GitLab project where you want to set up the integration.

2. In GitLab, go to Settings → CI/CD → Variables and add the following new variables:

   • FORTANIX_API_ENDPOINT

   • FORTANIX_API_KEY

   • FORTANIX_SECRET_NAME

3. Under the top level of your GitLab project, locate the .gitlab-ci.yaml configuration file and edit this file as following to define the CI/CD pipeline for the integration:

   stages:
     - build
   
   build:
     stage: build
     image: ubuntu
     script:
     - apt-get update
     - apt install jq -y
     - apt install curl -y
     - jq --version
     - curl -V
     - secret=$(curl -s -X POST -H "Authorization:Basic ${FORTANIX_API_KEY}" ${FORTANIX_API_ENDPOINT}/crypto/v1/keys/export -d "{\"name\":\"${FORTANIX_SECRET_NAME}\"}" | jq -r .value)
     - echo $CI_PIPELINE_ID
     - echo $secret
   

   The pipeline must automatically run after editing the .gitlab-ci.yaml file.
   If not, select Build → Pipelines → Run pipeline to initiate the integration process.

   

4. On GitLab UI, navigate to Build → Jobs from the left navigation bar to review the latest output.