https://sapmachine.io/assets/js/18315ae2.92fd500a.js

1"use strict";(globalThis.webpackChunksapmachine_io=globalThis.webpackChunksapmachine_io||[]).push([[755],{2262(e,n,r){r.r(n),r.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>p,frontMatter:()=>t,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"Using SapMachine/fips-configuration","title":"FIPS Configuration","description":"SapMachine can be configured to be FIPS compliant by using Bouncy Castle as a JCA security provider.","source":"@site/docs/Using SapMachine/fips-configuration.md","sourceDirName":"Using SapMachine","slug":"/fips-configuration","permalink":"/docs/fips-configuration","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"FIPS Configuration","sidebar_position":5,"slug":"/fips-configuration"},"sidebar":"docsSidebar","previous":{"title":"GitHub Actions setup-java","permalink":"/docs/github-actions-setup-java"},"next":{"title":"Features of SapMachine","permalink":"/docs/features"}}');var s=r(4848),o=r(8453);const t={title:"FIPS Configuration",sidebar_position:5,slug:"/fips-configuration"},a="FIPS Configuration",c={},d=[{value:"Adding Bouncy Castle as a Dependency",id:"adding-bouncy-castle-as-a-dependency",level:2},{value:"Configuring FIPS Mode via JVM Arguments",id:"configuring-fips-mode-via-jvm-arguments",level:2},{value:"<code>fips.security</code> File",id:"fipssecurity-file",level:3},{value:"JVM Arguments",id:"jvm-arguments",level:3},{value:"Example",id:"example",level:3},{value:"Using Java Tools (keytool, jarsigner, etc.)",id:"using-java-tools-keytool-jarsigner-etc",level:3},{value:"The Sun Provider and Entropy",id:"the-sun-provider-and-entropy",level:2},{value:"Alternative: Bouncy Castle JENT Entropy Provider",id:"alternative-bouncy-castle-jent-entropy-provider",level:3},{value:"Removing Non-FIPS-Compliant Algorithms",id:"removing-non-fips-compliant-algorithms",level:2}];function l(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"fips-configuration",children:"FIPS Configuration"})}),"\n",(0,s.jsx)(n.p,{children:"SapMachine can be configured to be FIPS compliant by using Bouncy Castle as a JCA security provider."}),"\n",(0,s.jsx)(n.h2,{id:"adding-bouncy-castle-as-a-dependency",children:"Adding Bouncy Castle as a Dependency"}),"\n",(0,s.jsxs)(n.p,{children:["Add the Bouncy Castle FIPS jars to your project. Check ",(0,s.jsx)(n.a,{href:"https://central.sonatype.com/search?q=bc-fips",children:"Maven Central"})," for the latest versions."]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Maven:"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-xml",children:"<dependency>\n    <groupId>org.bouncycastle</groupId>\n    <artifactId>bc-fips</artifactId>\n    <version>2.1.2</version>\n</dependency>\n<dependency>\n    <groupId>org.bouncycastle</groupId>\n    <artifactId>bctls-fips</artifactId>\n    <version>2.1.22</version>\n</dependency>\n"})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Gradle:"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-groovy",children:"implementation 'org.bouncycastle:bc-fips:2.1.2'\nimplementation 'org.bouncycastle:bctls-fips:2.1.22'\n"})}),"\n",(0,s.jsx)(n.h2,{id:"configuring-fips-mode-via-jvm-arguments",children:"Configuring FIPS Mode via JVM Arguments"}),"\n",(0,s.jsx)(n.p,{children:"FIPS mode can be configured entirely via JVM arguments, no code changes required."}),"\n",(0,s.jsxs)(n.h3,{id:"fipssecurity-file",children:[(0,s.jsx)(n.code,{children:"fips.security"})," File"]}),"\n",(0,s.jsxs)(n.p,{children:["Create a ",(0,s.jsx)(n.code,{children:"fips.security"})," file that overrides the default ",(0,s.jsx)(n.code,{children:"java.security"})," to register Bouncy Castle as the top-priority security providers:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-properties",children:"security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider\nsecurity.provider.2

1=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS\nsecurity.provider.3=sun.security.provider.Sun\n"})}),"\n",(0,s.jsx)(n.h3,{id:"jvm-arguments",children:"JVM Arguments"}),"\n",(0,s.jsxs)(n.p,{children:["Place the Bouncy Castle FIPS jars in a directory (e.g. ",(0,s.jsx)(n.code,{children:"fips-libs/"}),") and pass the following arguments when launching the JVM:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"--module-path <fips-libs-directory>"})," makes the Bouncy Castle FIPS jars available to the JVM."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"-Djava.security.properties=fips.security"})," merges ",(0,s.jsx)(n.code,{children:"fips.security"})," with the default ",(0,s.jsx)(n.code,{children:"java.security"}),", registering BCFIPS and BCJSSE as the top-priority security providers."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"-Dorg.bouncycastle.fips.approved_only=true"})," enables Bouncy Castle approved-only mode, which rejects non-FIPS algorithms such as MD5."]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"example",children:"Example"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"java \\\n  --module-path /path/to/fips-libs \\\n  -Djava.security.properties=fips.security \\\n  -Dorg.bouncycastle.fips.approved_only=true \\\n  -jar your-application.jar\n"})}),"\n",(0,s.jsx)(n.h3,{id:"using-java-tools-keytool-jarsigner-etc",children:"Using Java Tools (keytool, jarsigner, etc.)"}),"\n",(0,s.jsxs)(n.p,{children:["When using JDK tools rather than launching your own application, pass the same arguments via the ",(0,s.jsx)(n.code,{children:"JAVA_TOOL_OPTIONS"})," environment variable:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:'export JAVA_TOOL_OPTIONS="\\\n  --module-path=/path/to/fips-libs \\\n  -Djava.security.properties=fips.security \\\n  -Dorg.bouncycastle.fips.approved_only=true"\n\nkeytool ...\n'})}),"\n",(0,s.jsx)(n.h2,{id:"the-sun-provider-and-entropy",children:"The Sun Provider and Entropy"}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"fips.security"})," configuration above keeps ",(0,s.jsx)(n.code,{children:"sun.security.provider.Sun"})," as provider 3. One of its purposes is to provide entropy for seeding the BCFIPS Deterministic Random Bit Generator (DRBG): ",(0,s.jsx)(n.code,{children:"SecureRandom"})," from the Sun provider reads from ",(0,s.jsx)(n.code,{children:"/dev/random"})," or ",(0,s.jsx)(n.code,{children:"/dev/urandom"})," on Linux. This entropy is ",(0,s.jsx)(n.strong,{children:"only FIPS-validated if the underlying OS is itself FIPS-certified"}),"."]}),"\n",(0,s.jsx)(n.h3,{id:"alternative-bouncy-castle-jent-entropy-provider",children:"Alternative: Bouncy Castle JENT Entropy Provider"}),"\n",(0,s.jsxs)(n.p,{children:["If a pure-software, FIPS-validated entropy source is required without depending on OS FIPS certification, the Bouncy Castle JENT provider can replace the Sun provider as the entropy source. You can read more about it in ",(0,s.jsx)(n.a,{href:"https://csrc.nist.gov/CSRC/media/projects/cryptographic-module-validation-program/documents/entropy/E266_PublicUse.pdf",children:"JEntropy Engine PDF"}),"."]}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"NOTE:"})," JENT is significantly slower than reading from ",(0,s.jsx)(n.code,{children:"/dev/random"}),", especially during key generation. It is supported on Intel x86 and ARM Linux only. Prefer hardware RNG or OS-based entropy where available."]}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["Check ",(0,s.jsx)(n.a,{href:"https://central.sonatype.com/search?q=bc-rng-jent",children:"Maven Central"})," for the latest versions and add the Maven dependency:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-xml",children:"<dependency>\n    <groupId>org.bouncycastle</groupId>\n    <artifactId>bc-rng-jent</artifactId>\n    <version>1.3.6</version>\n</dependency>\n"})}),"\n",(0,s.jsxs)(n.p,{children:["Then update ",(0,s.jsx)(n.code,{children:"fips.security"})," to use the JENT provider and configure BCFIPS in HYBRID mode (which uses a background entropy pool to reduce blocking):"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-properties",children:"security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{ALL};

1\nsecurity.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS\nsecurity.provider.3=org.bouncycastle.entropy.provider.BouncyCastleEntropyProvider\nsecurity.provider.4=sun.security.provider.Sun\nsecurerandom.strongAlgorithms=ENTROPY:BCRNG\n"})}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.code,{children:"C:HYBRID;ENABLE{ALL};"}),' tells BCFIPS to collect entropy in the background continuously rather than only on demand. Without this, each cryptographic operation that needs fresh entropy blocks until enough jitter measurements have been taken, which with JENT can be noticeably slow. With HYBRID mode a background thread ("BC FIPS Entropy Daemon") keeps a pool of pre-collected entropy ready, so foreground operations rarely have to wait.']}),"\n",(0,s.jsx)(n.h2,{id:"removing-non-fips-compliant-algorithms",children:"Removing Non-FIPS-Compliant Algorithms"}),"\n",(0,s.jsxs)(n.p,{children:["The Sun provider also exposes non-FIPS algorithms (e.g. MD5, SHA-1 based operations). Because BCFIPS is registered at priority 1, most JCA/JCE calls will be routed to it, but co

1de that explicitly requests ",(0,s.jsx)(n.code,{children:'"SUN"'})," as the provider can still reach non-FIPS algorithms. Beyond having Bouncy Castle reject non-FIPS algorithms at runtime, you can proactively remove them from the JDK itself by extending the ",(0,s.jsx)(n.code,{children:"fips.security"})," override file with the JDK's built-in algorithm constraint properties. This prevents non-compliant algorithms from being negotiated even by JDK-native code paths."]}),"\n",(0,s.jsxs)(n.p,{children:["Add the following properties to your ",(0,s.jsx)(n.code,{children:"fips.security"})," file that are stricter than the Java defaults:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-properties",children:"# Larger key required size for DH, and block weak named curves\njdk.tls.disabledAlgorithms=DH keySize < 2048, include jdk.disabled.namedCurves\n\n# Larger key size required for RSA\njdk.certpath.disabledAlgorithms=RSA keySize < 2048\n"})}),"\n",(0,s.jsxs)(n.p,{children:["To replace the JDK defaults entirely instead of merging, use a double equals sign: ",(0,s.jsx)(n.code,{children:"-Djava.security.properties==fips.security"}),". In that case you must carry the full JDK default lists yourself in addition to the FIPS-specific entries above."]}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"Note:"})," The exact set of algorithms to disable depends on your compliance target (FIPS 140-2 vs. 140-3) and your environment. Review and adjust these lists to match your specific requirements."]}),"\n"]})]})}function p(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(l,{...e})}):l(e)}},8453(e,n,r){r.d(n,{R:()=>t,x:()=>a});var i=r(6540);const s={},o=i.createContext(s);function t(e){const n=i.useContext(o);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:t(e.components),i.createElement(o.Provider,{value:n},e.children)}}}]);