In-App Purchases on Andrew Bancroft

StoreKit Testing Swift Start

Thu, 25 Jun 2020 00:00:00 +0000

Manually Testing StoreKit Code

Development Workflow Changes

The previous workflow for setting up in-app purchases was a bit disjointed.

You’d have to create your app in Xcode… then jump out to App Store Connect to define your app there… set up your digital products there (in App Store Connect)… and then jump back to Xcode to write your StoreKit code.

Now, you can get started in Xcode, and stay in Xcode. Here’s how:

Go to the File menu
Click New ➡️ File
Type “storekit” into the filter
Click Next to add a StoreKit Configuration File ✅

From there, you get to add the digital products you intend to offer in your app, all without leaving Xcode!

Xcode offers support for configuring all three product types:

Consumable
Non-Consumable
Auto-Renewable Subscription

‼️Note: It appears that Non-Renewing Subscriptions are no longer encouraged

Once you have all of your products configured and your Store view written, you’ll want to use your configuration for testing.

To do it, you need to edit your app’s scheme:

Click your app target in the toolbar
Click Edit Scheme…
Click Options
Find StoreKit Configuration, and select the configuration you’ve added for your project in the dropdown ✅

Making Test Purchases

Now to actually test things!

To test things locally, you don’t need to create a sandbox tester account first (something else you used to have to do before testing in-app purchases).

Everything happens locally.

All of your code that would be communicating with the App Store itself in Production, is “taken care of” by Xcode.

So you may be wondering…

❓"Do my SKPaymentTransactionObserver functions get executed when they’re supposed to?"

👉Yes.

❓"Do I get a receipt for the purchase?"

👉Yes.

❓"Can I use that receipt to validate successfully?"

👉Kinda. Receipts from the local Xcode environment are not signed with the same signature as the Sandbox and Production environments are, so they cannot be used if you’re implementing server-side receipt validation.

Development Workflow Enhancements

StoreKit Transaction Manager

How often does your implementation work perfectly the first time?

Rarely?

Yeah… I’m with you.

With the new StoreKit Transaction Manager, it’s easy to “clear things out” so that previous test purchases that didn’t go so well can be tried again fresh, as if a purchase never happened.

Note: If you don’t see the StoreKit Transaction Manager icon in the debug console, make sure you’ve added the In-App Purchasing capability to your app. Then try again.

Test Edge Cases

To support testing out what could be considered “edge cases” in the in-app purchasing experience, Xcode 12 also has the ability to simulate things like:

Time Rate for Auto-Renewable Subscription expiration
Interrupted purchases
Failed transactions
Ask To Buy

Auto-Renewable Subscription Testing Enhancements

Testing subscription expiration is important for preserving the revenue you intend to generate from auto-renewable subscriptions.

The challenge is that you and I don’t have time to wait!

Previously, you could update your product in App Store Connect to have a shorter duration, and the Sandbox environment would interpret, say, a six month subscription to be “30 minutes” worth of time.

But that’s still a long time to wait between making a subscription purchase, and trying out expiration logic, isn’t it?

Problem. Solved. Now you can select even shorter durations for testing subscription expiration using the Time Rate menu option in Xcode’s editor menu when you’re on the StoreKit configuration page.

Remember: To see this editor menu, you have to be in the StoreKit configuration file of your app.

If a second equals a day, and there’s 30ish days in a month, a six month subscription should expire and auto-renew in three-ish minutes now.

A huge help for impatient types like myself!

Automated Testing for StoreKit Code

Tired of launching your app and clicking around manually to test things out?

Not only is that tedious, you and I are bound to either miss something, or test inconsistently, leading to a potentially sub-par end-user experience.

Apple has given us a new StoreKitTest framework that you can use within XCTest!

Everything that you can point-and-click on is fully testable with unit and UI tests with zero human interaction.

To get started using this new framework, it’s import StoreKitTest.

Is the Sandbox Environment Still Useful?

Super useful.

Testing things out locally is amazingly powerful for getting you started, but before you deploy your app to the App Store and send it into review, you still have to…

Set up your products in App Store Connect … right now the Xcode configuration doesn’t get “pushed up” to App Store Connect, so it’s a double-entry world right now.
Set up a Sandbox tester account in App Store Connect so that you can…
Test out your in-app purchasing workflow and receipt validation logic with receipts signed by a “real” App Store environment (just like your TestFlight testers and your App Reviewer will use)

And if you’re using App Store server notifications to detect changes to auto-renewable subscriptions, you need to test those out as well.

So for all of these reasons, the Sandbox environment is still there, and is still useful.

Alas, some manual testing is still required, but can you imagine some of the possibilities for getting started with implementing in-app purchases, right in Xcode, on day zero of your project?

Implementing In-App Purchases on iOS

Tue, 09 Jun 2020 10:03:33 +0000

Monetizing apps is challenging. In this course, Implementing In-App Purchases on iOS, you’ll learn to offer digital products and services directly within your app as in-app purchases.

Resources

Implementing In-App Purchases on iOS

Course Outline

First, you’ll explore how to translate business requirements into digital products and configure them in App Store Connect and Xcode.

Next, you’ll discover how to build and test a store within your app using StoreKit.

Finally, you’ll learn how to make sure purchases made within your app are authentic, and unlock content that’s been purchased by your users.

When you’re finished with this course, you’ll have the skills and knowledge needed to implement in-app purchases on iOS!

1 – Preparing to Implement In-App Purchases

Prepare to implement in-app purchases by understanding what’s involved from a big picture standpoint.

You will learn to configure digital products in App Store Connect and Xcode to kick off your in-app purchase learning adventure.

Topics in this module include…

The Perks (And the Work) Ahead of You
First Things First - Checking off the Prerequisites
Matching Product Types to Business Requirements
Setting Up Products in App Store Connect
Setting Up an Auto-Renewable Subscription
Configuring an Xcode Project for In-App Purchases

2 – Building In-App Purchase Functionality with StoreKit

The focus of this module is on the StoreKit APIs for working with digital products and App Store Connect.

You will learn to build and test a fully-working store view that will support in-app purchases.

Topics in this module include…

Using StoreKit to Build In-App Purchase Functionality: A Roadmap
Retrieving a Set of Products for Purchase from the App Store
Displaying Products in a User Interface
Implementing a “Buy” Button
Preparing to Test Purchases by Setting up a Sandbox Tester Account
Making Test Purchases
Implementing a “Restore Purchases” Button

3 – Protecting Your Revenue by Verifying Purchase Authenticity

After all your hard work to implement in-app purchases, how awful would it be if malicious users stole the content you’ve labored to create?

In this module, you will learn to implement measures to protect revenue generated through in-app purchases by validating App Store receipts.

Receipt validation is a notoriously burdensome hassle. But it doesn’t have to be!

I will teach you how to implement server-side receipt validation from end-to-end with no third-party libraries, no complicated server setup, and no platform-specific proprietary tools.

Here’s the roadmap of topics incluced:

Verifying Purchase Authenticity by Validating App Store Receipts
Weighing Strategies for Receipt Validation
Charting the Course for Server-side Receipt Validation
Sending the Receipt from Your App to Your Server
Writing Server-side Code to Forward the Receipt to the App Store for Validation
Handling the Response from the App Store on Your Server
Accounting for the Sandbox Environment on Your Server
Handling the Response from Your Server in Your App
The Case of the Missing Receipt: Requesting a Refresh

4 – Unlocking Purchased Content

After a user makes a valid purchase, you’ve got to unlock the content they legitimately bought!

Each product type has its own nuances for how to unlock and provide the associated content though.

What do you need to think about, and what code do you need to write to make it happen?

To find out, you will explore these topics:

Analyzing Content-providing Logic by Product Type
Persisting Purchased Products Securely
Using the iOS Keychain
Keeping Track of Consumable Product Inventory
Managing Non-Renewing Subscriptions
Synchronizing Purchases Across Devices
Handling Auto-Renewable Subscriptions
Saving Non-Consumable Transactions
Preparing for App Store Review

Feedback Welcome!

From the beginning I set out to make the course I wish I had when I started learning to implement in-app purchases for my apps. My unwavering goal is to help you filter the noise and learn as efficiently as possible. My hope is that this course benefits you in your iOS development career!

I welcome feedback on this course, and on other iOS development courses you might be interested in seeing in the Pluralsight library. Happy learning!

iOS Receipt Validation: Understanding and Troubleshooting the Original App Version Field

Wed, 05 Feb 2020 00:00:00 +0000

Setting the stage with a use case for checking the original_application_version

The task appears to be simple. Suppose that…

You have an existing app on the app store that’s currently at version 1.2
You want to shift to the “freemium” model by implementing in-app purchases starting with version 1.3
You want to be fair to previous-purchasers of my app (anyone who downloaded the app between version 1.0 and 1.2)

Therefore…

You want to check to see if someone originally purchased version 1.2 or below of your app so that you can “grandfather them in”

To figure this out, you’ll need to implement local receipt validation or set up an environment to do remote receipt validation.

When you’re done, you’ll get access to a field that contains an “original application version”.

The temptation is to inspect this field, parse it out into major and minor version numbers, and write some conditional logic to unlock (or not) certain features of your app.

But…

What does original_application_version really mean?

“Original application version” may not mean what you think it means.

What does it mean?

“Original application version” refers to the value of the Build field of your Xcode project at the time a user downloaded it from the App Store:

Just the Build field?

Yes. Just the Build field.

And that’s weird, because when you and I think of “application versions”, we naturally think in terms of the semantic version number of our apps.

Our brains think “1.2.5” as “{majorVersion}.{minorVersion}.{patchNumber}”.

Many folks use that natural intuition and splice together the Version and Build fields from the Xcode project configuration screen to make what could be considered to be the full semantic version of an app.

If you follow this logic through and conclude that the Version + Build fields are what appears in the original_application_version field of the Receipt, you’ll be in for a rude awakening like I was.

Your grandfathering unlocking logic could be buggy if you’re thinking “Build == patch number” and Apple is thinking “Build == application version at time of download from App Store”.

Gotchas when inspecting the original_application_version field

Sandbox vs App Store receipts

To make things even trickier, the value that’s present in this parsed receipt field is unlikely to be the same between the receipt you get from the sandbox environment and the receipt you get from the production environment (the App Store).

According to Apple’s Receipt Validation Programming Guide, the “original application version” field always contains “1.0” in the sandbox environment.

The only way that your sandbox receipt and your App Store receipt “original application version” fields will match is if you put “1.0” in the Build field of your Xcode project and deploy to the App Store.

Version / Build confusion

Furthermore, the fact that the sandbox environment has “1.0” as its value makes it look like it contains a {majorVersion}.{minorVersion} combo.

It’s deceiving.

It might seem like “original application version” corresponds to the Version field instead of the Build field of your Xcode project configuration.

But it doesn’t.

Build number cautions

Coming full circle now.

In the past, I often used the Build field of my Xcode project to mean the equivalent of a patch number for a given major-minor version of my app.

Using “Build” to mean “patch number” is a less-than-ideal use of the Build field if you plan to do app version checking for “grandfathering in” like I did.

Why?

1) Apple uses it to mean “app version at time of download”

By now you might be realizing that the using your Xcode project’s Build field to mean “patch number” when Apple uses it to mean “app version at time of download” presents some discrepancies in meaning, yes?

When it comes to receipt checking, it only makes sense to come to terms with what Build means to Apple.

You’ll set yourself up for success if you adjust your ussage to match theirs.

2) Build numbers aren’t unique

Build numbers can be reused across releases of your app.

Suppose that you decide you want to use your Xcode project’s Version and Build fields to construct a “semantic version” for your app.

You use “1.0” as your Xcode project’s Version.
You implement five rounds of bug fixes and land on “5” as your Xcode project’s Build.

In this way, you encode “1.0.5” as the semantic version of your app.

Now suppose that later on…

You use “1.1” as your Xcode project’s Version.
You implement five more rounds bug fixes for version 1.1 and land on “5” as your Xcode project’s Build.

In this way, you encode “1.1.5” as the “semantic version” of your app.

Guess what: The receipts for both app releases will contain “5” in the “original application version” field.

Why?

Because “original application version” only contains the value from the Build field, and that’s the Build value that landed in the App Store for both releases.

3) Using sequential “patch number” integers for the Build doesn’t contain enough encoded information to perform “grandfathering in” logic

To set yourself up for “grandfathering in” logic, you want to encode enough meaning in the Build field to write the most appropriate conditional logic for locking/unlocking your app’s purchase-only features.

Choosing a strategic Build value

What could you do? Here are a few ideas:

Regardless of what’s in the Version field of your Xcode project configuration, you could encode the full semantic version of your app in the Build field.

Doing this will let you parse the “original application version” value like you’d expect and implement the right if-else statements in your code.

You could encode more meaningful information in the Build field, such as a “date” represented as an integer

Suppose that it’s January 1, 2020 and you’re preparing builds for an App Store submission.

You could put “20200101.1” in the Build field to represent the first build of today’s submission.

Things may not go perfect during testing with the first upload.

If you need to submit a new build, you could change the Build field’s value to “20200101.2” to represent the second build of today’s submission.

In both cases, you’ve encoded a “date” as an integer inside of the Build field.

Now suppose that you want to grandfather in everyone who bought your app prior to today (January 1, 2020 from the scenario above).

Here’s the pseudo code narrative of the branching logic you’d write:

“If the user’s receipt contains a value less than 20200101 in his/her original application version field, consider them an original purchaser, grandfather them in, and unlock the feature. Otherwise, make them buy the in-app purchase before unlocking.”

Bottom line: If you can come to terms with the nuances of your app receipt’s “original application version” field, you’ll ensure that your app works correctly in production.

Local Receipt Validation for iOS in Swift From Start to Finish

Tue, 01 Aug 2017 17:55:09 +0000

Local receipt validation in Swift doesn’t seem to be widely written about. I’ve been able to find snippets of code scattered across the Internet, but nothing that brought everything together in one spot so that I could wrap my head around the whole process.

I’ve been working on some code for a while, and this post is my attempt to bring it all together from start to finish.

I’ve written seven guides that will take you from preparing to test receipt validation, all the way through to working with the result of the receipt validation process to enable/disable features of your app.

Additionally, I’ve put all of my code into a new GitHub repository for you to use and learn from!

Just want the code? Here you go!

Resources

Swifty Local Receipt Validator

Seven guides taking you from start to finish

If you’re interested in learning about each step along the way, here are the seven guides I’ve written on the topic of local receipt validation in Swift:

Disclaimer

Preventing software piracy is hard. The code presented in these guides and shared in the Git repository is not meant to protect you against unauthorized usage of your app or its features.

The guides and code are meant to be used for learning purposes, and perhaps as a starting point for implementing local receipt validation on your own. If you use this code as-is in your app, you do it at your own risk.

You must take additional efforts to obfuscate the code presented here to thwart an attacker’s attempt at circumventing the receipt validation logic contained within this repository.

Finalizing Receipt Validation in Swift – Computing a GUID Hash

Mon, 31 Jul 2017 12:36:26 +0000

The aim of this guide is to help you finalize the receipt validation process by computing the GUID hash for your app, and comparing it to the hash that’s stored within your receipt itself.

This is a continuation of my receipt validation series. I’m assuming that…

You’ve prepared to test receipt validation by setting up your app in iTunes Connect.
You’ve brought in a cryptography library like OpenSSL to be able to work with the PKCS #7 container that acts as the “envelope” for the receipt. Perhaps you’ve even done it the “easy way” with CocoaPods.
You’ve located and loaded the receipt for validation.
You’ve extracted the PKCS #7 container.
You’ve verified the signature on the receipt
You’ve parsed and decoded the receipt payload

After finishing this guide, you’ll simply need to use the parsed receipt data to perform any app-specific enabling/disabling of features based on the data within a valid receipt. If the receipt is invalid, you’ll need to handle that as well. But all of the relatively difficult work of working with the Open SSL crypto library will be DONE after this guide.

Just want the code? Here you go!

Resources

Swifty Local Receipt Validator

Ready? Let’s do this thing!

Validating the device GUID hash with ReceiptValidator

For this final step, I’ve imagined a single additional function within the ReceiptValidator struct called validateHash(receipt:).

It’ll take in a ParsedReceipt (review what it looks like), and will to the computation and comparison necessary to verify that the computed hash matches the hash stored in the receipt.

A ReceiptValidationError will be thrown if things go wrong within this function. No ReceiptValidationError being thrown indicates a successful hash computation and comparison.

Here’s the skeleton of the function:

fileprivate func validateHash(receipt: ParsedReceipt) throws {
    // Make sure that the ParsedReceipt instances has non-nil values needed for hash comparison

    // Compute the hash for your app & device

    // Compare the computed hash with the receipt's hash
}

Signaling hash validation failure

Before I get into the implementation of the validateHash(receipt:) function, let’s define one more ReceiptValidationError case to describe a bad hash comparison outcome:

enum ReceiptValidationError : Error {
    case couldNotFindReceipt
    case emptyReceiptContents
    case receiptNotSigned
    case appleRootCertificateNotFound
    case receiptSignatureInvalid
    case malformedReceipt
    case malformedInAppPurchaseReceipt
    case incorrectHash
}

Implementing validateHash function

I’ll put the code in front of you, and then do my best to explain my thought process.

fileprivate func validateHash(receipt: ParsedReceipt) throws {
    // Make sure that the ParsedReceipt instances has non-nil values needed for hash comparison
    guard let receiptOpaqueValueData = receipt.opaqueValue else { throw ReceiptValidationError.incorrectHash }
    guard let receiptBundleIdData = receipt.bundleIdData else { throw ReceiptValidationError.incorrectHash }
    guard let receiptHashData = receipt.sha1Hash else { throw ReceiptValidationError.incorrectHash }
    
    var deviceIdentifier = UIDevice.current.identifierForVendor?.uuid
    
    let rawDeviceIdentifierPointer = withUnsafePointer(to: &deviceIdentifier, {
        (unsafeDeviceIdentifierPointer: UnsafePointer<uuid_t?>) -> UnsafeRawPointer in
        return UnsafeRawPointer(unsafeDeviceIdentifierPointer)
    })
    
    let deviceIdentifierData = NSData(bytes: rawDeviceIdentifierPointer, length: 16)
    
    // Compute the hash for your app & device
    
    // Set up the hasing context
    var computedHash = Array<UInt8>(repeating: 0, count: 20)
    var sha1Context = SHA_CTX()
    
    SHA1_Init(&sha1Context)
    SHA1_Update(&sha1Context, deviceIdentifierData.bytes, deviceIdentifierData.length)
    SHA1_Update(&sha1Context, receiptOpaqueValueData.bytes, receiptOpaqueValueData.length)
    SHA1_Update(&sha1Context, receiptBundleIdData.bytes, receiptBundleIdData.length)
    SHA1_Final(&computedHash, &sha1Context)
    
    let computedHashData = NSData(bytes: &computedHash, length: 20)
    
    // Compare the computed hash with the receipt's hash
    guard computedHashData.isEqual(to: receiptHashData as Data) else { throw ReceiptValidationError.incorrectHash }
}

Walking through validateHash

First up, I’ve placed three guard statements:

1
2
3

guard let receiptOpaqueValueData = receipt.opaqueValue else { throw ReceiptValidationError.incorrectHash }
guard let receiptBundleIdData = receipt.bundleIdData else { throw ReceiptValidationError.incorrectHash }
guard let receiptHashData = receipt.sha1Hash else { throw ReceiptValidationError.incorrectHash }

These help guarantee that the rest of the function will have all of the required pieces of data that it needs to fully compute a hash and compare it with what’s in the receipt.

The hash for your app is computed with the following three pieces of information:

The app purchaser’s device identifier
A piece of “opaque data” found within the receipt
Your app’s bundle identifier found within the receipt

The app purchaser’s device identifier is represented as a uuid_t from the Foundation library. However, to use it with the Open SSL library, we’ll need to be working with an NSData instance. The following code goes from the uuid_t instance, to a raw pointer, to an NSData instance:

var deviceIdentifier = UIDevice.current.identifierForVendor?.uuid

let rawDeviceIdentifierPointer = withUnsafePointer(to: &deviceIdentifier, {
    (unsafeDeviceIdentifierPointer: UnsafePointer<uuid_t?>) -> UnsafeRawPointer in
    return UnsafeRawPointer(unsafeDeviceIdentifierPointer)
})

let deviceIdentifierData = NSData(bytes: rawDeviceIdentifierPointer, length: 16)

The last chunk of code within the function actually computes the hash data.

The hash is a SHA1 hash, so what we do here is initialize a SHA1 context, and then update it with all of the ingredients (device identifier, opaque data, and bundle identifier). The hash is finalized, and converted to an instance of NSData.

The final guard takes the computedHashData instance, and compares it to the receipt’s hash data. If it’s identical, validation passes! Otherwise, ReceiptValidationError.incorrectHash is thrown.

Final ReceiptValidator

Let’s put it all together into the final ReceiptValidator struct. Additions are highlighted below:

struct ReceiptValidator {
    let receiptLoader = ReceiptLoader()
    let receiptExtractor = ReceiptExtractor()
    let receiptSignatureValidator = ReceiptSignatureValidator()
    let receiptParser = ReceiptParser()
    
    func validateReceipt() -> ReceiptValidationResult {
        do {
            let receiptData = try receiptLoader.loadReceipt()
            let receiptContainer = try receiptExtractor.extractPKCS7Container(receiptData)
            
            try receiptSignatureValidator.checkSignaturePresence(receiptContainer)
            try receiptSignatureValidator.checkSignatureAuthenticity(receiptContainer)
            
            let parsedReceipt = try receiptParser.parse(receiptContainer)
            try validateHash(receipt: parsedReceipt)
            
            return .success(parsedReceipt)
        } catch {
            return .error(error as! ReceiptValidationError)
        }
    }
    
    fileprivate func validateHash(receipt: ParsedReceipt) throws {
        // Make sure that the ParsedReceipt instances has non-nil values needed for hash comparison
        guard let receiptOpaqueValueData = receipt.opaqueValue else { throw ReceiptValidationError.incorrectHash }
        guard let receiptBundleIdData = receipt.bundleIdData else { throw ReceiptValidationError.incorrectHash }
        guard let receiptHashData = receipt.sha1Hash else { throw ReceiptValidationError.incorrectHash }
        
        var deviceIdentifier = UIDevice.current.identifierForVendor?.uuid
        
        let rawDeviceIdentifierPointer = withUnsafePointer(to: &deviceIdentifier, {
            (unsafeDeviceIdentifierPointer: UnsafePointer<uuid_t?>) -> UnsafeRawPointer in
            return UnsafeRawPointer(unsafeDeviceIdentifierPointer)
        })
        
        let deviceIdentifierData = NSData(bytes: rawDeviceIdentifierPointer, length: 16)
        
        // Compute the hash for your app & device
        
        // Set up the hasing context
        var computedHash = Array<UInt8>(repeating: 0, count: 20)
        var sha1Context = SHA_CTX()
        
        SHA1_Init(&sha1Context)
        SHA1_Update(&sha1Context, deviceIdentifierData.bytes, deviceIdentifierData.length)
        SHA1_Update(&sha1Context, receiptOpaqueValueData.bytes, receiptOpaqueValueData.length)
        SHA1_Update(&sha1Context, receiptBundleIdData.bytes, receiptBundleIdData.length)
        SHA1_Final(&computedHash, &sha1Context)
        
        let computedHashData = NSData(bytes: &computedHash, length: 20)
        
        // Compare the computed hash with the receipt's hash
        guard computedHashData.isEqual(to: receiptHashData as Data) else { throw ReceiptValidationError.incorrectHash }
    }
}

What to do from here

So what now?

Well, at this stage, if no errors have been thrown, you’ve got a valid receipt.

The validateReceipt function returns an instance of ParsedReceipt so that you can inspect individual Swift-Typed values from the receipt payload to determine what features you should enable or disable, depending on what your needs are.

If a ReceiptValidationError is thrown at any point along the way, you’ll need to handle them.
Here are a few ideas:

Implement a grace period, just in case the receipt validation failure occurred for a reason that the user can’t control (e.g. maybe we couldn’t locate the receipt, and requesting a new one failed because Apple was having issues…)
Disable a feature in your app because receipt validation failed too many times
Maybe you just need to use the data within the ParsedReceipt because you’re changing the way you monetize your app. Now, instead of making users pay $0.99 for the app, you’re going to give it away for free, but let people buy an in-app purchase to enable “pro” features, or remove ads…whatever. In this case, you may check the ParsedReceipt to see the original version of the app that your user downloaded. Maybe you want to require users who download your app after version 2.0 to buy an in-app purchase for Feature X, but you want to give it to everyone who already has the app since they may have already paid $0.99 for it, and it’d make them feel ripped off if they had to buy the in-app purchase.

How you handle the parsed receipt data or a receipt validation error is really customizable and specific to your particular app.

The bottom line is that from this point on, you no longer need Open SSL or any additional cryptic, low-level, unsafe pointer-type stuff to finish things out.

I hope this series has been helpful in setting you up to validate receipts locally on a user’s device!

You might also enjoy…

Receipt Validation – Parse and Decode a Receipt with Swift

Fri, 28 Jul 2017 03:41:33 +0000

The aim of this guide is to help you parse a receipt and decode it so that you have readable pieces of metadata to inspect and finalize all of the receipt validation steps.

This is a continuation of my receipt validation series. I’m assuming that…

You’ve prepared to test receipt validation by setting up your app in iTunes Connect.
You’ve brought in a cryptography library like OpenSSL to be able to work with the PKCS #7 container that acts as the “envelope” for the receipt. Perhaps you’ve even done it the “easy way” with CocoaPods.
You’ve located and loaded the receipt for validation.
You’ve extracted the PKCS #7 container.
You’ve verified the signature on the receipt

After finishing this guide, you’ll still have to compute the GUID hash of your app to compare with the hash that’s found within the receipt. You’ll also have to inspect the receipt data to perform any app-specific verification steps. But in order to do either, you’ll need the parsed receipt metadata.

Just want the code? Here you go!

Resources

Swifty Local Receipt Validator

Want to understand the final ReceiptParser? Let’s get to it!

The final goal: A parsed receipt

The final goal of this guide is a parsed receipt.

What do you say we start things off by defining what one looks like?

At the end of the day, what we’d like back from the parsing process is a simple struct that contains the various pieces of metadata that are found within the extracted the PKCS #7 container. Things like…

the app’s bundle identifier,
the original app version that was purchased,
a collection of all the in app purchase receipts,
etc.

How does the following look?

struct ParsedReceipt {
    let bundleIdentifier: String?
    let bundleIdData: NSData?
    let appVersion: String?
    let opaqueValue: NSData?
    let sha1Hash: NSData?
    let inAppPurchaseReceipts: [ParsedInAppPurchaseReceipt]?
    let originalAppVersion: String?
    let receiptCreationDate: Date?
    let expirationDate: Date?
}

struct ParsedInAppPurchaseReceipt {
    let quantity: Int?
    let productIdentifier: String?
    let transactionIdentifier: String?
    let originalTransactionIdentifier: String?
    let purchaseDate: Date?
    let originalPurchaseDate: Date?
    let subscriptionExpirationDate: Date?
    let cancellationDate: Date?
    let webOrderLineItemId: Int?
}

You may be wondering, “How’d he know what values are encoded within the extracted receipt payload?”. Apple has a very handy list of all the values that are encoded, so I listed each property out in my struct according to their documentation.

Parsing the receipt produces the most valuable piece of the whole process. Sure, it’s necessary to go through all of the other validation steps, but having a decoded receipt with actual human-readable values is, to me, a huge step.

Full disclaimer though: parsing the receipt is not very… Swifty.

We’re going to be working with all kinds of ugly things like UnsafeMutablePointers, and cryptically-named C Types.

Let’s take it one step at a time though…

Visualizing the encoded receipt’s structure

Up to now, we’ve been working only with the PKCS #7 container for the receipt. Now it’s time to dig into the container and see what it actually contains.

If you crack open the container, what you find is a long series of bytes that encode the actual structure of the receipt.

From beginning to end, the bytes should encode what’s called an “ASN.1 Set”. In fact, if you open the PKCS #7 container and it doesn’t encode an ASN.1 Set, that’d warrant a receipt validation failure…more about handling that in a minute.

Here’s a visual representation of an ASN.1 Set:

Since we’ve just got a bunch of bytes encoding things, there’s got to be some way to say, “This byte, or these series of bytes, represent [this human understandable thing]”.

That’s exactly what we’ve got, as you can see by the visual representation.

The first byte in the receipt payload (the green box in the visualization) signals that the bytes that follow encode an ASN.1 Set.

The next bytes in the series (the blue box) encode how long the ASN.1 Set is, so that as you’re going along parsing and decoding the contents of the Set, you know when to stop.

The final series of bytes (the yellow boxes) encode chunks of information that can be decoded to give you human readable receipt attributes. Those chunks, themselves, are encoded as ASN.1 Sequences.

So what does an ASN.1 Sequence look like? Here’s a visual:

When it comes to app receipts, ASN.1 Sequences are used to say, “Hey, this series of bytes encodes the bundle identifier or the original app version or some other receipt attribute.”

Each ASN.1 Sequence has a flag (the pink box in the visualization) to signal that the bytes that follow do, in fact, encode an ASN.1 Sequence.

Then, just like an ASN.1 Set, the next bytes in line (the blue box) encode how long the Sequence is. Then comes what we’re really after in all this Set/Sequence talk:

The type of attribute (bundle identifier, for example) is encoded next in the series of bytes as an ASN.1 Integer (note that this isn’t a Swift Int…yet…we’ll decode it soon). Each attribute type has a unique ASN.1 Integer value, kind of like an ID. Apple’s documentation is helpful in figuring out which ASN.1 Integer value maps to which receipt attribute.

After the attribute type comes some bytes that encode an “attribute version”, also as an ASN.1 Integer. At the time of this guide’s publication, “attribute version” isn’t used for anything. Nonetheless, the series of bytes right after the attribute type within the ASN.1 Sequence is reserved and will always represent the “attribute version”.

The remaining bytes in the ASN.1 Sequence encode the actual value of the attribute as an ASN.1 Octet String (don’t let the word “Octet String” trick you into thinking that it’s actually a String… they’re bytes that we’ll have to decode shortly…)

Knowing how the receipt payload is structured will help us formulate a strategy around parsing it. Let’s imagine a simple algorithm to do it now.

Receipt parsing strategy

Let’s take it step by step. What if we approach parsing the receipt like this:

1) Do some preliminary checks to ensure that the receipt payload is in the correct structural format (it should be an ASN.1 Set, for example).

2) For each ASN.1 Sequence within the ASN.1 Set, check to see what type of attribute it is.

3) Decode its Octet String value into actual, human-readable values. The decoded values would be represented by Swift Types (Int, String, Date are sufficient to cover all of the possibilities for receipts). The final decoded value depends on what type of attribute it is.

4) Create and return a ParsedReceipt instance as the final product.

If at any point the receipt payload fails to live up to the expected structure, receipt validation will fail, and we can signal that by throwing an error.

A note on in-app purchase receipts

As we follow the receipt parsing strategy steps that I just described, there’s going to come a point where we run into the ASN.1 Sequence that encodes the in-app purchase receipts.

These are special.

In-app purchase receipts are encoded as ASN.1 Sets (with ASN.1 Sequences within) inside the primary ASN.1 Set receipt payload. In other words, they’re nested ASN.1 Sets within the overall ASN.1 Set that encodes the whole receipt. The nested Set contains the in-app purchase receipt attributes.

So in order to decode these, we’ll have to apply the receipt parsing strategy within the receipt parsing strategy. Fun, huh? We’ll only have to do it for the in-app purchase receipt attributes though.

Preparation step: Helper decoding functions

If you saw the ParsedReceipt struct that I proposed earlier in the guide, you’ll notice that there are essentially four Swift Types that the receipt attributes (and in-app purchase receipt attributes) get decoded into:

Int?
String?
NSData?
Date?

NSData has a constructor that can work with UnsafeRawPointers directly, but Int?, String?, and Date? need some help converting from the ASN.1 versions of those Types to the Swift versions of those Types.

Let me put the code before you and follow up with what I’m doing here:

func DecodeASN1Integer(startOfInt intPointer: inout UnsafePointer<UInt8>?, length: Int) -> Int? {
    // These will be set by ASN1_get_object
    var type = Int32(0)
    var xclass = Int32(0)
    var intLength = 0
    
    ASN1_get_object(&intPointer, &intLength, &type, &xclass, length)
    
    guard type == V_ASN1_INTEGER else {
        return nil
    }
    
    let integer = c2i_ASN1_INTEGER(nil, &intPointer, intLength)
    let result = ASN1_INTEGER_get(integer)
    ASN1_INTEGER_free(integer)
    
    return result
}

func DecodeASN1String(startOfString stringPointer: inout UnsafePointer<UInt8>?, length: Int) -> String? {
    // These will be set by ASN1_get_object
    var type = Int32(0)
    var xclass = Int32(0)
    var stringLength = 0

    ASN1_get_object(&stringPointer, &stringLength, &type, &xclass, length)
    
    if type == V_ASN1_UTF8STRING {
        let mutableStringPointer = UnsafeMutableRawPointer(mutating: stringPointer!)
        return String(bytesNoCopy: mutableStringPointer, length: stringLength, encoding: String.Encoding.utf8, freeWhenDone: false)
    }
    
    if type == V_ASN1_IA5STRING {
        let mutableStringPointer = UnsafeMutableRawPointer(mutating: stringPointer!)
        return String(bytesNoCopy: mutableStringPointer, length: stringLength, encoding: String.Encoding.ascii, freeWhenDone: false)
    }
    
    return nil
}

func DecodeASN1Date(startOfDate datePointer: inout UnsafePointer<UInt8>?, length: Int) -> Date? {
    // Date formatter code from https://www.objc.io/issues/17-security/receipt-validation/#parsing-the-receipt
    let dateFormatter = DateFormatter()
    dateFormatter.locale = Locale(identifier: "en_US_POSIX")
    dateFormatter.dateFormat = "yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'"
    dateFormatter.timeZone = TimeZone(secondsFromGMT: 0)
    
    if let dateString = DecodeASN1String(startOfString: &datePointer, length:length) {
        return dateFormatter.date(from: dateString)
    }
    
    return nil
}

Each of these decoding functions are dealing with the receipt attribute value portion of the ASN.1 Sequence that we’re working on at the time. Recall the structure:

So we take in a pointer that’s pointing to the start of one of the attribute values (a yellow box). The yellow box’s ASN.1 Octet String encodes either an integer, a string, or a date. (Okay, technically I guess you could include NSData, but this doesn’t need to be “decoded” really. And the in-app purchase receipts will be parsed and decoded into the stated Types as well, so it all boils down to the three I just mentioned…thus the reason for only three helper functions).

The strategy for the first two functions is basically to take what we’re pointing to, and call ASN1_get_object.

This function call gets us enough information to decode the bytes from the start of the object to the end of the object into either an Int? or a String?. If it fails, nil is returned.

Decoding dates simply involves initializing a DateFormatter with the appropriate locale and date format. The datePointer parameter actually points to an encoded string, so the strategy is to use the DecodeASN1String function we made, and pass the date string to the date formatter.

So long as the string can be decoded, the date formatter instance is used to create an actual Date? instance and return it. Otherwise, nil is returned.

Handling error conditions

The kinds of errors that can occur when parsing the receipt payload all have to do with unexpected structure.

For example, if we’re expecting to be stepping through an ASN.1 Payload or an ASN.1 Sequence but instead find that it’s not what we expect, this is a situation where reeipt validation should fail, because there’s no way to decode the receipt attributes if the bytes of the payload don’t conform to the expected structure.

In situations where the receipt payload or one of its in-app purchase receipt payloads is “malformed” in some way, we can throw an Error.

I’ve highlighted two new ReceiptValidationError cases here:

enum ReceiptValidationError : Error {
    case couldNotFindReceipt
    case emptyReceiptContents
    case receiptNotSigned
    case appleRootCertificateNotFound
    case receiptSignatureInvalid
    case malformedReceipt
    case malformedInAppPurchaseReceipt
}

Implenting ReceiptParser

OK! We’ve got a few helper functions to decode the receipt attributes, and we’ve got some ReceiptValidationError cases to throw in case parsing fails.

At a very high level, the ReceiptParser will take the following skeletal structure:

struct ReceiptParser {
    func parse(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws -> ParsedReceipt {
        var bundleIdentifier: String?
        var bundleIdData: NSData?
        var appVersion: String?
        var opaqueValue: NSData?
        var sha1Hash: NSData?
        var inAppPurchaseReceipts = [ParsedInAppPurchaseReceipt]()
        var originalAppVersion: String?
        var receiptCreationDate: Date?
        var expirationDate: Date?
        
        // Parse the receipt, setting each variable
        
        return ParsedReceipt(bundleIdentifier: bundleIdentifier,
                             bundleIdData: bundleIdData,
                             appVersion: appVersion,
                             opaqueValue: opaqueValue,
                             sha1Hash: sha1Hash,
                             inAppPurchaseReceipts: inAppPurchaseReceipts,
                             originalAppVersion: originalAppVersion,
                             receiptCreationDate: receiptCreationDate,
                             expirationDate: expirationDate)
    }
    
    func parseInAppPurchaseReceipt(currentInAppPurchaseASN1PayloadLocation: inout UnsafePointer<UInt8>?, payloadLength: Int) throws -> ParsedInAppPurchaseReceipt {
        var quantity: Int?
        var productIdentifier: String?
        var transactionIdentifier: String?
        var originalTransactionIdentifier: String?
        var purchaseDate: Date?
        var originalPurchaseDate: Date?
        var subscriptionExpirationDate: Date?
        var cancellationDate: Date?
        var webOrderLineItemId: Int?
        
        // Parse the in-app purchase receipt, setting each variable
        
        return ParsedInAppPurchaseReceipt(quantity: quantity,
                                          productIdentifier: productIdentifier,
                                          transactionIdentifier: transactionIdentifier,
                                          originalTransactionIdentifier: originalTransactionIdentifier,
                                          purchaseDate: purchaseDate,
                                          originalPurchaseDate: originalPurchaseDate,
                                          subscriptionExpirationDate: subscriptionExpirationDate,
                                          cancellationDate: cancellationDate,
                                          webOrderLineItemId: webOrderLineItemId)
    }

So a total of two functions: one to parse the overall receipt, and one to parse each in-app purchase receipt nested within the overall receipt.

Now comes the hard part. Actually doing all the decoding. Don’t forget the strategy we’re going to take! That’ll help you walk through this code without getting insanely overwhelmed (hopefully).

`parse` function implementation

First, the implementation of parse(_:) with comments throughout to help you find where each step of the strategy is being implemented:

func parse(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws -> ParsedReceipt {
    var bundleIdentifier: String?
    var bundleIdData: NSData?
    var appVersion: String?
    var opaqueValue: NSData?
    var sha1Hash: NSData?
    var inAppPurchaseReceipts = [ParsedInAppPurchaseReceipt]()
    var originalAppVersion: String?
    var receiptCreationDate: Date?
    var expirationDate: Date?
    
    // Strategy Step 1: Preliminary structure checks

    // Must have data to work with
    guard let contents = PKCS7Container.pointee.d.sign.pointee.contents, let octets = contents.pointee.d.data else {
        throw ReceiptValidationError.malformedReceipt
    }
    
    // Determine the start and end of the receipt payload
    var currentASN1PayloadLocation = UnsafePointer(octets.pointee.data)
    let endOfPayload = currentASN1PayloadLocation!.advanced(by: Int(octets.pointee.length))
    
    var type = Int32(0)
    var xclass = Int32(0)
    var length = 0
    
    ASN1_get_object(&currentASN1PayloadLocation, &length, &type, &xclass,Int(octets.pointee.length))
    
    // Payload must be an ASN1 Set
    guard type == V_ASN1_SET else {
        throw ReceiptValidationError.malformedReceipt
    }
    
    // Decode Payload
    // Strategy Step 2: Walk through payload (ASN1 Set) and parse each ASN1 Sequence 
    // within (ASN1 Sets contain one or more ASN1 Sequences)
    while currentASN1PayloadLocation! < endOfPayload {
        
        // Get next ASN1 Sequence
        ASN1_get_object(&#038;currentASN1PayloadLocation, &#038;length, &#038;type, &#038;xclass, currentASN1PayloadLocation!.distance(to: endOfPayload))
        
        // ASN1 Object type must be an ASN1 Sequence
        guard type == V_ASN1_SEQUENCE else {
            throw ReceiptValidationError.malformedReceipt
        }
        
        // Attribute type of ASN1 Sequence must be an Integer
        guard let attributeType = DecodeASN1Integer(startOfInt: &#038;currentASN1PayloadLocation, length: currentASN1PayloadLocation!.distance(to: endOfPayload)) else {
            throw ReceiptValidationError.malformedReceipt
        }
        
        // Attribute version of ASN1 Sequence must be an Integer
        guard DecodeASN1Integer(startOfInt: &#038;currentASN1PayloadLocation, length: currentASN1PayloadLocation!.distance(to: endOfPayload)) != nil else {
            throw ReceiptValidationError.malformedReceipt
        }
        
        // Get ASN1 Sequence value
        ASN1_get_object(&#038;currentASN1PayloadLocation, &#038;length, &#038;type, &#038;xclass, currentASN1PayloadLocation!.distance(to: endOfPayload))
        
        // ASN1 Sequence value must be an ASN1 Octet String
        guard type == V_ASN1_OCTET_STRING else {
            throw ReceiptValidationError.malformedReceipt
        }
        
        // Strategy Step 3: Decode attributes
        switch attributeType {
        case 2:
            var startOfBundleId = currentASN1PayloadLocation
            bundleIdData = NSData(bytes: startOfBundleId, length: length)
            bundleIdentifier = DecodeASN1String(startOfString: &#038;startOfBundleId, length: length)
        case 3:
            var startOfAppVersion = currentASN1PayloadLocation
            appVersion = DecodeASN1String(startOfString: &#038;startOfAppVersion, length: length)
        case 4:
            let startOfOpaqueValue = currentASN1PayloadLocation
            opaqueValue = NSData(bytes: startOfOpaqueValue, length: length)
        case 5:
            let startOfSha1Hash = currentASN1PayloadLocation
            sha1Hash = NSData(bytes: startOfSha1Hash, length: length)
        case 17:
            var startOfInAppPurchaseReceipt = currentASN1PayloadLocation
            let iapReceipt = try parseInAppPurchaseReceipt(currentInAppPurchaseASN1PayloadLocation: &#038;startOfInAppPurchaseReceipt, payloadLength: length)
            inAppPurchaseReceipts.append(iapReceipt)
        case 12:
            var startOfReceiptCreationDate = currentASN1PayloadLocation
            receiptCreationDate = DecodeASN1Date(startOfDate: &#038;startOfReceiptCreationDate, length: length)
        case 19:
            var startOfOriginalAppVersion = currentASN1PayloadLocation
            originalAppVersion = DecodeASN1String(startOfString: &#038;startOfOriginalAppVersion, length: length)
        case 21:
            var startOfExpirationDate = currentASN1PayloadLocation
            expirationDate = DecodeASN1Date(startOfDate: &#038;startOfExpirationDate, length: length)
        default:
            break
        }
        
        currentASN1PayloadLocation = currentASN1PayloadLocation?.advanced(by: length)
    }
    
    // Strategy Step 4: Return ParsedReceipt
    return ParsedReceipt(bundleIdentifier: bundleIdentifier,
                            bundleIdData: bundleIdData,
                            appVersion: appVersion,
                            opaqueValue: opaqueValue,
                            sha1Hash: sha1Hash,
                            inAppPurchaseReceipts: inAppPurchaseReceipts,
                            originalAppVersion: originalAppVersion,
                            receiptCreationDate: receiptCreationDate,
                            expirationDate: expirationDate)
}

Aside from the work with pointers and the Open SSL function names, the strategy is pretty straight-forward when you look it from a bird’s-eye point of view.

Once again, if you’re curious about how I knew to map each case within the switch to the correct receipt attribute, I simply got them from Apple’s documentation.

`parseInAppPurchaseRectipt` function implementation

Now it’s time to see how to parse an in-app purchase receipt payload. Take a look:

func parseInAppPurchaseReceipt(currentInAppPurchaseASN1PayloadLocation: inout UnsafePointer<UInt8>?, payloadLength: Int) throws -> ParsedInAppPurchaseReceipt {
    var quantity: Int?
    var productIdentifier: String?
    var transactionIdentifier: String?
    var originalTransactionIdentifier: String?
    var purchaseDate: Date?
    var originalPurchaseDate: Date?
    var subscriptionExpirationDate: Date?
    var cancellationDate: Date?
    var webOrderLineItemId: Int?
    
    // Find the end of the in-app purchase receipt payload
    let endOfPayload = currentInAppPurchaseASN1PayloadLocation!.advanced(by: payloadLength)
    var type = Int32(0)
    var xclass = Int32(0)
    var length = 0
    
    ASN1_get_object(&currentInAppPurchaseASN1PayloadLocation, &length, &type, &xclass, payloadLength)
    
    // Payload must be an ASN1 Set
    guard type == V_ASN1_SET else {
        throw ReceiptValidationError.malformedInAppPurchaseReceipt
    }
    
    // Decode Payload
    // Step through payload (ASN1 Set) and parse each ASN1 Sequence within (ASN1 Sets contain one or more ASN1 Sequences)
    while currentInAppPurchaseASN1PayloadLocation! < endOfPayload {
        
        // Get next ASN1 Sequence
        ASN1_get_object(&#038;currentInAppPurchaseASN1PayloadLocation, &#038;length, &#038;type, &#038;xclass, currentInAppPurchaseASN1PayloadLocation!.distance(to: endOfPayload))
        
        // ASN1 Object type must be an ASN1 Sequence
        guard type == V_ASN1_SEQUENCE else {
            throw ReceiptValidationError.malformedInAppPurchaseReceipt
        }
        
        // Attribute type of ASN1 Sequence must be an Integer
        guard let attributeType = DecodeASN1Integer(startOfInt: &#038;currentInAppPurchaseASN1PayloadLocation, length: currentInAppPurchaseASN1PayloadLocation!.distance(to: endOfPayload)) else {
            throw ReceiptValidationError.malformedInAppPurchaseReceipt
        }
        
        // Attribute version of ASN1 Sequence must be an Integer
        guard DecodeASN1Integer(startOfInt: &#038;currentInAppPurchaseASN1PayloadLocation, length: currentInAppPurchaseASN1PayloadLocation!.distance(to: endOfPayload)) != nil else {
            throw ReceiptValidationError.malformedInAppPurchaseReceipt
        }
        
        // Get ASN1 Sequence value
        ASN1_get_object(&#038;currentInAppPurchaseASN1PayloadLocation, &#038;length, &#038;type, &#038;xclass, currentInAppPurchaseASN1PayloadLocation!.distance(to: endOfPayload))
        
        // ASN1 Sequence value must be an ASN1 Octet String
        guard type == V_ASN1_OCTET_STRING else {
            throw ReceiptValidationError.malformedInAppPurchaseReceipt
        }
        
        // Decode attributes
        switch attributeType {
        case 1701:
            var startOfQuantity = currentInAppPurchaseASN1PayloadLocation
            quantity = DecodeASN1Integer(startOfInt: &#038;startOfQuantity , length: length)
        case 1702:
            var startOfProductIdentifier = currentInAppPurchaseASN1PayloadLocation
            productIdentifier = DecodeASN1String(startOfString: &#038;startOfProductIdentifier, length: length)
        case 1703:
            var startOfTransactionIdentifier = currentInAppPurchaseASN1PayloadLocation
            transactionIdentifier = DecodeASN1String(startOfString: &#038;startOfTransactionIdentifier, length: length)
        case 1705:
            var startOfOriginalTransactionIdentifier = currentInAppPurchaseASN1PayloadLocation
            originalTransactionIdentifier = DecodeASN1String(startOfString: &#038;startOfOriginalTransactionIdentifier, length: length)
        case 1704:
            var startOfPurchaseDate = currentInAppPurchaseASN1PayloadLocation
            purchaseDate = DecodeASN1Date(startOfDate: &#038;startOfPurchaseDate, length: length)
        case 1706:
            var startOfOriginalPurchaseDate = currentInAppPurchaseASN1PayloadLocation
            originalPurchaseDate = DecodeASN1Date(startOfDate: &#038;startOfOriginalPurchaseDate, length: length)
        case 1708:
            var startOfSubscriptionExpirationDate = currentInAppPurchaseASN1PayloadLocation
            subscriptionExpirationDate = DecodeASN1Date(startOfDate: &#038;startOfSubscriptionExpirationDate, length: length)
        case 1712:
            var startOfCancellationDate = currentInAppPurchaseASN1PayloadLocation
            cancellationDate = DecodeASN1Date(startOfDate: &#038;startOfCancellationDate, length: length)
        case 1711:
            var startOfWebOrderLineItemId = currentInAppPurchaseASN1PayloadLocation
            webOrderLineItemId = DecodeASN1Integer(startOfInt: &#038;startOfWebOrderLineItemId, length: length)
        default:
            break
        }
        
        currentInAppPurchaseASN1PayloadLocation = currentInAppPurchaseASN1PayloadLocation!.advanced(by: length)
    }
    
    return ParsedInAppPurchaseReceipt(quantity: quantity,
                                        productIdentifier: productIdentifier,
                                        transactionIdentifier: transactionIdentifier,
                                        originalTransactionIdentifier: originalTransactionIdentifier,
                                        purchaseDate: purchaseDate,
                                        originalPurchaseDate: originalPurchaseDate,
                                        subscriptionExpirationDate: subscriptionExpirationDate,
                                        cancellationDate: cancellationDate,
                                        webOrderLineItemId: webOrderLineItemId)
}

As you can see, parsing an in-app purchase receipt uses the same strategy as parsing the overall receipt does.

A receipt may contain zero or more in-app purchase receipts, so this function may get called zero, one, or many times, depending on what your app offers as in-app purchases, and of course, what your users have actually purchased.

Final `ReceiptParser`

I realize that breaking the code apart like I’ve done is good for teaching purposes, but perhaps not so much for “I just wanna copy-paste and use this” purposes.

I’ll spare you having to scroll through all that code again. If you’d like to see the full ReceiptParser, check out the Swifty Local Receipt Validator repo on GitHub.

Using `ReceiptParser`

I initialize an instance of ReceiptParser in my ReceiptValidator struct, and then call the parse(_:) function from validateReceipt():

enum ReceiptValidationResult {
    case success(ParsedReceipt) // Now has ParsedReceipt for an associated value
    case error(ReceiptValidationError)
}

struct ReceiptValidator {
    let receiptLoader = ReceiptLoader()
    let receiptExtractor = ReceiptExtractor()
    let receiptSignatureValidator = ReceiptSignatureValidator()
    let receiptParser = ReceiptParser()
    
    func validateReceipt() -> ReceiptValidationResult {
        do {
            let receiptData = try receiptLoader.loadReceipt()
            let receiptContainer = try receiptExtractor.extractPKCS7Container(receiptData)
            
            try receiptSignatureValidator.checkSignaturePresence(receiptContainer)
            try receiptSignatureValidator.checkSignatureAuthenticity(receiptContainer)
            
            let parsedReceipt = try receiptParser.parse(receiptContainer)
            return .success(parsedReceipt)
        } catch {
            return .error(error as! ReceiptValidationError)
        }
    }
}

Preparing to finish receipt validation!

What a journey this has been! We’re almost done with this receipt validation process.

What’s left? After this guide, you still need to…

Compute the GUID hash of your app to compare with the hash that’s found within the receipt.
You’ll also have to inspect the receipt data to perform any app-specific verification steps.

We’re that much closer now though! See you next time.

Receipt Validation – Verifying a Receipt Signature in Swift

Sun, 16 Jul 2017 21:43:21 +0000

You’ve prepared to test receipt validation by setting up your app in iTunes Connect.
You’ve brought in a cryptography library like OpenSSL to be able to work with the PKCS #7 container that acts as the “envelope” for the receipt. Perhaps you’ve even done it the “easy way” with CocoaPods.
You’ve located and loaded the receipt for validation.
You’ve extracted the PKCS #7 container.

The aim of this guide is to help you take a look inside the PKCS #7 container, and verify the presence and authenticity of the signature on the receipt.

Just want the code? Here you go!

Resources

Swifty Local Receipt Validator

Recap from the previous guide

In Loading a Receipt for Validation with Swift, I began the process of breaking out the various steps of the receipt validation process into separate single-responsibility structs with clearly named functions to help clarify what each piece of code is doing.

Recall that I’ve created a main Type called ReceiptValidator, with references to several smaller single-responsibility Types that it uses to accomplish the overall validation process.

Accordingly, I’ve created a ReceiptLoader that finds the receipt on the file system and loads it into memory.

As of the last entry in this series of guides, I’ve also got a ReceiptExtractor to extract the receipt contents from its PKCS #7 container.

If a validation step ever fails along the way, I’ve decided to take advantage of Swift’s error throwing features to clearly describe what failed. So far, there’s only two cases:

enum ReceiptValidationError : Error {
    case couldNotFindReceipt
    case emptyReceiptContents
}

Preparation step: Download Apple’s root certificate

You need a copy of Apple’s root certificate in order to fully complete this phase of receipt validation.

How do you get a copy of it? Great question (with an answer)!

If you go to https://www.apple.com/certificateauthority/, you can get your hands on a copy by downloading the “Apple Inc. Root Certificate” file:

Once you have it, you need to add the certificate to your Xcode project, and add it to your app’s target:

What can go wrong with receipt signature verification?

I’ll start off the code piece of this guide by asking, “What could go wrong?”. That’ll help define a few more ReceiptValidationError cases, and might point us in a direction when it comes to implementing a new Type to use within the ReceiptValidator.

Right off the bat, I can think of two or three things that could go awry at this stage of the receipt validation process:

1 – The receipt that we loaded may not be signed at all
2 – We don’t have a copy of Apple’s root certificate to validate the signature with
3 – The signature on the receipt is invalid because it doesn’t match against Apple’s root certificate

I’ll add those three new error states to the ReceiptValidationError enum now:

enum ReceiptValidationError : Error {
    case couldNotFindReceipt
    case emptyReceiptContents
    case receiptNotSigned
    case appleRootCertificateNotFound
    case receiptSignatureInvalid
}

ReceiptSignatureValidator concept

Another step, another Type. This has been my strategy so far, so I’m stickin’ to it!

I’m validating the presence and authenticity of the signature on the receipt, so I picked the name ReceiptSignatureValidator for this one.

When I identified three new ReceiptValidationError cases earlier, I had in mind that they could potentially point me in a direction when implementing this new ReceiptSignatureValidator Type.

What if this Type had two functions?

checkSignaturePresence
checkSignatureAuthenticity

In checkSignaturePresence, I’ll look, and if the receipt isn’t signed at all, I’ll throw the receiptNotSigned Error case.

In checkSignatureAuthenticity, I’ll look, and if the Apple root certificate is missing from the bundle for some reason, I’ll throw appleRootCertificateNotFound. And if the signature on the receipt doesn’t jive with Apple’s root certificate, I’ll throw receiptSignatureInvalid.

Here’s the skeleton of the struct:

struct ReceiptSignatureValidator {
    func checkSignaturePresence(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
        // Implementation coming
    }
    
    func checkSignatureAuthenticity(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
        // Implementation coming
    }
}

Both checkSignaturePresence and checkSignatureAuthenticity need to peek into the PKCS #7 container that encapsulates the receipt data, so each function asks for a reference to an UnsafeMutablePointer<PKCS7> as one of its arguments.

If you’re following along with the series, you’ll be glad to know that the ReceiptExtractor that we built previously has a method called extractPKCS7Container that actually returns a UnsafeMutablePointer<PKCS7>, so you can just use the a call to extractPKCS7Container with the new ReceiptSignatureValidator's functions.

ReceiptSignatureValidator implementation

Now to actually implement ReceiptSignatureValidator…

Checking signature presence

Checking for the presence of a signature is actually relatively simple. Take a look:

struct ReceiptSignatureValidator {
    func checkSignaturePresence(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
        let pkcs7SignedTypeCode = OBJ_obj2nid(PKCS7Container.pointee.type)
        
        guard pkcs7SignedTypeCode == NID_pkcs7_signed else {
            throw ReceiptValidationError.receiptNotSigned
        }
    }
    
    func checkSignatureAuthenticity(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
        // Implementation coming
    }
}

The PKCS #7 container has a type code associated with it if it’s signed. All we need to do is access that type code, and compare it against the NID_pkcs7_signed constant.

In order to be valid, the receipt must be signed, so I’ve implemented this as a guard.

Checking signature authenticity

Loading Apple’s root certificate

Now comes the part where we check whether the signature on the receipt is authentic or not.

First, we’ve got to load up Apple’s root certificate (assuming it exists in the app bundle). Here’s a function that can be nested inside of ReceiptSignatureValidator to do the job:

fileprivate func loadAppleRootCertificate() throws -> UnsafeMutablePointer<X509> {
    guard
        let appleRootCertificateURL = Bundle.main.url(forResource: "AppleIncRootCertificate", withExtension: "cer"),
        let appleRootCertificateData = try? Data(contentsOf: appleRootCertificateURL)
        else {
            throw ReceiptValidationError.appleRootCertificateNotFound
    }
    
    //①
    let appleRootCertificateBIO = BIO_new(BIO_s_mem())

    //②
    BIO_write(appleRootCertificateBIO, (appleRootCertificateData as NSData).bytes, Int32(appleRootCertificateData.count))

    //③
    let appleRootCertificateX509 = d2i_X509_bio(appleRootCertificateBIO, nil)
    
    return appleRootCertificateX509!
}

This function guards against the absence of Apple’s root certificate. If it can’t be found in the main bundle, the function throws appleRootCertificateNotFound. This error is obviously preventable, but hey – never hurts to protect yourself if you’re using this code in multiple projects and forget to grab a copy of Apple’s root certificate.

① As long as the .cer file exists in the app bundle, the next step is to create a new in-memory BIO (basic input-output) pointer. That’s what let appleRootCertificateBIO = BIO_new(BIO_s_mem()) does.

② Next, we’ve got to write the contents of the certificate to memory so we can work with it:

`1`	`BIO_write(appleRootCertificateBIO, (appleRootCertificateData as NSData).bytes, Int32(appleRootCertificateData.count))`

BIO_write needs a location to write to, namely, our appleRootCertificateBIO pointer.

It also needs to know what to write: (appleRootCertificateData as NSData).bytes

Finally, it needs to know the length of the data to write: Int32(appleRootCertificateData.count)

③ Once that’s complete, we can obtain pointer to an X509, which will be used for the next step: verifying the authenticity of the signature on the receipt with the x509 certificate from Apple’s root certificate authority. let appleRootCertificateX509 = d2i_X509_bio(appleRootCertificateBIO, nil) gives us our return value!

Verifying signature authenticity

The final step is to take the X509 pointer, and use it to verify the authenticity of the signature on the PKCS #7 Container.

Once again, here’s a function that can take both items and do the work:

fileprivate func verifyAuthenticity(_ x509Certificate: UnsafeMutablePointer<X509>, PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
    //①
    let x509CertificateStore = X509_STORE_new()

    //②
    X509_STORE_add_cert(x509CertificateStore, x509Certificate)
    
    //③
    OpenSSL_add_all_digests()
    
    //④
    let result = PKCS7_verify(PKCS7Container, nil, x509CertificateStore, nil, nil, 0)
    
    //⑤
    if result != 1 {
        throw ReceiptValidationError.receiptSignatureInvalid
    }
}

① The X509 Store is what holds the information for verification, so we use X509_STORE_new() to create one.

② Next, X509_STORE_add_cert function is used to prepare the X509 Store, and the X509 Certificate for verification purposes.

③ OpenSSL keeps an internal table of digest algorithms and ciphers. It uses this table to lookup ciphers via certain functions. OpenSSL_add_all_digests() is called to load the necessary digest algorithms for verification.

④ The final step is to use the PKCS7_verify function, passing it the PKCS #7 Container, and the x509 Certificate Store.

⑤ PKCS7_Verify will return 1 if the signature is valid. If PKCS7_Verify returns any integer value other than 1, the signature is to be interpreted as invalid.

Putting it all together

Final ReceiptSignatureValidator implementation

The final version of the ReceiptSignatureValidator looks like this:

struct ReceiptSignatureValidator {
    func checkSignaturePresence(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
        let pkcs7SignedTypeCode = OBJ_obj2nid(PKCS7Container.pointee.type)
        
        guard pkcs7SignedTypeCode == NID_pkcs7_signed else {
            throw ReceiptValidationError.receiptNotSigned
        }
    }
    
    func checkSignatureAuthenticity(_ PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
        let appleRootCertificateX509 = try loadAppleRootCertificate()
        
        try verifyAuthenticity(appleRootCertificateX509, PKCS7Container: PKCS7Container)
    }
    
    fileprivate func loadAppleRootCertificate() throws -> UnsafeMutablePointer<X509> {
        guard
            let appleRootCertificateURL = Bundle.main.url(forResource: "AppleIncRootCertificate", withExtension: "cer"),
            let appleRootCertificateData = try? Data(contentsOf: appleRootCertificateURL)
            else {
                throw ReceiptValidationError.appleRootCertificateNotFound
        }
        
        let appleRootCertificateBIO = BIO_new(BIO_s_mem())
        BIO_write(appleRootCertificateBIO, (appleRootCertificateData as NSData).bytes, Int32(appleRootCertificateData.count))
        let appleRootCertificateX509 = d2i_X509_bio(appleRootCertificateBIO, nil)
        
        return appleRootCertificateX509!
    }
    
    fileprivate func verifyAuthenticity(_ x509Certificate: UnsafeMutablePointer<X509>, PKCS7Container: UnsafeMutablePointer<PKCS7>) throws {
        let x509CertificateStore = X509_STORE_new()
        X509_STORE_add_cert(x509CertificateStore, x509Certificate)
        
        OpenSSL_add_all_digests()
        
        let result = PKCS7_verify(PKCS7Container, nil, x509CertificateStore, nil, nil, 0)
        
        if result != 1 {
            throw ReceiptValidationError.receiptSignatureInvalid
        }
    }
}

Additions to ReceiptValidator

The ReceiptValidator struct that’s been growing to accommodate each of the steps now looks like this (additions highlighted):

struct ReceiptValidator {
    let receiptLoader = ReceiptLoader()
    let receiptExtractor = ReceiptExtractor()
    let receiptSignatureValidator = ReceiptSignatureValidator()

    
    func validateReceipt() -> ReceiptValidationResult {
        do {
            let receiptData = try receiptLoader.loadReceipt()
            let receiptContainer = try receiptExtractor.extractPKCS7Container(receiptData)
            
            try receiptSignatureValidator.checkSignaturePresence(receiptContainer)
            try receiptSignatureValidator.checkSignatureAuthenticity(receiptContainer)
            return .success
        } catch {
            return .error(error as! ReceiptValidationError)
        }
    }
}

Handling errors

The final piece is to attempt to do something intelligent with any of the possible error conditions that could be included with the ReceiptValidator validation result. Here’s a sample implementation at the call site for validateReceipt() (probably in a view controller somewhere in your app:

override public func viewDidLoad() {
    super.viewDidLoad()

    let validationResult = receiptValidator.validateReceipt()
        
    switch validationResult {
    case .success:
        // Enable app features
    case .error(let error):
        print(error)
        receiptRequest.start()
    }   
}

In the case where the receipt signature is invalid, my only thought right now is to request a new receipt from the app store and attempt to re-validate it.

Upcoming hurdles

Wait, there’s more? In short, yes. We’ve made significant progress, but there’s still more work to be done if you want to fully validate a receipt for your app, or for an in-app purchase.

You might also enjoy…

Extracting a PKCS7 Container for Receipt Validation with Swift

Fri, 10 Jun 2016 03:44:58 +0000

So you’ve prepared to test receipt validation by setting up your app in iTunes Connect.

You’ve brought in a cryptography library like OpenSSL to be able to work with the PKCS #7 container that acts as the “envelope” for the receipt. Perhaps you’ve even done it the “easy way” with CocoaPods.

You’ve located and loaded the receipt for validation.

Now you’re ready to extract the PKCS #7 container and work with it.

The aim of this guide is to get you started using the OpenSSL library in your Swift code by employing it to extract the receipt contents from its PKCS #7 container.

Just want the code? Here you go!

Resources

Swifty Local Receipt Validator

Recap from the previous guide

Recall that I’ve created a main Type called ReceiptValidator, with references to several smaller single-responsibility Types that it uses to accomplish the overall validation process. So accordingly, as of my last post in the series, I’ve created a ReceiptLoader that finds the receipt on the file system and loads it into memory.

If a validation step ever fails along the way, I’ve decided to take advantage of Swift’s error throwing features to clearly describe what failed. So far, there’s only one case:

1
2
3

enum ReceiptValidationError : Error {
    case couldNotFindReceipt
}

I’ll expand this enum Type to cover more failure conditions in this guide.

ReceiptExtractor struct outline

The OpenSSL library comes to us in the form of a C static library. It’s not a beautiful API to say the least. The names of the Types and functions are really cryptic at times, so I’ve decided it’s best for my own memory to wrap each step in small function routines that are named for what they do.

So supposing you’ve located and loaded the receipt data, or used Store Kit to request a receipt from Apple… Take a look at this new ReceiptExtractor skeleton of a struct to get an idea of what’s going to be required to extract the PKCS7 container for the receipt:

struct ReceiptExtractor {
    func extractPKCS7Container(_ receiptData: Data) throws -> UnsafeMutablePointer<PKCS7> {
        // use Open SSL to extract the PKCS7 container
        // throw a ReceiptValidationError if something goes wrong in this process
    }
}

New ReceiptValidationError cases

When extracting the receipt information from the PKCS7 container, there are going to be things that would cause overall validation to fail. For example, if the receipt Data instance ends up being empty, that’s a validation failure. The PKCS7 container needs to have information inside of it for validation to pass (obviously).

So in this guide, I’ll expand the ReceiptValidationError enum to have the following cases:

enum ReceiptValidationError : Error {
    case couldNotFindReceipt
    case emptyReceiptContents
}

Preparation step: PKCS7 union accessors

Before attempting to work with OpenSSL’s PKCS7 functions, you’ve got to do a little prep work to get the functions to play nicely with Swift.

Unfortunately, Swift doesn’t work well with C union types. It simply can’t see things defined with a C union.

Thankfully, we can work around the problem by creating some wrappers. If you’ll add two new files to your project and implement them, you’ll be on your way. They are:

pkcs7_union_accessors.h
pkcs7_union_accessors.c

pkcs7_union_accessors.h implementation

#ifndef pkcs7_union_accessors_h
#define pkcs7_union_accessors_h

#include <openssl/pkcs7.h>

char *pkcs7_d_char(PKCS7 *ptr);
ASN1_OCTET_STRING *pkcs7_d_data(PKCS7 *ptr);
PKCS7_SIGNED *pkcs7_d_sign(PKCS7 *ptr);
PKCS7_ENVELOPE *pkcs7_d_enveloped(PKCS7 *ptr);
PKCS7_SIGN_ENVELOPE *pkcs7_d_signed_and_enveloped(PKCS7 *ptr);
PKCS7_DIGEST *pkcs7_d_digest(PKCS7 *ptr);
PKCS7_ENCRYPT *pkcs7_d_encrypted(PKCS7 *ptr);
ASN1_TYPE *pkcs7_d_other(PKCS7 *ptr);

#endif /* pkcs7_union_accessors_h */

pkcs7_union_accessors.c implementation

#include "pkcs7_union_accessors.h"

inline char *pkcs7_d_char(PKCS7 *ptr) {
    return ptr->d.ptr;
}

inline ASN1_OCTET_STRING *pkcs7_d_data(PKCS7 *ptr) {
    return ptr->d.data;
}

inline PKCS7_SIGNED *pkcs7_d_sign(PKCS7 *ptr) {
    return ptr->d.sign;
}

inline PKCS7_ENVELOPE *pkcs7_d_enveloped(PKCS7 *ptr) {
    return ptr->d.enveloped;
}

inline PKCS7_SIGN_ENVELOPE *pkcs7_d_signed_and_enveloped(PKCS7 *ptr) {
    return ptr->d.signed_and_enveloped;
}

inline PKCS7_DIGEST *pkcs7_d_digest(PKCS7 *ptr) {
    return ptr->d.digest;
}

inline PKCS7_ENCRYPT *pkcs7_d_encrypted(PKCS7 *ptr) {
    return ptr->d.encrypted;
}

inline ASN1_TYPE *pkcs7_d_other(PKCS7 *ptr) {
    return ptr->d.other;
}

Bridging header updates

After you create the union accessor files, you need to update your project’s bridging header to import the new header file:

1
2
3

#import <openssl/pkcs7.h>
#import <openssl/objects.h>
#import "pkcs7_union_accessors.h"

ReceiptExtractor struct implementation

Now it’s time to dive into the actual implementation of what I’m calling a ReceiptExtractor. Have a look at the code with some explanatory comments following:

struct ReceiptExtractor {
    func extractPKCS7Container(_ receiptData: Data) throws -> UnsafeMutablePointer<PKCS7> {
        let receiptBIO = BIO_new(BIO_s_mem())       
        BIO_write(receiptBIO, (receiptData as NSData).bytes, Int32(receiptData.count))
        let receiptPKCS7Container = d2i_PKCS7_bio(receiptBIO, nil)
        
        guard receiptPKCS7Container != nil else {
            throw ReceiptValidationError.emptyReceiptContents
        }
        
        let pkcs7DataTypeCode = OBJ_obj2nid(pkcs7_d_sign(receiptPKCS7Container).pointee.contents.pointee.type)
        
        guard pkcs7DataTypeCode == NID_pkcs7_data else {
            throw ReceiptValidationError.emptyReceiptContents
        }
        
        return receiptPKCS7Container!
    }
}

ReceiptExtractor struct explanation

Most of the code above is a Swift translation of what’s found at Objc.io’s Receipt Validation guide.

I did a little research over at the OpenSSL site though, and thought it might be helpful for the curious to know what some of these non-intuitive function names stand for and what they do.

BIO_new for example. “BIO” stands for “Basic I/O”. It’s an abstraction over the underlying basic input and output operations that your app uses for cryptographic operations.

What we’re doing with BIO_new(BIO_s_mem()) is saying that we want a new Basic I/O mechanism that uses memory for its I/O operations.

BIO_write takes the receiptData that was located and loaded, and writes the entire length of its bytes to memory (the receiptBIO that was created first).

To get the actual PKCS #7 container, the d2i_PKCS7_bio function is used.

Once we have the container in hand, it’s a matter of making sure it has contents.

I couldn’t find a lot of information about the call to pkcs7_d_sign, but the primary point of line 13 above is to get a “numerical identifier”, which is what “NID” stands for in OBJ_obj2nid.

Digging into the PKCS #7 container, you can access the right property and convert it to a numerical identifier that you can check.

As long as the NID returned is equal to the NID_pkcs7_data constant value, things are good. If they’re not, that means the receipt has no information and validation fails (thus, the guard and throw statement in lines 14-15).

If everything passes the guard, though, the PKCS #7 container is returned, and we’re ready for the next step of the receipt validation process, which is to verify the signature on the receipt with Apple’s root certificate. That, however, will happen in another entry to this series.

Until next time!

Loading a Receipt for Validation with Swift

Wed, 14 Oct 2015 03:24:02 +0000

I’m working through a progression of entries on the process of validating receipts with OpenSSL for iOS in Swift.

Just want the code? Here you go!

Resources

Swifty Local Receipt Validator

To-date, I’ve explained how to get OpenSSL into your project (the easy way), and I’ve walked through how to prepare to test receipt validation, including how to set everything up in the Apple Developer member center, and in iTunes Connect.

There are at least 5 steps to validate a receipt, as the Receipt Validation Programming Guide outlines:

1 – Locate the receipt.
If no receipt is present, validation fails.

2 – Verify that the receipt is properly signed by Apple.
If it is not signed by Apple, validation fails.

3 – Verify that the bundle identifier in the receipt matches a hard-coded constant containing the CFBundleIdentifier value you expect in the Info.plist file.
If they do not match, validation fails.

4 – Verify that the version identifier string in the receipt matches a hard-coded constant containing the CFBundleShortVersionString value (for macOS) or the CFBundleVersion value (for iOS) that you expect in the Info.plist file.
If they do not match, validation fails.

5 – Compute the hash of the GUID as described in Compute the Hash of the GUID.
If the result does not match the hash in the receipt, validation fails.

The thought I had when I saw 5 steps is, “This is going to become too much responsibility for a single Type to handle”. I easily got overwhelmed when I analyzed the most extensive write-up on the subject, found at Objc.io.

Validation organization strategy overview

To help keep my head wrapped around this process, I’ve developed a strategy that has kept me sane so far. It incorporates 3 components:

1 – ReceiptValidator

First, I’ve created a top-level Type called ReceiptValidator. My idea is to have a single method, validateReceipt() that will either run and succeed, or start propagating errors.

2 – Map validation steps to separate Types

Second, I’ve tried to take each of the steps involved in validating the receipt and create a simple Swift Type to encapsulate the logic that needs to happen in that step.

So when step 1 says to “locate and load the receipt”, I created a struct called ReceiptLoader that has two methods: receiptFound() and loadReceipt().

ReceiptValidator currently holds references to instances of each of these little helper Types, and the validator class itself calls methods on those instances to get the overall job of validating the receipt done.

3 – Throw errors when a validation step fails

Third, whenever some step along the way fails, I’m utilizing Swift’s error handling features. I’ve created an enum called ReceiptValidationError with various descriptive values. Whenever a validation error occurs, one of the values in the ReceiptValidationError enum is thrown.

The enum’s definition is simple right now, but it will grow as time goes on with various other error conditions related to receipt validation (and why validation might fail):

1
2
3

enum ReceiptValidationError : Error {
    case couldNotFindReceipt
}

This enum simply implements the Error “marker” protocol, which allows its values to be used in Swift’s error-throwing system. For this blog entry, we’ll stick with simply throwing the value couldNotFindReceipt whenever a receipt can’t be found and needs to be re-requested from the App Store.

ReceiptValidator implementation

ReceiptValidator is where everything for validating receipts launches for me at this point. Calling a single method, validateReceipt() will kick off the 5+ step process that Apple describes.

The first thing that needs to happen is to load a receipt that’ll be validated. If a receipt is not found on the device, a new receipt needs to be requested from the App Store.

I mentioned ReceiptLoader in the overview. An implementation will follow, but we’ll let this instance do the locating and loading of the receipt.

With that architecture in mind, here’s what ReceiptValidator looks like right now:

enum ReceiptValidationResult {
    case success
    case error(ReceiptValidationError)
}

struct ReceiptValidator {
    let receiptLoader = ReceiptLoader()
    
    func validateReceipt() -> ReceiptValidationResult {
        do {
            let receiptData = try receiptLoader.loadReceipt()
            
            // Continue validation steps with receiptData if error not thrown
            return .success
        } catch {
            return .error(error as! ReceiptValidationError)
        }
    }
}

So the validator simply lets the ReceiptLoader instance do it’s loading job. If it doesn’t return any data containing a receipt to work with, the validator will catch the error and return the .error ReceiptValidationResult case with the error cast to a ReceiptValidationError as an associated value.

The View Controller is what calls validateReceipt(), so it will be waiting to deal with the ReceiptValidationResult that’s returned by the ReceiptValidator.

ReceiptLoader implementation

The ReceiptLoader has the sole responsibility of going to receipt storage location on a user’s device and attempting to discover the receipt and pull out the contents of that file in the form of a Data instance if it’s there.

Here’s the implementation with explanation to follow:

struct ReceiptLoader {
    let receiptUrl = Bundle.main.appStoreReceiptURL
    
    func loadReceipt() throws -> Data {
        if(receiptFound()) {
            let receiptData = try? Data(contentsOf: receiptUrl!)
            if let receiptData = receiptData {
                return receiptData
            }
        }
        
        throw ReceiptValidationError.couldNotFindReceipt
    }
    
    fileprivate func receiptFound() -> Bool {
        do {
            if let isReachable = try receiptUrl?.checkResourceIsReachable() {
                return isReachable
            }
        } catch _ {
            return false
        }
        
        return false
    }
}

The loadReceipt() method will do the job and either return a Data instance with the receipt contents that can be extracted and parsed in later steps, or it will throw the ReceiptValidationError.couldNotFindReceipt enum value.

The rest of the implementation is all around making sure the receipt is there and accessible by utilizing standard URL and Data methods.

ViewController implementation

The View Controller is the kick-off point of all-things receipt validation. To have some code in front of us, take a look at this implementation. Explanatory details are below:

public class ViewController: UIViewController, SKRequestDelegate {
    let receiptValidator = ReceiptValidator()
    let receiptRequest = SKReceiptRefreshRequest()
    
    // MARK: View Controller Life Cycle Methods
    override public func viewDidLoad() {
        super.viewDidLoad()
        receiptRequest.delegate = self
        
        let validationResult = receiptValidator.validateReceipt()
 
        switch validationResult {
        case .success:
            // Enable app features
        case .error(let error):
            print(error)
            receiptRequest.start()
        }   
    }
    
    public func requestDidFinish(_ request: SKRequest) {
        do {
            try receiptValidator.validateReceipt()
        } catch {
            // Log unsuccessful attempt and optionally begin grace period
            // before disabling app functionality, or simply disable features
        }
    }
    
    public func request(_ request: SKRequest, didFailWithError error: Error) {
        // debug error condition
        print(error.localizedDescription)
 
        // Log unsuccessful attempt and optionally begin grace period
        // before disabling app functionality, or simply disable features
    }
}

When the app starts and the controller has loaded, it will prepare itself in a couple of ways:

First, it will initialize a ReceiptValidator and an SKReceiptRefreshRequest (in case a receipt isn’t present on the device).

Subtle but important, the SKReceiptRefreshRequest instance’s delegate is set to the view controller itself in viewDidLoad().

Control is then handed over to the ReceiptValidator instance to begin its multi-step process (of which we’ve got step 1 down up to this point).

The View Controller acts as the main error handler for now. If a receipt couldn’t be found, signaled by the throwing of ReceiptValidationError.couldNotFindReceipt by the validator, the receipt refresh request is started.

The View Controller also acts as the SKRequestDelegate, and thus gets called back whenever the request finishes (or fails with an error).

If receipt validation fails once the receipt is downloaded to the device, Apple recommends that in iOS, we do not attempt to terminate the app.

Rather, they recommend logging that the receipt validation failed and then initiating a grace period, or disabling functionality in your app, depending on the situation.

Upcoming hurdles

That about wraps up locating and loading the receipt. The real challenges of using OpenSSL to extract the receipt, verify its authenticity, parse it, and more are still ahead. I’ll be sure to chronicle my journey as I jump those hurdles. Stay tuned!

You might also enjoy…

Preparing to Test Receipt Validation for iOS

Mon, 05 Oct 2015 18:25:09 +0000

After having to piece together each step along the path of preparing to test receipt validation for iOS apps, I’ve decided to combine everything into the following guide. Whether you’re working to implement receipt validation for a new iOS app, or for an existing one, this walk-through should provide guidance to get you ready to work with receipts in your iOS application.

iTunes Connect App Record Setup

1 – Log in to the Apple Developer Member Center.

2 – Make sure you have a bundle identifier set up for your app.

If this is an existing app you’re wanting to add receipt validation to, you’re already set. If this is a brand new, un-released app, you need to set up a bundle identifier first.

2a) Click on Certificates, Identifiers & Profiles:

2b) Click on Identifiers:

2c) Add a new App ID that’s appropriate for your app:

3 – Log into iTunes Connect.

4 – Click “My Apps” from the main iTunes Connect dashboard page.

5 – Click the + button to add your app into iTunes Connect.

Sandbox Tester Setup

1 – Create a new e-mail address that’s not associated with an Apple ID already

Your sandbox user account is actually going to be a separate Apple ID. Since it’s probably going to be you that’s testing the purchasing and receipt features of your app, you will need to create a new e-mail address to associate with a new Apple ID, since Apple does not allow you to use an e-mail address already associated with an existing Apple ID.

2 – Log in to iTunes Connect if you’re not still logged in from the previous steps

3 – Click on Users and Roles

4 – Click Sandbox Testers

5 – Click the Add (+) button

6 – Fill out all of the information on this page, and use the new e-mail address you created as the Email field value.

7 – Save the new sandbox user.

8 – You will receive an e-mail from Apple asking you to verify your new Apple ID. Verify it.

iOS Device Setup

1 – On your physical device (not in the Simulator), open Settings and navigate to “App and iTunes Stores”.

Important: If you mistakenly use a sandbox tester account to log in to a production environment on your test device instead of your test environment, the sandbox account becomes invalid and can’t be used again. If this happens, create a new sandbox tester account with a new email address.

Later on, when you run your app on your device from Xcode, you’ll get a prompt to sign in to the fake App Store. You’ll enter the credentials you created for the Sandbox User test account into the prompt.

Note: Ideally, this step is done on an iOS test device, not on your own personal device. That being said, there are times (like in my own situation) where you might not have a test device and you’re forced to switch between Apple IDs to test.

3 – Go through the necessary steps to set up a new iTunes Store account. You’ll receive a “Welcome” e-mail from the iTunes Store once everything is completely set up.

Write Some Receipt Verification Code

As a quick example, consider the following class that will act as a ReceiptFetcher. To test things out, you can simply create an instance of this class in your primary view controller, and call fetchReceipt in the viewDidLoad() method.

You’ll be looking to make sure you’re prompted for iTunes Store credentials, and that you successfully receive a receipt (ie, request(_:didFailWithError:) did not get called, but instead requestDidFinish(_:) got called):

Receipt Fetcher

 2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

                               

class="lnt"> 1 language-swift" data-lang="swift">import Foundation class="kd">import StoreKit class="kd">class ReceiptFetcher : NSObject, SKRequestDelegate {

let receiptRefreshRequest = SKReceiptRefreshRequest()

override init() { super.init() receiptRefreshRequest.delegate = self }

func fetchReceipt() { let receiptUrl = Bundle.main.appStoreReceiptURL

do { if let receiptFound = try receiptUrl?.checkResourceIsReachable() { if (receiptFound == false) { receiptRefreshRequest.start() } } } catch { print("Could not check for receipt presence for some reason... \(error.localizedDescription)") } }

func requestDidFinish(_ request: SKRequest) { print("The request finished successfully") }

func request(_ request: SKRequest, didFailWithError error: Error) { print("Something went wrong: \(error.localizedDescription)") } class="p">}

View Controller

public class ViewController: UIViewController {

    // Note that an instance of ReceiptFetcher is kept at the class-level
    let receiptFetcher = ReceiptFetcher()
    
    override public func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.

        receiptFetcher.fetchReceipt()
    }
}

Note: Once again, note that the instance of ReceiptFetcher is held at the view controller’s class-level scope. This is necessary to allow the delegate callback functions to be invoked. If you initialize the ReceiptFetcher in viewDidLoad without holding a reference at the class level, the instance will be deallocated prior to the delegate callback functions being invoked.

Debug App on Device

1 – Run your app from Xcode on the device you’ve just set up.

2 – Executing code, such as a request to refresh a receipt should prompt you for your newly created Sandbox Tester credentials.

3 – Enter the password for that Apple ID – you should receive a receipt!

You might also enjoy…

OpenSSL for iOS and Swift the Easy Way

Tue, 22 Sep 2015 04:39:28 +0000

I’m currently working on outfitting an app I’m working on to be able to validate receipts to verify purchases of the app.

Little did I know, this adventure would introduce the need to understand how to use cryptography in order to work with the receipt.

Cryptography library needed

In order to even “open” the receipt itself, we’ve got to work with something called a “PKCS #7 container”. Once we get the container open, we need to be able to validate Apple’s certificate that they use to sign every purchase of every app.

All of this requires the use of a cryptography library, and OpenSSL seems to be the common choice, due to its being open source.

I found that figuring out what to do to get OpenSSL into my project was harder than I wanted it to be. It turns out that there are a few to do this, but I wanted the easiest to implement (and the easiest to maintain). The options I was able to identify are:

Build the binaries for each platform yourself. To do this you’ve got to make sure you build for both the simulator and the device by running special config routines and using makefiles and what-not. It seemed error-prone, and I’m not confident enough in my ability to know whether or not I’ve done it right.
Download a pre-built static library – however, this introduces a risk that I wasn’t really willing to take. How do I trust that pre-built library? If there’s a vulnerability there, how do I easily upgrade the library to the patched version? Every recommendation I’ve seen thus far says, “Always build your own static library, rather than download it already-built from somewhere”.
Cocoapods. Simply put, this was the easiest route for me.

OpenSSL for iOS with Cocoapods

How easy is it to get started with OpenSSL for iOS with Cocoapods?

Pretty easy.

If you don’t have Cocoapods yet, you can head over to Cocoapods.org and follow their instructions for installing. It’s literally one command at the terminal:

sudo gem install cocoapods

Once Cocoapods is installed, open your project in Xcode and add a new empty file (File -> New File -> Other -> Empty) called Podfile.

In its contents, you simply add a reference to the OpenSSL library:

1
2
3

target 'NameOfYourApp' do
    pod 'OpenSSL', '~> 1.0'
end

Note that there are several ‘OpenSSL’ Cocoapod specs out there to choose from. I originally tried one that looked like it was for iOS (OpenSSL-iOS), but I was never able to get Swift code to recognize the C functions and types.

The one that seemed to still pull the source from openssl.org and build it when the pod is installed was simply named ‘OpenSSL’ and I’ve verified that my Swift code can ‘see’ the C code without running into ‘unresolved identifier’ compiler errors.

Once the Podfile is created and configured, save it and close Xcode. Then head to the Terminal.

Navigate to your Xcode project folder where the Podfile is located and run pod install.

Once it’s finished doing its thing (be patient… it took several minutes for me), you can open the new .xcworkspace file that Cocoapods created for you. You’ll have everything in your project configured to depend on the OpenSSL library through the new Pods project that’s been added to your Workspace.

Bridging header

In order to use OpenSSL with Swift, you’re going to need to create an Objective-C bridging header to access the functionality provided in the OpenSSL libraries.

If you don’t already have an Objective-C bridging header, it’s simple to get one added automatically by Xcode for you:

Choose File -> New -> File
Choose Source under iOS (on the left
Choose Objective-C File
Name it “bridge” (or anything, really – it’s a dummy file that you’ll delete after Xcode generates the bridging header)
Choose Next, and then Create

Xcode will prompt you to create the bridging header – you should let it. Once it’s created, you can delete “bridge.m” (the Objective-C .m file that you just created in the steps above).

Within the bridging header, you can insert some #import statements to make the OpenSSL library components visible to your Swift project. For example, to start off, you could flesh out the bridging header with a couple of OpenSSL header files:

1
2
3

#import <openssl/pkcs7.h>
#import <openssl/objects.h>
// Others that you may need in your Swift project

Xcode 7 & Bitcode

When you build and run your newly configured project in the Simulator, things are going to work fine.

When you build it for your device, however, it will fail.

…Pods/OpenSSL/lib/libcrypto.a(bio_lib.o)’ does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE), obtain an updated library from the vendor, or disable bitcode for this target. for architecture arm64

At the time of this writing, there is somthing in OpenSSL that doesn’t support Xcode 7’s Bitcode feature. Eventually (hopefully) they’ll fix it, but for now, if you want to use OpenSSL in a Swift project using Xcode 7, you’ll have to turn off Bitcode.

Click on your project, and then click on your app target under ‘Targets’ in the project settings window.

Find Build Options and set Enable Bitcode to ‘No'

If you try re-building against the device with this setting set to ‘No’, it should build and run without issue.

Wrapping up

That’s all there is to getting OpenSSL built and added as a reference in your app. Now will come the fun part of using it with Swift, but I will save that for another entry.

You might also enjoy…

In-App Purchases on Andrew Bancroft

StoreKit Testing Swift Start

Manually Testing StoreKit Code

Development Workflow Changes

Making Test Purchases

Development Workflow Enhancements

StoreKit Transaction Manager

Test Edge Cases

Auto-Renewable Subscription Testing Enhancements

Automated Testing for StoreKit Code

Is the Sandbox Environment Still Useful?

Implementing In-App Purchases on iOS

Course Outline

1 – Preparing to Implement In-App Purchases

2 – Building In-App Purchase Functionality with StoreKit

3 – Protecting Your Revenue by Verifying Purchase Authenticity

4 – Unlocking Purchased Content

Feedback Welcome!

iOS Receipt Validation: Understanding and Troubleshooting the Original App Version Field

Setting the stage with a use case for checking the original_application_version

What does original_application_version really mean?

Gotchas when inspecting the original_application_version field

Sandbox vs App Store receipts

Version / Build confusion

Build number cautions

Choosing a strategic Build value

Local Receipt Validation for iOS in Swift From Start to Finish

Seven guides taking you from start to finish

Disclaimer

Finalizing Receipt Validation in Swift – Computing a GUID Hash

Validating the device GUID hash with ReceiptValidator

Signaling hash validation failure

Implementing validateHash function

Walking through validateHash

Final ReceiptValidator

What to do from here

Receipt Validation – Parse and Decode a Receipt with Swift

The final goal: A parsed receipt

Visualizing the encoded receipt’s structure

Receipt parsing strategy

A note on in-app purchase receipts

Preparation step: Helper decoding functions

Handling error conditions

Implenting ReceiptParser

parse function implementation

parseInAppPurchaseRectipt function implementation

Final ReceiptParser

Using ReceiptParser

Preparing to finish receipt validation!

Receipt Validation – Verifying a Receipt Signature in Swift

Recap from the previous guide

Preparation step: Download Apple’s root certificate

What can go wrong with receipt signature verification?

ReceiptSignatureValidator concept

ReceiptSignatureValidator implementation

Checking signature presence

Checking signature authenticity

Loading Apple’s root certificate

Verifying signature authenticity

Putting it all together

Final ReceiptSignatureValidator implementation

Additions to ReceiptValidator

Handling errors

Upcoming hurdles

Extracting a PKCS7 Container for Receipt Validation with Swift

Recap from the previous guide

ReceiptExtractor struct outline

New ReceiptValidationError cases

Preparation step: PKCS7 union accessors

pkcs7_union_accessors.h implementation

pkcs7_union_accessors.c implementation

Bridging header updates

ReceiptExtractor struct implementation

ReceiptExtractor struct explanation

Loading a Receipt for Validation with Swift

Validation organization strategy overview

1 – ReceiptValidator

2 – Map validation steps to separate Types

3 – Throw errors when a validation step fails

ReceiptValidator implementation

`parse` function implementation

`parseInAppPurchaseRectipt` function implementation

Final `ReceiptParser`

Using `ReceiptParser`