Certificate Transparency device management payload settings for Apple devices

Use the Certificate Transparency payload to control the behavior of Certificate Transparency enforcement for users of Apple devices. This custom payload doesn’t require a device management service or the device’s serial number to appear in Apple School Manager or Apple Business.

iOS, iPadOS, macOS, tvOS, watchOS 10, and visionOS 1.1 have Certificate Transparency requirements in order for TLS certificates to be trusted. Certificate Transparency involves submitting your server’s public certificate to a log that’s available to the public. If you use certificates for internal-only servers, you may not be able to show those servers and so won’t be able to use Certificate Transparency. As a result, the Certificate Transparency requirements causes certificate trust failures for your users.

This payload allows device administrators to selectively lower the Certificate Transparency requirements for internal domains and servers to avoid those trust failures on devices communicating with the internal servers.

The Certificate Transparency payload supports the following. For more information, see Payload information.

Supported payload identifier: com.apple.security.certificatetransparency
Supported operating systems and channels: iOS, iPadOS, Shared iPad device, macOS device, tvOS, watchOS 10, visionOS 1.1.
Supported enrollment methods: User Enrollment, Device Enrollment, Automated Device Enrollment.
Duplicates allowed: True—more than one Certificate Transparency payload can be delivered to a device.

You can use the settings in the table below with the Certificate Transparency payload.

Setting	Description	Required
Disable Certificate Transparency enforcement for specific certificates	Select this option to permit private, untrusted certificates by disabling the enforcement of Certificate Transparency. The certificates to be disabled need to contain (1) the algorithm that was used by the issuer to sign the certificate and (2) the public key that’s associated with the identity the certificate is issued to. For the specific values you need, see the rest of this table.	No.
Algorithm	The algorithm that was used by the issuer to sign the certificate. The value needs to be “sha256”.	Yes, if Disable Certificate Transparency enforcement for specific certificates is used.
Hash of `subjectPublicKeyInfo`	The public key associated with the identity the certificate is issued to.	Yes, if Disable Certificate Transparency enforcement for specific certificates is used.
Disable specific domains	A list of domains where certificate transparency is disabled. A leading period can be used to match subdomains, but a domain matching rule can’t match all domains within a top level domain. (“.com” and “.co.uk” aren’t allowed, but “.melardclothing.com” and “.melardclothing.co.uk” are allowed).	No.

Note: Each device management service developer implements these settings differently. To learn how various Certificate Transparency settings are applied to your devices, consult your developer’s device management service documentation.

How to create the hash of subjectPublicKeyInfo

In order for Certificate Transparency enforcement to be disabled when this policy is set, the subjectPublicKeyInfo hash needs to be one of the following:

The first method to stop Certificate Transparency enforcement
A hash of the server leaf certificate’s `subjectPublicKeyInfo` value.

The second method to stop Certificate Transparency enforcement
The hash is of a `subjectPublicKeyInfo` field of the root certificate or any intermediates in the certificate chain. That root or intermediate certificate is constrained via the X.509v3 `nameConstraints` extension. One or more `directoryName` `nameConstraints` are present in the `permittedSubtrees`. The `directoryName` contains an `organizationName` attribute.

The third method to stop Certificate Transparency enforcement
The hash is of a `subjectPublicKeyInfo` field of the root certificate or any intermediates in the certificate chain. That root or intermediate certificate has one or more `organizationName` attributes in the certificate Subject. The server’s leaf certificate contains the same number of `organizationName` attributes, in the same order, and is a precise match, with byte-for-byte identical values.

How to generate the specified data

In the subjectPublicKeyInfo dictionary, use the following commands:

PEM encoded certificate: openssl x509 -pubkey -in example_certificate.pem -inform pem | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64
DER encoded certificate: openssl x509 -pubkey -in example_certificate.der -inform der | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64

If your certificate doesn’t have a .pem or .der extension, use the following file commands to identify its encoding type:

file example_certificate.crt
file example_certificate.cer

To view a complete example of this custom payload, see the Certificate Transparency custom payload example.

Helpful?

Apple Platform Deployment

Certificate Transparency device management payload settings for Apple devices

How to create the hash of subjectPublicKeyInfo

How to generate the specified data