ClientCertificateInstall CSP

The ClientCertificateInstall configuration service provider enables the enterprise to install client certificates. A client certificate has a unique ID, which is the [UniqueID] for this configuration. Each client certificate must have different UniqueIDs for the SCEP enrollment request.

For PFX certificate installation and SCEP installation, the SyncML commands must be wrapped in atomic commands to ensure enrollment execution is not triggered until all settings are configured. The Enroll command must be the last item in the atomic block.

Note
Currently in Windows 10, version 1511, when using the ClientCertificateInstall to install certificates to the device store and the user store and both certificates are sent to the device in the same MDM payload, the certificate intended for the device store will also get installed in the user store. This may cause issues with Wi-Fi or VPN when choosing the correct certificate to establish a connection. We are working to fix this issue.

You can only set PFXKeyExportable to true if KeyLocation=3. For any other KeyLocation value, the CSP will fail.

The following image shows the ClientCertificateInstall configuration service provider in tree format.

clientcertificateinstall csp

Device or User

For device certificates, use ./Device/Vendor/MSFT path and for user certificates use ./User/Vendor/MSFT path.

ClientCertificateInstall

The root node for the ClientCertificateInstaller configuration service provider.

ClientCertificateInstall/PFXCertInstall

Required for PFX certificate installation. The parent node grouping the PFX certificate related settings.

Supported operation is Get.

ClientCertificateInstall/PFXCertInstall/UniqueID

Required for PFX certificate installation. A unique ID to differentiate different certificate install requests.

The data type format is node.

Supported operations are Get, Add, and Replace.

Calling Delete on this node should delete the certificates and the keys that were installed by the corresponding PFX blob.

ClientCertificateInstall/PFXCertInstall/UniqueID/KeyLocation

Required for PFX certificate installation. Indicates the KeyStorage provider to target the private key installation to.

Supported operations are Get, Add, and Replace.

The data type is an integer corresponding to one of the following values:

Value Description
1 Install to TPM if present, fail if not present.
2 Install to TPM if present. If not present, fallback to software.
3 Install to software.
4 Install to Windows Hello for Business (formerly known as Microsoft Passport for Work) whose name is specified

ClientCertificateInstall/PFXCertInstall/UniqueID/ContainerName

Optional. Specifies the Windows Hello for Business (formerly known as Microsoft Passport for Work) container name (if Windows Hello for Business storage provider (KSP) is chosen for the KeyLocation). If this node is not specified when Windows Hello for Business KSP is chosen, enrollment will fail.

Date type is string.

Supported operations are Get, Add, Delete, and Replace.

ClientCertificateInstall/PFXCertInstall/UniqueID/PFXCertBlob

CRYPT_DATA_BLOB structure that contains a PFX packet with the exported and encrypted certificates and keys. The Add operation triggers the addition to the PFX certificate. This requires that all the other nodes under UniqueID that are parameters for PFX installation (Container Name, KeyLocation, CertPassword, KeyExportable) are present before this is called. This also sets the Status node to the current Status of the operation.

The data type format is binary.

Supported operations are Get, Add, and Replace.

If a blob already exists, the Add operation will fail. If Replace is called on this node, the existing certificates are overwritten.

If Add is called on this node for a new PFX, the certificate will be added. When a certificate does not exist, Replace operation on this node will fail.

In other words, using Replace or Add will result in the effect of either overwriting the old certificate or adding a new certificate CRYPT_DATA_BLOB, which can be found in CRYPT_INTEGER_BLOB.

ClientCertificateInstall/PFXCertInstall/UniqueID/PFXCertPassword

Password that protects the PFX blob. This is required if the PFX is password protected.

Data Type is a string.

Supported operations are Get, Add, and Replace.

ClientCertificateInstall/PFXCertInstall/UniqueID/PFXCertPasswordEncryptionType

Optional. Used to specify whether the PFX certificate password is encrypted with the MDM certificate by the MDM server.

The data type is int. Valid values:

  • 0 - Password is not encrypted.
  • 1 - Password is encrypted with the MDM certificate.
  • 2 - Password is encrypted with custom certificate.

When PFXCertPasswordEncryptionType =2, you must specify the store name in PFXCertPasswordEncryptionStore setting.

Supported operations are Get, Add, and Replace.

ClientCertificateInstall/PFXCertInstall/UniqueID/PFXKeyExportable

Optional. Used to specify if the private key installed is exportable (and can be exported later). The PFX is not exportable when it is installed to TPM.

Note You can only set PFXKeyExportable to true if KeyLocation=3. For any other KeyLocation value, the CSP will fail.

The data type bool.

Supported operations are Get, Add, and Replace.

ClientCertificateInstall/PFXCertInstall/UniqueID/Thumbprint

Returns the thumbprint of the installed PFX certificate.

The datatype is a string.

Supported operation is Get.

ClientCertificateInstall/PFXCertInstall/UniqueID/Status

Required. Returns the error code of the PFX installation from the GetLastError command called after the PfxImportCertStore.

Data type is an integer.

Supported operation is Get.

ClientCertificateInstall/PFXCertInstall/UniqueID/PFXCertPasswordEncryptionStore

Added in Windows 10, version 1511. When PFXCertPasswordEncryptionType = 2, it specifies the store name of the certificate used for decrypting the PFXCertPassword.

Data type is string.

Supported operations are Add, Get, and Replace.

ClientCertificateInstall/SCEP

Node for SCEP.

Note An alert is sent after the SCEP certificate is installed.

ClientCertificateInstall/SCEP/UniqueID

A unique ID to differentiate different certificate installation requests.

ClientCertificateInstall/SCEP/UniqueID/Install

A node required for SCEP certificate enrollment. Parent node to group SCEP cert installation related requests.

Supported operations are Get, Add, Replace, and Delete.

Note Although the child nodes under Install support Replace commands, once the Exec command is sent to the device, the device will take the values that are set when the Exec command is accepted. The server should not expect the node value change after Exec command is accepted, as it will impact the current enrollment underway. The server should check the Status node value and make sure the device is not at an unknown state before changing child node values.

ClientCertificateInstall/SCEP/UniqueID/Install/ServerURL

Required for SCEP certificate enrollment. Specifies the certificate enrollment server. Multiple server URLs can be listed, separated by semicolons.

Data type is string.

Supported operations are Get, Add, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/Challenge

Required for SCEP certificate enrollment. B64 encoded SCEP enrollment challenge. Challenge is deleted shortly after the Exec command is accepted.

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/EKUMapping

Required. Specifies extended key usages. Subject to SCEP server configuration. The list of OIDs are separated by a plus +. For example, OID1+OID2+OID3.

Data type is string.

Required for enrollment. Specifies the key usage bits (0x80, 0x20, 0xA0, etc.) for the certificate in decimal format. The value should at least have the second (0x20), fourth (0x80) or both bits set. If the value doesn’t have those bits set, the configuration will fail.

Data type is int.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/SubjectName

Required. Specifies the subject name.

Data type is string.

Supported operations are Add, Get, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/KeyProtection

Optional. Specifies where to keep the private key.

Note Even if the private key is protected by TPM, it is not protected with a TPM PIN.

The data type is an integer corresponding to one of the following values:

Value Description
1 Private key protected by TPM.
2 Private key protected by phone TPM if the device supports TPM. All Windows Phone 8.1 devices support TPM and will treat value 2 as 1.
3 (Default) Private key saved in software KSP.
4 Private key protected by Windows Hello for Business (formerly known as Microsoft Passport for Work). If this option is specified, the ContainerName must be specifed, otherwise enrollment will fail.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/KeyUsage

Required for enrollment. Specify the key usage bits (0x80, 0x20, 0xA0, etc.) for the certificate in decimal format. The value should at least have second (0x20) or forth (0x80) or both bits set. If the value doesn’t have those bits set, configuration will fail.

Supported operations are Add, Get, Delete, and Replace. Value type is integer.

ClientCertificateInstall/SCEP/UniqueID/Install/RetryDelay

Optional. When the SCEP server sends a pending status, this value specifies the device retry waiting time in minutes.

Data type format is an integer.

The default value is 5.

The minimum value is 1.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/RetryCount

Optional. Unique to SCEP. Specifies the device retry times when the SCEP server sends a pending status.

Data type is integer.

Default value is 3.

Maximum value is 30. If the value is larger than 30, the device will use 30.

Minimum value is 0, which indicates no retry.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/TemplateName

Optional. OID of certificate template name.

Note This name is typically ignored by the SCEP server; therefore the MDM server typically doesn’t need to provide it.

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/KeyLength

Required for enrollment. Specify private key length (RSA).

Data type is integer.

Valid values are 1024, 2048, and 4096.

For Windows Hello for Business (formerly known as Microsoft Passport for Work) , only 2048 is the supported key length.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/HashAlgorithm

Required. Hash algorithm family (SHA-1, SHA-2, SHA-3) specified by MDM server. If multiple hash algorithm families are specified, they must be separated with +.

For Windows Hello for Business, only SHA256 is the supported algorithm.

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/CAThumbprint

Required. Specifies Root CA thumbprint. This is a 20-byte value of the SHA1 certificate hash specified as a hexadecimal string value. When client authenticates the SCEP server, it checks the CA certificate from the SCEP server to verify a match with this certificate. If it is not a match, the authentication will fail.

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/SubjectAlternativeNames

Optional. Specifies subject alternative names (SAN). Multiple alternative names can be specified by this node. Each name is the combination of name format+actual name. Refer to the name type definitions in MSDN for more information.

Each pair is separated by semicolon. For example, multiple SANs are presented in the format of [name format1]+[actual name1];[name format 2]+[actual name2].

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/ValidPeriod

Optional. Specifies the units for the valid certificate period.

Data type is string.

Valid values are:

  • Days (Default)
  • Months
  • Years

Note The device only sends the MDM server expected certificate validation period (ValidPeriodUnits + ValidPeriod) to the SCEP server as part of certificate enrollment request. Depending on the server configuration, the server defines how to use this valid period to create the certificate.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/ValidPeriodUnits

Optional. Specifies the desired number of units used in the validity period. This is subject to SCEP server configuration. Default value is 0. The unit type (days, months, or years) are defined in the ValidPeriod node. Note the valid period specified by MDM will overwrite the valid period specified in the certificate template. For example, if ValidPeriod is Days and ValidPeriodUnits is 30, it means the total valid duration is 30 days.

Data type is string.

Note The device only sends the MDM server expected certificate validation period (ValidPeriodUnits + ValidPeriod) to the SCEP server as part of certificate enrollment request. Depending on the server configuration, the server defines how to use this valid period to create the certificate.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/ContainerName

Optional. Specifies the Windows Hello for Business container name (if Windows Hello for Business KSP is chosen for the node). If this node is not specified when Windows Hello for Business KSP is chosen, the enrollment will fail.

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/CustomTextToShowInPrompt

Optional. Specifies the custom text to show on the Windows Hello for Business PIN prompt during certificate enrollment. The admin can choose to provide more contextual information in this field for why the user needs to enter the PIN and what the certificate will be used for.

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/Install/Enroll

Required. Triggers the device to start the certificate enrollment. The device will not notify MDM server after certificate enrollment is done. The MDM server could later query the device to find out whether new certificate is added.

The date type format is Null, meaning this node doesn’t contain a value.

The only supported operation is Execute.

ClientCertificateInstall/SCEP/UniqueID/Install/AADKeyIdentifierList

Optional. Specify the AAD Key Identifier List as a list of semicolon separated values. On Enroll, the values in this list are validated against the AAD Key present on the device. If no match is found, enrollment will fail.

Data type is string.

Supported operations are Add, Get, Delete, and Replace.

ClientCertificateInstall/SCEP/UniqueID/CertThumbprint

Optional. Specifies the current certificate’s thumbprint if certificate enrollment succeeds. It is a 20-byte value of the SHA1 certificate hash specified as a hexadecimal string value.

If the certificate on the device becomes invalid (Cert expired, Cert chain is not valid, private key deleted) then it will return an empty string.

Data type is string.

The only supported operation is Get.

ClientCertificateInstall/SCEP/UniqueID/Status

Required. Specifies latest status of the certificated during the enrollment request.

Data type is string. Valid values:

The only supported operation is Get.

Value Description
1 Finished successfully
2 Pending (the device hasn’t finished the action but has received the SCEP server pending response)
16 Action failed
32 Unknown

ClientCertificateInstall/SCEP/UniqueID/ErrorCode

Optional. An integer value that indicates the HRESULT of the last enrollment error code.

The only supported operation is Get.

ClientCertificateInstall/SCEP/UniqueID/RespondentServerUrl

Required. Returns the URL of the SCEP server that responded to the enrollment request.

Data type is string.

The only supported operation is Get.

Example

Enroll a client certificate through SCEP.

<SyncML xmlns="SYNCML:SYNCML1.2">
    <SyncBody>
        <Atomic>
        <Add>
            <CmdID>301</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere></LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">node</Format>
                </Meta>
            </Item>
        </Add>
        <Add>
            <CmdID>302</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/RetryCount</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">int</Format>
                </Meta>
                <Data>1</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>303</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/RetryDelay</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">int</Format>
                </Meta>
                <Data>1</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>304</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/KeyUsage</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">int</Format>
                </Meta>
                <Data>160</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>305</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/KeyLength</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">int</Format>
                </Meta>
                <Data>1024</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>306</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/HashAlgorithm</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data>SHA-1</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>307</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/SubjectName</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data>CN=ContosoCSP</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>308</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/SubjectAlternativeNames</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data></Data>
            </Item>
        </Add>
        <Add>
            <CmdID>309</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/ValidPeriod</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data>Years</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>310</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/ValidPeriodUnits</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">int</Format>
                </Meta>
                <Data>1</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>311</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/EKUMapping</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data>1.3.6.1.4.1.311.10.3.12+1.3.6.1.4.1.311.10.3.4+1.3.6.1.4.1.311.20.2.2+1.3.6.1.5.5.7.3.2</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>312</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/KeyProtection</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">int</Format>
                </Meta>
                <Data>3</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>313$</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/ServerURL</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data>http://constoso.com/certsrv/mscep/mscep.dll</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>314</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/Challenge</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data>1234CB055B7EBF384A9486A22B7559A5</Data>
            </Item>
        </Add>
        <Add>
            <CmdID>315</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/CAThumbprint</LocURI>
                </Target>
                <Meta>
                    <Format xmlns="syncml:metinf">chr</Format>
                </Meta>
                <Data>12345087E648875D1DF5D9F9FF89DD10</Data>
            </Item>
        </Add>
        <Exec>
            <CmdID>316</CmdID>
            <Item>
                <Target>
                    <LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/<InsertUniqueIDHere>/Install/Enroll</LocURI>
                </Target>
            </Item>
        </Exec>
        </Atomic>
        <Final/>
    </SyncBody>
</SyncML>

Add a PFX certificate. The PFX certificate password is encrypted with a custom certificate fro "My" store.

<SyncML>
    <SyncBody>
            <Delete>
                <CmdID>$CmdID$</CmdID>
                <Item>
                    <Target>
                        <LocURI>./User/Vendor/MSFT/ClientCertificateInstall/PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D351900C</LocURI>
                    </Target>
                </Item>
            </Delete>
        <Atomic>
            <CmdID>$CmdID$</CmdID>
            <Add>
                <CmdID>$CmdID$</CmdID>
                <Item>
                    <Target>
                        <LocURI>./User/Vendor/MSFT/ClientCertificateInstall/PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D351900C/KeyLocation</LocURI>
                    </Target>
                    <Meta>
                        <Format xmlns="syncml:metinf">int</Format>
                    </Meta>
                    <Data>2</Data>
                </Item>
            </Add>
            <Add>
                <CmdID>$CmdID$</CmdID>
                <Item>
                    <Target>
                        <LocURI>./User/Vendor/MSFT/ClientCertificateInstall/PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D351900C/PFXCertBlob</LocURI>
                    </Target>
                     <Meta>
                        <Format xmlns="syncml:metinf">chr</Format>
                    </Meta>
                    <Data>Base64_Encode_Cert_Blob</Data>
                </Item>
            </Add>
            <Add>
                <CmdID>$CmdID$</CmdID>
                <Item>
                    <Target>
                        <LocURI>./User/Vendor/MSFT/ClientCertificateInstall/PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D351900C/PFXCertPassword</LocURI>
                    </Target>
                     <Meta>
                        <Format xmlns="syncml:metinf">chr</Format>
                    </Meta>
                    <Data>Base64Encoded_Encrypted_Password_Blog</Data>
                </Item>
            </Add>
            <Add>
                <CmdID>$CmdID$</CmdID>
                <Item>
                    <Target>
                        <LocURI>./User/Vendor/MSFT/ClientCertificateInstall/PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D351900C/PFXCertPasswordEncryptionType</LocURI>
                    </Target>
                    <Meta>
                        <Format xmlns="syncml:metinf">int</Format>
                    </Meta>
                    <Data>2</Data>
                </Item>
            </Add>
            <Add>
                <CmdID>$CmdID$</CmdID>
                <Item>
                    <Target>
                        <LocURI>./User/Vendor/MSFT/ClientCertificateInstall/PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D351900C/PFXCertPasswordEncryptionStore</LocURI>
                    </Target>
                    <Meta>
                        <Format xmlns="syncml:metinf">chr</Format>
                    </Meta>
                    <Data>My</Data>
                </Item>
            </Add>

            <Add>
                <CmdID>$CmdID$</CmdID>
                <Item>
                    <Target>
                        <LocURI>./User/Vendor/MSFT/ClientCertificateInstall/PFXCertInstall/813A171D7341E1DA90D4A01878DD5328D351900C/PFXKeyExportable</LocURI>
                    </Target>
                    <Meta>
                        <Format xmlns="syncml:metinf">bool</Format>
                    </Meta>
                    <Data>true</Data>
                </Item>
            </Add>
        </Atomic>
    <Final/>
    </SyncBody>
</SyncML>

Configuration service provider reference