OpenSSL on Andrew Bancroft

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

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. 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!

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.