1--- 2stage: none 3group: unassigned 4info: 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 5--- 6 7# FIPS compliance 8 9FIPS is short for "Federal Information Processing Standard", a document which 10defines certain security practices for a "cryptographic module" (CM). It aims 11to ensure a certain security floor is met by vendors selling products to U.S. 12Federal institutions. 13 14WARNING: 15GitLab is not FIPS compliant, even when built and run on a FIPS-enforcing 16system. Large parts of the build are broken, and many features use forbidden 17cryptographic primitives. Running GitLab on a FIPS-enforcing system is not 18supported and may result in data loss. This document is intended to help 19engineers looking to develop FIPS-related fixes. It is not intended to be used 20to run a production GitLab instance. 21 22There are two current FIPS standards: [140-2](https://en.wikipedia.org/wiki/FIPS_140-2) 23and [140-3](https://en.wikipedia.org/wiki/FIPS_140-3). At GitLab we usually 24mean FIPS 140-2. 25 26## Current status 27 28GitLab Inc has not committed to making GitLab FIPS-compliant at this time. We are 29performing initial investigations to see how much work such an effort would be. 30 31Read [Epic &5104](https://gitlab.com/groups/gitlab-org/-/epics/5104) for more 32information on the status of the investigation. 33 34## FIPS compliance at GitLab 35 36In a FIPS context, compliance is a form of self-certification - if we say we are 37"FIPS compliant", we mean that we *believe* we are. There are no external 38certifications to acquire, but if we are aware of non-compliant areas 39in GitLab, we cannot self-certify in good faith. 40 41The known areas of non-compliance are tracked in [Epic &5104](https://gitlab.com/groups/gitlab-org/-/epics/5104). 42 43To be compliant, all components (GitLab itself, Gitaly, etc) must be compliant, 44along with the communication between those components, and any storage used by 45them. Where functionality cannot be brought into compliance, it must be disabled 46when FIPS mode is enabled. 47 48## FIPS validation at GitLab 49 50Unlike FIPS compliance, FIPS validation is a formal declaration of compliance by 51an accredited auditor. The requirements needed to pass the audit are the same as 52for FIPS compliance. 53 54A list of FIPS-validated modules can be found at the 55NIST (National Institute of Standards and Technology) 56[cryptographic module validation program](https://csrc.nist.gov/projects/cryptographic-module-validation-program/validated-modules). 57 58## Setting up a FIPS-enabled development environment 59 60The simplest approach is to set up a virtual machine running 61[Red Hat Enterprise Linux 8](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#switching-the-system-to-fips-mode_using-the-system-wide-cryptographic-policies). 62 63Red Hat provide free licenses to developers, and permit the CD image to be 64downloaded from the [Red Hat developer's portal](https://developers.redhat.com). 65Registration is required. 66 67After the virtual machine is set up, you can follow the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) 68installation instructions, including the [advanced instructions for RHEL](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/advanced.md#red-hat-enterprise-linux). 69Note that `asdf` is not used for dependency management because it's essential to 70use the RedHat-provided Go compiler and other system dependencies. 71 72### Working around broken frontend asset compilation 73 74A known bug affects asset compilation with FIPS mode enabled: [issue #322883](https://gitlab.com/gitlab-org/gitlab/-/issues/322883). 75Until this is resolved, working on frontend issues is not feasible. We can still 76work on backend issues by compiling the assets while FIPS is disabled, and 77placing GDK into [static asset mode](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/configuration.md#webpack-settings): 78 791. Modify your `gdk.yml` to contain the following: 80 81 ```yaml 82 webpack: 83 host: 127.0.0.1 84 port: 3808 85 static: true 86 ``` 87 881. In the GitLab repository, apply this patch to prevent the assets from being 89 automatically deleted whenever GDK is restarted: 90 91 ```diff 92 diff --git a/scripts/frontend/webpack_dev_server.js b/scripts/frontend/webpack_dev_server.js 93 index fbb80c9617d..114720d457c 100755 94 --- a/scripts/frontend/webpack_dev_server.js 95 +++ b/scripts/frontend/webpack_dev_server.js 96 @@ -15,7 +15,7 @@ const baseConfig = { 97 // run webpack in compile-once mode and watch for changes 98 if (STATIC_MODE) { 99 nodemon({ 100 - exec: `rm -rf public/assets/webpack ; yarn run webpack && exec ruby -run -e httpd public/ -p ${DEV_SERVER_PORT}`, 101 + exec: `ruby -run -e httpd public/ -p ${DEV_SERVER_PORT}`, 102 watch: [ 103 'config/webpack.config.js', 104 'app/assets/javascripts', 105 ``` 106 1071. Run this command in the GitLab repository to generate the asset files 108 to be served: 109 110 ```shell 111 bin/rails gitlab:assets:compile 112 ``` 113 114Every time you change a frontend asset, you must re-run this command 115(with FIPS mode disabled) before seeing the changes. 116 117### Enable FIPS mode 118 119After the assets are generated, run this command (as root) and restart the 120virtual machine: 121 122```shell 123fips-mode-setup --enable 124``` 125 126You can check whether it's taken effect by running: 127 128```shell 129fips-mode-setup --check 130``` 131 132In this environment, OpenSSL refuses to perform cryptographic operations 133forbidden by the FIPS standards. This enables you to reproduce FIPS-related bugs, 134and validate fixes. 135 136You should be able to open a web browser inside the virtual machine and log in 137to the GitLab instance. 138 139You can disable FIPS mode again by running this command, then restarting the 140virtual machine: 141 142```shell 143fips-mode-setup --disable 144``` 145