Deploy Files v2

The file distribution plugin executes files or downloads them to a specific location. The Policy Server communicates with the agent to distribute, execute, and install files on endpoints.

• Distribute necessary files to endpoints
• Install uninstalled software on endpoints

File Distribution v2 plugin has been added, focusing on strengthening security from the existing file distribution plugin.

File Distribution v2 plugin provides file integrity verification and distributor identity confirmation for secure file distribution.

• Performs 3-step integrity verification
• Distributor identification and approval by end-user

The File Distribution v2 plugin mandatorily requires digital signatures for files being distributed and uses the Sigstore Signing method, designed for supply chain security, for digital signatures and signature verification. The File Distribution v2 plugin can selectively use two methods of Sigstore Signing: Sigstore Keyless Signing and Public Key Signing.

• Tools and Services for Digital Signature and Digital Signature Verification (Sigstore)

Verification Method	Sigstore Keyless Signing (Keyless)	Public Key Signing (self-managed-key)
Verification Content	Performs digital signature on distribution files with identity information by authenticating with OIDC (OpenID Connect) from Google/Github/MS Endpoints receiving the file verify that it is a Sigstore-signed file using User ID (e.g., Google ID) and OIDC (Google Account) information	Performs digital signature on distribution files using self-owned private/public keys Certificates (public keys) for verification are distributed upon Node Action reception
Environment Setup	Usable only in environments with Internet access	Usable in both Internet and isolated network environments
Key Management	Requires only security for administrator accounts, as no separate keys are used	Requires secure storage of separate private keys
Preparations	Cosign binary file required for digital signing of distribution files (Download cosign-windows-amd64.exe from Assets at Sigstore GitHub Release v2.1.1 download) External internet communication required for digital signing/signature verification of distribution files (Signing PC, Policy Server, User Endpoint) OIDC (Google, Git, MS) accounts required for digital signing of distribution files	Cosign binary file required for digital signing of distribution files Keys required for digital signing of distribution files, can be generated using cosign or prepared separately
Constraints	Cannot change from the initially registered distributor to another distributor	Cannot change from the initially registered distributor to another distributor Key files used for digital signing of distribution files must be managed separately (e.g., USB)

Sigstore Keyless Signing Method

Sigstore generates short-lived certificates using OpenID Connect (OIDC).

These certificates are used to sign software, and the signed software can be publicly verified via cosign.

OIDC is an extension of OAuth 2.0, a framework that uses login authentication to provide users access to resources. Because OIDC can generate certificates without requiring user passwords, it is used by Sigstore to generate short-lived certificates.

How to Use Sigstore Keyless Signing

Step1. Digital Signature of Distribution File

1. Download cosign and save it to the directory to be used for digital signing of the distribution file.

2. Change the file name to cosign.exe.

3. Copy the file to be digitally signed to the directory.

4. Go to the directory where cosign.exe is located by entering cmd in Start > Run and executing it.

5. Perform digital signing by entering the command below:

   > cosign.exe sign-blob {Distribution_File_Name} --output-certificate {Generated_Cert_File_Name.cert} --output-signature {Generated_Signature_File_Name.sig}
   

6. Copy the URL information displayed in the cmd window and access the web page using a browser.

7. Confirm that the 8-character value displayed in the cmd window is the same as the 8-character value displayed in the cmd window and click the Submit button.

8. Select one of the three OIDCs: Git, Google, Microsoft and perform authentication.

9. After a moment, enter y in the cmd window to agree to the terms of service.

10. Confirm that Cert, Sig files have been successfully generated in the directory.

Step2. Verify Digital Signature

1. In the Start window, enter the command below:

   > cosign.exe verify-blob {Distribution_File_Name} --certificate {Generated_Cert_File_Name.cert} --signature {Generated_Signature_File_Name.sig} --certificate-identity={ID_Used_for_Auth} --certificate-oidc-issuer={OIDC_Issuer}
   Example> cosign.exe verify-blob agent.zip --certificate agent.cert --signature agent.sig --certificate-identity=genian@genians.com --certificate-oidc-issuer=https://accounts.google.com
   

2. If the digital signature is performed successfully, Verified OK will be displayed.

Step3. Create Node Action

1. Access the Policy Server Web Console and go to Policy in the top menu.
2. Go to Node Policy > Node Action in the left menu.
3. Click Select Action > Create in the top menu.

Below are Basic Settings.

4. For Action Name, use the format "(Purpose)Action Name" according to its purpose for easy distinction of node actions during future operation.
5. Description can be used to distinguish the purpose of the node action if it is used differently depending on the purpose.
6. Adding a Label allows you to classify the plugin with a custom label displayed in the "Description" input field.

Configure the Action Execution Settings below.

7. For OS Type, select the appropriate OS among macOS, Linux, and Windows targets.

8. Condition Settings are generally used to distribute files to users meeting specific conditions.

   Example: If you distribute using the condition "if c:\%ProgramFiles%\abc.exe does not exist", distribution is only possible to endpoints where abc.exe does not exist.
   

9. In Plugin Selection, select File Distribution V2.

10. For Distribution File, click the Upload button to select the file.

11. For Distribution File Verification Method, select Sigstore Keyless Signing.

12. For Trusted OIDC Issuer, select the OIDC (Github, Google, Microsoft) used for authentication during digital signing.

13. For Trusted ID, enter the ID (email address format) used for authentication during digital signing.

14. For Certificate, click the Read File button on the right to add the cert file generated during digital signing.

15. For Signature, click the Read File button on the right to add the sig file generated during digital signing.

16. For Distribution Options, configure the distribution method.

• Execute File: If it's a compressed file, configure the file to execute in "File Path", and set "Execution Options" and "Execution Account" to execute the file. Set reboot preference after file execution via "Reboot Option".
• Download: Specify the file and folder path on the endpoint where the distribution file will be copied.

17. Click the Modify button.
18. Go to Node Policy in the left Policy menu, then click Default Policy.
19. Find Node Action Settings and click the Assign button.
20. In the Available items, find File Distribution and drag it to the Selected items.
21. Click the Modify button, then click the Modify button again.

Note

For Sigstore Keyless Signing method, external communication is essential for digital signing/signature verification, and communication to the domains below must be allowed.

(Source: Policy Server, Agent), (Service Port: TCP/443)

rekor.sigstore.dev : Ledger recording system

oauth2.sigstore.dev : Sigstore oauth flow provisioning server

accounts.google.com : OIDC provider (If it's another OIDC, use that OIDC domain)

fulcio.sigstore.dev : sigstore CA server

tuf-repo-cdn.sigstore.dev : SLSA verification

Public Key Signing Method

Sigstore cosign also provides a self-managed key digital signing method.

The Public Key Signing method involves directly generating a key for digital signing or using a separately created key that is already in use.

How to Use Public Key Signing

Step1. Digital Signature of Distribution File

1. Perform steps 1-4 of Step 1 in Sigstore Keyless Signing method, then proceed.

2. If you do not have a separate key for digital signing, enter the command below to generate a private key and public key for digital signing.

   > cosign.exe generate-key-pair
   > Enter private key password
   > Confirm private key password
   > Enter dir to confirm that private key (key) file and public key (pub) file have been generated.
   

3. If you have generated a key, perform digital signing on the distribution file using the generated key as follows:

   > cosign.exe sign-blob {Distribution_File_Name} --key cosign.key --tlog-upload=false --output-signature {Generated_Signature_File_Name.sig}
   Example> cosign.exe sign-blob agent.zip --key cosign.key --tlog-upload=false --output-signature agent.sig
   

Step2. Verify Digital Signature

1. In the CMD window, enter the command below:

   > cosign.exe verify-blob {Distribution_File_Name} --key {Public_Key_File_Name.pub} --signature {Generated_Signature_File_Name.sig} --insecure-ignore-tlog=true --insecure-ignore-sct=true
   Example> cosign.exe verify-blob agent.zip --key cosign.pub --signature agent.sig --insecure-ignore-tlog=true --insecure-ignore-sct=true
   

2. If the digital signature is performed successfully, Verified OK will be displayed.

Step3. Create Node Action

1. Perform steps 1-10 of Step 3 in Sigstore Keyless Signing method, then proceed.
2. For Distribution File Verification Method, select Public Key Signing.
3. For Trusted Public Key, click the Read File button on the right to add the pub file that was generated during key creation.
4. For Signature, click the Read File button on the right to add the sig file that was generated during digital signing.
5. Perform steps 16-21 of Step 3 in Sigstore Keyless Signing method.

Danger

It is impossible to change the initially set distribution method and distributor, so the Private key used during the initial node action creation must be kept securely to prevent loss.

Registered distributor information can be confirmed in Web Console Settings > Preferences > Agent > Distribution Options section.

Yubikey Personal Key Management Method

While managing private keys with the Public Key method, there are many cases of key loss due to formatting of the managed PC, etc. Furthermore, storing private keys on external tokens provides physical separation, protecting them from hacking or malicious software. For these reasons, it is recommended to securely manage private keys using an external token (YubiKey).

The cosign piv-tool command provides utilities for managing hardware tokens.

Step1. Yubikey Initialization

Model used in this introduction : yubikey 5 nfc

> cosign piv-tool reset

Danger

This command initializes the hardware token, so if there are any existing certificates stored on the Yubikey, they will be deleted.

Step2. PIN Configuration

• After initialization, the default PIN is 123456

• Below is an example where the PIN is defined as ‘111222’.

  > cosign piv-tool set-pin --new-pin=111222
  ? pin. This will overwrite the previous pin.: y
  Setting new pin. This will overwrite the previous pin.: y
  

• To change the PIN when it is already defined, execute the command as follows:

  > cosign piv-tool set-pin --old-pin=111222 --new-pin=232323
  ? pin. This will overwrite the previous pin.: y
  Setting new pin. This will overwrite the previous pin.: y323
  

• The PIN changes from ‘111222’ to ‘232323’.

Step3. Certificate Generation

• Generate a certificate on the Yubikey.

  > cosign piv-tool generate-key --random-management-key
  

Step4. Verify Registered Key

• Outputs the certificate information stored on the Yubikey.

  > cosign piv-tool attestation
  

Step5. Extract Public Key

• As explained above, target file, public key, and signature are required for digital signature verification.

• You can export the Yubikey public key to a file using the following command. A publickey.pub file will be generated.

  > cosign.exe public-key —sk > publickey.pub
  

Step6. Code Signing (Signature Generation)

• This is similar to the cosign.exe sign-blob command in Public Key Signing Method - Step1. Digital Signature of Distribution File, but with the difference of using a smart card token.

• Since piv is connected, in this command, the --key option is omitted, and code signing is attempted.

  > cosign.exe sign-blob {Distribution_File_Name} --tlog-upload=false --output-signature {Generated_Signature_File_Name.sig}
  Example> cosign.exe sign-blob agent.zip --tlog-upload=false --output-signature agent.sig
  > Enter registered PIN
  > Perform physical touch on Yubikey
  

Step7. Integrity Verification

• Perform identically to Public Key Signing Method - Step2. Verify Digital Signature.