Skip to content

Tutorial: Setting up Code Sign Manager - SaaS with a user API key

Info

If you need to configure Code Sign Manager - SaaS for a service account rather than an individual user, see the companion tutorial on using a service account.

This tutorial shows you how to configure Code Sign Manager - SaaS for an individual user, such as a developer. You will set up the required objects in Code Sign Manager - SaaS, authenticate the Code Sign Client using the user’s API key, and sign a file using a Signing Key that is generated, stored, and managed by Code Sign Manager - SaaS.

This tutorial does not cover all configuration options. Instead, it provides a simplified, end-to-end workflow that demonstrates the signing process from the perspective of an individual user.

What you'll do

This tutorial includes tasks performed by two roles:

  • Administrator — responsible for creating the objects needed for signing.
  • Authorized Signer — the user who installs the Code Sign Client and performs the signing operation on their signing workstation.

The Administrator will:

  • Set up a user to act as the Authorized Signer.
  • Create a Project.
  • Create a Signing Key and assign it to the Project.

After those tasks are complete, the Authorized Signer will:

  • Download and install the Code Sign Client on their signing workstation.
  • Authenticate the Code Sign Client using their API key.
  • Sync the Signing Key created by the Administrator.
  • Sign a file and verify the signature.

Before you begin

To complete this tutorial, you will need the following:

  • An account with administrative permissions (either the System Administrator or PKI Administrator role in Certificate Manager - SaaS).
  • A signing workstation where you can install the Code Sign Client. This can be a Windows, Linux, or macOS workstation. See system requirements.

Step 1: Set up an account for the Authorized Signer

Start here if you do not already have a user to designate as the Authorized Signer for this tutorial. If you are unsure, follow these steps to review your existing users.

  1. Sign in to Certificate Manager - SaaS.

  2. Click Settings > Users.

    Review the list of active users. If the user you want to designate as the Authorized Signer is already registered, proceed to Step 2: Create a Code Sign Project. Otherwise, follow the steps below to invite a new user.

  3. Click Invite.

  4. Copy the invitation URL and send it to the person who will be the Authorized Signer. Have that person complete the registration steps.

    Note

    By default, the new user will be given the "Guest" role. This is sufficient for a user to act as an Authorized Signer. You can learn more about roles here.

Step 2: Create a Code Sign Project

Next, you will create a Code Sign Project and assign the Authorized Signer to it.

  1. Click Configurations > Code Sign Projects.
  2. Click New.
  3. In Project name, enter Tutorial project.
  4. From Owners, select any other administrators you would like to be able to manage this Project.
  5. In Description, enter This is my tutorial project.
  6. Click Continue.
  7. From Authorized signers, select the user who will be allowed to sign using this Project.

Step 3: Create a Signing Key

You can now add a Signing Key to the Project. The Authorized Signer is allowed to use all Signing Keys associated with the Project.

  1. Click Inventory > Signing Keys.
  2. From Projects, ensure that Tutorial project is selected.
  3. Click New.
  4. In Signing key name, enter Tutorial key.
  5. In Description, enter This is my tutorial signing key.
  6. Click Continue.
  7. In Key pair properties, do the following:
    • Leave Key storage type and Key storage location as is. These are the only available options.
    • Set the validity period to 24 hours.
    • Select any Key algorithm.
  8. Click Continue.
  9. In Certificate properties, do the following:
    • Leave Certificate authority set to Built-in CA.
    • Leave Product option set to Default product.
    • For Common name, enter Tutorial, Inc.
    • All other fields are optional.
  10. Click Continue.
  11. In Cryptographic object creation, select Create cryptographic objects now, and then select Finish.

After the key and certificate are created, the details drawer for the Signing Key opens automatically.

Step 4: Download and install the Code Sign Client

With the Project and Signing Key created, the Authorized Signer can install the Code Sign Client and sync the key and certificate to the signing workstation. Steps 4–6 are performed by the Authorized Signer.

  1. Sign in to Certificate Manager - SaaS.
  2. Click Inventory > Signing Keys.
  3. Click Tutorial key.
  4. Click the Client installation tab.
  5. Select the appropriate platform, and then either download and install the client or follow the on-screen installation instructions.

Note

Additional usage instructions appear in the UI. Those instructions lead to the same outcome as steps 5 and 6 in this tutorial. This tutorial includes extra details not shown in the UI.

Step 5: Sync key and certificate to the signing workstation

With the Code Sign Client installed, you are ready to sign in and sync the keys and certificates that your administrator created.

First, the Authorized Signer must obtain their API key. Follow these steps if you do not already have it:

  1. Sign in to Certificate Manager - SaaS.
  2. Select your avatar in the top-right corner, and then click Preferences.

  3. From API keys, copy your API key.

    Note

    If you do not have an API key yet, select Generate at the bottom of the screen.

  4. On your signing workstation, open a terminal.

  5. Run the following to sign in using the Code Sign Client:

    pkcs11config login
    This launches the interactive configuration wizard.

    1. Enter the hostname of the Code Sign Manager server for your region.
    2. When prompted for an authentication method, select API key.
    3. Enter your API key.

  6. (Optional) Verify your configuration.

    pkcs11config option show

    Your result should look similar to the following: 

    Name             │ Value
─────────────────┼───────────────────────────────────────────────────
HSM SERVER URL   │ https://api.venafi.cloud/vedhsm/
SUPPORTS API KEY │ true
AUTH SERVER URL  │ https://api.venafi.cloud/
API KEY          │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CSC SERVER URL   │ https://dl.venafi.cloud/cyberark-code-sign-client/

  7. List your keys and certificates: 

    pkcs11config list

    Your result should look similar to the following: 

    Certificate 1:
Label:       Tutorial project-Tutorial key
Subject:     CN=Tutorial\, Inc
ID:          34353563356132632D333634392D343065652D616261302D306132623436326632333466
Environment: Certificate

Public Key 1:
Label:       Tutorial project-Tutorial key
Key-Type:    RSA 2048
ID:          34353563356132632D333634392D343065652D616261302D306132623436326632333466
Environment: Certificate
    If you do not see any objects, confirm that you are assigned as an Authorized Signer on the Project.

Step 6: Sign a file and verify the signature

With your Signing Key now synced, you can use the key to sign. In these next steps, we'll use the Code Sign Client's built-in sign and verify utilities.

  1. In a temporary location on your filesystem, create a new file called signme.txt. This is the file we'll sign. 
    echo "This is my test file" > signme.txt

  2. Sign the file using Code Sign Manager - SaaS using the interactive signing wizard. 

    pkcs11config sign

    1. From File to sign, arrow down to the signme.txt file you created in the previous step. Press Enter twice.
    2. In File to store signature, type signme.txt.sig. Press Enter.
    3. From Signing key label, arrow down to the Signing Key to sign with. If you've followed the steps in this tutorial, the label value will be Tutorial project-Tutorial key. Press Enter twice.

    After these steps, you will see a success message similar to SUCCESS: Signed file 'signme.txt', signature written to 'signme.txt.sig'.

    Note

    You can avoid the interactive wizard by just entering the command options directly. Here is the command for the wizard you just ran:

    pkcs11config sign --filename signme.txt --label "Tutorial project-Tutorial key" --output signme.txt.sig

  3. Verify the signature. This time we'll enter all the command options directly rather than using the interactive wizard. If you'd prefer to use the wizard, just run pkcs11config verify. 

    pkcs11config verify --filename signme.txt --label "Tutorial project-Tutorial key" --output signme.txt.sig

Step 7: View signing statistics and event Event Log

Now that the key has been used, you will see its usage appear in usage counts and in the event log.

If you return to the Signing Keys page in Certificate Manager - SaaS, you will now see that this key has been used.

Administrators can open the Event Log by selecting Settings > Event Log and filtering for Signing succeeded events.

Conclusion

You have now successfully signed a file using Code Sign Manager - SaaS. The private key used to sign the file was generated and stored securely on a remote HSM and never had to be on the signing workstation itself.

What's next

  • If you are done with the tutorial key, sign in again to Certificate Manager - SaaS, go to the Signing Keys page, and either disable or delete that key. If you want other Authorized Signers to complete this tutorial, delete both the tutorial Signing Key and Project.
  • Continue creating Projects and Signing Keys as needed for your use cases.
  • Review the CLI documentation for details about all available options.
  • Explore sample integrations with common code signing applications.