jotools/codesign repository overview

⁠Azure Artifact Signing

⁠Configuration

Create the following two .json files on your host machine:

azure.json

{
  "TenantId": "[Azure Tenant Id]",
  "ClientId": "[Azure Client Id]",
  "ClientSecret": "[Azure Client Secret]"
}

acs.json

{
  "Endpoint": "https://weu.codesigning.azure.net",
  "CodeSigningAccountName": "[ACS Code Signing Account Name]",
  "CertificateProfileName": "[ACS Certificate Profile Name]"
}

And mount them into the following location when running the Docker Container:

/etc/aas-codesign/azure.json
/etc/aas-codesign/acs.json

Instead of mounting the two .json files, you can also provide the configuration via Environment Variables:

AZURE_TENANT_ID=[Azure Tenant Id]
AZURE_CLIENT_ID=[Azure Client Id]
AZURE_CLIENT_SECRET=[Azure Client Secret]
ACS_ENDPOINT=https://weu.codesigning.azure.net
ACS_ACCOUNT_NAME=[ACS Code Signing Account Name]
ACS_CERTIFICATE_PROFILE_NAME=[ACS Certificate Profile Name]

⁠Timestamp Server

The Timestamp Server will be automatically chosen by jsign.
To change it you can set the Environment Variables:

TIMESTAMP_SERVER=http://timestamp.domain.org
TIMESTAMP_MODE=[RFC3161|Authenticode]

⁠Codesign certificate .pfx

⁠Configuration

Create the following .json file on your host machine:

pfx.json

{
  "Password": "pfx-password",
  "TimestampServer": "http://timestamp.digicert.com",
  "TimestampMode": "Authenticode"
}

Have your codesign certificate certificate.pfx located on your host machine.

Mount them into the following location when running the Docker Container:

/etc/pfx-codesign/pfx.json
/etc/pfx-codesign/certificate.pfx (Note: always required)

Instead of mounting the .json file, you can also provide the configuration via Environment Variable:

PFX_PASSWORD=[PFX Password]
TIMESTAMP_SERVER=http://timestamp.domain.org
TIMESTAMP_MODE=[RFC3161|Authenticode]

⁠Code Signing using aas-codesign.sh

The included Shell Script aas-codesign.sh is a helper script which will

• pick up the configuration from Environment Variables or the mounted .json files
• perform the Windows Code Signing using Azure Artifact Signing⁠ with jsign⁠

⁠Example: Docker Run - CodeSign

The following example will

• run the Docker Image jotools/codesign⁠
• use configuration from .json files stored on the host machine
• mount a folder on the host machine into /data
• use entry point aas-codesign.sh
• codesign all .exe's and .dll's in /data (recursively)

docker run \
    --rm \
    -v /local/path/to/acs.json:/etc/aas-codesign/acs.json \
    -v /local/path/to/azure.json:/etc/aas-codesign/azure.json \
    -v /local/path/to/build-folder:/data \
    -w /data \
    --entrypoint aas-codesign.sh \
    jotools/codesign \
    "./**/*.exe" "./**/*.dll"

The same example, but

• use a different Timestamp Server (set via Environment Variable)

docker run \
    --rm \
    -e TIMESTAMP_SERVER=http://timestamp.digicert.com \
    -v /local/path/to/acs.json:/etc/aas-codesign/acs.json \
    -v /local/path/to/azure.json:/etc/aas-codesign/azure.json \
    -v /local/path/to/build-folder:/data \
    -w /data \
    --entrypoint aas-codesign.sh \
    jotools/codesign \
    "./**/*.exe" "./**/*.dll"

⁠Example: Docker Container Shell

The following example will

• use Environment Variables to setup the configuration
• mount a folder on the host machine into /data
• run the Docker Container interactively (removing it after)
  • use entry point sh
  • you then can manually sign files, e.g.:
    aas-codesign.sh "./**/*.exe" "./**/*.dll"
aas-codesign.sh myapp.exe mylib.dll

docker run \
    --rm \
    -it \
    --entrypoint sh \
    -e AZURE_TENANT_ID="MY_AZURE_TENANT_ID" \
    -e AZURE_CLIENT_ID="MY_AZURE_CLIENT_ID" \
    -e AZURE_CLIENT_SECRET="MY_AZURE_CLIENT_SECRET" \
    -e ACS_ENDPOINT=https://weu.codesigning.azure.net \
    -e ACS_ACCOUNT_NAME="ACS Code Signing Account Name" \
    -e ACS_CERTIFICATE_PROFILE_NAME="ACS Certificate Profile Name" \
    -v /local/path/to/build-folder:/data \
    jotools/codesign

The following example will

• use the locally stored configuration files acs.json and azure.json
• mount a folder on the host machine into /data
• run the Docker Container interactively (removing it after)
  • use entry point sh
  • you then can manually sign files, e.g.:
    aas-codesign.sh "./**/*.exe" "./**/*.dll"
aas-codesign.sh myapp.exe mylib.dll

docker run \
    --rm \
    -it \
    --entrypoint sh \
    -v /local/path/to/acs.json:/etc/aas-codesign/acs.json \
    -v /local/path/to/azure.json:/etc/aas-codesign/azure.json \
    -v /local/path/to/build-folder:/data \
    jotools/codesign

⁠Code Signing using pfx-codesign.sh

The included Shell Script pfx-codesign.sh is a helper script which will

• pick up the configuration from Environment Variables or the mounted .json file
• perform the Windows Code Signing with jsign⁠

⁠Example: Docker Run - CodeSign

The following example will

• run the Docker Image jotools/codesign⁠
• use configuration from .json file stored on the host machine
• use codesign certificate .pfx stored on the host machine
• mount a folder on the host machine into /data
• use entry point pfx-codesign.sh
• codesign all .exe's and .dll's in /data (recursively)

docker run \
    --rm \
    -v /local/path/to/pfx.json:/etc/pfx-codesign/pfx.json \
    -v /local/path/to/my-certificate.pfx:/etc/pfx-codesign/certificate.pfx \
    -v /local/path/to/build-folder:/data \
    -w /data \
    --entrypoint pfx-codesign.sh \
    jotools/codesign \
    "./**/*.exe" "./**/*.dll"

⁠Example: Docker Container Shell

The following example will

• use the locally stored configuration file pfx.json
• use codesign certificate .pfx stored on the host machine
• mount a folder on the host machine into /data
• run the Docker Container interactively (removing it after)
  • use entry point sh
  • you then can manually sign files, e.g.:
    pfx-codesign.sh "./**/*.exe" "./**/*.dll"
pfx-codesign.sh myapp.exe mylib.dll

docker run \
    --rm \
    -it \
    --entrypoint sh \
    -v /local/path/to/pfx.json:/etc/pfx-codesign/pfx.json \
    -v /local/path/to/my-certificate.pfx:/etc/pfx-codesign/certificate.pfx \
    -v /local/path/to/build-folder:/data \
    jotools/codesign

Storing secrets in plaintext files poses significant security risks, including:

• Exposure to unauthorized users if file permissions are not properly set.
• Inclusion in backups or version control (e.g., Git), leading to unintentional leaks.
• Easy access for malware or attackers on a compromised system.

Instead of storing secrets in a .json configuration file, consider these more secure approaches:

1. Use OS-Level Secret Storage

   • macOS: Store secrets in Keychain Access and retrieve them using the security CLI tool.
   • Linux: Use GNOME Keyring or KWallet to securely store and retrieve secrets.
   • Windows: Store credentials in Windows Credential Manager and access them via PowerShell.

2. Use a Secrets Manager

   • Cloud providers like AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager offer secure, centralized secret storage with access control.
   • Local alternatives like 1Password CLI, Bitwarden CLI, or HashiCorp Vault allow secure retrieval of secrets at runtime.

3. Use GitHub Actions Secrets (for CI/CD Pipelines)

• If using this Docker Container in GitHub Actions, store secrets securely in GitHub Secrets.
• Reference secrets in workflows using ${{ secrets.MY_SECRET }} instead of storing them in the repository.