Skip to main content

Sign binary commands

Learn how to use SMCTL commands to manage signatures (sign, verify signature, remove signature), using flags to define the command parameters.

For signing, we offer traditional tool-based signing and simple signing.

참고

Simple signing is a new feature. We're working to expand its capabilities, including adding supported file types and metadata capturing.

Traditional signing and simple signing

Traditional signing

Pros

Cons

  • Requires the use of established third-party signing tools and libraries, such as signtool,jarsigner, and osslsigncode.

  • May require DigiCert-specific components, such as KSP or PKCS11 modules.

  • Doesn't support bulk signing

Simple signing

Pros

Cons

  • Uses the --simple flag to sign without the need of third-party tools, extra libraries, or external signing infrastructure.

  • Uses the --unsigned to ensure that only unsigned files are signed, preventing unintended re-signing.

  • Supports bulk signing. To learn more, see Bulk signing.

  • Fewer file types are supported

  • Metadata data collection (timestamp, tool, checksums) isn't supported

Prerequisites

For traditional signing:

  • Tools used for signing must be present in the path variable of the operating system

  • A PKCS11 config file is mandatory for jarsigner, apksigner, and jSign.

  • Specify either a key pair alias (--keypair-alias) or a certificate fingerprint (--fingerprint) for signing.

For simple signing:

  • SMCTL

  • Access to signing key pairs

Configuration

For traditional signing:

  • Default tool selection: SMCTL selects the signing tool automatically based on your operating system.

  • Signature algorithm: Use the --sigalg string flag to specify the signature algorithm, depending on what the selected tool supports.

  • Digest algorithm: Use the the <--digalg string> flag to specify the digest algorithm, also based on the supported options of the tool.

  • Sign specific file: Use the <--tool string> flag to sign a specific file type.

    • For example, --tool apksigner signs only .apk files.

  • APK signer support: The minimum SDK version supported for apksigner is 18.

For simple signing:

  • No tool selection required: SMCTL handles the signing directly. You don't need to install or reference third-party tools.

  • No DigiCert libraries required: DigiCert KSP, PKCS11, or other local libraries aren't needed; only SMCTL is required.

Sign commands

Review the following two ways to begin a sign command:

smctl signature <keypair alias>

or

smctl sign <keypair alias >

Flags for simple signing

Review the following flags that can be used with the sign command for simple signing:

표 1. Flags for simple signing

Flag

Description

--simple

This flag signs without the need of third-party signing tools and libraries and only applies to simplified signing workflows.

--unsigned

This flag only signs unsigned files and only applies to simplified signing workflows.


Flags for traditional signing

Review the following flags that can be used with the sign command for simple signing:

표 2. Flags for traditional signing

Flag

Description

--all-metadata

Capture all signature metadata. Default is to capture all metadata.

--certificate string

Provide the path of the certificate to be used for signing. 

Format:

--certificate="<value>"

--checksum-after-signing

Capture the checksum in the signature metadata after signing the file. Leave blank to capture by default.

--checksum-before-signing

Capture the checksum in the signature metadata before signing the file. Leave blank to capture by default.

--config-file string

Provide the path to the PKCS11 config file. 

Format:

--config-file="<value>"

--deep

Sign all internal frameworks and plugins (This flag only applies to Apple codesign) (default true)

참고

This flag only applies to Apple codesign commands.

  • --digalg string

  • -d (shortcut)

Specify the digest algorithm to use for signing (default based on the tool used for signing).

Format:

--digalg="<value>"

--digest-algorithm

Capture the digest algorithm in the signature metadata. Leave blank to capture by default.

--digicert-ctk-app-path string

Provide the path to DigiCert SSM Signing Clients.app.

참고

This flag only applies to Apple codesign and productsign commands.

--digicert-ctk-cli-path string

Provide the path to DigiCert SSM Signing Clients.app's CLI.

참고

This flag only applies to Apple codesign and productsign commands.

--dryrun

Verify if the file can be signed without actually signing it (This flag only applies to Apple codesign)

--entitlements-file-path

Specify the entitlements file path.

참고

This flag only applies to Apple codesign commands.

--exit-non-zero-on-fail

Returns a non-zero status if any file within a folder or directory fails to be signed.

--failfast

Stops signing a folder or directory immediately upon encountering the first file that can't be signed.

--file-location

Capture the file location in the signature metadata. Leave blank to capture by default.

--file-name

Capture the file name in the signature metadata. Leave blank to capture by default.

  • --fingerprint string

  • -f (shortcut)

Provide the fingerprint of the certificate to be used for signing. 

Format:

--fingerprint="<value>"

참고

For Apple codesign and productsign, after the key is added to the token.

--force

Replace existing signatures (default value 'true').

참고

This flag only applies to Apple codesign commands.

--identity string

Specify the apple developer or installer certificate that you'll use to sign with. This information can be found using a security export-smartcard.

참고

This flag only applies to Apple codesign commands, after the key is added to the token.

  • --input string

  • -i (shortcut)

Provide the path to the file or folder to be signed. If you specify a folder, all files inside the folder will be signed. 

Format:

--input="<value>"

--keychain-path string

Provide the path to Keychain (This flag only applies to Apple productsign)

  • --keypair-alias string

  • -k (shortcut)

Keypair alias to be used for signing. 

Format:

--keypair-alias="<value>"

--output-file

Signed package file (should be different than input file)

참고

This flag is compulsory for Apple productsign.

--openssl-pkcs11-engine string

Provide the path to the OpenSSL PKCS11 engine.

참고

This flag only applies to osslsigncode.

--pkcs11-module string

Provide the absolute path to the DigiCert​​®​​ Software Trust Manager PKCS11 library.

--preserve-metadata

Preserve the metadata.

참고

This flag only applies to Apple codesign commands.

  • --sigalg string

  • -s (shortcut)

Signature algorithm to use (default based on the tool used for signing). 

Format:

--sigalg="<value>"

--signing-tool

Capture the signing tool in the signature metadata. Leave blank to capture by default.

--timestamp

Use this flag to enable or disable timestamping for your signature. The syntax is --timestamp=false to disable timestamping. By default, the timestamp is enabled (TRUE).

--timestamp-flag

Capture the timestamp in the signature metadata. Leave blank to capture by default.

  • --tool string

  • -t (shortcut)

Specify the tool to use for signing (leave it blank to sign with the default signing tool based on the file extension).

Format:

--tool="<value>"

--tsa-url

Capture the timestamp (TSA) URL in the signature metadata. Leave blank to capture by default.

  • --verbose

  • -v (shortcut)

Verbose logging for signing.

  • --help

  • -h (shortcut)

Help for signing.


Subcommands for traditional signing

The sign command supports the following subcommands:

smctl signature <subcommand>

or

smctl sign <subcommand>

표 3. Subcommands for managing signatures

Subcommand

Description

remove

Remove signature

verify

Verify signed binary.

sign-hash

Sign hashes.

verify-hash

Verify hashes.

in-toto

Sign and verify JSON SBOMs using in-toto functionality.


Sample commands

Review the following sample command for traditional signing:

smctl sign MyKeyAlias --input="MyApp.exe" --tool=signtool --certificate="path/to/cert.pem" --config-file="path/to/pkcs11.cfg" --sigalg="SHA256" --digalg="SHA256" --all-metadata --timestamp --verbose

Review the following sample command for simple signing:

smctl sign MyKeyAlias --input="MyApp.exe" --simple --sigalg="SHA256" --digalg="SHA256" --verbose

작은 정보

Bulk signing

Bulk signing allows you to submit a batch of files to be signed simultaneously. If you are attempting to sign a large sets of files, this feature reduces signing time and improves efficiency. For more information, refer to Bulk signing.

Dynamic authentication behavior for signing

Dynamic authentication behaves differently depending on the signing method used.

Simple and bulk signing with SMCTL only

When using the --simple signing approach, all signing operations are performed directly by SMCTL. In this scenario, dynamic authentication works as expected when the --dynamic-auth flag is provided.

Example command

smctl sign --keypair-alias <aliasname> --input <file_or_folder> --simple --dynamic-auth

작은 정보

This works for both simple and bulk signing because the --simple option does not rely on third party signing tools.

Signing with third party tools

When signing without the --simple flag, SMCTL delegates the signing operation to third party tools such as signtool or jarsigner. These tools rely on Software Trust Manager libraries such as KSP or PKCS#11.

Command example

smctl sign --keypair-alias <aliasname> --input <file_or_folder> --dynamic-auth

작은 정보

Providing the --dynamic-auth flag alone is not sufficient. The signing operation will fail because the dynamic authentication setting is not automatically passed to the underlying libraries.

Required environment variable for third party signing

To enable dynamic authentication when using third party signing tools, you must set the following environment variable command before running the signing command:

This environment variable allows the libraries used by tools like KSP and PKCS#11 to participate in the dynamic authentication flow.

작은 정보

Once this environment variable is set, the signing command will work as expected with dynamic authentication enabled.

이 섹션의 내용: