Package: venafi-codesigning-gitlab-integration
Venafi CodeSign Protect: Gitlab integrationThis product integratesVenafi CodeSign Protectwith Gitlab-based CI/CD processes.Venafi CodeSign Protect is a solution for securing machines against attacks and exploits, by signing executables, libraries and other machine runtime artifacts with digital signatures. Unlike naive methods of code signing, Venafi CodeSign Protect is more secure, by storing and securing the signing key separately from the CI/CD infrastructure (perhaps even in a Hardware Security Module) and by providing access control to signing keys. It also provides important insights to security teams, such as how and when signing keys are used.This product allows one to sign and verify files through Venafi CodeSign Protect. The following signing tools are currently supported:Jarsigner (Java)Signtool (Windows)Table of contentsUsage overviewSetting up executor hosts (shell and SSH executors only)CompatibilityUsageSign with JarsignerDocker executorShell or SSH executorVariablesVerify with JarsignerDocker executorShell or SSH executorVariablesSign with SigntoolDocker executorShell or SSH executorVariablesVerify with SigntoolDocker executorShell or SSH executorVariablesDocker imagesList of published Docker image tagsImage versioning policySigntool caveatsContribution & developmentUsage overviewYou must already have access to one or more Venafi Trust Protection Platforms™ (TPPs). This Gitlab integration product requires you to specify TPP address and authentication details.You use this Gitlab integration product by defining, inside your Gitlab CI YAML, steps that perform signing or verification. These steps consume artifacts generated by previous steps (such as unsigned .jar files), and may output artifacts that you can use in later steps (such as signed .jar files).Setting up executor hosts (shell and SSH executors only)If you plan on using this Gitlab integration product in combination with the shell and SSH executors, then you must install the following software on the hosts on which those executors operate. This Gitlab integration product does not take care of installing these prerequisites for you.Install Venafi CodeSign Protect client tools (seeCompatibilityto learn which versions are supported)You donotneed toconfigurethe client tools (i.e. they don't need to be configured with a TPP address or credentials). They just need to be installed. This Gitlab integration product will take care of configuring the client tools with specific TPPs.Install one or more signing tools, e.g.Jarsigner(part of the JDK) orSigntool(part of the Windows 10 SDK).Install Python >= 3.8. Ensure that it's in PATH.Install our Gitlab integration package:pip install venafi-codesigning-gitlab-integrationCompatibilityThis product is compatible with:Trust Protection Platform 20.2 or later.Venafi CodeSign Protect client tools 20.2 or later.This product supports the following Gitlab runner executors:ShellSSHDockerExecutor support differs per OS:SignerOSShellSSHDockerJarsignerLinux✅✅✅JarsignerWindows✅❌❌SigntoolLinux❌❌❌SigntoolWindows✅❌✅UsageSign with JarsignerThis section shows how to sign one or more files with Java'sJarsignertool. It assumes that jarsigner is in PATH.Docker executorDefine a job that callsvenafi-sign-jarsigner.Ensure the job operates within the imagequay.io/venafi-gitlab-integration/codesigning-jarsigner:<TAG>.Select a tag based on the Venafi client tools version that you require. SeeDocker images.Set theINPUT_PATHorINPUT_GLOBvariable to the file(s) that you wish to sign.Set other required variables too. See the variables reference below.stages:-build-sign# Build a 'foo.jar' and pass it as an artifact to the 'sign' stage.build_jar:stage:buildscript:-echo 'public class Foo { public static void main() { } }' > Foo.java-javac Foo.java-jar -cf foo.jar Foo.classartifacts:paths:-foo.jar# Sign the 'foo.jar' that was generated by the 'build' stage,# then store the signed jar as an artifact.sign_jarsigner:stage:signimage:quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64script:-venafi-sign-jarsignervariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:foo.jarCERTIFICATE_LABEL:my labelartifacts:paths:-foo.jarShell or SSH executorDefine a job that callsvenafi-sign-jarsigner.Set theINPUT_PATHorINPUT_GLOBvariable to the file(s) that you wish to sign.Set other required variables too. See the variables reference below.stages:-build-sign# Build a 'foo.jar' and pass it as an artifact to the 'sign' stage.build_jar:stage:buildscript:-echo 'public class Foo { public static void main() { } }' > Foo.java-javac Foo.java-jar -cf foo.jar Foo.classartifacts:paths:-foo.jar# Sign the 'foo.jar' that was generated by the 'build' stage,# then store the signed jar as an artifact.sign_jarsigner:stage:signscript:-venafi-sign-jarsignervariables:TPP_AUTH_URL:https://my-tpp/authTPP_HSM_URL:https://my-tpp/hsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:foo.jarCERTIFICATE_LABEL:my labelartifacts:paths:-foo.jarVariablesRequired:TPP_AUTH_URL: The TPP's authorization URL.TPP_HSM_URL: The TPP's Hardware Security Module (HSM) backend URL.TPP_USERNAME: A login username for the TPP.TPP_PASSWORDorTPP_PASSWORD_BASE64: The password associated with the login username. You can specify it normally, or in Base64 format. The latter is useful for storing the password in a Gitlab variable, in masked form, because Gitlab can only mask variables whose content only consists of Base64 characters.INPUT_PATHorINPUT_GLOB: Specifies the file(s) to sign, either through a single filename, or a glob.CERTIFICATE_LABEL: The label of the certificate (inside the TPP) to use for code signing. You can obtain a list of labels withpkcs11config listcertificates.Optional:TIMESTAMPING_SERVERS: Specifies one or more timestamping authority servers to use during signing. Specifying this is strongly recommended, because it allows signed files to be usable even after the original signing certificate has expired.If you specify more than one server, then a random one will be used.Example:TIMESTAMPING_SERVERS: http://server1,http://server2Tip:here are some public timestamping authorities that you can use:http://timestamp.digicert.comhttp://timestamp.globalsign.comhttp://timestamp.comodoca.com/authenticodehttp://tsa.starfieldtech.comEXTRA_ARGS: Specifies extra custom CLI arguments to pass to Jarsigner. The arguments are comma-separated.These arguments will beappendedto the Jarsigner CLI invocation, and take precedence over any arguments implicitly passed by this plugin.Example:EXTRA_ARGS: -arg1,-arg2EXTRA_TRUSTED_TLS_CA_CERTS(only applicable when using Docker): Allows registering extra TLS CA certificates into the truststore. This is useful if your TPP's TLS certificate is not recognized by the TLS trust store in our Docker image.Set the value to the path of a .pem file that contains one or more certificates to add to the trust store.The certificates are added to the truststore during execution ofvenafi-sign-jarsigner. So the recommended way to use this feature, is by adding an additional command — prior to the execution ofvenafi-sign-jarsigner— to fetch the CA certificate file and to place it at the expected location. Example:sign_jarsigner:image:quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64script:-wget -O /downloaded-ca.crt https://internal.company.url/path-to-your-ca-chain.crt-venafi-sign-jarsignervariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:foo.jarCERTIFICATE_LABEL:my labelEXTRA_TRUSTED_TLS_CA_CERTS:/downloaded-ca.crtVENAFI_CLIENT_TOOLS_DIR: Specifies the path to the directory in which Venafi CodeSign Protect client tools are installed. If not specified, it's autodetected as follows:Linux: /opt/venafi/codesignmacOS: /Library/Venafi/CodeSigningWindows: autodetected from the registry, or (if that fails): C:\Program Files\Venafi CodeSign ProtectVerify with JarsignerThis section shows how to verify one or more files with Java'sJarsignertool. It assumes that jarsigner is in PATH.Docker executorDefine a job that callsvenafi-verify-jarsigner.Ensure the job operates within the imagequay.io/venafi-gitlab-integration/codesigning-jarsigner:<TAG>.Select a tag based on the Venafi client tools version that you require. SeeDocker images.Set theINPUT_PATHorINPUT_GLOBvariable to the file(s) that you wish to verify.Set other required variables too. See the variables reference below.stages:-fetch-verify# Fetch a signed 'signed.jar' and pass it as an artifact to the 'verify' stage.fetch_jar:stage:fetchscript:-wget https://internal.lan/signed.jarartifacts:paths:-signed.jar# Verify 'signed.jar' that was fetched by the 'fetch' stage.verify_jarsigner:stage:verifyimage:quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64script:-venafi-verify-jarsignervariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:signed.jarCERTIFICATE_LABEL:my labelShell or SSH executorDefine a job that callsvenafi-verify-jarsigner.Set theINPUT_PATHorINPUT_GLOBvariable to the file(s) that you wish to verify.Set other required variables too. See the variables reference below.Note: the host which performs the verification does not need to have pre-installed the certificate against which to verify. We'll will fetch the certificate from the TPP, which is why it requires a certificate label.stages:-fetch-verify# Fetch a signed 'signed.jar' and pass it as an artifact to the 'verify' stage.fetch_jar:stage:fetchscript:-wget https://internal.lan/signed.jarartifacts:paths:-signed.jar# Verify 'signed.jar' that was fetched by the 'fetch' stage.verify_jarsigner:stage:verifyscript:-venafi-verify-jarsignervariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:signed.jarCERTIFICATE_LABEL:my labelVariablesRequired:TPP_AUTH_URL: The TPP's authorization URL.TPP_HSM_URL: The TPP's Hardware Security Module (HSM) backend URL.TPP_USERNAME: A login username for the TPP.TPP_PASSWORDorTPP_PASSWORD_BASE64: The password associated with the login username. You can specify it normally, or in Base64 format. The latter is useful for storing the password in a Gitlab variable, in masked form, because Gitlab can only mask variables whose content only consists of Base64 characters.INPUT_PATHorINPUT_GLOB: Specifies the file(s) to verify, either through a single filename, or a glob.CERTIFICATE_LABEL: The label of the certificate (inside the TPP) that was used for signing the file(s). You can obtain a list of labels withpkcs11config listcertificates.Optional:EXTRA_TRUSTED_TLS_CA_CERTS(only applicable when using Docker): Allows registering extra TLS CA certificates into the truststore. This is useful if your TPP's TLS certificate is not recognized by the TLS trust store in our Docker image.Set the value to the path of a .pem file that contains one or more certificates to add to the trust store.The certificates are added to the truststore during execution ofvenafi-verify-jarsigner. So the recommended way to use this feature, is by adding an additional command — prior to the execution ofvenafi-verify-jarsigner— to fetch the CA certificate file and to place it at the expected location. Example:verify_jarsigner:image:quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64script:-wget -O /downloaded-ca.crt https://internal.company.url/path-to-your-ca-chain.crt-venafi-verify-jarsignervariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:signed.jarCERTIFICATE_LABEL:my labelEXTRA_TRUSTED_TLS_CA_CERTS:/downloaded-ca.crtVENAFI_CLIENT_TOOLS_DIR: Specifies the path to the directory in which Venafi CodeSign Protect client tools are installed. If not specified, it's autodetected as follows:Linux: /opt/venafi/codesignmacOS: /Library/Venafi/CodeSigningWindows: autodetected from the registry, or (if that fails): C:\Program Files\Venafi CodeSign ProtectSign with SigntoolThis section shows how to sign one or more files with Microsoft'sSigntooltool.Docker executorUsage instructions:Define a job that callsvenafi-sign-signtool.Ensure that this job runs on a Windows-based runner, by setting the proper tags.Ensure this job operates within the imagequay.io/venafi-gitlab-integration/codesigning-signtool:<TAG>.Select a tag based on the Venafi client tools version that you require. SeeDocker images.Set theINPUT_PATHvariable to a filename or a glob that you wish to sign.Set other required variables too. See the variables reference below.Notes:Our image uses x64 signtool by default. If you wish to use a different architecture's signtool, then setSIGNTOOL_PATHtoC:\winsdk\<arch>\signtool.We use 'sha256' as the default signature digest algorithm, unlike Signtool's default ('sha1'). You may want to override this if you care about compatibility with older Windows versions that didn't support SHA-256.Please read theSigntool caveats.stages:-build-sign# Build a 'foo.exe' and pass it as an artifact to the 'sign' stage.build_exe:stage:buildimage:quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64tags:-windowsscript:-copy C:\Windows\System32\Notepad.exe foo.exeartifacts:paths:-foo.exe# Sign the 'foo.exe' that was generated by the 'build' stage,# then store the signed exe as an artifact.sign_signtool:stage:signimage:quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64tags:-windowsscript:-venafi-sign-signtoolvariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:foo.exeCERTIFICATE_SUBJECT_NAME:mydomain.comartifacts:paths:-foo.exeShell or SSH executorUsage instructions:Define a job that callsvenafi-sign-signtool.Ensure that this job runs on a Windows-based runner, by setting the proper tags.Set theINPUT_PATHvariable to a filename or a glob that you wish to sign.Set other required variables too. See the variables reference below.Notes:We assume that signtool.exe is in PATH, unless you explicitly specify its path withSIGNTOOL_PATH.We use 'sha256' as the default signature digest algorithm, unlike Signtool's default ('sha1'). You may want to override this if you care about compatibility with older Windows versions that didn't support SHA-256.Please read theSigntool caveats.stages:-build-sign# Build a 'foo.exe' and pass it as an artifact to the 'sign' stage.build_exe:stage:buildtags:-windowsscript:-copy C:\Windows\System32\Notepad.exe foo.exeartifacts:paths:-foo.exe# Sign the 'foo.exe' that was generated by the 'build' stage,# then store the signed exe as an artifact.sign_signtool:stage:signtags:-windowsscript:-venafi-sign-signtoolvariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:foo.exeCERTIFICATE_SUBJECT_NAME:mydomain.comartifacts:paths:-foo.exeVariablesRequired:TPP_AUTH_URL: The TPP's authorization URL.TPP_HSM_URL: The TPP's Hardware Security Module (HSM) backend URL.TPP_USERNAME: A login username for the TPP.TPP_PASSWORDorTPP_PASSWORD_BASE64: The password associated with the login username. You can specify it normally, or in Base64 format. The latter is useful for storing the password in a Gitlab variable, in masked form, because Gitlab can only mask variables whose content only consists of Base64 characters.INPUT_PATH: A path or a glob that specifies the file(s) to be signed.CERTIFICATE_SUBJECT_NAMEorCERTIFICATE_SHA1: Specifies the certificate (inside the TPP) to use for signing.You can either specify the certificate's Common Name ("Issued to" or "CN"), or its SHA-1 hash.You can obtain a list of Common Names withcspconfig listcertificatesand checking what comes afterCN=.Specifying the SHA-1 hash is useful if there are multiple certificates with the same Common Name.Optional:TIMESTAMPING_SERVERS: Specifies one or more timestamping authority servers to use during signing. Specifying this is strongly recommended, because it allows signed files to be usable even after the original signing certificate has expired.If you specify more than one server, then a random one will be used.Example:TIMESTAMPING_SERVERS: http://server1,http://server2Tip:here are some public timestamping authorities that you can use:http://timestamp.digicert.comhttp://timestamp.globalsign.comhttp://timestamp.comodoca.com/authenticodehttp://tsa.starfieldtech.comSIGNATURE_DIGEST_ALGOS: The digest algorithm(s) to use to creating signatures.If none specified, 'sha256' is used as the default algorithm. This is very secure, but may not be compatible with older Windows versions. If you need compatibility with older Windows versions, you should specify 'sha1,sha256' (in that order).When multiple digest algorithms are specified, they are applied in the order specified.Example:SIGNATURE_DIGEST_ALGOS=sha1,sha256APPEND_SIGNATURES(boolean): If the target file(s) already have signatures, then append a new signature instead of overwriting the existing signatures.Defaults tofalse.EXTRA_ARGS: Specifies extra custom CLI arguments to pass to Signtool. The arguments are comma-separated.These arguments will beappendedto the Signtool CLI invocation. If they overlap with any arguments implicitly passed by this plugin,
then Signtool will raise an error.Example:EXTRA_ARGS: /arg1,/arg2EXTRA_TRUSTED_TLS_CA_CERTS(only applicable when using Docker): Allows registering extra TLS CA certificates into the truststore. This is useful if your TPP's TLS certificate is not recognized by the TLS trust store in our Docker image.Set the value to the path of a PEM or DER file that contains one or more certificates to add to the trust store.The certificates are added to the truststore during execution ofvenafi-sign-signtool. So the recommended way to use this feature, is by adding an additional command — prior to the execution ofvenafi-sign-signtool— to fetch the CA certificate file and to place it at the expected location. Example:sign_signtool:script:-powershell -Command "Invoke-WebRequest -Uri 'https://internal.company.url/path-to-your-ca-chain.crt' -OutFile 'C:\downloaded-ca.crt'"-venafi-sign-signtoolvariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:foo.exeCERTIFICATE_SUBJECT_NAME:mydomain.comEXTRA_TRUSTED_TLS_CA_CERTS:C:\downloaded-ca.crtSIGNTOOL_PATH: The full path to signtool.exe. If not specified, we assume that it's in PATH.VENAFI_CLIENT_TOOLS_DIR: Specifies the path to the directory in which Venafi CodeSign Protect client tools are installed. If not specified, it's autodetected from the registry. If that fails, we fallback to C:\Program Files\Venafi CodeSign Protect.MACHINE_CONFIGURATION(boolean): Whether to load CSP configuration from the machine registry hive instead of the user registry hive. Defaults to false.Verify with SigntoolThis section shows how to verify one or more files with Microsoft'sSigntooltool.Docker executorUsage instructions:Define a job that callsvenafi-verify-signtool.Ensure that this job runs on a Windows-based runner, by setting the proper tags.Ensure this job operates within the imagequay.io/venafi-integration/codesigning-signtool:<TAG>.Select a tag based on the Venafi client tools version that you require. SeeDocker images.Set theINPUT_PATHvariable to a filename or a glob that you wish to verify.Set other required variables too. See the variables reference below.Notes:Our image uses x64 signtool by default. If you wish to use a different architecture's signtool, then setSIGNTOOL_PATHtoC:\winsdk\<arch>\signtool.Please read theSigntool caveats.stages:-fetch-verify# Fetch a signed 'signed.exe' and pass it as an artifact to the 'verify' stage.fetch_exe:stage:fetchimage:quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64tags:-windowsscript:-powershell -Command "Invoke-WebRequest -Uri 'https://internal.lan/signed.exe' -OutFile 'C:\signed.exe'"artifacts:paths:-C:\signed.exe# Verify 'signed.exe' that was fetched by the 'fetch' stage.verify_signtool:stage:signimage:quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64tags:-windowsscript:-venafi-verify-signtoolvariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:signed.exeShell or SSH executorUsage instructions:Define a job that callsvenafi-verify-signtool.Ensure that this job runs on a Windows-based runner, by setting the proper tags.Set theINPUT_PATHvariable to a filename or a glob that you wish to verify.Set other required variables too. See the variables reference below.Notes:We assume that signtool.exe is in PATH, unless you explicitly specify its path withSIGNTOOL_PATH.Please read theSigntool caveats.stages:-fetch-verify# Fetch a signed 'signed.exe' and pass it as an artifact to the 'verify' stage.fetch_exe:stage:fetchtags:-windowsscript:-powershell -Command "Invoke-WebRequest -Uri 'https://internal.lan/signed.exe' -OutFile 'C:\signed.exe'"artifacts:paths:-C:\signed.exe# Verify 'signed.exe' that was fetched by the 'fetch' stage.verify_signtool:stage:signtags:-windowsscript:-venafi-verify-signtoolvariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:signed.exeVariablesRequired:TPP_AUTH_URL: The TPP's authorization URL.TPP_HSM_URL: The TPP's Hardware Security Module (HSM) backend URL.TPP_USERNAME: A login username for the TPP.TPP_PASSWORDorTPP_PASSWORD_BASE64: The password associated with the login username. You can specify it normally, or in Base64 format. The latter is useful for storing the password in a Gitlab variable, in masked form, because Gitlab can only mask variables whose content only consists of Base64 characters.INPUT_PATH: A path or a glob that specifies the file(s) to verify.Optional:EXTRA_TRUSTED_TLS_CA_CERTS(only applicable when using Docker): Allows registering extra TLS CA certificates into the truststore. This is useful if your TPP's TLS certificate is not recognized by the TLS trust store in our Docker image.Set the value to the path of a PEM or DER file that contains one or more certificates to add to the trust store.The certificates are added to the truststore during execution ofvenafi-verify-signtool. So the recommended way to use this feature, is by adding an additional command — prior to the execution ofvenafi-verify-signtool— to fetch the CA certificate file and to place it at the expected location. Example:verify_signtool:script:-powershell -Command "Invoke-WebRequest -Uri 'https://internal.company.url/path-to-your-ca-chain.crt' -OutFile 'C:\downloaded-ca.crt'"-venafi-verify-signtoolvariables:TPP_AUTH_URL:https://my-tpp/vedauthTPP_HSM_URL:https://my-tpp/vedhsmTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.INPUT_PATH:signed.exeEXTRA_TRUSTED_TLS_CA_CERTS:C:\downloaded-ca.crtTRUSTED_CHAIN_LABEL(only applicable when using Docker): Allows registering a chain in the TPP, into the truststore. This is useful if you want to verify files, that are signed with a chain that's not already in the container's default truststore.Set the value to the label of the certificate (inside the TPP) for which its chain you want to trust. You can obtain a list of labels withcspconfig listcertificates.SIGNTOOL_PATH: The full path to signtool.exe. If not specified, we assume that it's in PATH.VENAFI_CLIENT_TOOLS_DIR: Specifies the path to the directory in which Venafi CodeSign Protect client tools are installed. If not specified, it's autodetected from the registry. If that fails, we fallback to C:\Program Files\Venafi CodeSign Protect.Docker imagesWe supply a number of Docker images, for the purpose of using this Gitlab integration product with Gitlab CI's Docker executor. These images include the Venafi client tools.Images have the following address format:quay.io/venafi-gitlab-integration/codesigning-<SIGNING TOOL>:<TAG>Where:SIGNING TOOLis eitherjarsignerorsigntool.TAGspecifies the version components and architecture that you want to use. This is in the format of:Specify thelatest-<ARCHITECTURE>tag if you want to use the latest version of this Gitlab integration product, in combination with the latest version of the Venafi client tools that we support.Note that older TPPs may not be compatible with newer client tools. We therefore do not recommend usinglatest.Specify<PRODUCT VERSION>-<VENAFI CLIENT TOOLS VERSION>-<ARCHITECTURE>as tag, if you want to have more control.PRODUCT VERSIONis the major + minor version of this Gitlab integration product. Seethe releases listto learn which versions are available.We only provide images for the latest tiny version, which is why you can't specify the tiny version number in the tag. So for example, if only product versions 1.0.0 and 1.0.1 exist, we only provide an image for 1.0 (which contains product version 1.0.1).VENAFI CLIENT TOOLS VERSIONis the version of the Venafi client tools that you wish to use, for example22.3.ARCHITECTUREis the architecture of the node on which you plan to run the container. Currently, onlyx86_64is available.Example: product version 1.2 + Venafi client tools 22.3, for use with Jarsigner on x86_64:quay.io/venafi-gitlab-integration/codesigning-jarsigner:1.2-22.3-x86_64Example: latest product version + latest Venafi client tools, for use with Signtool on x86_64:quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64List of published Docker image tagsYou can see the available tags on Quay.io:codesigning-jarsignercodesigning-signtoolImage versioning policyWe always supply the latest version of Signtool.We always supply the latest version of Jarsigner, as is installable via the base image's package manager.Our Jarsigner images are currently based on RockyOS 8, so we always supply the latest Jarsigner as is provided by RockyOS 8's YUM repository.We supply the last minor versions of the Venafi client tools, though no earlier than 21. (for example: 22.3 and 21.4).For each Venafi client tools minor version, we always supply the latest patch version.Signtool caveatsWhen using Signtool, you must ensure that all your TPP environments disable the option "Include Certificate Chain". You must do this forallTPP environments that the authenticated user account has access to: not just the ones to be used together with Signtool.If you do not do this, then Signtool will trigger a confirmation dialog box, in which Windows asks for approval to import root certificates. Signtool can't continue until a human manually clicks "Yes".This is especially problematic when using Signtool in a container, because there is no user interface, so it's impossible to click on anything.Gitlab Runner caveatsWhen using the Signtool Docker image (which is based on Windows ltsc2019) you may have to ensure that theshellhave to be set topowershellin the runner configuration, because sinceGitlab Runner 14 and laterthe default behavior changed. The default shell is now set topwsh.The following error can occur when the shell is not set correctly.FileNotFoundError: [WinError 2] The system cannot find the file specifiedGit caveatsWhen using the Signtool Docker image you may get ownership errors due to recent Git restrictions. You can solve this by adding apre_clone_scriptandpost_clone_scriptto the runner configuration that
includes the git command to configure safe directories likegit config --global --add safe.directory '*'. You may want to change the '*' to a specific directory.The following error can occur when dubious ownership is detected.fatal: detected dubious ownership in repository atContribution & developmentSee thecontribution guide.