> For the complete documentation index, see [llms.txt](https://documentation.2pintsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.2pintsoftware.com/2pxe-server/planning/certificate-considerations.md). # Certificate Considerations 2PXE (2Pint Software's build of iPXE) comes pre-built with a limited set of trusted root certificates. This list includes a custom 2Pint Software CA certificate (public key available in the 2PXE installation directory under `x64\ca.crt` ) and the iPXE root CA (public key available here: ). Additionally, by way of cross-signing against the iPXE root CA certificate, the [Mozilla public CA list](#supported-certificate-configurations) is also trusted. Since these CA certificates need to be provided at build time, it is not possible to install your own internal PKI CA certificate for use as a trusted root CA for the initial bootstrapping of the 2PXE boot process. Additionally, because our 2PXE builds are signed by Microsoft which allow them to be trusted by Secure Boot, we are unable to make custom builds of 2PXE that include customer provided internal PKI CA certificates. This document outlines the supported certificate configurations for traditional 2PXE scenarios including any special configuration necessary to make the scenario supported. ## Supported Certificate Configurations {% hint style="info" %} **Note:** While certain configurations of certificates may have been tested to work, we're fans of keeping it simple. So, while it might work to use a Public certificate for 2PXE with a Cross-signed PKI certificate for iPXE Anywhere Web Service, this could be considered a needless complication when a simpler solution (use the public certificate for both services) is available. {% endhint %} Please note in the following table: * ***2PXE Generated*** refers to the certificate issued by the included 2PintSoftware.com CA certificate when 2PXE is not configured to use a different HostCertificateThumbprint * ***Cross-Signed Internal PKI*** refers to a certificate issued by a public key infrastructure (PKI) for your organization, whose root CA certificate has been cross-signed by the 2PintSoftware.com CA certificate. Please see [this link](#supported-certificate-configurations) for a list of supported algorithms for Internal PKI certificates. * ***Non-cross-signed Internal PKI*** refers to a certificate issued by a public key infrastructure (PKI) for your organization, whose root CA certificate has **NOT** been cross-signed by the 2PintSoftware.com CA certificate. * ***Public*** refers to a certificate issued by a publicly trusted certificate authority in the [Mozilla Root CA list](https://wiki.mozilla.org/CA/Included_Certificates).
2PXE (iPXE)iPXE Anywhere Web Service (WS)ConfigMgr (Internal PKI or eHTTPS)DeployR / OtherTested to Work
Any internal PKI CertificateN/AN/AN/A❌*
2PXE Generated or PublicNot installedConfigured (2PXE installed on DP)N/A✅
2PXE Generated or PublicCross-signed Internal PKIN/AN/A❌*
2PXE Generated or Public2PXE Generated or PublicN/A2PXE Generated or Public✅
2PXE Generated or Public2PXE Generated or PublicN/ACross-signed Internal PKI✅**
2PXE Generated or Public2PXE Generated or PublicN/ANon-cross-signed Internal PKI❌
\*Because the iPXE binaries are pre-compiled with limited trusted root certificates, only certificates issued by the 2PintSoftware.com CA (self-generated scenario) or a certificate authority in the [Mozilla Root CA list](https://wiki.mozilla.org/CA/Included_Certificates) can be used to boot iPXE/2PXE \*\*This is a supported scenario but requires modifications to the iPXE WS scripts to download and install the root CA certificate from your Internal PKI. See [#manually-installing-root-ca-certificates-to-ipxe-certificate-store](#manually-installing-root-ca-certificates-to-ipxe-certificate-store "mention") below. ## Example Configurations The following is not an exhaustive list of possible configurations, but rather a set of four of the most common configurations we see in customer environments. ### Public Certificate for All Services This configuration assumes that all services run on the same server and use the same FQDN or CNAME for DNS resolution. Additionally, this assumes that the public certificate has been issued to your server (or a wildcard for your domain) and is installed in the personal store for the local computer. #### 2PXE Settings Edit the following values in the `2Pint.2PXE.Service.exe.config` file and then restart the "2Pint 2PXE Server" service: * **ExternalFQDNOverride:** should match either the subject or a subject alternative name (SAN) of the public certificate. * **HostCertificateThumbprint:** should match the thumbprint of the public certificate #### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of the public certificate #### DeployR Settings Edit the following values in the DeployR Config Editor and then restart the "2Pint Software DeployR Service": * **Certificate location mechanism:** "CertificateThumbprint" * **Certificate thumbprint:** should match the thumbprint of the public certificate ### 2PXE Generated for All Services This configuration assumes that all services run on the same server and use the same FQDN or CNAME for DNS resolution. #### 2PXE Settings Edit the following values in the `2Pint.2PXE.Service.exe.config` file and then restart the "2Pint 2PXE Server" service: * **ExternalFQDNOverride:** should match the FQDN of the server as you wish it to be presented to connecting clients * **HostCertificateThumbprint:** this value should be empty ("") After setting these values and restarting the "2Pint 2PXE Server", a 2PXE generated certificate is created and stored in the local computer personal certificate store (as well as `%ProgramData%\2Pint Software\2PXE\Certificates` by default). You need to get the thumbprint for this certificate for use in later values:
#### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of the 2PXE generated certificate (captured above) #### DeployR Settings Edit the following values in the DeployR Config Editor and then restart the "2Pint Software DeployR Service": * **Certificate location mechanism:** "CertificateThumbprint" * **Certificate thumbprint:** should match the thumbprint of the 2PXE generated certificate (captured above) ### 2PXE Generated for 2PXE/WS, PKI For DeployR/Other This configuration assumes that all services run on the same server and use the same FQDN or CNAME for DNS resolution. This configuration also assumes that you wish to use a PKI certificate for the DeployR service instead of the 2PXE generated certificate. #### 2PXE Settings Edit the following values in the `2Pint.2PXE.Service.exe.config` file and then restart the "2Pint 2PXE Server" service: * **ExternalFQDNOverride:** should match the FQDN of the server as you wish it to be presented to connecting clients * **HostCertificateThumbprint:** this value should be empty ("") * **CustomCACertificate:** this value should be the thumbprint of the internal PKI root CA certificate After setting these values and restarting the "2Pint 2PXE Server", a 2PXE generated certificate is created and stored in the local computer personal certificate store (as well as `%ProgramData%\2Pint Software\2PXE\Certificates` by default). You need to get the thumbprint for this certificate for use in later values:
#### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of the 2PXE generated certificate (captured above) #### DeployR Settings Edit the following values in the DeployR Config Editor and then restart the "2Pint Software DeployR Service": * **Certificate location mechanism:** "CertificateThumbprint" * **Certificate thumbprint:** should match the thumbprint of the issued PKI certificate you have issued You will also need to force the cross signed certificate that was generated by changing the `CustomCACertificate` value into your PXE boot process, please see [this section](#manually-installing-root-ca-certificates-to-ipxe-certificate-store) of the document for that setup. ### 2PXE integration with ConfigMgr (SCCM) and eHTTPS/PKI This configuration assumes that the 2PXE server runs on a distribution point and the ConfigMgr environment is setup for HTTPS or eHTTPS mode. This is not a complete list of configurations necessary for the 2PXE integrations with ConfigMgr - just the relevant certificate configurations. #### 2PXE Settings Edit the following values in the `2Pint.2PXE.Service.exe.config` file and then restart the "2Pint 2PXE Server" service: * **ExternalFQDNOverride:** should match the FQDN of the server as you wish it to be presented to connecting clients * **HostCertificateThumbprint:** should be empty ("") to generate the 2PXE generated certificate or should match the thumbprint of a certificate that meets one of the following criteria: * Is the 2PXE generated certificate (same thumbprint as used by 2PXE) * Is a certificate signed by a publicly trusted root CA * **EnableSCCMExtension:** should equal 1 to enable 2PXE to gather and cross-sign the relevant certificates from the distribution point * **SCCMCAThumbprint:** in most cases will be empty (""), except when using public certificates with ConfigMgr in which case it should be the thumbprint of the root CA certificate which generated the certificate for the distribution point After setting these values and restarting the "2Pint 2PXE Server", a 2PXE generated certificate is created and stored in the local computer personal certificate store (as well as `%ProgramData%\2Pint Software\2PXE\Certificates` by default). You need to get the thumbprint for this certificate for use in later values:
#### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of a certificate that meets one of the following criteria: * Is the 2PXE generated certificate (same thumbprint as used by 2PXE) * Is a certificate signed by a publicly trusted root CA ## Manually Installing Root CA Certificates to iPXE Certificate Store For an HTTPs call to be supported anywhere in your 2PXE boot process, the certificate presented by the web server must be signed by a root certificate trusted (signed or cross-signed) by the 2Pint Software CA or iPXE root CA certificates or signed by the 2Pint Software CA certificate itself (the "self-generated" scenario above). When using a certificate authority that is not trusted by 2PXE by default, the root CA must be imported into the iPXE certificate store. This is accomplished in an iPXE script using the [iPXE certstore](#supported-certificate-configurations) command. To enable booting or downloading of content from a server that uses an internal PKI certificate for HTTPs communication, the root CA certificate thumbprint must be configured in the 2PXE config file (`2Pint.2PXE.Services.exe.config`) under the `CustomCAThumprint` value. This generates the necessary cross-signed certificate which can be downloaded to the device during the boot process from 2PXE at the following URL: `https://`***`{2PXEFQDN}`***`/2PXE/Certificate/RootCA.crt` After configuring the `CustomCAThumbprint` value and restarting the 2PXE service, you should validate that the cross-signed certificate has been generated. By default, this certificate is stored at `%ProgramData%\2Pint Software\2PXE\Certificates\CrossSignedCert.crt`. Once you have validated the cross-signed certificate has been generated, you must then add the following lines to your `iPXEboot.ps1` file, or anywhere in your iPXE Web Service scripts before you make a call to download from a HTTPs endpoint which uses a certificate issued by the internal PKI: ``` $Paramdata certstore `${pxeurl}2PXE/Certificate/Cross.crt##params=paramdata ``` For example:
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://documentation.2pintsoftware.com/2pxe-server/planning/certificate-considerations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.