debian-mirror-gitlab/doc/development/fips_compliance.md

stage	group	info
none	unassigned	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

FIPS compliance

FIPS is short for "Federal Information Processing Standard", a document which defines certain security practices for a "cryptographic module" (CM). It aims to ensure a certain security floor is met by vendors selling products to U.S. Federal institutions.

WARNING: GitLab is not FIPS compliant, even when built and run on a FIPS-enforcing system. Large parts of the build are broken, and many features use forbidden cryptographic primitives. Running GitLab on a FIPS-enforcing system is not supported and may result in data loss. This document is intended to help engineers looking to develop FIPS-related fixes. It is not intended to be used to run a production GitLab instance.

There are two current FIPS standards: 140-2 and 140-3. At GitLab we usually mean FIPS 140-2.

Current status

GitLab Inc has not committed to making GitLab FIPS-compliant at this time. We are performing initial investigations to see how much work such an effort would be.

Read Epic &5104 for more information on the status of the investigation.

FIPS compliance at GitLab

In a FIPS context, compliance is a form of self-certification - if we say we are "FIPS compliant", we mean that we believe we are. There are no external certifications to acquire, but if we are aware of non-compliant areas in GitLab, we cannot self-certify in good faith.

The known areas of non-compliance are tracked in Epic &5104.

To be compliant, all components (GitLab itself, Gitaly, etc) must be compliant, along with the communication between those components, and any storage used by them. Where functionality cannot be brought into compliance, it must be disabled when FIPS mode is enabled.

FIPS validation at GitLab

Unlike FIPS compliance, FIPS validation is a formal declaration of compliance by an accredited auditor. The requirements needed to pass the audit are the same as for FIPS compliance.

A list of FIPS-validated modules can be found at the NIST (National Institute of Standards and Technology) cryptographic module validation program.

Setting up a FIPS-enabled development environment

The simplest approach is to set up a virtual machine running Red Hat Enterprise Linux 8.

Red Hat provide free licenses to developers, and permit the CD image to be downloaded from the Red Hat developer's portal. Registration is required.

After the virtual machine is set up, you can follow the GDK installation instructions, including the advanced instructions for RHEL. Note that asdf is not used for dependency management because it's essential to use the RedHat-provided Go compiler and other system dependencies.

Working around broken frontend asset compilation

A known bug affects asset compilation with FIPS mode enabled: issue #322883. Until this is resolved, working on frontend issues is not feasible. We can still work on backend issues by compiling the assets while FIPS is disabled, and placing GDK into static asset mode:

1. Modify your gdk.yml to contain the following:

   webpack:
     host: 127.0.0.1
     port: 3808
     static: true
   

2. In the GitLab repository, apply this patch to prevent the assets from being automatically deleted whenever GDK is restarted:

   diff --git a/scripts/frontend/webpack_dev_server.js b/scripts/frontend/webpack_dev_server.js
   index fbb80c9617d..114720d457c 100755
   --- a/scripts/frontend/webpack_dev_server.js
   +++ b/scripts/frontend/webpack_dev_server.js
   @@ -15,7 +15,7 @@ const baseConfig = {
    // run webpack in compile-once mode and watch for changes
    if (STATIC_MODE) {
      nodemon({
   -    exec: `rm -rf public/assets/webpack ; yarn run webpack && exec ruby -run -e httpd public/ -p ${DEV_SERVER_PORT}`,
   +    exec: `ruby -run -e httpd public/ -p ${DEV_SERVER_PORT}`,
        watch: [
          'config/webpack.config.js',
          'app/assets/javascripts',
   

3. Run this command in the GitLab repository to generate the asset files to be served:

   bin/rails gitlab:assets:compile
   

Every time you change a frontend asset, you must re-run this command (with FIPS mode disabled) before seeing the changes.

Enable FIPS mode

After the assets are generated, run this command (as root) and restart the virtual machine:

fips-mode-setup --enable

You can check whether it's taken effect by running:

fips-mode-setup --check

In this environment, OpenSSL refuses to perform cryptographic operations forbidden by the FIPS standards. This enables you to reproduce FIPS-related bugs, and validate fixes.

You should be able to open a web browser inside the virtual machine and log in to the GitLab instance.

You can disable FIPS mode again by running this command, then restarting the virtual machine:

fips-mode-setup --disable