venafi-codesigning-gitlab-integration 1.2.0
Venafi CodeSign Protect: Gitlab integration
License: Apache 2.0
Requires Python: >=3.8

# Venafi CodeSign Protect: Gitlab integration

This product integrates [Venafi CodeSign Protect](https://www.venafi.com/platform/code-signing) with 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 contents**

 - [Usage overview](#usage-overview)
 - [Setting up executor hosts (shell and SSH executors only)](#setting-up-executor-hosts-shell-and-ssh-executors-only)
 - [Compatibility](#compatibility)
 - [Usage](#usage)
   - [Sign with Jarsigner](#sign-with-jarsigner)
     - [Docker executor](#docker-executor)
     - [Shell or SSH executor](#shell-or-ssh-executor)
     - [Variables](#variables)
   - [Verify with Jarsigner](#verify-with-jarsigner)
     - [Docker executor](#docker-executor-1)
     - [Shell or SSH executor](#shell-or-ssh-executor-1)
     - [Variables](#variables-1)
   - [Sign with Signtool](#sign-with-signtool)
     - [Docker executor](#docker-executor-2)
     - [Shell or SSH executor](#shell-or-ssh-executor-2)
     - [Variables](#variables-2)
   - [Verify with Signtool](#verify-with-signtool)
     - [Docker executor](#docker-executor-3)
     - [Shell or SSH executor](#shell-or-ssh-executor-3)
     - [Variables](#variables-3)
 - [Docker images](#docker-images)
     - [List of published Docker image tags](#list-of-published-docker-image-tags)
     - [Image versioning policy](#image-versioning-policy)
 - [Signtool caveats](#signtool-caveats)
 - [Contribution & development](#contribution-development)

## Usage overview

You 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 (see [Compatibility](#compatibility) to learn which versions are supported)
    - You do *not* need to *configure* the 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](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/jarsigner.html) (part of the JDK) or [Signtool](https://docs.microsoft.com/en-us/dotnet/framework/tools/signtool-exe) (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-integration`

## Compatibility

This 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:

 * Shell
 * SSH
 * Docker

Executor support differs per OS:

| Signer    | OS      | Shell | SSH | Docker |
|-----------|---------|-------|-----|--------|
| Jarsigner | Linux   | ✅    | ✅  | ✅     |
| Jarsigner | Windows | ✅    | ❌  | ❌     |
| Signtool  | Linux   | ❌    | ❌  | ❌     |
| Signtool  | Windows | ✅    | ❌  | ✅     |

## Usage

### Sign with Jarsigner

This section shows how to sign one or more files with Java's [Jarsigner](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/jarsigner.html) tool. It assumes that jarsigner is in PATH.

#### Docker executor

 * Define a job that calls `venafi-sign-jarsigner`.
 * Ensure the job operates within the image `quay.io/venafi-gitlab-integration/codesigning-jarsigner:<TAG>`.
    - Select a tag based on the Venafi client tools version that you require. See [Docker images](#docker-images).
 * Set the `INPUT_PATH` or `INPUT_GLOB` variable to the file(s) that you wish to sign.
 * Set other required variables too. See the variables reference below.

~~~yaml
stages:
  - build
  - sign

# Build a 'foo.jar' and pass it as an artifact to the 'sign' stage.
build_jar:
  stage: build
  script:
    - echo 'public class Foo { public static void main() { } }' > Foo.java
    - javac Foo.java
    - jar -cf foo.jar Foo.class
  artifacts:
    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: sign
  image: quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64
  script:
    - venafi-sign-jarsigner
  variables:
    TPP_AUTH_URL: https://my-tpp/vedauth
    TPP_HSM_URL: https://my-tpp/vedhsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: foo.jar
    CERTIFICATE_LABEL: my label
  artifacts:
    paths:
      - foo.jar
~~~

#### Shell or SSH executor

 * Define a job that calls `venafi-sign-jarsigner`.
 * Set the `INPUT_PATH` or `INPUT_GLOB` variable to the file(s) that you wish to sign.
 * Set other required variables too. See the variables reference below.

~~~yaml
stages:
  - build
  - sign

# Build a 'foo.jar' and pass it as an artifact to the 'sign' stage.
build_jar:
  stage: build
  script:
    - echo 'public class Foo { public static void main() { } }' > Foo.java
    - javac Foo.java
    - jar -cf foo.jar Foo.class
  artifacts:
    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: sign
  script:
    - venafi-sign-jarsigner
  variables:
    TPP_AUTH_URL: https://my-tpp/auth
    TPP_HSM_URL: https://my-tpp/hsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: foo.jar
    CERTIFICATE_LABEL: my label
  artifacts:
    paths:
      - foo.jar
~~~

#### Variables

Required:

 * `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_PASSWORD` or `TPP_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` or `INPUT_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 with `pkcs11config 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://server2
    ~~~

    **Tip:** here are some public timestamping authorities that you can use:

     - http://timestamp.digicert.com
     - http://timestamp.globalsign.com
     - http://timestamp.comodoca.com/authenticode
     - http://tsa.starfieldtech.com

 * `EXTRA_ARGS`: Specifies extra custom CLI arguments to pass to Jarsigner. The arguments are comma-separated.

    These arguments will be _appended_ to the Jarsigner CLI invocation, and take precedence over any arguments implicitly passed by this plugin.

    Example:

    ~~~
    EXTRA_ARGS: -arg1,-arg2
    ~~~

 * `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 of `venafi-sign-jarsigner`. So the recommended way to use this feature, is by adding an additional command — prior to the execution of `venafi-sign-jarsigner` — to fetch the CA certificate file and to place it at the expected location. Example:

   ~~~yaml
   sign_jarsigner:
     image: quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64
     script:
       - wget -O /downloaded-ca.crt https://internal.company.url/path-to-your-ca-chain.crt
       - venafi-sign-jarsigner
     variables:
       TPP_AUTH_URL: https://my-tpp/vedauth
       TPP_HSM_URL: https://my-tpp/vedhsm
       TPP_USERNAME: my_username
       # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

       INPUT_PATH: foo.jar
       CERTIFICATE_LABEL: my label
       EXTRA_TRUSTED_TLS_CA_CERTS: /downloaded-ca.crt
   ~~~

 * `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 as follows:

     - Linux: /opt/venafi/codesign
     - macOS: /Library/Venafi/CodeSigning
     - Windows: autodetected from the registry, or (if that fails): C:\Program Files\Venafi CodeSign Protect

### Verify with Jarsigner

This section shows how to verify one or more files with Java's [Jarsigner](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/jarsigner.html) tool. It assumes that jarsigner is in PATH.

#### Docker executor

 * Define a job that calls `venafi-verify-jarsigner`.
 * Ensure the job operates within the image `quay.io/venafi-gitlab-integration/codesigning-jarsigner:<TAG>`.
    - Select a tag based on the Venafi client tools version that you require. See [Docker images](#docker-images).
 * Set the `INPUT_PATH` or `INPUT_GLOB` variable to the file(s) that you wish to verify.
 * Set other required variables too. See the variables reference below.

~~~yaml
stages:
  - fetch
  - verify

# Fetch a signed 'signed.jar' and pass it as an artifact to the 'verify' stage.
fetch_jar:
  stage: fetch
  script:
    - wget https://internal.lan/signed.jar
  artifacts:
    paths:
      - signed.jar

# Verify 'signed.jar' that was fetched by the 'fetch' stage.
verify_jarsigner:
  stage: verify
  image: quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64
  script:
    - venafi-verify-jarsigner
  variables:
    TPP_AUTH_URL: https://my-tpp/vedauth
    TPP_HSM_URL: https://my-tpp/vedhsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: signed.jar
    CERTIFICATE_LABEL: my label
~~~

#### Shell or SSH executor

 * Define a job that calls `venafi-verify-jarsigner`.
 * Set the `INPUT_PATH` or `INPUT_GLOB` variable 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.

~~~yaml
stages:
  - fetch
  - verify

# Fetch a signed 'signed.jar' and pass it as an artifact to the 'verify' stage.
fetch_jar:
  stage: fetch
  script:
    - wget https://internal.lan/signed.jar
  artifacts:
    paths:
      - signed.jar

# Verify 'signed.jar' that was fetched by the 'fetch' stage.
verify_jarsigner:
  stage: verify
  script:
    - venafi-verify-jarsigner
  variables:
    TPP_AUTH_URL: https://my-tpp/vedauth
    TPP_HSM_URL: https://my-tpp/vedhsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: signed.jar
    CERTIFICATE_LABEL: my label
~~~

#### Variables

Required:

 * `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_PASSWORD` or `TPP_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` or `INPUT_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 with `pkcs11config 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 of `venafi-verify-jarsigner`. So the recommended way to use this feature, is by adding an additional command — prior to the execution of `venafi-verify-jarsigner` — to fetch the CA certificate file and to place it at the expected location. Example:

   ~~~yaml
   verify_jarsigner:
     image: quay.io/venafi-gitlab-integration/codesigning-jarsigner:latest-x86_64
     script:
       - wget -O /downloaded-ca.crt https://internal.company.url/path-to-your-ca-chain.crt
       - venafi-verify-jarsigner
     variables:
       TPP_AUTH_URL: https://my-tpp/vedauth
       TPP_HSM_URL: https://my-tpp/vedhsm
       TPP_USERNAME: my_username
       # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

       INPUT_PATH: signed.jar
       CERTIFICATE_LABEL: my label
       EXTRA_TRUSTED_TLS_CA_CERTS: /downloaded-ca.crt
   ~~~

 * `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 as follows:

     - Linux: /opt/venafi/codesign
     - macOS: /Library/Venafi/CodeSigning
     - Windows: autodetected from the registry, or (if that fails): C:\Program Files\Venafi CodeSign Protect

### Sign with Signtool

This section shows how to sign one or more files with Microsoft's [Signtool](https://docs.microsoft.com/en-us/dotnet/framework/tools/signtool-exe) tool.

#### Docker executor

Usage instructions:

 * Define a job that calls `venafi-sign-signtool`.
 * Ensure that this job runs on a Windows-based runner, by setting the proper tags.
 * Ensure this job operates within the image `quay.io/venafi-gitlab-integration/codesigning-signtool:<TAG>`.
    - Select a tag based on the Venafi client tools version that you require. See [Docker images](#docker-images).
 * Set the `INPUT_PATH` variable 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 set `SIGNTOOL_PATH` to `C:\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 the [Signtool caveats](#signtool-caveats).

~~~yaml
stages:
  - build
  - sign

# Build a 'foo.exe' and pass it as an artifact to the 'sign' stage.
build_exe:
  stage: build
  image: quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64
  tags:
    - windows
  script:
    - copy C:\Windows\System32\Notepad.exe foo.exe
  artifacts:
    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: sign
  image: quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64
  tags:
    - windows
  script:
    - venafi-sign-signtool
  variables:
    TPP_AUTH_URL: https://my-tpp/vedauth
    TPP_HSM_URL: https://my-tpp/vedhsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: foo.exe
    CERTIFICATE_SUBJECT_NAME: mydomain.com
  artifacts:
    paths:
      - foo.exe
~~~

#### Shell or SSH executor

Usage instructions:

 * Define a job that calls `venafi-sign-signtool`.
 * Ensure that this job runs on a Windows-based runner, by setting the proper tags.
 * Set the `INPUT_PATH` variable 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 with `SIGNTOOL_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 the [Signtool caveats](#signtool-caveats).

~~~yaml
stages:
  - build
  - sign

# Build a 'foo.exe' and pass it as an artifact to the 'sign' stage.
build_exe:
  stage: build
  tags:
    - windows
  script:
    - copy C:\Windows\System32\Notepad.exe foo.exe
  artifacts:
    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: sign
  tags:
    - windows
  script:
    - venafi-sign-signtool
  variables:
    TPP_AUTH_URL: https://my-tpp/vedauth
    TPP_HSM_URL: https://my-tpp/vedhsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: foo.exe
    CERTIFICATE_SUBJECT_NAME: mydomain.com
  artifacts:
    paths:
      - foo.exe
~~~

#### Variables

Required:

 * `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_PASSWORD` or `TPP_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_NAME` or `CERTIFICATE_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 with `cspconfig listcertificates` and checking what comes after `CN=`.

   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://server2
    ~~~

    **Tip:** here are some public timestamping authorities that you can use:

     - http://timestamp.digicert.com
     - http://timestamp.globalsign.com
     - http://timestamp.comodoca.com/authenticode
     - http://tsa.starfieldtech.com

 * `SIGNATURE_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,sha256
    ~~~

 * `APPEND_SIGNATURES` (boolean): If the target file(s) already have signatures, then append a new signature instead of overwriting the existing signatures.

   Defaults to `false`.

 * `EXTRA_ARGS`: Specifies extra custom CLI arguments to pass to Signtool. The arguments are comma-separated.

    These arguments will be _appended_ to 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,/arg2
    ~~~

 * `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 of `venafi-sign-signtool`. So the recommended way to use this feature, is by adding an additional command — prior to the execution of `venafi-sign-signtool` — to fetch the CA certificate file and to place it at the expected location. Example:

   ~~~yaml
   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-signtool
     variables:
       TPP_AUTH_URL: https://my-tpp/vedauth
       TPP_HSM_URL: https://my-tpp/vedhsm
       TPP_USERNAME: my_username
       # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

       INPUT_PATH: foo.exe
       CERTIFICATE_SUBJECT_NAME: mydomain.com
       EXTRA_TRUSTED_TLS_CA_CERTS: C:\downloaded-ca.crt
   ~~~

 * `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.

 * `MACHINE_CONFIGURATION` (boolean): Whether to load CSP configuration from the machine registry hive instead of the user registry hive. Defaults to false.

### Verify with Signtool

This section shows how to verify one or more files with Microsoft's [Signtool](https://docs.microsoft.com/en-us/dotnet/framework/tools/signtool-exe) tool.

#### Docker executor

Usage instructions:

 * Define a job that calls `venafi-verify-signtool`.
 * Ensure that this job runs on a Windows-based runner, by setting the proper tags.
 * Ensure this job operates within the image `quay.io/venafi-integration/codesigning-signtool:<TAG>`.
    - Select a tag based on the Venafi client tools version that you require. See [Docker images](#docker-images).
 * Set the `INPUT_PATH` variable 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 set `SIGNTOOL_PATH` to `C:\winsdk\<arch>\signtool`.
 - Please read the [Signtool caveats](#signtool-caveats).

~~~yaml
stages:
  - fetch
  - verify

# Fetch a signed 'signed.exe' and pass it as an artifact to the 'verify' stage.
fetch_exe:
  stage: fetch
  image: quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64
  tags:
    - windows
  script:
    - 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: sign
  image: quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64
  tags:
    - windows
  script:
    - venafi-verify-signtool
  variables:
    TPP_AUTH_URL: https://my-tpp/vedauth
    TPP_HSM_URL: https://my-tpp/vedhsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: signed.exe
~~~

#### Shell or SSH executor

Usage instructions:

 * Define a job that calls `venafi-verify-signtool`.
 * Ensure that this job runs on a Windows-based runner, by setting the proper tags.
 * Set the `INPUT_PATH` variable 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 with `SIGNTOOL_PATH`.
 - Please read the [Signtool caveats](#signtool-caveats).

~~~yaml
stages:
  - fetch
  - verify

# Fetch a signed 'signed.exe' and pass it as an artifact to the 'verify' stage.
fetch_exe:
  stage: fetch
  tags:
    - windows
  script:
    - 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: sign
  tags:
    - windows
  script:
    - venafi-verify-signtool
  variables:
    TPP_AUTH_URL: https://my-tpp/vedauth
    TPP_HSM_URL: https://my-tpp/vedhsm
    TPP_USERNAME: my_username
    # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

    INPUT_PATH: signed.exe
~~~

#### Variables

Required:

 * `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_PASSWORD` or `TPP_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 of `venafi-verify-signtool`. So the recommended way to use this feature, is by adding an additional command — prior to the execution of `venafi-verify-signtool` — to fetch the CA certificate file and to place it at the expected location. Example:

   ~~~yaml
   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-signtool
     variables:
       TPP_AUTH_URL: https://my-tpp/vedauth
       TPP_HSM_URL: https://my-tpp/vedhsm
       TPP_USERNAME: my_username
       # TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.

       INPUT_PATH: signed.exe
       EXTRA_TRUSTED_TLS_CA_CERTS: C:\downloaded-ca.crt
   ~~~

 * `TRUSTED_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 with `cspconfig 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 images

We 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 TOOL` is either `jarsigner` or `signtool`.
 * `TAG` specifies the version components and architecture that you want to use. This is in the format of:

    - Specify the `latest-<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 using `latest`.

    - Specify `<PRODUCT VERSION>-<VENAFI CLIENT TOOLS VERSION>-<ARCHITECTURE>` as tag, if you want to have more control.

       - `PRODUCT VERSION` is the major + minor version of this Gitlab integration product. See [the releases list](https://github.com/labs/venafi-codesigning-gitlab-integration/releases) to 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 VERSION` is the version of the Venafi client tools that you wish to use, for example `22.3`.

    - `ARCHITECTURE` is the architecture of the node on which you plan to run the container. Currently, only `x86_64` is 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_64
~~~

Example: latest product version + latest Venafi client tools, for use with Signtool on x86\_64:

~~~
quay.io/venafi-gitlab-integration/codesigning-signtool:latest-x86_64
~~~

### List of published Docker image tags

You can see the available tags on Quay.io:

 * [codesigning-jarsigner](https://quay.io/repository/venafi-gitlab-integration/codesigning-jarsigner?tab=tags)
 * [codesigning-signtool](https://quay.io/repository/venafi-gitlab-integration/codesigning-signtool?tab=tags)

### Image versioning policy

 * We 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 caveats

When using Signtool, you must ensure that all your TPP environments disable the option "Include Certificate Chain". You must do this for *all* TPP 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 caveats

When using the Signtool Docker image (which is based on Windows ltsc2019) you may have to ensure that the `shell` have to be set to `powershell` in the runner configuration, because since [Gitlab Runner 14 and later](https://docs.gitlab.com/runner/shells/) the default behavior changed. The default shell is now set to `pwsh`.

The following error can occur when the shell is not set correctly.

```
FileNotFoundError: [WinError 2] The system cannot find the file specified
```

# Git caveats

When using the Signtool Docker image you may get ownership errors due to recent Git restrictions. You can solve this by adding a `pre_clone_script` and `post_clone_script` to the runner configuration that
includes the git command to configure safe directories like `git 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 at
```

## Contribution & development

See the [contribution guide](CONTRIBUTING.md).