B2C Commerce Hyperforce: Generating and Managing mTLS Code Upload Certificates for Staging

Please find instructions for uploading code to a B2C Commerce Staging instance on Hyperforce via CLI and OpenSSL

CLI Instructions:

Detailed steps to upload code via CLI using the Agentic B2C Developer Toolkit are outlined in Deploying to Hyperforce.

OpenSSL Instructions:

Step 1: Generate a Self-Signed CA Certificate and Private Key

Run the following openssl command to generate a CA certificate (.crt) and private key (.key). Replace <realm> and <customer> with your actual realm ID and customer ID.

CERT_HOST=staging-<realm>-<customer>.demandware.net
openssl req -new -newkey rsa:2048 -sha256 -days 365 -x509 -nodes \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -keyout ${CERT_HOST}.key \
  -out ${CERT_HOST}.crt

This command produces two files in your working directory:

• ${CERT_HOST}.crt — the CA certificate (upload this to Business Manager in Step 2)
• ${CERT_HOST}.key — the private key (upload this alongside the certificate in Step 2)

When prompted, fill in your organisation details. For Common Name, use the same value you set for CERT_HOST (for example, staging-noramer-mycustomer.demandware.net).
Example prompt responses:

Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: MA
Locality Name (eg, city) []: Burlington
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Salesforce
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []: staging-<realm>-<customer>.demandware.net
Email Address []:

Key parameters explained:

• -newkey rsa:2048 — generates a new RSA (Rivest–Shamir–Adleman) key pair with a 2048-bit key length, which meets current security standards.
• -sha256 — signs the certificate using the SHA-256 hashing algorithm.
• -days 365 — sets the certificate validity to 365 days (the maximum allowed by B2C Commerce).
• -x509 — outputs a self-signed certificate rather than a certificate signing request (CSR).
• -nodes — generates the private key without a passphrase (required for automated server-side use).
• -addext "basicConstraints=critical,CA:TRUE" — marks this certificate as a Certificate Authority (CA) certificate. This flag is required. See the Troubleshooting section if you omit it.
• -addext "keyUsage=critical,keyCertSign,cRLSign" — specifies that this CA certificate can sign other certificates and certificate revocation lists (CRLs). Best practice.
  
  

Step 2: Upload the Certificate and Private Key in Business Manager

In Business Manager for your Staging instance, navigate to Administration → Site Development → Development Setup → Code Upload Certificate.

1. Select Add Certificate.
2. Enter a Certificate Name (any descriptive label for your own organisation — for example, hyperforce-staging-ca-2024).
3. Paste the contents of ${CERT_HOST}.crt into the Certificate field.
4. Paste the contents of ${CERT_HOST}.key into the Private Key field.
5. Select Save.
   
   Important: Upload the CA certificate generated in Step 1 — not a client (leaf) certificate. If you upload a client certificate by mistake, Business Manager returns the error: "Failed to create mTLS certificate." See the Troubleshooting section for how to distinguish between a CA certificate and a client certificate.
   
   

(Optional) Delete Unused or Expired CA Certificates

Multiple CA certificates can be active simultaneously. If any CA certificates are unused, expired, or compromised, select them on this screen and delete them.

Step 3: Sign Client Certificates Using the Self-Signed CA Certificate

Client certificates are generated per user but can all be signed with the same CA certificate from Step 1. Each user needs their own client certificate to upload code. Complete the following steps for each user:

3a. Create a Certificate Signing Request (CSR) for the user.

Replace <bm_username> with the user's Business Manager username. Omit a challenge password and optional company name when prompted.

USER=<bm_username>
openssl req -new -sha256 -newkey rsa:2048 -nodes -out ${USER}.req -keyout ${USER}.key

This produces:

• • ${USER}.req — the CSR file (used in the next step to generate the signed certificate)
  • ${USER}.key — the user's private key (share this securely with the user alongside the .p12 file)

3b. Sign the CSR using the CA certificate.

openssl x509 -CA ${CERT_HOST}.crt -CAkey ${CERT_HOST}.key \
  -req -in ${USER}.req -out ${USER}.pem -days 90

This produces ${USER}.pem — the signed client certificate. The -days 90 value sets a 90-day validity period for client certificates. Adjust as appropriate for your security policy, but note that the CA certificate itself expires after 365 days.

3c. Convert the signed certificate to PKCS#12 (p12) format.

The .p12 file is the format accepted by UX Studio and WebDAV clients such as CyberDuck. Set an export password when prompted — share this password securely with the user alongside the .p12 file.

openssl pkcs12 -export -legacy -in ${USER}.pem -inkey ${USER}.key \
  -certfile ${CERT_HOST}.crt -name ${USER} -out ${USER}.p12

This produces ${USER}.p12 — the client certificate bundle to distribute to the user.
Note on the -legacy flag: Newer versions of OpenSSL (3.x) use a different default encryption algorithm for .p12 files that macOS Keychain cannot import. The -legacy flag instructs OpenSSL to use the older encryption format. If you are not on macOS or are using OpenSSL 1.x, you may not need this flag.
The ${USER}.p12 file can now be used with UX Studio and WebDAV clients like CyberDuck to upload code to the Staging instance.

Rotating or Renewing the CA Certificate

The CA certificate expires after a maximum of 365 days. Renew it before expiry to avoid disruption to code uploads. Also rotate if the CA certificate or any client certificate it has signed is compromised.
To renew:

1. Repeat Step 1 to generate a new CA certificate and private key.
2. Repeat Step 2 to upload the new CA certificate to Business Manager. Multiple CA certificates can be active simultaneously — this allows you to run the old and new certificates in parallel during the transition.
3. Repeat Step 3 to generate new client certificates signed by the new CA certificate for each user.
4. Validate that code uploads work with the new client certificates.
5. Delete the old CA certificate from Business Manager once all users have been migrated to new client certificates.

Alternatively, use the CDN-API delete code upload certificate endpoint to delete the old CA certificate programmatically.

Troubleshooting

Error: "Certificate Creation Error. The certificate couldn't be created"

This error appears in Business Manager when you attempt to upload a certificate that is not a valid CA certificate.
Run the following diagnostic command to inspect your certificate:

openssl x509 -in ${CERT_HOST}.crt -text -noout | grep -A2 -E "Basic Constraints|Signature Algorithm"

In the output, look for the X509v3 Basic Constraints section. If this section is missing entirely or contains CA:FALSE, the certificate was generated without the -addext "basicConstraints=critical,CA:TRUE" flag.
Regenerate the certificate using the full command from Step 1, which includes both required extensions:

openssl req -new -newkey rsa:2048 -sha256 -days 365 -x509 -nodes \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -keyout ${CERT_HOST}.key \
  -out ${CERT_HOST}.crt

Root cause: macOS ships with a version of OpenSSL (LibreSSL) that does not include basicConstraints=CA:TRUE in its default configuration. Always use the explicit -addext flags shown above.

Error: "Failed to create mTLS certificate"

This error means you uploaded a client (leaf) certificate instead of a CA certificate. Return to Step 1 and ensure you are uploading the .crt file produced by the openssl req ... -x509 command, not a .pem file produced during Step 3.