# Certificate and Key Requirements {% hint style="danger" %} **CRITICAL: Only PEM Format is Supported** Bindplane collectors (based on OpenTelemetry Collector) ONLY support PEM-encoded certificates and keys. DER and PKCS#12/PFX formats are NOT supported and must be converted first. {% endhint %} ## Format Requirements Summary | Requirement | Status | Details | | --------------- | -------------------------------------------------------- | ------------------------------------------------------- | | **Format** | PEM ONLY | Base64-encoded text with headers | | **DER Format** | NOT SUPPORTED | Binary format must be converted to PEM | | **PKCS#12/PFX** | NOT SUPPORTED | Bundle format (`.p12`, `.pfx`) must be extracted to PEM | | **Private Key** | Must be unencrypted | Password-protected keys NOT supported | | **Certificate** | Must start with `-----BEGIN CERTIFICATE-----` | Binary files NOT supported | | **Private Key** | Must start with `-----BEGIN PRIVATE KEY-----` or similar | Binary files NOT supported | ## PEM Format Identification ### What PEM Files Look Like PEM files are **human-readable text files** containing Base64-encoded data with clearly marked headers and footers. **Valid PEM certificate:** ``` -----BEGIN CERTIFICATE----- MIIDXTCCAkWgAwIBAgIJAKJ3PqGFGNkqMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX ... (more base64 text) ... -----END CERTIFICATE----- ``` **Valid PEM private key headers:** ``` -----BEGIN PRIVATE KEY----- (PKCS#8 format - most common for modern keys) -----BEGIN RSA PRIVATE KEY----- (PKCS#1 format - traditional RSA keys) -----BEGIN EC PRIVATE KEY----- (SEC1 format - ECDSA keys) ``` ### How to Check Your File Format {% tabs %} {% tab title="Linux/macOS" %} ```bash head -n 5 /path/to/certificate.crt ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell Get-Content C:\certs\certificate.crt -First 5 ``` {% endtab %} {% endtabs %} **What you should see:** * If you see `-----BEGIN CERTIFICATE-----` or `-----BEGIN PRIVATE KEY-----` → PEM format * If you see binary gibberish or unreadable characters → DER format or other ## Supported Key Types | Key Type | Supported | Private Key Format | Notes | | ----------- | --------- | ------------------ | --------------------------------------------------------------------------------------------- | | **RSA** | YES | PKCS#1 or PKCS#8 | Most common. Headers: `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN PRIVATE KEY-----` | | **ECDSA** | YES | SEC1 or PKCS#8 | Modern, efficient. Headers: `-----BEGIN EC PRIVATE KEY-----` or `-----BEGIN PRIVATE KEY-----` | | **Ed25519** | YES | PKCS#8 only | Modern, fast. Header: `-----BEGIN PRIVATE KEY-----` | | **DSA** | NO | Not supported | Legacy algorithm | ## Encrypted Private Keys Are NOT Supported {% hint style="danger" %} **CRITICAL LIMITATION** OpenTelemetry Collector cannot use password-protected (encrypted) private keys. This is a fundamental limitation of Go's `crypto/tls` library - there is no mechanism for the collector to prompt for or use a passphrase during startup. {% endhint %} ### How to Check if Your Key is Encrypted **View the key file:** {% tabs %} {% tab title="Linux/macOS" %} ```bash head -n 10 /path/to/private.key ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell Get-Content C:\certs\private.key -First 10 ``` {% endtab %} {% endtabs %} **Encrypted keys contain one of these indicators:** * Header: `-----BEGIN ENCRYPTED PRIVATE KEY-----` * Contains line: `Proc-Type: 4,ENCRYPTED` * Contains line: `DEK-Info: DES-EDE3-CBC,...` ### Decrypting Private Keys If your key is encrypted, you MUST decrypt it before use: **For RSA keys (PKCS#1):** {% tabs %} {% tab title="Linux/macOS" %} ```bash openssl rsa -in encrypted-key.pem -out decrypted-key.pem # You'll be prompted for the passphrase ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell openssl rsa -in C:\certs\encrypted-key.pem -out C:\certs\decrypted-key.pem # You'll be prompted for the passphrase ``` {% endtab %} {% endtabs %} **For other key types or PKCS#8 format:** {% tabs %} {% tab title="Linux/macOS" %} ```bash openssl pkey -in encrypted-key.pem -out decrypted-key.pem ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell openssl pkey -in C:\certs\encrypted-key.pem -out C:\certs\decrypted-key.pem ``` {% endtab %} {% endtabs %} **Secure the decrypted key file:** {% tabs %} {% tab title="Linux/macOS" %} ```bash chmod 600 decrypted-key.pem chown : decrypted-key.pem ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell icacls C:\certs\decrypted-key.pem /inheritance:r /grant:r "$($env:USERNAME):(R)" ``` {% endtab %} {% endtabs %} **Verify the key is unencrypted:** {% tabs %} {% tab title="Linux/macOS" %} ```bash head -n 5 decrypted-key.pem # Should show: "-----BEGIN RSA PRIVATE KEY-----" or "-----BEGIN PRIVATE KEY-----" # Should NOT contain "ENCRYPTED" or "Proc-Type" ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell Get-Content C:\certs\decrypted-key.pem -First 5 # Should show: "-----BEGIN RSA PRIVATE KEY-----" or "-----BEGIN PRIVATE KEY-----" # Should NOT contain "ENCRYPTED" or "Proc-Type" ``` {% endtab %} {% endtabs %} ## Certificate Chain Requirements ### What Clients Need to Verify When a client connects to your collector, it needs to verify the certificate chain from your server certificate up to a trusted root CA. If any intermediate certificates are missing, clients will fail with errors like: * "Unknown CA" * "Certificate verification failed" * "Unable to get issuer certificate" ### Creating a Full Chain Certificate Your certificate file should contain certificates in this order: 1. Server/leaf certificate (first) 2. Intermediate CA certificate(s) 3. Root CA (optional, clients usually have this) **Example:** {% tabs %} {% tab title="Linux/macOS" %} ```bash # Concatenate certificates into a single file cat server-cert.crt intermediate-ca.crt > fullchain.crt ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell # Concatenate certificates into a single file Get-Content server-cert.crt, intermediate-ca.crt | Set-Content fullchain.crt ``` {% endtab %} {% endtabs %} The resulting file should look like: ``` -----BEGIN CERTIFICATE----- [Your Server Certificate] -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- [Intermediate CA Certificate] -----END CERTIFICATE----- ``` {% hint style="info" %} **Certificate Order Matters** The order must be: leaf certificate first, then intermediate(s), optionally root CA last. Reverse order will cause verification failures. {% endhint %} ## Private Key Requirements **CRITICAL REQUIREMENTS:** 1. **Must be PEM format** - Binary DER format is not supported 2. **Must be unencrypted** - Password-protected keys are not supported 3. **Must match the certificate** - The private key must be the one used to generate the certificate For instructions on verifying that your certificate and key match, see [Testing and Verification: Verify Certificate and Key Match](/how-to-guides/security-and-tls/using-tls/reference/testing-verification.md#verify-certificate-and-key-match). ## File Permissions and Security Proper file permissions are critical for security: **Private key files:** {% tabs %} {% tab title="Linux/macOS" %} ```bash chmod 600 /path/to/server.key chown : /path/to/server.key ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell icacls C:\certs\server.key /inheritance:r /grant:r "$($env:USERNAME):(R)" ``` {% endtab %} {% endtabs %} **Certificate files:** {% tabs %} {% tab title="Linux/macOS" %} ```bash chmod 644 /path/to/fullchain.crt chown : /path/to/fullchain.crt ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell icacls C:\certs\fullchain.crt /inheritance:r /grant:r "$($env:USERNAME):(R)" /grant:r "Everyone:(R)" ``` {% endtab %} {% endtabs %} {% hint style="warning" %} **Security Best Practice** Private keys should only be readable by the user running the collector. Never commit private keys to version control or share them insecurely. {% endhint %} ## Quick Format Verification Checklist Before using certificates with Bindplane collectors, verify: * [ ] Certificate file starts with `-----BEGIN CERTIFICATE-----` * [ ] Private key file starts with `-----BEGIN PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN EC PRIVATE KEY-----` * [ ] Private key file does NOT contain "ENCRYPTED" in the header * [ ] Private key file does NOT contain "Proc-Type: 4,ENCRYPTED" * [ ] Files are readable text (not binary) * [ ] Files have proper permissions (600 for keys, 644 for certificates) * [ ] Certificate and key match (verify with [testing commands](/how-to-guides/security-and-tls/using-tls/reference/testing-verification.md#verify-certificate-and-key-match)) ## File Extensions and Naming Conventions {% hint style="info" %} **File Extensions Are Just Naming Conventions** Extensions like `.crt`, `.pem`, `.key`, `.cer`, and `.cert` are naming conventions, not strict indicators of content. The actual file format (PEM vs DER) matters more than the extension. {% endhint %} | Extension | Typical Content | Format | Notes | | ------------------------- | -------------------------------------------------------- | --------------------------- | -------------------------------------- | | `.pem` | Anything (cert, private key, public key, CA cert, chain) | Base64-encoded with headers | Most flexible format | | `.crt` / `.cert` / `.cer` | Certificate (public certificate) | Usually PEM, sometimes DER | Convention suggests it's a certificate | | `.key` | Private key | Usually PEM, sometimes DER | Convention suggests it's a private key | | `.ca` / `.ca-bundle` | CA certificate(s) | Usually PEM | Multiple CA certs concatenated | | `.der` | Anything | Binary DER encoding | Not human-readable | ## Inspecting File Contents You can't always trust the file extension. To see what's actually in a file: {% tabs %} {% tab title="Linux/macOS" %} ```bash # View file contents (look for BEGIN/END headers) cat certificate.pem # Check certificate details openssl x509 -in certificate.crt -text -noout # Check private key details openssl rsa -in private.key -text -noout # Determine if file is PEM or DER format head -n 1 certificate.crt # PEM starts with "-----BEGIN CERTIFICATE-----" # DER is binary data (gibberish when viewed as text) ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell # View file contents (look for BEGIN/END headers) Get-Content C:\certs\certificate.pem # Check certificate details openssl x509 -in C:\certs\certificate.crt -text -noout # Check private key details openssl rsa -in C:\certs\private.key -text -noout # Determine if file is PEM or DER format Get-Content C:\certs\certificate.crt -First 1 # PEM starts with "-----BEGIN CERTIFICATE-----" # DER is binary data (gibberish when viewed as text) ``` {% endtab %} {% endtabs %} ## Need to Convert Formats? If your certificates are not in PEM format, see [Certificate Conversion Guide](/how-to-guides/security-and-tls/using-tls/reference/certificate-conversion.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bindplane.com/how-to-guides/security-and-tls/using-tls/requirements.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.