Monthly Archives: February 2012

MAS Preparation, Part 5

Posted on by
1

Mac App Store receipt validation

In the last installment of Preparing for Mac App Store Submission, I discussed the (general) source code modifications that you may need to make in order to convert your downloadable Mac OS X project into one acceptable for the Mac App Store (MAS).

Now, in this fifth part, I will talk about a more specific addition to your source code, functionality for checking the presence and validity of a MAS receipt file.  While this change is not required, and would not cause your submission to be rejected, it is strongly recommend for reasons detailed below.  In fact, we will start there…

0. Consider the reason for receipt validation

Before implementation, it is good to understand, in general terms, the purpose of receipt validation.

When somebody “purchases” an application from the Mac App Store, a receipt file is added to the downloaded bundle authenticating it; this includes free products as well.  However, the level of checking provided by the system itself is minimal.  Soon after the MAS launch, it was discovered that there was a fairly simply method [details deliberately omitted] by which even a simple-minded software thief could circumvent the very basic protections and run stolen MAS applications.

The solution, of course, is to verify the validity of the software receipt for your application, which helps prevent “script kiddies” from easily stealing and distributing your products.  Of course, it is never quite as simple as that, especially since code signatures and encryption are inherently complex, and the program needs to validate a receipt file that has not been created yet (making this code rather tricky to test).

Keep in mind that this validation process is optional, so you can choose not to do it all, to fully validate the receipt file, or to implement only partial checks; the choice is up to you.

The official Apple documentation for this process is in Validating Mac App Store Receipts.

1. Obtain a sample receipt for testing

As mentioned above, your first challenge is that the receipt checking code needs to be able to validate a receipt file from a purchase that is to be made in the future.  To do this, you may want to get a sample receipt for testing.

This used to be fairly easy, as Apple provided a sample receipt, along with the associated validation data, to Mac developers.  Unfortunately, recently (as in, since this series began), the certification signature on the original sample receipt expired and, instead of providing a newer one, Apple has decided to remove the sample receipt entirely in favor of connecting to the iTunes servers to obtain one directly.  Whatever.

Now, the process involves getting the application to initially quit with an exit code of 173, which indicates a failed verification, which is supposed to trigger iTunes to prompt you for your (test) account credentials and then download a valid receipt and insert it into the application bundle, as described in Test During the Development Process.  In practice, this definitively does not work all of the time during development, and the prerequisites are not clear.

What is clear is that the application needs to be signed before Mac OS X (version 10.6.6 or higher) will request iTunes credentials, and that they need to be for a test account.  However, any old test account will apparently not do, and a failure to produce and/or download a receipt displays no error message (just no receipt and only a vague “returnCode:1” in the console).  It appears to be that the application needs to already be in iTunes Connect and that the test account must be associated with that application via the master company account.  Unfortunately, for the moment, this remains as an exercise for the reader.

Another (unproven) approach could be simply borrowing a receipt from any purchased application from the Mac App Store.  You will need to know the exact bundle identifier (fairly easy), version number (also easy), and computer GUID (not quite as easy), but you could use such a receipt exactly like the sample receipt previously provided by Apple.

Important: Do NOT include any receipt files in your project.  Receipts are specific to the application, version, and system, and they are generated and added by the Mac App Store/iTunes; including a receipt in your submission bundle will result in summary rejection of the application.

2. Locate the receipt file

The first step to take in your source code is to locate the receipt file for checking.  In the release version, intended for distribution, the location of the receipt is always within your application bundle at ‘Contents/_MASReceipt/receipt‘.

If you decide to use a sample receipt for testing, you will probably want to define its (different) location, the parameters expected from the sample receipt, and a definition to use for conditional compilation.  In our case, the debug versions define USE_SAMPLE_RECEIPT and the other values (from the old sample receipt) like so:

#ifdef APPSTORE
    #define RECEIPT         "Contents/_MASReceipt/receipt"

    #ifdef _DEBUG
        #define USE_SAMPLE_RECEIPT
    #endif

    #ifdef USE_SAMPLE_RECEIPT
        #define SAMPLE_RECEIPT  "/Users/Gregg/Desktop/receipt"
        #define SAMPLE_BUNDLE   "com.example.SampleApp"
        #define SAMPLE_VERSION  "1.0.2"
        #define SAMPLE_GUID     { 0x00, 0x17, 0xF2, 0xC4, 0xBC, 0xC0 }
    #endif
#endif

Note that we explicitly define different path variables (RECEIPT versus SAMPLE_RECEIPT) and only define the sample parameters when USE_SAMPLE_RECEIPT is defined.  This is additional protection against accidentally using a property intended only for testing in release code.  For the same reasons, we also include this check in the code before the main loop:

#ifndef _DEBUG
#ifdef USE_SAMPLE_RECEIPT
    ErrorMessage ( "Warning!  Sample receipt is being checked in release version." );
#endif
#endif

So, our first verification function is GetReceipt(), which returns the path of the (untouched) receipt file.  The routine obtains the path to the bundle and then generates the path directly to the receipt for later verification, adjusted appropriately if USE_SAMPLE_RECEIPT is defined.  Additionally, just for another sanity check, it also verifies that the actual bundle identifier and short version string match definitions within the code (so we can safely use the definitions later).

3. Check the signature

The next step in validating a receipt is to check the signature to verify that it is properly signed by Apple.  Sample code for doing this (as well as the next two steps) can be found in the Implementation Tips section of the Validating Mac App Store Receipts document, as well as via a nice web search.

Our second verification function is CheckSignature(), which returns a PKCS7* data pointer (and is essentially a fleshed out version of Listing 1-4 in the section linked above).  It opens the receipt file, validates the data types, adds the “Apple Root CA” certificate, and verifies the receipt signature (via PKCS7_verify), then cleans up everything except the receipt pointer, which is returned for use in the next function.

At this point, you know that the receipt file exists, it contains data, and its signature is valid.

4. Verify the receipt contents

The next step is validating a receipt is to verify the receipt contents and confirm that the receipt is intended for your application and the current version number.  The document referenced above gives more details about implementation, but the process is essentially stepping through the objects in the receipt and processing each one appropriately.

There are four types of objects within each receipt that are relevant to the validation process: bundle identifier, bundle version, opaque value, and hash.  In this step, you want to verify that the bundle identifier and bundle version match the hard-coded definitions for your project.  Note that matching against values retrieved from the bundle is not as safe, since the ‘Info.plist’ file could potentially be modified to match an invalid receipt.  Also, you will want to store the bundle identifier, opaque value, and hash object values for checking during the next step.

Our third verification function is VerifyData(), which accepts the PKCS7* data pointer returned by the previous function.  It loops through the objects in the receipt and processes them appropriately, failing if either bundle identifier or bundle version do not match our hard-coded values (IDENTIFIER and VERSION, or SAMPLE_BUNDLE/SAMPLE_VERSION), or if either of these objects is missing from the receipt.  Additionally, it saves the objects necessary for the next step.

At this point, you know that the receipt is intended specifically for the current version of your application.

5. Verify the system hash

The next (and, perhaps, final) step in validating a receipt is to verify the system hash to confirm that the receipt is intended for the particular system on which it is being launched.  This step prevents the outright copying of entire application bundles from one system to another.  Of course, on failure, users are presented with the opportunity to enter their iTunes account information to obtain a valid receipt automatically, so legitimate customers are protected.

The general process for this step involves two parts: obtaining the computer’s GUID and then computing the hash of the GUID, which is then compared to the hash value stored in the last step.  The sample code in the Apple documentation referenced above describes both steps sufficiently (in listings 1-3 and 1-7, respectively).

Our fourth verification function is VerifySystem(), which calls a CopyMacAddress() function to perform the first part of the process, then uses that information to check the system hash.  More specifically, the GUID returned is added to a digest, along with the opaque value and the bundle identifier, and an expected hash is calculated.  The routine verifies that the computed hash length is the same as that of hash and then checks that the contents are identical.

At this point in the process, you now know (to a reasonable degree) that the receipt file exists and is completely valid for that system running the current version of your application.

6. Take extra validation steps

If you are particularly concerned (or paranoid), you can take extra validation steps, such as verifying the certification authorities, double-checking the bundle signature, or (apparently) even sending a receipt back to the App Store for verification.  You can also take steps to obfuscate your code and make it harder for crackers to find and modify the application to circumvent your checks, and Apple provides some suggestions.

However, just taking the general steps documented here will probably eliminate 99% of the problem, and with robust coding, error checking, and testing, theft of the Mac App Store version of your game should be minimal.  (In fact, you will likely lose significantly more money to downward pricing pressures than to piracy, but that is another topic altogether…)

Conclusion

With the addition of receipt validation checking to your project source code, your application should not be subject to simple receipt spoofing, once accepted into the Mac App Store.  In the next (final) installment, Part 6: App Sandboxing implementation, I will discuss the process of preparing for and implementing application sandboxing, as required for the Mac App Store by June 1, 2012 (recently pushed back from March 1st).

MAS Preparation, Part 4

Posted on by
2

Source code modifications

In the previous installment of Preparing for Mac App Store Submission, I provided some guidelines for application data and resources that should be followed (where applicable) as you transform an existing Mac OS X game project into a project that can be successfully submitted to the Mac App Store (MAS).

In this fourth part, I will describe a number of modifications to the source code of your project that you may want to make to avoid unnecessary MAS rejections and, perhaps, improve your customer support and project maintenance.  These recommendations build on the theme of earlier posts, as most of these changes are due to Apple restrictions against anything having to do with downloading or external sales, including the use of registration codes.

As before, these suggestions are based solely on our experience with our products, so it could help to understand the basics of our sales system.  We have two separate downloadable builds for each Mac OS X product: one is a trial version, with limitations, and the other is a full version, which is unrestricted but requires a customer-specific registration code (as well as the hidden download location).  In order to better understand our customers, each web link in the program adds a very basic tracking code, so we know which version is being used; when online high scores are submitted, we include a hash of the registration code so the scores can be applied to the correct player account.

For this process, we have created a new store version, which is unrestricted (like the full version), includes available extra data (avoiding downloads), and cannot require a registration code.  (Instead, the Mac App Store automatically includes a “receipt” which should be checked, as discussed in the next installment.)  Here are the steps we took…

1. Store game data within user library folder

For the Mac App Store, game data that is not directly created by the user must be stored within the user library (not documents) folder.  Originally, we stored our saved games and statistics in ‘~/Documents/<project name>/<player>’, which made them easily accessible for our customers, but MAS guidelines (and an explicit rejection) required us to relocate such files to ‘~/Library/<project name>/<player>’, where they are less discoverable by users, especially since ‘~/Library’ is now hidden in Finder.  In our case, we actually relocated the files for all SKUs, including a function in the downloadable versions to automatically copy this game data to the new location, to make future customer support more manageable.

Note that, with application sandboxing (as discussed in the final installment), the actual location of the (sandboxed) user library is a significantly longer path name, and the main user documents folder is not accessible by default.  Obviously, the paths given above are illustrative only; one should never hard-code a path in project source code.

2. Remove all registration code via conditionals

Since any sort of registration code is forbidden, you should remove all registration code functionality via conditional compilation.  As part of our Project modifications earlier, we added an APPSTORE preprocessor variable to the store version target (only), which now allows us to remove sections of code with “#ifndef APPSTORE”/”#endif” sections.

In our case, every place in the code where the trial and full versions were different were already denoted with the preprocessor variable ‘DEMO’, so we only needed to look at each such section and decide if it should be like the full version (i.e., no limitations), which was the case most of the time, or like the trial version (i.e., no registration codes).

3. Add fixed internal MAS registration code

Because we used registration codes to differentiate between customers, we needed to add a fixed internal MAS registration code for all store version customers.  In order to replicate the previous functionality for online high score submissions, we needed a way to distinguish among different users without accessing any individually identifiable user information.  Alas, in the end, we had to provide a hash of some system information that was reasonably unique, and simply accept the possibility of a certain number of collisions.  (Thus far, MAS sales have not been high enough to get to levels where collisions are likely, though.)

Honestly, there is a possibility that information from the included MAS receipt could have provided a better (unique) customer identifier, but our implementation (above) was completed before receipt checking was considered.  In this case, that is left as an exercise for the reader (but comments on implementation are encouraged).

4. Update version tracking codes

For the store version, you should update any version tracking codes in your project, using conditional compilation (APPSTORE) where necessary.  This will allow any usage statistics to differentiate between downloadable and MAS customers, as well as from trial version users (i.e., potential customers).

In our case, we simply add a character to the end of link URLs (i.e., as part of a single GET variable) that makes this distinction, so we just added another legal value for MAS purchases.  Additionally, our shortened version numbers are slightly different so (savvy) players can identify the product played on the online high score pages (for example, on this FreeCell scores page, see the ‘Product’ column).

5. Remove or modify marketing screens

Consider whether you should modify or remove any marketing screens in your product.  If you have dialog boxes which have the occasional link to ordering pages or downloadable content, you will need to remove those links (and any referencing text); if you have dialogs that are explicitly for the purpose of marketing, it may make sense to remove them entirely instead.

In the case of our products, we include a fairly self-explanatory ‘Help Center‘ screen which not only contains links to the help files for the product, but also serves as a portal to all manner of support services, including sales (verboten), registration code entry (not allowed), customer support email (probably OK), and suggestions for other games (who knows?).  We found that removing the disallowed and questionable content from these pages made them almost pointless, so we instead replaced the entire dialog with a direct link to the help file contents page (within the bundle).

6. Remove links to any downloadable content

You must remove any links to downloadable content or risk the rejection of your product.  Note that these links (and, in truth, a number of other “offenses”) may not always be obvious on initial review, so your product can certainly get accepted once and then later rejected for something that was there in the first version; it has happened to us more than once.  (All Apple reviewers are not created equal.)

In the case of Pretty Good Solitaire, we have card sets which customers can freely download, plus a feature to check for and download updates, both of which are forbidden in the Mac App Store.  The following subsections describe the issues that we had to address to prevent suggesting that there was anything outside the MAS playground.

6a. Remove download links from main menus

We had to remove our ‘Download Additional Card Sets‘ menu option from both the main and game menus.

6b. Remove version checking from main menus

We had to remove our ‘Download Latest Version‘ menu option, which includes an implicit version check, from the both the main and game menus.

6c. Remove download links from submenus

We had to also remove a ‘Download Additional Card Sets‘ menu option from our submenu that players use to select the desired card set (a logical and convenient place to find it).

6d. Remove download links from buttons

Finally, we had a ‘Download Additional Card Sets‘ button within the program preferences, which also had to be removed (actually, hidden).

Note:  In all of these cases, rather than modify our user interface (.nib) files, and thus have to manage different sets of files, we added conditional code that simply removed the offending menu option or hid the button, keeping the source code (including .nib files) identical between downloadable and store versions (distinguished solely by the presence/absence of APPSTORE).

7. Review any use of the Application Support folder

Before submitting your application to MAS, carefully review your use of the Application Support folder (if any).  Specifically, you are allowed to create and (appropriately) use a folder at ‘~/Library/Application Support/<app-identifier>’, where <app-identifier> “can be your application’s bundle identifier, its name, or your company’s name.”

However, there is a twist:  “These strings must match what you provided through iTunes Connect for this application.”  This particular requirement is somewhat buried in the guidelines, and it is not always checked.

In our case, we inadvertently created but did not use (in the store version) a folder, ‘~/Library/Application Support/Goodsol’, which seems to fit the criteria.  However, it was supposed to end in ‘Goodsol Development’ to meet the letter of this requirement.  This “violation” was not discovered until our third or fourth submission, and our downloadable versions already used the folder extensively as named.  Fortunately, the store version did not actually use it (by virtue of including all downloadable content), so we just removed the spurious creation of an empty folder.  Problem solved (albeit with yet another rejection and delay).

Conclusion

With the above modifications to source code, plus perhaps a little detective work finding similar issues with any particular application, your project should be tentatively ready for submission to the Mac App Store.  In the next installment, Part 5: Mac App Store receipt validation, I will discuss the reasons that you should probably validate receipts in your shipping product and provide a few links to useful code and resources.

MAS Preparation, Part 3

Posted on by
2

Data and Resource guidelines

In the previous installment of Preparing for Mac App Store Submission, I detailed changes to the information property list that are necessary (or recommended) for a Mac OS X game project being converted to one suitable for MAS submission.

This third part deals with practical implications of guidelines for project data and resources, in particular, artwork and help files.  These points are necessarily somewhat specific to the manner in which we implemented our products, but they should give you some idea of items to look out for, and as always, comments on your experiences are encouraged.

Now, please review all of the artwork and other (non-code) resources in your project with these points in mind…

1. Include a 512×512 image in the application icon

The Mac App Store requires a 512×512 image in the application icon file.  Although this is generally overkill for an application, it is necessary for MAS submissions, where that image size is (presumably) used for presenting your product to users.

We actually produce our Macintosh (.icns) icons under Windows using Axialis IconWorkshop, which handles the required sizes without problem; we recommend this tool for processing icons for multiple platforms.  (We have no affiliation with Axialis, except as a satisfied customer.)

2. Update branding artwork

Although it seems (and truly is) silly, you need to review your branding artwork and update anything that even hints that there is another way to obtain software than through the Mac App Store.

Herein lies a theme: Apple hates downloads; Apple hates external sales.  Any suggestion that a customer may download or purchase anything outside of MAS will result in the rejection of your submission.  (Trust me, we had this thrown in our face, via rejection, more than once.)

In our case, we had a static bitmap used as a splash screen.  It included the (innocuous) line, “Download the latest version of Pretty Good Solitaire from http://goodsol.com“; it was hardly noticeable, and the web address was not even a hot link.  Rejection.  We had to remove that text before resubmitting (and we also removed the line with our support email address, just in case).

3. Add any extra product data desired

Continuing with the theme, you will need to add any extra product data that you may want customers to have, especially any data previously available via download.  In our case, we have (20) extra card sets that are available for Pretty Good Solitaire customers to download (and, likewise, extra tile sets and custom layouts for Pretty Good MahJongg), so these needed to be added to the main bundle to avoid Apple’s allergy to downloading.

The one minor advantage of this, of course, is that Apple has to bear the full download bandwidth burden.  (Card set artwork is not small.)

4. Remove trial version resources from the project

If appropriate, remove any resources used only in trial versions of your product.  In our case, we have an exit screen for trial users, as well as a separate interface (nib) file with all dialogs displayed (only) in the trial version, so we removed these.  (There is no sense including unused files, especially if they could give Apple more places to find reasons to reject.)

Similarly, if you have an install bitmap in your bundle, as I recommended in Making Mac Disk Images Pretty, you may as well remove that, too (since there is no disk image packaging to be done).

5. Remove any ‘How to Order’ section from help files

Review your help files and remove any pages that discuss verboten topics, such as downloading, registering, or (especially) purchasing the product.  We have an entire section called “How to Order”, dealing with all of those topics, that is just removed wholesale for the MAS submission (but remains in our downloadable versions); it was the cause for a rejection.

Note that Apple does not reject for simple web links back to a product site, which itself may have loads of sales and download information, but you will want to be careful about the surrounding text.

6. Remove text referring to downloading or sales

Building from the previous guideline, after removing entire pages about problematic topics, check other help topics and remove any text referring to downloads or sales, even indirectly.

In our case, we have rule pages for our bonus games, which are provided in the full (purchased) version, and we removed the line, “Note: This game is only available in the full version of Pretty Good Solitaire.”  Elsewhere, we also replaced “the full version” with “this version”.

Conclusion

Using the above guidelines, you should be able to make sure that your project does not include any content that Apple may find “objectionable”, giving them cause to reject the submission.  In the next installment, Part 4: Source code modifications, I will discuss the numerous (small) changes that may be necessary in your project source code.