Order code signing certificate

• Code Signing: code_signing
• EV Code Signing: code_signing_ev

Code Signing and EV Code Signing provisioning methods

When creating a code signing certificate order, you choose how to generate and store the private key by specifying a provisioning method (cs_provisioning_method) in your request.

CertCentral supports these provisioning methods:

• DigiCert-provided hardware token
• Use existing token
• Install on HSM
• DigiCert KeyLocker

DigiCert-provided hardware token (ship_token)

DigiCert ships you a hardware token with instructions to activate your certificate (see Set Up Your DigiCert Provided eToken). To provide your shipping address, use the ship_info object. Otherwise, DigiCert uses the default shipping address from your CertCentral account settings.

When you receive your token, use the DigiCert Hardware Certificate Installer (DHCI) to install the certificate. To get the initialization code for the order to use with DHCI, check the value of the hardware_init_code parameter on the Order info API response.

Use existing token (client_app)

Install the certificate on a supported secure token you already own. To identify your device, use the certificate.server_platform object.

When your certificate is issued, use DHCI to install the certificate. To get the initialization code for the order to use with DHCI, check the value of the hardware_init_code parameter on the Order info API response.

Install on an HSM (email)

DigiCert sends you the certificate to install on your own Common Criteria EAL4+ standard or FIPS 140-2 level 2 HSM. A csr is required when using this provisioning method. If you don’t have a compatible HSM, use a different provisioning method.

When using the email provisioning method, DigiCert sends the certificate requestor an agreement email. This email is to ensure that the private key is stored on an HSM that is certified as FIPS 140 Level 2, Common Criteria EAL 4+, or equivalent. DigiCert only issues the certificate after the requestor agrees to the private key protection requirement.

DigiCert KeyLocker (keylocker)

Use DigiCert KeyLocker to generate and store your private key. DigiCert KeyLocker is a cloud‐based solution that provides FIPS 140-2 level 2 compliant private key generation and storage for your code signing certificates. [Learn more about DigiCert KeyLocker](http://If you don’t have a compatible HSM, select a different provisioning method. ).

When using keylocker as the provisioning method, you still use CertCentral to complete validation and manage your order. When your certificate is issued, it is available in the DigiCert KeyLocker account linked to your CertCentral account. To use the certificate to sign code, you must have access to DigiCert KeyLocker.

• I don’t have access to DigiCert KeyLocker The first time DigiCert receives a request from your CertCentral account to create a code signing certificate order with keylocker as the provisioning method, your primary CertCentral account administrator receives an email with instructions to set up DigiCert KeyLocker. To get access to the DigiCert KeyLocker UI and client tools, contact the primary administrator in your CertCentral account.

  Tip

  For account administrators: Learn how to create a DigiCert KeyLocker user.
• I have access to DigiCert KeyLocker When issued, your certificate is available in your DigiCert KeyLocker account. You can immediately begin using the DigiCert KeyLocker client tools to sign code.

Example requests and responses

• Preconfigured hardware token (ship_token)
• Use existing token (client_app)
• Install on HSM (email)
• DigiCert KeyLocker (keylocker)

curl --request POST 'https://www.digicert.com/services/v2/order/certificate/{{code_signing_certificate_id}}' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "signature_hash": "sha256"
  },
  "order_validity": {
    "years": 1
  },
  "organization": {
    "id": 12345,
    "contacts": [
      {
        "contact_type": "verified_contact",
        "user_id": 12345
      }
    ]
  },
  "skip_approval": true,
  "cs_provisioning_method": "ship_token",
  "ship_info": {
    "name": "John Doe",
    "addr1": "360 Taylor Street",
    "addr2": "Floor 74",
    "city": "Richmond",
    "state": "va",
    "zip": "69662",
    "country": "us",
    "method": "EXPEDITED"
  }
}'

curl --request POST 'https://www.digicert.com/services/v2/order/certificate/{{code_signing_certificate_id}}' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "signature_hash": "sha256",
    "server_platform": {
      "id": 23
    }
  },
  "order_validity": {
    "years": 1
  },
  "organization": {
    "id": 12345,
    "contacts": [
      {
        "contact_type": "verified_contact",
        "user_id": 12345
      }
    ]
  },
  "skip_approval": true,
  "cs_provisioning_method": "client_app"
}'

curl --request POST 'https://www.digicert.com/services/v2/order/certificate/{{code_signing_certificate_id}}' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "signature_hash": "sha256",
    "csr": "<csr>",
    "server_platform": {
      "id": -1
    }
  },
  "order_validity": {
    "years": 1
  },
  "organization": {
    "id": 12345,
    "contacts": [
      {
        "contact_type": "verified_contact",
        "user_id": 12345
      }
    ]
  },
  "skip_approval": true,
  "cs_provisioning_method": "email"
}'

curl --request POST 'https://www.digicert.com/services/v2/order/certificate/{{code_signing_certificate_id}}' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "signature_hash": "sha256"
  },
  "order_validity": {
    "years": 1
  },
  "organization": {
    "id": 12345,
    "contacts": [
      {
        "contact_type": "verified_contact",
        "user_id": 12345
      }
    ]
  },
  "skip_approval": true,
  "cs_provisioning_method": "keylocker"
}'

• 201 Created (skip approval)
• 201 Created (one-step approval)
• 201 Created (two-step approval)
• 201 Created (auto approval)

{
  "id": 112233,
  "certificate_id": 445566
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "pending"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "submitted"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "approved"
    }
  ],
  "certificate_id": 113
}

Path parameters

Request parameters

Response parameters

Contact types

CS and EV CS organization validation

Code Signing (CS) and EV Code Signing (EV CS) certificate orders must include information about the organization to associate with the code signing certificate. DigiCert must validate the organization before issuing the certificate. The following examples show three ways to add an organization to your CS or EV CS certificate order.

Use existing organization (validated)

When including an organization already submitted for CS or EV CS validation, either by itself or as part of an earlier certificate order request, you only need to include the organization’s ID in your new order request:

{
  "certificate": {
    ...
  }
  "organization": {
    "id": 12345
  },
  ...
}

If needed, you can update the organization contact or technical contact and add new verified contacts to the organization. Use the organization.contacts array to provide information about each new contact. To learn more, see Contact types.

{
  "certificate": {
    ...
  }
  "organization": {
    "id": 12345,
    "contacts": [
      {
        "contact_type": "verified_contact",
        "user_id": 12345
      },
      { 
        "contact_type": "organization_contact",
        "user_id": 56789
      },
      {
        "contact_type": "technical_contact",
        "first_name": "Jane",        
        "last_name": "Doe",        
        "job_title": "Technician",      
        "telephone": "1234567890",        
        "email": "jane.doe@example.com"
      }
    ]
  },
  ...
}

Use existing organization (not validated)

When including an existing organization never submitted for CS or EV CS validation, you can submit the organization for validation as part of your certificate order request:

1. In the organization object, provide the id of the existing organization.
2. In the organization.contacts array, provide a list of verified contacts to submit as CS or EV CS approvers for the organization.
3. After creating the order, the organization is automatically submitted for the validation type corresponding to the chosen product (CS or EV CS).

For example:

{
  "certificate": {
    ...
  }
  "organization": {
    "id": 12345,
    "contacts": [
      {
        "contact_type": "verified_contact",
        "user_id": 12345
      }
  },
  ...
}

Use a new organization

When adding a new organization, use the organization object to provide the organization’s name, location, and phone number. Make sure to include an organization_contact and at least one verified_contact (see Contact types). When you create the order, the new organization is added to your CertCentral account and submitted for CS or EV CS validation.

{
  "certificate": {
    ...
  },
  "organization": {
    "name": "New Organization",
    "assumed_name": "New Organization",
    "country": "us",
    "address": "123 Example Street",
    "address2": "Floor 08",
    "city": "Lehi",
    "state": "Utah",
    "zip": "12345",
    "telephone": "123-456-789",
    "contacts": [
     {
        "contact_type": "verified_contact",
        "first_name": "John",
        "last_name": "Doe",
        "job_title": "Technician",
        "telephone": "1234567890",
        "email": "john.doe@example.com"
      },
      {
        "contact_type": "organization_contact",
        "first_name": "Jane",
        "last_name": "Doe",
        "job_title": "Supervisor",
        "telephone": "1234567890",
        "email": "jane.doe@example.com"
      },
      {
        "contact_type": "technical_contact",
        "first_name": "Alex",
        "last_name": "Doe",
        "job_title": "Technician",
        "telephone": "1234567890",
        "email": "alex.doe@example.com"
      }
    ]
  },
  ...
}

API changes for new private key storage requirements

Starting May 16, 2023, DigiCert requires private keys for Code Signing (code_signing) certificates to be stored on hardware certified as FIPS 140 Level 2, Common Criteria EAL 4+, or equivalent. This change affects new, renewal, and reissue code signing certificate requests submitted using the CertCentral UI and the Services API.

Starting May 2, 2023:

• The CertCentral Services API will accept code signing certificate requests using the new provisioning methods. The new provisioning methods are the same provisioning methods DigiCert already supports for EV Code Signing certificates.
• CertCentral administrators can choose default provisioning methods for Code Signing and EV Code Signing certificates. DigiCert uses the default provisioning methods when we receive code signing certificate requests that do not specify a provisioning method.

Learn more about DigiCert’s timeline for changes to the Code Signing workflow.

What do I need to do?

Do you use the Services API to order Code Signing certificates?

• No No action required.
• Yes Between May 2 and May 16, 2023, complete the following:
  • In API clients that request or reissue Code Signing certificates, migrate your usage to the new provisioning methods. See Code Signing and EV Code Signing provisioning methods.
  • Update your CertCentral account settings:
    • Select default provisioning methods for Code Signing and EV Code Signing certificates that are compatible with your workflows.
    • Confirm the default shipping address for the DigiCert-provided hardware token option.