.. _linux-deploy-files2: Deploy Files v2 ===================== .. note:: The file distribution plugin is not included in the CC evaluation items, so public institutions requiring CC certification cannot use this plugin. 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 Deploy Files v2 plugin has been added, focusing on strengthening security from the existing file distribution plugin. Deploy Files 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 Deploy Files 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. Deploy Files v2 plugin can selectively use two methods of Sigstore Signing: Sigstore Keyless Signing and Public Key Signing. .. toctree:: :maxdepth: 1 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 | - Performs digital signature on distribution files using self-owned private/public keys | | | - Endpoints receiving the file verify that it is a Sigstore-signed file using User ID (e.g., Google ID) and OIDC (Google Account) information | - 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`_) | - Cosign binary file required for digital signing of distribution files | | | - External internet communication required for digital signing/signature verification of distribution files (Signing PC, Policy Server, User Endpoint) | - Keys required for digital signing of distribution files, can be generated using cosign or prepared separately | | | - OIDC (Google, Git, MS) accounts required for digital signing of distribution files | | +----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+ | 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. 3. Copy the file to be digitally signed to the directory. 4. Open a terminal and go to the directory where the cosign file is located. 5. Perform digital signing by entering the command below: .. code-block:: bash > cosign 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 terminal and access the web page using a browser. 7. Confirm that the 8-character value displayed in the terminal is the same as the 8-character value displayed in the terminal 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 terminal 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 terminal, enter the command below: .. code-block:: bash > cosign 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 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. .. code-block:: bash Example: "if c:\%ProgramFiles%\abc.exe does not exist" condition means distribution is only possible to endpoints where abc.exe does not exist. 9. In **Plugin Selection**, select **Deploy Files 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 **Deploy Files** and drag it to the **Selected** items. 21. Click the **Modify** button, then click the **Modify** button again. .. _linux-deploy-files2-domain: .. 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. .. code-block:: bash > cosign generate-key-pair > Enter private key password > Confirm private key password > Enter ls 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: .. code-block:: bash > cosign sign-blob {Distribution_File_Name} --key cosign.key --tlog-upload=false --output-signature {Generated_Signature_File_Name.sig} Example> cosign sign-blob agent.zip --key cosign.key --tlog-upload=false --output-signature agent.sig **Step2. Verify Digital Signature** 1. In the terminal, enter the command below: .. code-block:: bash > cosign 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 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. .. _download: https://github.com/sigstore/cosign/releases/