Chef

Feedback
Create a Chef Connection
Feedback
Ensure your network security policies allow incoming requests from Hanzo KMS to this certificate sync provider, if network restrictions apply.

The Chef Certificate Sync requires the following permissions to be set on the Chef user for Hanzo KMS to sync certificates to Chef: data bag read, data bag create, data bag update, data bag delete.

Any role with these permissions would work such as a custom role with Data Bag permissions.

Certificates synced to Chef will be stored as data bag items within the specified data bag, preserving both the certificate and private key components as separate fields.

1. Navigate to Project > Integrations > Certificate Syncs and press Add Sync.

2. Select the Chef option.

3. Configure the Destination to where certificates should be deployed, then click Next.

   • Chef Connection: The Chef Connection to authenticate with.
   • Data Bag Name: The name of the Chef data bag where certificates will be stored.

4. Configure the Sync Options to specify how certificates should be synced, then click Next.

   • Enable Removal of Expired/Revoked Certificates: If enabled, Hanzo KMS will remove certificates from the destination if they are no longer active in Hanzo KMS.
   • Preserve Data Bag Item on Renewal: Only applies to certificate renewals. When a certificate is renewed in Hanzo KMS, this option controls how the renewed certificate is handled. If enabled, the renewed certificate will update the existing data bag item, preserving the same item name. If disabled, the renewed certificate will be created as a new data bag item with a new name.
   • Include Root CA: If enabled, the Root CA certificate will be included in the certificate chain when syncing to Chef data bags. If disabled, only intermediate certificates will be included.
   • Certificate Name Schema (Optional): Customize how certificate item names are generated in Chef data bags. Use {{certificateId}} as a placeholder for the certificate ID.
   • Auto-Sync Enabled: If enabled, certificates will automatically be synced when changes occur. Disable to enforce manual syncing only.

5. Configure the Field Mappings to customize how certificate data is stored in Chef data bag items, then click Next.

   • Certificate Field: The field name where the certificate will be stored in the data bag item (default: certificate)
   • Private Key Field: The field name where the private key will be stored in the data bag item (default: private_key)
   • Certificate Chain Field: The field name where the full certificate chain excluding the root CA certificate will be stored (default: certificate_chain)
   • CA Certificate Field: The field name where the root CA certificate will be stored (default: ca_certificate)

Chef Data Bag Item Structure: Certificates are stored in Chef data bags as items with the following structure (field names can be customized via field mappings):

{
  "id": "certificate-item-name",
  "certificate": "-----BEGIN CERTIFICATE-----\n...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "certificate_chain": "-----BEGIN CERTIFICATE-----\n...",
  "ca_certificate": "-----BEGIN CERTIFICATE-----\n..."
}

Example with Custom Field Mappings:

{
  "id": "certificate-item-name",
  "ssl_cert": "-----BEGIN CERTIFICATE-----\n...",
  "ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
  "ssl_chain": "-----BEGIN CERTIFICATE-----\n...",
  "ssl_ca": "-----BEGIN CERTIFICATE-----\n..."
}

6. Configure the Details of your Chef Certificate Sync, then click Next.

   • Name: The name of your sync. Must be slug-friendly.
   • Description: An optional description for your sync.

7. Select which certificates should be synced to Chef.

8. Review your Chef Certificate Sync configuration, then click Create Sync.

9. If enabled, your Chef Certificate Sync will begin syncing your certificates to the destination endpoint.

To create a Chef Certificate Sync, make an API request to the Create Chef Certificate Sync API endpoint.

Sample request

You can optionally specify certificateIds during sync creation to immediately add certificates to the sync. If not provided, you can add certificates later using the certificate management endpoints.

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/cert-manager/syncs/chef \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "my-chef-cert-sync",
    "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "description": "an example certificate sync",
    "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "destination": "chef",
    "isAutoSyncEnabled": true,
    "certificateIds": [
        "550e8400-e29b-41d4-a716-446655440000",
        "660f1234-e29b-41d4-a716-446655440001"
    ],
    "syncOptions": {
        "canRemoveCertificates": true,
        "preserveSecretOnRenewal": true,
        "canImportCertificates": false,
        "includeRootCa": false,
        "certificateNameSchema": "myapp-{{certificateId}}",
        "fieldMappings": {
            "certificate": "ssl_cert",
            "privateKey": "ssl_key",
            "certificateChain": "ssl_chain",
            "caCertificate": "ssl_ca"
        }
    },
    "destinationConfig": {
        "dataBagName": "ssl_certificates"
    }
}'

Example with Default Field Mappings

curl --request POST \
--url https://app.kms.hanzo.ai/api/v1/cert-manager/syncs/chef \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "my-chef-cert-sync-default",
    "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "description": "Chef sync with default field mappings",
    "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "destination": "chef",
    "isAutoSyncEnabled": true,
    "syncOptions": {
        "canRemoveCertificates": true,
        "preserveSecretOnRenewal": true,
        "canImportCertificates": false,
        "includeRootCa": false,
        "certificateNameSchema": "{{commonName}}-{{certificateId}}",
        "fieldMappings": {
            "certificate": "certificate",
            "privateKey": "private_key",
            "certificateChain": "certificate_chain",
            "caCertificate": "ca_certificate"
        }
    },
    "destinationConfig": {
        "dataBagName": "certificates"
    }
}'

Sample response

{
    "pkiSync": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "my-chef-cert-sync",
        "description": "an example certificate sync",
        "destination": "chef",
        "isAutoSyncEnabled": true,
        "destinationConfig": {
            "dataBagName": "ssl_certificates"
        },
        "syncOptions": {
            "canRemoveCertificates": true,
            "preserveSecretOnRenewal": true,
            "canImportCertificates": false,
            "includeRootCa": false,
            "certificateNameSchema": "myapp-{{certificateId}}",
            "fieldMappings": {
                "certificate": "ssl_cert",
                "privateKey": "ssl_key",
                "certificateChain": "ssl_chain",
                "caCertificate": "ssl_ca"
            }
        },
        "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "createdAt": "2023-01-01T00:00:00.000Z",
        "updatedAt": "2023-01-01T00:00:00.000Z"
    }
}

Certificate Management

Feedback
Automatic Deployment: Deploy certificates in Hanzo KMS to Chef data bags with customizable field names.
Feedback
Certificate Updates: Update certificates in Chef data bags when renewals occur.
Feedback
Expiration Handling: Optionally remove expired certificates from Chef data bags (if enabled).
Feedback
Format Preservation: Maintain certificate format during sync operations.
Feedback
Field Customization: Map certificate data to custom field names that match your Chef cookbook requirements.
Feedback
CA Certificate Support: Include CA certificates in data bag items for complete certificate chain management.

Chef Certificate Syncs support both automatic and manual synchronization modes. When auto-sync is enabled, certificates are automatically deployed as they are issued or renewed.

Manual Certificate Sync

Feedback
Initial setup when you have existing certificates to deploy
Feedback
One-time sync of specific certificates
Feedback
Testing certificate sync configurations
Feedback
Force sync after making changes

FAQ

Chef does not support importing certificates back into Hanzo KMS due to the nature of Chef data bags where certificates are stored as data rather than managed certificate objects.