devicecheck

package
v0.6.16 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package devicecheck provides Go bindings for the DeviceCheck framework.

Reduce fraudulent use of your services by managing device state and asserting app integrity.

The DeviceCheck services consist of both a framework interface that you access from your app and an Apple server interface that you access from your own server.

Device identification

App Attest

Errors

  • DCError: DeviceCheck error codes.
  • DCErrorDomain: The error domain for errors associated with DeviceCheck APIs.//

Key Types

  • DCAppAttestService - A service that you use to validate the instance of your app running on a device.
  • DCDevice - A representation of a device that provides a unique, authenticated token.

Code generated from Apple documentation. DO NOT EDIT.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DCErrorDomain is the error domain for errors associated with DeviceCheck APIs.
	//
	// See: https://developer.apple.com/documentation/DeviceCheck/DCErrorDomain
	DCErrorDomain foundation.NSErrorDomain
)

Functions

func NewDataErrorBlock 

func NewDataErrorBlock(handler DataErrorHandler) (objc.ID, func())

NewDataErrorBlock wraps a Go DataErrorHandler as an Objective-C block. The caller must defer the returned cleanup function.

Used by:

func NewStringErrorBlock 

func NewStringErrorBlock(handler StringErrorHandler) (objc.ID, func())

NewStringErrorBlock wraps a Go StringErrorHandler as an Objective-C block. The caller must defer the returned cleanup function.

Used by:

Types

type DCAppAttestService 

type DCAppAttestService struct {
	objectivec.Object
}

A service that you use to validate the instance of your app running on a device.

Overview

Use the DCAppAttestServiceClass.SharedService instance of the DCAppAttestService class to assert the legitimacy of a particular instance of your app to your server. After ensuring service availability by reading the [DCAppAttestService.Supported] property, you use the service to:

- Create a cryptographic key in the Secure Enclave by calling the DCAppAttestService.GenerateKeyWithCompletionHandler method. - Ask Apple to certify the key by calling the DCAppAttestService.AttestKeyClientDataHashCompletionHandler method. - Prepare an assertion of your app’s integrity to accompany any or all server requests using the DCAppAttestService.GenerateAssertionClientDataHashCompletionHandler method.

For more information about how to support App Attest in your app, see Establishing your app’s integrity. For information about the complementary procedures you implement on your server, see Validating apps that connect to your server.

Accessing the service

Preparing a key

Validating the app instance

See: https://developer.apple.com/documentation/DeviceCheck/DCAppAttestService

func DCAppAttestServiceFromID 

func DCAppAttestServiceFromID(id objc.ID) DCAppAttestService

DCAppAttestServiceFromID constructs a DCAppAttestService from an objc.ID.

A service that you use to validate the instance of your app running on a device.

func NewDCAppAttestService 

func NewDCAppAttestService() DCAppAttestService

NewDCAppAttestService creates a new DCAppAttestService instance.

func (DCAppAttestService) AttestKeyClientDataHash 

func (d DCAppAttestService) AttestKeyClientDataHash(ctx context.Context, keyId string, clientDataHash foundation.NSData) (*foundation.NSData, error)

AttestKeyClientDataHash is a synchronous wrapper around DCAppAttestService.AttestKeyClientDataHashCompletionHandler. It blocks until the completion handler fires or the context is cancelled.

func (DCAppAttestService) AttestKeyClientDataHashCompletionHandler 

func (d DCAppAttestService) AttestKeyClientDataHashCompletionHandler(keyId string, clientDataHash foundation.NSData, completionHandler DataErrorHandler)

Asks Apple to attest to the validity of a generated cryptographic key.

keyId: The identifier you received when generating a cryptographic key by calling the DCAppAttestService.GenerateKeyWithCompletionHandler method.

clientDataHash: A SHA256 hash of a unique, single-use data block that embeds a challenge from your server. Should be at least 16 bytes in length.

completionHandler: A closure that the method calls upon completion with the following parameters:

- `attestationObject`: A statement from Apple about the validity of the key associated with `keyId`. Send this to your server for processing. - `error`: A DCError instance that indicates the reason for failure, or `nil` on success.

Discussion

This method asks Apple to attest to the validity of a key that you previously generated with a call to the DCAppAttestService.GenerateKeyWithCompletionHandler method. Provide the method with both the key identifier and a computed hash of a data block that includes a one-time challenge from your server to prevent replay attacks. For example, you can use CryptoKit to create a SHA256 hash of challenge data:

The attest method calls its completion handler to return an attestation object to you, which you must send to your server for verification. A compromised version of your app could falsify the verification result, thus circumventing App Attest.

If you successfully verify the attestation object on your server, as described in Validating apps that connect to your server, then you can associate the key identifier with the user on the device for future reference. You’ll need the identifier to generate assertions with calls to DCAppAttestService.GenerateAssertionClientDataHashCompletionHandler. If your server fails to verify the attestation object, discard the key identifier.

If the method’s completion handler returns the serverUnavailable error — typically due to network connectivity issues — it means that the framework failed to reach the App Attest service to complete the attestation. In this case, retry attestation again using the same key and client data hash later to avoid unnecessarily generating new keys. Retrying with the same inputs helps to preserve the risk metric for a given device.

See: https://developer.apple.com/documentation/DeviceCheck/DCAppAttestService/attestKey(_:clientDataHash:completionHandler:)

func (DCAppAttestService) Autorelease 

func (d DCAppAttestService) Autorelease() DCAppAttestService

Autorelease adds the receiver to the current autorelease pool.

func (DCAppAttestService) GenerateAssertionClientDataHash 

func (d DCAppAttestService) GenerateAssertionClientDataHash(ctx context.Context, keyId string, clientDataHash foundation.NSData) (*foundation.NSData, error)

GenerateAssertionClientDataHash is a synchronous wrapper around DCAppAttestService.GenerateAssertionClientDataHashCompletionHandler. It blocks until the completion handler fires or the context is cancelled.

func (DCAppAttestService) GenerateAssertionClientDataHashCompletionHandler 

func (d DCAppAttestService) GenerateAssertionClientDataHashCompletionHandler(keyId string, clientDataHash foundation.NSData, completionHandler DataErrorHandler)

Creates a block of data that demonstrates the legitimacy of an instance of your app running on a device.

keyId: The identifier you received when generating a cryptographic key by calling the DCAppAttestService.GenerateKeyWithCompletionHandler method.

clientDataHash: A SHA256 hash of a unique, single-use data block that represents the client data to be signed with the attested private key. Should be at least 16 bytes in length.

completionHandler: A closure that the method calls upon completion with the following parameters:

- `assertionObject`: A data structure that you send to your server for processing. - `error` : A DCError instance that indicates the reason for failure, or `nil` on success.

Discussion

After generating a key with the DCAppAttestService.GenerateKeyWithCompletionHandler method and validating it with the DCAppAttestService.AttestKeyClientDataHashCompletionHandler method, you can use the key at critical moments in your app’s life cycle — like when a user tries to access premium content — to reaffirm the legitimacy of a given instance of your app. Do this by using the DCAppAttestService.GenerateAssertionClientDataHashCompletionHandler method to sign server requests with your attested key.

You provide the key identifier and a hash of the request that includes a challenge from your server to prevent replay attacks, where an attacker reuses captured network traffic to pose as someone else. The method returns an assertion object in its completion handler that you send to your server for verification, as described in Establishing your app’s integrity.

See: https://developer.apple.com/documentation/DeviceCheck/DCAppAttestService/generateAssertion(_:clientDataHash:completionHandler:)

func (DCAppAttestService) GenerateKey 

func (d DCAppAttestService) GenerateKey(ctx context.Context) (*string, error)

GenerateKey is a synchronous wrapper around DCAppAttestService.GenerateKeyWithCompletionHandler. It blocks until the completion handler fires or the context is cancelled.

func (DCAppAttestService) GenerateKeyWithCompletionHandler 

func (d DCAppAttestService) GenerateKeyWithCompletionHandler(completionHandler StringErrorHandler)

Creates a new cryptographic key for use with the App Attest service.

completionHandler: A closure that the method calls upon completion with the following parameters:

- `keyId`: An identifier that you use to refer to the key. The framework securely stores the key in the Secure Enclave. - `error`: A DCError instance that indicates the reason for failure, or `nil` on success.

Discussion

Call this method to request the creation of a secure, unattested key pair on a device for a specific user. On success, the method provides your app with an identifier that represents the key pair stored in the Secure Enclave. Because there’s no way to use or retrieve the key without the identifier, you’ll want to either record it in your app or on your server right away. If key generation fails, the closure provides a DCError that indicates the reason for the failure.

Create a unique key for each user account on a device. Otherwise it’s hard to detect an attack that uses a single compromised device to serve multiple remote users running a compromised version of your app. For more information, see Assessing fraud risk.

After you get the identifier, you call the DCAppAttestService.AttestKeyClientDataHashCompletionHandler method with the key identifier to ask Apple to attest to the validity of the associated key. Later, you call the DCAppAttestService.GenerateAssertionClientDataHashCompletionHandler method with the key identifier to answer a challenge from your server, and establish the legitimacy of this instance of your app.

See: https://developer.apple.com/documentation/DeviceCheck/DCAppAttestService/generateKey(completionHandler:)

func (DCAppAttestService) Init 

func (d DCAppAttestService) Init() DCAppAttestService

Init initializes the instance.

func (DCAppAttestService) IsSupported 

func (d DCAppAttestService) IsSupported() bool

A Boolean value that indicates whether a particular device provides the App Attest service.

Discussion

If you read [DCAppAttestService.Supported] from within an app extension, the value might be true or false, depending on the extension type. However, most extensions don’t support App Attest. The DCAppAttestService.GenerateKeyWithCompletionHandler method fails when you call it from an app extension, regardless of the value of [DCAppAttestService.Supported].

The only app extensions that support App Attest are watchOS extensions in watchOS 9 or later. For these extensions, you can use the results from [DCAppAttestService.Supported] to indicate whether your WatchKit extension bypasses attestation.

See: https://developer.apple.com/documentation/DeviceCheck/DCAppAttestService/isSupported

type DCAppAttestServiceClass 

type DCAppAttestServiceClass struct {
	// contains filtered or unexported fields
}

func GetDCAppAttestServiceClass 

func GetDCAppAttestServiceClass() DCAppAttestServiceClass

GetDCAppAttestServiceClass returns the class object for DCAppAttestService.

func (DCAppAttestServiceClass) Alloc 

func (dc DCAppAttestServiceClass) Alloc() DCAppAttestService

Alloc allocates memory for a new instance of the class.

func (DCAppAttestServiceClass) Class 

func (dc DCAppAttestServiceClass) Class() objc.Class

Class returns the underlying Objective-C class pointer.

func (DCAppAttestServiceClass) SharedService 

func (_DCAppAttestServiceClass DCAppAttestServiceClass) SharedService() DCAppAttestService

The shared App Attest service that you use to validate your app.

Discussion

Use the shared instance of the service to generate and to certify a cryptographic key, and then to assert your app’s validity using that key.

See: https://developer.apple.com/documentation/DeviceCheck/DCAppAttestService/shared

type DCDevice 

type DCDevice struct {
	objectivec.Object
}

A representation of a device that provides a unique, authenticated token.

Overview

Use the shared instance of the DCDevice class to generate a token that identifies a device. Call the DCDevice.GenerateTokenWithCompletionHandler method to get the token, and then send it to your server:

On your server, combine the token with an authentication key that you obtain from Apple, and use the result to request access to two per-device binary digits (bits). After authenticating the device, Apple passes the current values of the bits, along with the date they were last modified, to your server. Your server applies its business logic to this information and communicates the results to your app. For more information about server-side procedures, see Accessing and modifying per-device data.

Apple records the bits for you, and reports the bits back to you, but you’re responsible for keeping track of what the bits mean. You’re also responsible for determining when to reset the bits for a given device; for example, when a user sells the device to someone else.

Determining API support

  • DCDevice.IsSupported: A Boolean value that indicates whether the device supports the DeviceCheck API.

Getting a device token

See: https://developer.apple.com/documentation/DeviceCheck/DCDevice

func DCDeviceFromID 

func DCDeviceFromID(id objc.ID) DCDevice

DCDeviceFromID constructs a DCDevice from an objc.ID.

A representation of a device that provides a unique, authenticated token.

func NewDCDevice 

func NewDCDevice() DCDevice

NewDCDevice creates a new DCDevice instance.

func (DCDevice) Autorelease 

func (d DCDevice) Autorelease() DCDevice

Autorelease adds the receiver to the current autorelease pool.

func (DCDevice) GenerateToken 

func (d DCDevice) GenerateToken(ctx context.Context) (*foundation.NSData, error)

GenerateToken is a synchronous wrapper around DCDevice.GenerateTokenWithCompletionHandler. It blocks until the completion handler fires or the context is cancelled.

func (DCDevice) GenerateTokenWithCompletionHandler 

func (d DCDevice) GenerateTokenWithCompletionHandler(completion DataErrorHandler)

Generates a token that identifies the current device.

completion: A completion block that includes the following parameters:

- `token`: An ephemeral token that identifies the current device. - `error`: The error that occurred, if any.

Discussion

Your server uses the generated token in its requests to get or set the persistent bits for the current device. You should treat the token you receive in the completion block as single-use. Although the token remains valid long enough for your server to retry a specific request if necessary, you should not use a token multiple times. Instead, use this method to generate a new token.

See: https://developer.apple.com/documentation/DeviceCheck/DCDevice/generateToken(completionHandler:)

func (DCDevice) Init 

func (d DCDevice) Init() DCDevice

Init initializes the instance.

func (DCDevice) IsSupported 

func (d DCDevice) IsSupported() bool

A Boolean value that indicates whether the device supports the DeviceCheck API.

See: https://developer.apple.com/documentation/DeviceCheck/DCDevice/isSupported

type DCDeviceClass 

type DCDeviceClass struct {
	// contains filtered or unexported fields
}

func GetDCDeviceClass 

func GetDCDeviceClass() DCDeviceClass

GetDCDeviceClass returns the class object for DCDevice.

func (DCDeviceClass) Alloc 

func (dc DCDeviceClass) Alloc() DCDevice

Alloc allocates memory for a new instance of the class.

func (DCDeviceClass) Class 

func (dc DCDeviceClass) Class() objc.Class

Class returns the underlying Objective-C class pointer.

func (DCDeviceClass) CurrentDevice 

func (_DCDeviceClass DCDeviceClass) CurrentDevice() DCDevice

A representation of the device for which you want to query the two bits of data.

See: https://developer.apple.com/documentation/DeviceCheck/DCDevice/current

type DCError 

type DCError int

See: https://developer.apple.com/documentation/DeviceCheck/DCError-swift.struct/Code 

const (
	// DCErrorFeatureUnsupported: DeviceCheck is unavailable on this device.
	DCErrorFeatureUnsupported DCError = 1
	// DCErrorInvalidInput: An error code that indicates when your app provides data that isn’t formatted correctly.
	DCErrorInvalidInput DCError = 2
	// DCErrorInvalidKey: An error caused by a failed attempt to use the App Attest key.
	DCErrorInvalidKey DCError = 3
	// DCErrorServerUnavailable: An error that indicates a failed attempt to contact the App Attest service during an attestation.
	DCErrorServerUnavailable DCError = 4
	// DCErrorUnknownSystemFailure: A failure has occurred, such as the failure to generate a token.
	DCErrorUnknownSystemFailure DCError = 0
)

func (DCError) String 

func (e DCError) String() string

type DataErrorHandler 

type DataErrorHandler = func(*foundation.NSData, error)

DataErrorHandler handles A closure that the method calls upon completion with the following parameters: The error can be type-asserted to *foundation.NSError for Domain, Code, and UserInfo.

Used by:

type IDCAppAttestService 

type IDCAppAttestService interface {
	objectivec.IObject

	// A Boolean value that indicates whether a particular device provides the App Attest service.
	IsSupported() bool

	// Creates a new cryptographic key for use with the App Attest service.
	GenerateKeyWithCompletionHandler(completionHandler StringErrorHandler)
	// Asks Apple to attest to the validity of a generated cryptographic key.
	AttestKeyClientDataHashCompletionHandler(keyId string, clientDataHash foundation.NSData, completionHandler DataErrorHandler)

	// Creates a block of data that demonstrates the legitimacy of an instance of your app running on a device.
	GenerateAssertionClientDataHashCompletionHandler(keyId string, clientDataHash foundation.NSData, completionHandler DataErrorHandler)
}

An interface definition for the DCAppAttestService class.

Accessing the service

Preparing a key

Validating the app instance

See: https://developer.apple.com/documentation/DeviceCheck/DCAppAttestService

type IDCDevice 

type IDCDevice interface {
	objectivec.IObject

	// A Boolean value that indicates whether the device supports the DeviceCheck API.
	IsSupported() bool

	// Generates a token that identifies the current device.
	GenerateTokenWithCompletionHandler(completion DataErrorHandler)
}

An interface definition for the DCDevice class.

Determining API support

Getting a device token

See: https://developer.apple.com/documentation/DeviceCheck/DCDevice

type StringErrorHandler 

type StringErrorHandler = func(*string, error)

StringErrorHandler handles A closure that the method calls upon completion with the following parameters: The error can be type-asserted to *foundation.NSError for Domain, Code, and UserInfo.

Used by:

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.