{"id":99,"date":"2026-07-19T00:00:00","date_gmt":"2026-07-19T00:00:00","guid":{"rendered":"http:\/\/\/var\/www\/html\/?p=99"},"modified":"2026-07-19T16:42:01","modified_gmt":"2026-07-19T16:42:01","slug":"openssl-self-signed-certificate-in-certificate-chain-validation-on-macos-local-environment","status":"publish","type":"post","link":"https:\/\/staging.butitworkedlocal.com\/?p=99","title":{"rendered":"Fixing OpenSSL Self-Signed Certificate Chain Validation Errors on macOS Local Environments"},"content":{"rendered":"\n

Resolve OpenSSL validation issues with self-signed certificates on macOS. Learn to trust local development certificates in Keychain Access and for various tools.<\/strong><\/p>\n\n\n

Introduction<\/h2>\n\n

Developing locally on macOS often involves interacting with services that use self-signed SSL certificates. Whether it's a backend API, a local database, or a custom microservice running in Docker, these certificates are not inherently trusted by your operating system or development tools. This leads to frustrating "certificate validation failed" errors when your applications or curl<\/code> commands try to establish secure connections. This guide will walk you through the precise steps to properly trust these certificates on macOS, ensuring your local development environment runs smoothly.<\/p>\n\n

Symptom & Error Signature<\/h3>\n\n

You will typically encounter errors when attempting to connect to your local HTTPS service via a web browser, curl<\/code>, Node.js, Python, or other client applications. The exact error message can vary but usually points to an untrusted certificate or certificate chain.<\/p>\n\n

Common Error Outputs:<\/strong><\/p>\n\n

  • curl<\/code>:<\/strong><\/li>
  • <\/code>`bash<\/li>
  • curl: (60) SSL certificate problem: self signed certificate in certificate chain<\/li>
  • More details here: https:\/\/curl.haxx.se\/docs\/sslcerts.html<\/li>
  • curl failed to verify the legitimacy of the server and therefore could not<\/li>
  • establish a secure connection to it. To learn more about this situation and<\/li>
  • how to fix it, please visit the web page mentioned above.<\/li>
  • <\/code>`<\/li><\/ul>\n\n
    • Node.js (e.g., fetch<\/code> or https<\/code> module):<\/strong><\/li>
    • <\/code>`<\/li>
    • FetchError: request to https:\/\/localhost:8443\/api failed, reason: self-signed certificate in certificate chain<\/li>
    • at ClientRequest.<anonymous> (\/path\/to\/node_modules\/node-fetch\/lib\/index.js:1505:11)<\/li>
    • at ClientRequest.emit (node:events:514:28)<\/li>
    • at TLSSocket.socketErrorListener (node:http<\/em>client:481:9)<\/li>
    • at TLSSocket.emit (node:events:514:28)<\/li>
    • at emitErrorNT (node:internal\/streams\/destroy:151:8)<\/li>
    • at emitErrorCloseNT (node:internal\/streams\/destroy:120:3)<\/li>
    • at process.processTicksAndRejections (node:internal\/process\/task_queues:82:21) {<\/li>
    • type: 'system',<\/li>
    • errno: 'DEPTHZERO<\/em>SELFSIGNED<\/em>CERT',<\/li>
    • code: 'DEPTHZERO<\/em>SELFSIGNED<\/em>CERT'<\/li>
    • }<\/li>
    • <\/code>`<\/li><\/ul>\n\n
      • Python (requests<\/code> library):<\/strong><\/li>
      • <\/code>`python<\/li>
      • requests.exceptions.SSLError: HTTPSConnectionPool(host='localhost', port=8443): Max retries exceeded with url: \/api (Caused by SSLError(1, '[SSL: CERTIFICATEVERIFY<\/em>FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:1007)'))<\/li>
      • <\/code>`<\/li><\/ul>\n\n
        • Browser (e.g., Chrome\/Firefox):<\/strong><\/li>
        • You will see a "Your connection is not private" or "Warning: Potential Security Risk Ahead" page with an error code like NET::ERRCERT<\/em>AUTHORITYINVALID<\/code> or SEC<\/em>ERRORUNKNOWN<\/em>ISSUER<\/code>.<\/li><\/ul>\n\n

          Root Cause Analysis<\/h3>\n\n

          The core of the problem lies in the trust chain<\/em> of your SSL certificate. When a client (browser, curl<\/code>, Node.js app) connects to an HTTPS server, it receives the server's SSL certificate. The client then attempts to validate this certificate by tracing its signing authority back to a trusted Root Certificate Authority (CA).<\/p>\n\n

          1. Self-Signed Certificates:<\/strong> In a local development environment, you often create certificates that are "self-signed," meaning the certificate is signed by its own private key, or signed by a custom Certificate Authority (CA) that you<\/em> created.<\/li>
          2. Untrusted Authority:<\/strong> Neither your self-signed certificate nor your custom CA's certificate is recognized or pre-installed in the default trust stores of macOS or the various applications you use. These trust stores contain public certificates from globally recognized CAs (like Let's Encrypt, DigiCert, etc.).<\/li>
          3. macOS Keychain vs. Application Trust:<\/strong> macOS has its own system-wide trust store (Keychain Access). While many applications, especially GUI ones and those using Apple's Secure Transport framework, will leverage this, others (like curl<\/code> linked to Homebrew's OpenSSL, Node.js, Python's requests<\/code> library) might rely on their own bundled CA bundles or specific OpenSSL configurations. This divergence means trusting a certificate in Keychain Access might not automatically resolve issues for all tools.<\/li>
          4. certificate chain<\/code><\/strong>: The error "self signed certificate in certificate chain" indicates that the certificate presented by the server is part of a chain where one or more intermediate certificates, or the root certificate itself, is self-signed and not trusted. Typically, for local development, you create a Root CA<\/em> and then sign your server certificate<\/em> with that Root CA. The client then needs to trust your Root CA<\/em>.<\/li><\/ol>\n\n

            Step-by-Step Resolution<\/h3>\n\n

            The resolution involves two primary phases: ensuring you have a properly generated self-signed certificate (or CA) and then explicitly adding that certificate to the relevant trust stores on your macOS system.<\/p>\n\n

            1. Generate a Self-Signed Root CA and Server Certificate (If you don't have one)<\/h4>\n\n

            If you are just using a basic, self-signed server certificate, your client may complain about a "depth 0" error. For a more robust local setup that mimics production, it's better to create your own Root Certificate Authority (CA) and then use it to sign individual server certificates. This allows you to trust your single CA on your development machine, and all certificates signed by it will automatically be trusted.<\/p>\n\n

            [!IMPORTANT]\nIf you are already using a self-signed certificate or have a custom CA certificate (e.g., from a Docker container or another local setup), you can skip this step and proceed to Step 2 with your existing CA certificate. Ensure you have the .crt<\/code> (or .pem<\/code>) file of your Root CA<\/strong>.<\/p><\/blockquote>\n\n

            We'll use openssl<\/code> via Homebrew on macOS.<\/p>\n\n

            First, install or ensure OpenSSL is updated via Homebrew:\n<\/code>`bash\nbrew update\nbrew install openssl@3\n# Link openssl@3 if not already linked (this might prompt for sudo access or specific commands)\nbrew link openssl@3 –force\n<\/code>`<\/p>\n\n

            Now, let's create a directory for our certificates and generate the CA:\n<\/code>`bash\nmkdir -p ~\/certs\/local-ca\ncd ~\/certs\/local-ca<\/p>\n\n

            1. Generate CA Private Key\nopenssl genrsa -aes256 -out ca.key 4096<\/h1>\n\n

            2. Create CA Certificate Request\nopenssl req -new -x509 -sha256 -days 3650 -key ca.key -out ca.crt \n -subj "\/C=US\/ST=CA\/O=Local Development\/CN=Local Development CA"<\/h1>\n\n

            Now generate a server certificate signed by this CA:\n# We'll use example.com and localhost for the server certificate\nSERVER_NAME="localhost" # Or your local dev domain, e.g., myapp.local<\/h1>\n\n

            1. Generate Server Private Key\nopenssl genrsa -out $SERVER_NAME.key 2048<\/h1>\n\n

            2. Create Server Certificate Signing Request (CSR)\nopenssl req -new -key $SERVERNAME.key -out $SERVER<\/em>NAME.csr \n -subj "\/C=US\/ST=CA\/O=Local Development\/CN=$SERVER_NAME"<\/h1>\n\n

            3. Create a V3 Ext File for SAN (Subject Alternative Name)\n# This is crucial for modern browsers and clients which require SAN.\ncat <<EOF > $SERVER_NAME.ext\nauthorityKeyIdentifier=keyid,issuer\nbasicConstraints=CA:FALSE\nkeyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment\nsubjectAltName = @alt_names<\/h1>\n\n

            [alt_names]\nDNS.1 = $SERVER_NAME\nDNS.2 = localhost\nIP.1 = 127.0.0.1\nEOF<\/p>\n\n

            4. Sign the Server Certificate with your CA\nopenssl x509 -req -in $SERVER_NAME.csr -CA ca.crt -CAkey ca.key -CAcreateserial \n -out $SERVERNAME.crt -days 365 -sha256 -extfile $SERVER<\/em>NAME.ext<\/h1>\n\n

            echo "Certificates generated in ~\/certs\/local-ca:"\nls -l ~\/certs\/local-ca\n<\/code>`\nYou now have ca.crt<\/code> (your Root CA certificate) and $SERVER_NAME.crt<\/code> (your server certificate) along with their respective keys. The ca.crt<\/code> is what needs to be trusted.<\/p>\n\n

            2. Trust the Root CA Certificate in macOS Keychain Access<\/h4>\n\n

            This step adds your custom Root CA to the macOS system trust store, which many applications (especially browsers and those using Apple's Secure Transport) will automatically use.<\/p>\n\n

            # Assuming your CA certificate is named ca.crt and is in ~\/certs\/local-ca\nsudo security add-trusted-cert -d -r trustRoot -k \/Library\/Keychains\/System.keychain ~\/certs\/local-ca\/ca.crt\n```<\/code><\/pre>\n\n
            After running the command:\n1.  Open Keychain Access.app<\/strong> (Applications > Utilities > Keychain Access).\n2.  Select "System" under "Keychains" on the left sidebar.\n3.  Select "Certificates" under "Category" on the left sidebar.\n4.  Search for "Local Development CA" (or whatever CN you used).\n5.  Double-click your CA certificate.\n6.  Expand the "Trust" section.\n7.  For "When using this certificate:", select "Always Trust" from the dropdown.\n8.  Close the window, and you'll be prompted to enter your password again to save changes.<\/p>\n\n
            [!IMPORTANT]\nSome applications, especially those from Homebrew, might use a different OpenSSL configuration that doesn't directly leverage the macOS Keychain. This requires additional steps.<\/p><\/blockquote>\n\n
            3. Configure Applications and Development Runtimes to Use the Trusted CA<\/h4>\n\n
            Even after adding to Keychain, some applications might still fail. This is because they might be looking for certificates in specific locations or using their own bundled CAs.<\/p>\n\n
            a. For curl<\/code> and Homebrew-installed OpenSSL<\/h5>\n\n
            Homebrew-installed OpenSSL typically looks for trusted certificates in \/usr\/local\/etc\/openssl@3\/certs\/<\/code>. You need to symlink your CA certificate there and then rehash the directory.<\/p>\n\n
            # Assuming your CA certificate is ~\/certs\/local-ca\/ca.crt\nCA_CERT_PATH=~\/certs\/local-ca\/ca.crt<\/code><\/pre>\n\n
            Create a symlink to your CA cert in OpenSSL's certs directory\nln -s "$CACERT<\/em>PATH" "$OPENSSLCERTS<\/em>DIR\/$(openssl x509 -hash -noout -in "$CACERT<\/em>PATH").0"<\/h1>\n\n
            Update OpenSSL's certificate trust store\n# This command re-scans the directory and creates necessary links\n\/usr\/local\/opt\/openssl@3\/bin\/crehash "$OPENSSL<\/em>CERTS_DIR"\n<\/code>`<\/h1>\n\n
            Now, test curl<\/code>:\n<\/code>`bash\ncurl https:\/\/localhost:8443\/ # Replace with your local service URL\n<\/code>`\nIt should now connect successfully without -k<\/code> or --insecure<\/code>.<\/p>\n\n
            b. For Node.js Applications<\/h5>\n\n
            Node.js can be configured using the NODEEXTRA<\/em>CA_CERTS<\/code> environment variable.<\/p>\n\n
            # Add this to your shell profile (.bashrc, .zshrc, .profile)<\/code><\/pre>\n\n
            Or set it when running a specific command\nNODEEXTRA<\/em>CACERTS=~\/certs\/local-ca\/ca.crt node your<\/em>app.js\n<\/code>`<\/h1>\n\n
            [!NOTE]\nFor Electron apps or webviews, ensuring the certificate is trusted in Keychain Access (Step 2) is usually sufficient, as they often leverage the system's trust store.<\/p><\/blockquote>\n\n
            c. For Python Applications (e.g., requests<\/code> library)<\/h5>\n\n
            Python's requests<\/code> library often uses certifi<\/code> which has its own bundle. You can specify an additional CA bundle.<\/p>\n\n
            # Add this to your shell profile (.bashrc, .zshrc, .profile)<\/code><\/pre>\n\n
            Or set it when running a specific script\nREQUESTSCA<\/em>BUNDLE=~\/certs\/local-ca\/ca.crt python your_script.py\n<\/code>`<\/h1>\n\n
            Alternatively, you can modify the certifi<\/code> bundle directly (less recommended for maintainability) or pass the verify<\/code> parameter to requests<\/code> (not recommended for general use, but useful for debugging).<\/p>\n\n
            d. For PHP Applications (cURL extension)<\/h5>\n\n
            PHP's cURL extension, when compiled against OpenSSL, might need the CURLOPT_CAINFO<\/code> option or a global curl.cainfo<\/code> setting.<\/p>\n\n
            <?php\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL, "https:\/\/localhost:8443\/");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\/\/ Specify the path to your CA certificate\ncurl_setopt($ch, CURLOPT_CAINFO, "\/Users\/youruser\/certs\/local-ca\/ca.crt");\n$output = curl_exec($ch);\nif (curl_errno($ch)) {\n    echo 'Curl error: ' . curl_error($ch);\n}\ncurl_close($ch);\necho $output;\n?><\/code><\/pre>\n\n
            For a more global approach, you can set the SSLCERT<\/em>FILE<\/code> environment variable for the PHP process or ensure the OpenSSL ca-certificates<\/code> package (if applicable to your PHP setup, e.g., via Homebrew or Docker) is updated with your CA.<\/p>\n\n
            e. For Ruby Applications<\/h5>\n\n
            Ruby's Net::HTTP<\/code> and other libraries that use OpenSSL typically respect the SSLCERT<\/em>FILE<\/code> or SSLCERT<\/em>DIR<\/code> environment variables.<\/p>\n\n
            # Add this to your shell profile (.bashrc, .zshrc, .profile)<\/code><\/pre>\n\n
            Or set it when running a specific script\nSSLCERT<\/em>FILE=~\/certs\/local-ca\/ca.crt ruby your_script.rb\n<\/code>`<\/h1>\n\n
            f. For Git<\/h5>\n\n
            Git can be configured to trust your CA certificate.<\/p>\n\n
            git config --global http.sslCAInfo ~\/certs\/local-ca\/ca.crt<\/code><\/pre>\n\n
            [!WARNING]\nWhile git config --global http.sslVerify false<\/code> can temporarily fix issues, it's a security risk<\/strong> as it disables all SSL verification. Only use it for temporary debugging and never in production or for sensitive operations. Always prefer to properly trust the certificate.<\/p><\/blockquote>\n\n
            4. Restart Services and Applications<\/h4>\n\n
            After making changes to environment variables or adding certificates, it's crucial to restart any applications, terminals, or services that rely on these configurations. A full system reboot might sometimes be necessary to ensure all processes pick up the new trust settings, especially for GUI applications.<\/p>\n\n
            For Docker containers, if your container is the one initiating the connection to an external (or host-local) HTTPS service and needs to trust your CA, you'll need to inject your ca.crt<\/code> into the container's trust store.<\/p>\n\n
            Example for a Debian\/Ubuntu-based Docker container:<\/strong><\/p>\n\n
            1.  Copy your CA certificate into the container's build context.<\/li>
            2.  Modify your Dockerfile<\/code>:<\/li>
            3.     <\/code>`dockerfile<\/li>
            4.     # In your Dockerfile<\/li>
            5.     COPY ~\/certs\/local-ca\/ca.crt \/usr\/local\/share\/ca-certificates\/local-dev-ca.crt<\/li>
            6.     RUN chmod 644 \/usr\/local\/share\/ca-certificates\/local-dev-ca.crt && update-ca-certificates<\/li>
            7.     <\/code>`<\/li>
            8.     This adds your CA to the container's trust store, making applications inside the container trust it.<\/li><\/ol>\n\n
              By following these detailed steps, you should successfully overcome the "self signed certificate in certificate chain validation" errors on your macOS local development environment, leading to a much smoother and more secure development workflow.<\/p>","protected":false},"excerpt":{"rendered":"
              Resolve OpenSSL validation issues with self-signed certificates on macOS. Learn to trust local development certificates in Keychain Access and for various tools.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[26],"tags":[41,48,47,240,268,27],"class_list":["post-99","post","type-post","status-publish","format-standard","hentry","category-ssl-certs","tag-certificate-validation","tag-local-development","tag-macos","tag-openssl","tag-self-signed","tag-ssl"],"_links":{"self":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts\/99","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=99"}],"version-history":[{"count":1,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts\/99\/revisions"}],"predecessor-version":[{"id":218,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=\/wp\/v2\/posts\/99\/revisions\/218"}],"wp:attachment":[{"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=99"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=99"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/staging.butitworkedlocal.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=99"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}