AppReceiptValidator

An iOS and macOS library intended for dealing with App Store receipts, offering basic local retrieval, validation and parsing of receipt files.

Provides Demo Apps on iOS and macOS to inspect receipt files.

Integration with Carthage

Add this line to your Cartfile.

github "IdeasOnCanvas/AppReceiptValidator"

Usage in Code

Apple advises to write your own code for receipt validation, and build and link OpenSSL statically to your app target. Anyways this repo might be a starting point for you, or be used as a dependency at your own risk, or might just be helpful for you to inspect receipts.

Just parsing a receipt

let receiptValidator = AppReceiptValidator()

let installedReceipt = receiptValidator.parseReceipt(origin: .installedInMainBundle)

let customReceipt = receiptValidator.parseReceipt(origin: .data(dataFromSomewhere))

Result may look like this:

Receipt(
    bundleIdentifier: com.some.bundleidentifier,
    bundleIdData: BVWNwKILNEWPOJWELKWEF=,
    appVersion: 1,
    opaqueValue: xN1AVLC2Gge+tYX2qELgSA==,
    sha1Hash: LgoRW+rBxXAjpb03NJlVqa2Z200=,
    originalAppVersion: 1.0,
    receiptCreationDate: 2015-08-13T07:50:46Z,
    expirationDate: nil,
    inAppPurchaseReceipts: [
    InAppPurchaseReceipt(
        quantity: nil,
        productIdentifier: consumable,
        transactionIdentifier: 1000000166865231,
        originalTransactionIdentifier: 1000000166865231,
        purchaseDate: 2015-08-07T20:37:55Z,
        originalPurchaseDate: 2015-08-07T20:37:55Z,
        subscriptionExpirationDate: nil,
        cancellationDate: nil,
        webOrderLineItemId: nil
    ),
    InAppPurchaseReceipt(
        quantity: nil,
        productIdentifier: monthly,
        transactionIdentifier: 1000000166965150,
        originalTransactionIdentifier: 1000000166965150,
        purchaseDate: 2015-08-10T06:49:32Z,
        originalPurchaseDate: 2015-08-10T06:49:33Z,
        subscriptionExpirationDate: 2015-08-10T06:54:32Z,
        cancellationDate: nil,
        webOrderLineItemId: nil
    )
    ]
)

Receipt is Equatable, so you can do comparisons in Unit Tests. There are also some opt-in unofficial attributes, but this is experimental and should not be used in production.

Validating a receipt's signature and hash

// Full validation of signature and hash based on installed receipt
let result = receiptValidator.validateReceipt()

switch result {
    case .success(let receipt, let receiptData, let deviceIdentifier):
    print("receipt validated and parsed: \(receipt)")
    print("the retrieved receipt file's data was: \(receiptData.count) bytes")
    print("the retrieved deviceIdentifier is: \(deviceIdentifier)")
    case .error(let validationError, let receiptData, let deviceIdentifier):
    print("receipt not valid: \(validationError)")
    // receiptData and deviceIdentifier are optional and might still have been retrieved
}

Customize validation dependencies or steps

Take AppReceiptValidator.Parameters.default and customize it, then pass it to validateReceipt(parameters:), like so:

// Customizing validation parameters with configuration block, base on .default
let parameters = AppReceiptValidator.Parameters.default.with {
    $0.receiptOrigin = .data(myData)
    $0.shouldValidateSignaturePresence = false // skip signature presence validation
    $0.signatureValidation = .skip // skip signature authenticity validation
    $0.shouldValidateHash = false // skip hash validation
    $0.deviceIdentifier = .data(myCustomDeviceIdentifierData)

    // validate some string properties, this can also be done 
    // independently with validateProperties(receipt:, validations:)
    // There are also shorthands for comparing with main bundle's 
    // info.plist, e.g. bundleIdMatchingMainBundle and friends.
    // Note that appVersion meaning is platform specific.
    $0.propertyValidations = [
        .string(\.bundleIdentifier, expected: "my.bundle.identifier"),
        .string(\.appVersion, expected: "123"),
        .string(\.originalAppVersion, expected: "1")
    ]
}

let result = AppReceiptValidator().validate(parameters: parameters)

// switch on result

Demo Apps

Paste base64-encoded receipt data into the macOS or iOS demo app to see what AppReceiptValidator parses from it. The macOS App supports:

Drag n Drop an application or its receipt file onto it to inspect

StoreKit Hints

This framework currently doesn't deal with StoreKit. But the receipt file might not exist at all. What now?

If you have no receipt (happens in development builds) or your receipt is invalid, see resources on how to update it using StoreKit functionality. Known caveats:

SKReceiptRefreshRequest might not complete on certain macOS Versions, but reliable on iOS - openradar
SKPaymentQueue.restoreCompletedTransactions() might not update the the receipt, especially if no IAPs were made or the receipt is valid - openradar
exit(173) only works on macOS
Make some kind of purchase, i.e. App Store transaction, to update it
Each mechanism of receipt refresh will be intrusive to the user, mostly asking for AppleID password.
Apple advises to write your own code for receipt validation, and build and link OpenSSL statically to your app target. Anyways this repo might be a starting point for you.
Also have a look at SwiftyStoreKit for dealing with StoreKit, interpretation of receipts, server-verification, and more

How it Works

AppReceiptValidator Uses OpenSSL

OpenSSL is used for PKCS#7 container parsing and signature validation, and also for parsing the ASN1 payload of the PKCS#7, which contains the receipts attributes.

Other Options

Alternatives to PKCS#7 of OpenSSL

Security.framework - CMSDecoder for PKCS#7 interaction only available on macOS, AppStoreReceiptChecker uses this.
BoringSSL instead of OpenSSL, seems included as frameworks in modern iOS and macOS, but not officially supported?

Alternatives to ASN1 of OpenSSL

decoding-asn1-der-sequences-in-swift implemented here
Asn1Parser.swift
AppStoreReceiptChecker

Validation Server to Server

An app can send its receipt file to a backend from where Apples receipt API can be called. See Resources.

Advantages doing it locally:

Works offline
Validation mechanisms can be adjusted
Can be parsed without validation

Resources

Apple guide
objc.io guide
Andrew Bancroft complete guide, or directly ReceiptValidator.swift. This is what the AppReceiptValidator implementation is originally based on, thanks Andrew!!
OpenSSL-Universal Pod
WWDC 2013 - 308 Using Receipts to Protect Your Digital Sales
WWDC 2014 - 305 Preventing Unauthorized Purchases with Receipts
WWDC 2016 - 702 Using Store Kit for In-App Purchases with Swift 3
WWDC 2017 - 304 What's New in Storekit
WWDC 2017 - 305 Advanced StoreKit: Receipt checking and it's internals
nsomar about Module Maps 1
nsomar about Module Maps 2
SwiftyStoreKit
AppStoreReceiptChecker - macOS, uses CMSDecoder and a Swift ASN1 Implementation

Updating Apple Root Certificate

For convenience, AppReceiptValidator contains a copy of apples root certificate to validate the signature against. If uncomfortable with this, you can specify your own by changing the parameters like this:

let myParameters = AppReceiptValidator.Parameters.default.with {
    $0.signatureValidation = .shouldValidate(.data(myAppleRootCertData))
}

Updating OpenSSL

For convenience, AppReceiptValidator contains a pre-built binaries of OpenSSL. The AppReceiptValidator.modulemap exposes these only on demand via import AppReceiptValidator.OpenSSL. If you are not comfortable using pre-built binary or want to update OpenSSL:

build or find prebuilt static libraries for iOS and macOS. They can for example be obtained from the OpenSSL-Universal Pod. To build, you might download the openssl sources and use his gist.
Replace the OpenSSL related .a and .h files in the project
After replacing the files, make sure the .h files use direct includes like #include "asn1.h" instead of #include "<OpenSSL/ans1.h>". In Xcode regex-batch-replace #(\s*)include <openssl\/([^>]+)> with #$1include "$2"
Make sure the OpenSSL related headers are in the private headers of the framework AppReceiptValidator iOS and AppReceiptValidator macOS targets respectively
Make sure the OpenSSL related headers are listed in the AppReceiptValidator.modulemap file

Anybody want to automate this, or find a more elegant way?

Credits

AppReceiptValidator is brought to you by IdeasOnCanvas GmbH, the creator of MindNode for iOS, macOS & watchOS.

iby / AppReceiptValidator