Tag Archives: coding

The Beauty of Code

Posted on by
Reply

Programming itself provides opportunities for self-expression.

In the midst of chaos and strife, when I need to take a break from the “real world”, I most often find my escape in source code, programming anything really. Of course, having more projects than I could hope to finish, and clients providing additional work to boot, means that I always have a ready avenue for directing my focus. However, it is not solely about the product, nor the money; it is also about the pleasure and enjoyment of coding itself.

There are a number of fairly passive experiences that I (and I imagine most of us) use to pass the time: playing games, reading books, watching television or movies. There are also more productive activities such as exercise (I quite enjoy hiking, bicycling, and swimming), house cleaning and organization, home improvement, and “gardening” (of a sort). None of these activities, however, provides the same creative outlet as programming.

When it comes to creative expression, appropriately, there are lots of different ways that people find to fulfill that need, which is important to our being. I know lots of people who like to sketch or doodle, or to write (for which I have gained some appreciation over the years), and others participate in higher commitment activities such as making stuffed animals, woodworking, or designing jewelry. When I was younger, I turned to more “design” oriented expression, such as creating original mazes, designing pinball machines, and architecting dream houses; at one time I designed a complete go-kart business, including the tracks and buildings.

The beauty of code is that it allows for self-expression within a systematic framework. I have always enjoyed numbers, logic, and the rational, and these all factor into programming. Within the rules, though, there are essentially infinite ways to express an idea, both in terms of method and of presentation. Of course, there are demonstrably “wrong” ways to do things, such as code that does not compile, fails to work, or crashes, but there are many levels of “right” ways to accomplish things, including how to efficiently increase functionality, how to handle errors and unexpected situations, and (importantly) how to make the source code understandable.

When I was required to attend an “advanced” BASIC course in high school, having already programmed for years (but with no formal education to show it took vociferous insistence just to avoid the “beginner” class), one of the first problems we were presented was to take a three-digit number as input and reverse the digits. I was the very first person to complete the task, twice. My second version was the anticipated method of accepting numerical input, with constraints placed on the operator (not the program) to limit the input to 3 digits, separating the number into ones, tens, and hundreds places, and printing them in reverse order, just to prove that I knew how to do it that way. My first version accepted the input as a string and printed the characters in reverse order, which worked on the specified input type, but also on numbers of arbitrary size, or any characters that could be input.

Around that time, I also set myself a challenge to create an “unbreakable” game, which I was able to accomplish with a high degree of confidence. To be unbreakable, the program had to be bulletproof, once executed, such that nobody could deliberately nor accidentally get to the prompt (and, hence, have access to the source code). This meant that the program needed to have no syntax errors (BASIC was interpreted code, rather than compiled, so such errors would only be found when executed), no logic or constraint errors that would allow a crash (such as selecting an unexpected/illogical action or overloading an input buffer), and also disallow breaking (via ^C), which was accomplished via system-specific methods. The only ways to end the program were turning off the power or hitting the reset button.

Programming has a lot in common with the scientific method. Although you use known logic to devise provably correct solutions, rather than testing hypotheses, you still test to confirm your approach and resolve errors, whether they be in your understanding of the problem, your design of a potential solution, or your execution of the plan. In fact, I constantly use this approach when building a program to regularly test my assumptions. I will make an interim change and state (to myself) the expected failure outcome, whether that be a compiler error (or specific number of compilation errors) or some weird behavior, just to confirm my understanding. If some code compiles unexpectedly, or the behavior is not as anticipated, I revisit the problem and make sure than I can explain why things went differently.

This shows yet another beautiful aspect of programming: its digital nature makes it precise and enables, at least ostensibly, the pursuit of perfection. You can experiment with something new with confidence that, if it does not work out, you can return to exactly the original situation. It does not matter how far out in the weeds I get with an idea; I can always get back to where I started. (Try that with oil painting.😉) Also, as my first computer book helpfully pointed out at the start of my career, nothing that you do with source code, short of typing it with a hammer, can break your computer (and while that is not strictly true, exceptions are exceptionally rare and not worth concern).

The fact that I value the actual source code as well as the outcome, which tends to be better for such appreciation, explains why I am not a fan of “visual programming”. With traditional source code, everything is enumerated and readily viewable, having been written by you or another programmer. While visual programming is ostensibly the same, it hides aspects of the code and logic behind objects, making development more like hide-and-seek. My first experiences were in the very early ’90s with Asymetrix ToolBook and Borland ObjectVision, where one would have to check every page and object to find all of the scripts to have a complete understanding of the logic, which unnecessarily fragmented the code. Today, such tools as Unity, Unreal Engine, and Interface Builder certainly make visual layout easier, but with the inherent risk that the complexity hides some of the logic, removing it from the source code and fragmenting it. It can be quicker to develop visually (especially if one is inclined toward fast results over quality), but it is inarguably harder to debug.

Outstanding programming is more craft than art, by which I mean that it can be learned and refined over the course of years, and one does not necessarily require an inherent creative ability. I can explain the rationale behind decisions in my source code, and I can teach you techniques, and if you have the requisite logical intelligence (which many people do not), then you can become at least a very good programmer. (I doubt one can read a book about fine art and learn what it takes to be a master.) One of the best compliments I can get is when I am told that I taught somebody the value of maintainable source code, or defensive programming, or quality assurance techniques.

With that in mind, I intend to document more of my approaches to development in general, to provide insights that interested parties can take or leave, along the lines of my Quality [index] series from many years ago. One current focus is refining my programming standards, so look for that in the near future.

MAS Preparation, Part 6

Posted on by
2

App Sandboxing implementation

In the previous installment of Preparing for Mac App Store Submission, I discussed the reasons and methods for implementating Mac App Store receipt validation within your project.  At this point in the series, you may have already completed all of the currently necessary and recommended changes for converting your Mac OS X game, available for direct download, into an application suitable for the Mac App Store (MAS); you may have even submitted it already.

This final part is a discussion of the latest imposition by Apple, a technology known as application sandboxing, which was introduced with Mac OS X 10.7 Lion.  The general concept of sandboxing is that an application simply runs in its is own “sandbox”, unable to do anything outside its own little piece of the file system, except in specific cases, for which it must have entitlements.  The idea is that a compromised program (via malware or bad programming) is limited in the amount of system damage that can be done.  This is the way that all iOS applications work, and this is, in fact, just a transference of that approach to OS X.  The problem, of course, is that desktop systems are (and should be) different than tablets and phones, so certain types of programs are left out, including those which interact with other programs, such as those which provide ease of access to people who need assistance using computers.  (This is a very poorly considered decision on Apple’s part.)

Frankly, the main reason that you need to understand application sandboxing is that, as of June 1, 2012, all new applications and significant updates submitted to the Mac App Store are required to be sandboxed.  (This deadline was recently pushed back from the original date of March 1 in light of a considerable number of issues that Apple is still having with their implementation.)  If you already have a MAS application (or submit one before the deadline), you will be allowed to apply bug fixes without adding sandboxing, but otherwise, you will need to have sandboxing implemented.  (At least, that is what they are saying right now.)

0. Understand sandboxing

The first step is to understand application sandboxing and the implications of using it for your game.  The definitive documentation for Apple’s implementation of this technology is App Sandbox Design Guide, which is recommended reading.

Essentially, by default, your application is contained entirely within its own (read-only) bundle and a directory named by your bundle identifier (e.g., ‘com.goodsol.com/PrettyGoodSolitaire’) under the ‘~/Library/Containers’ folder.  An internal technology called Powerbox regulates (reads: mostly disallows) any access outside these two folders.  Most access to hardware features and user information is also disallowed without a specific entitlement.

If your game is entirely self-contained, then sandboxing may not present much of a problem.  If you use certain technologies, such as submitting high scores to a web site via the Internet, then you will have to enable appropriate entitlements.  If you have more involved interactions, especially involving other applications (or helpers), you may be forced to redesign/eliminate those features, or else give up on sandboxing (and, hence, the Mac App Store).  Whatever the situation, you will need to determine how this requirement will affect your application.

In our case, we lost the capability to load custom card sets, since the default operation (in the downloadable version) is to read installed files from the ‘Application Support’ folder, though that was not a huge blow since MAS already killed the idea of downloading improvements to the game.  The other feature that is gone is the ability to explicitly load and save games (for now) because the current version of our games are still built with Carbon, which cannot navigate the sandbox/Powerbox.  (Our primary save game feature, AutoSave, still works perfectly fine.)

1. Identify possible sandboxing issues

The next step is to identify possible issues with sandboxing your application, so let’s look at three different categories of features…

What you CAN do:
  • You may read files from your application bundle, as usual.  (Bundles should always be considered read-only, so your code should never attempt to write here.)
  • You may read and write files within your sandbox folders; this process is transparent provided you are using system calls to obtain the correct user folders (and you should never hard-code folder paths, anyway).
  • You may update your application preferences (.plist) using a standard API.
  • You may provide a simple link to a web page; this is allowed by default entitlements (i.e., not considered an outbound connection).
What you CANNOT do:
  • You may not read from nor write to most locations outside your sandbox, including the user desktop and document folders, without the user explicitly selecting the location (and the appropriate entitlement set).
  • You may not use any Carbon navigation dialogs, nor any Cocoa navigation dialogs other than NSOpenPanel and NSSavePanel, and you may not simulate user input to those panels.
  • You may not use “incompatible” functions, including those included in the Authorization Services and Accessibility APIs.
  • You may not send Apple events to arbitrary applications, nor broadcast user-info dictionaries.
  • You may not load any kernel extensions.
  • You may not alter preferences of other applications, nor terminate other applications, including helper applications.
  • You may not sign future updates with a different certificate than the original; doing so will cause Mac OS X to deliberately crash the program.
What requires an entitlement:
  • You need an entitlement to allow outbound network sockets (i.e., for sending information to the internet, operating as a client).
  • You need an entitlement to allow inbound network connections (i.e., for acting as a server).
  • You need an entitlement to allow read or write access to folders or files selected explicitly by the user (via NSOpenPanel/NSSavePanel).
  • You need entitlements to access the user’s ‘Movies’, ‘Music’, and ‘Pictures’ folders.
  • You need entitlements to access camera, microphone, or Bluetooth devices.
  • You need entitlements to access serial, USB, or FireWire ports.
  • You need an entitlement to allow printing.
  • You need entitlements to access the user’s address book or calendars.
  • You need an entitlement to allow the use of Core Location for determining geographical location.

 

After perusing the notes above, write down a list of features that may (or should) fall afoul of application sandboxing and be sure to test each of these features to confirm that they are working prior to enabling sandboxing entitlements.

2. Enable default entitlements

The next step is to enable the default entitlements for sandboxing; essentially, this disables all restricted access types, which allows us to verify which features of the game really need entitlements, and which work without modification.

To do this in Xcode 4.2.1 (under Lion) is fairly simple: Just open the ‘Summary’ tab for your target settings, scroll down to the ‘Entitlements’ section, and check the ‘Enable Entitlements’ (top) checkbox, and then confirm that the ‘Enable App Sandboxing’ checkbox is also selected.  If you are not already using iCloud in your project, then you should make sure that the ‘iCloud Key-Value Store’ is unchecked and cleared, and that that ‘iCloud Containers’ table is empty.

What the first checkbox actually does is create an entitlements file, a property list with the root name from ‘Entitlements File’ (defaults to the project name) and ‘.entitlements’ as the extension (e.g., ‘Pretty Good Solitaire.entitlements’), and it adds that file to your project.  The other (app sandboxing) checkbox automatically adds the ‘com.apple.security.app-sandbox‘ key to the entitlements file, which sets the default/maximum restrictions.

In order to build with application sandboxing enabled, you must be code signing the project.  Clearly this is already the case for projects being submitted to the Mac App Store.  However, if you are only testing and/or do not have an appropriate certificate (such as in our case where, as a contractor, I do not have access to the distribution certificate), you can follow the instructions in the ‘Create a Code Signing Certificate for Testing‘ section of the App Sandbox Quick Start.  [Editor: Sorry for no direct link, but section links on that page are fuzzled.]  The next section, ‘Specify the Code Signing Identity’, explains how to make the new certificate work with your project.

3. Verify access failures

Your next step is to verify access failures with application sandboxing enabled in the project.  To do this, start by launching the Console utility (from ‘Utilities’) and clearing its display.  This will show log entries to confirm a service denied by sandboxing.

Now, work through the list of suspect features that you created earlier and retest every one of those features with the new signed/sandboxed build.  Failures are, of course, expected, and for every failure there should be a log entry in Console from “sandboxd” and usually containing the text “deny” and an indication of the restricted service.

Note each confirmed failure, and determine which (if any) of the entitlements listed on the target ‘Summary’ page is likely to resolve the issue.  Do not make any changes to the entitlements until all of the suspect features are tested and notated.  A complete list of available entitlements can be found on the Enabling App Sandbox page of the Entitlement Key Reference.  (Note that some entitlements may not be listed on the ‘Summary’ page, requiring direct editing of the entitlements property file.)

If there are any features that are confirmed to fail only under sandboxing and for which there is not an appropriate entitlement, you may want to check the App Sandbox Temporary Exception Entitlements page for a solution that, as the name suggests, may work for the time being, but will probably not be available in the future.  If none of the entitlements nor temporary exceptions will resolve the problem, then you may need to redesign or remove that feature and/or lobby Apple to add an entitlement for the particular action you are attempting.

4. Add necessary entitlements

The next step is adding the necessary entitlements to the project, which should be done as an iterative process.  For each entitlement that you anticipate requiring, enable that entitlement, rebuild the project, then test every feature that is confirmed to have failed with sandboxing previously, noting each one that now functions correctly.

The general idea is that one should minimize the number of entitlements included (requested?) in a sandboxed application.  If you add an entitlement that does not actually help any of your features function, then you should immediately remove that entitlement.  Using excessive entitlements, in addition to reducing the (dubious) security, is a potential cause for rejection from the Mac App Store.  (In other words, simply checking all of the boxes may work in testing, but not for MAS submission.)

When you have completed this process, you should have a reasonably small number of entitlement keys (perhaps even zero) enabled, and all of the features of your program should be functioning properly.  It is always a good idea to double-check all of the identified features, as well as do some additional testing, once the “final” list of entitlements is enabled.  If you still have features that do not work under sandboxing (only), and have no appropriate entitlements, then you may have a decision to make.

In our case, we only had to add the ‘com.apple.security.network.client’ entitlement key, in order to perform submissions to our online high score server, but then we had to make the hard decision to lose the ‘Open…’ and ‘Save…’ features from our store version (for reasons stated previously).

5. Create file migration rules

The penultimate step in the process is creating file migration rules which is simply a property information file that is used only once (on a system) to indicate which existing files should be moved (not copied) into the sandbox.  If you have a new project, without existing users, then you have the luxury of skipping the final two steps.

The rest of us need to create a new property list, named (exactly) “container-migration.plist“, and add it to the project.  This file contains a dictionary key, ‘Move‘, which contains string keys indicating the names of folders and/or individual files to be moved into the equivalent location within the sandbox (or array pairs of strings if you wanted to both move files into the sandbox and relocate them within the relative folder hierarchy, though I cannot think of a good reason why you would).

The specific documentation for the (simple) format of this migration file is in Migrating an App to a Sandbox (which read).  The relevant portion of our migration file is as follows:

<dict>
    <key>Move</key>
    <array>
        <string>${Library}/Pretty Good Solitaire</string>
    </array>
</dict>

This is all it takes to move the entire (unsandboxed) ‘~/Library/Pretty Good Solitaire’ folder into the equivalent sandboxed folder (the unwieldy ‘~/Library/Containers/com.goodsol.PrettyGoodSolitaire/Data/Library/Pretty Good Solitaire’).

Important: Note that the files are moved to the sandbox; they are not copied (and there is no documented process to only copy them).  The ramifications of this are that existing users switching to a sandboxed version will automatically have their files and settings moved for them, but those files and settings will no longer be available to any unsandboxed versions, nor to any other application that may have been accessing these files.

6. Test file migration

The final step is to test the file migration process to assure that your migration file works correctly.

On a system on which you have unsandboxed data for the application in question, manually duplicate the folder and/or files (in ‘Finder’), giving you a backup for additional testing (especially important should the migration fail).  Confirm that the sandbox container folder (i.e., ‘~/Library/Containers/<bundle_id>’) does not exist (and delete it and empty the trash if it does).

Build the application with sandboxing enabled and with the ‘container-migration.plist’ file included in the project.  Run the application.  A container folder should have been created and the specified files/folders moved into appropriate locations within the container’s ‘Data’ folder.

If you need to retest (or if you decide against sandboxing entirely), you can completely delete the container folder for your application (‘<bundle_id>’ and below, not the ‘Containers’ folder) and copy the duplicated data back to its original location.

Conclusion

Following the above process to enable application sandboxing in your game, after having updated your project based on the previous five parts, you should be completely ready to submit to the Mac App Store.  Go for it!  Just keep in mind that the process changes, reviewers vary, and if your project is accepted on its first submission, you are very lucky.  However, if you use the available tools to check your code and your project build, and follow the guidelines in this series of posts, your path should be smoother.

I sincerely hope that you have enjoyed, or at least benefited from, all of these posts.  Comments are definitely appreciated, as are links to this blog, good word of mouth, and US currency in both large and small denominations.

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.

Objective-C: @property gotcha #1

Posted on by
Reply

Sometimes “best” practices can bite you.

In Apple iOS documentation, they strongly recommend the use of declared properties to automatically generate access methods to class variables.  In header files, you would have something like this:

@interface MyClass
{
    IBOutlet UIView* view;
}

@property (nonatomic, retain) IBOutlet UIView* view;

@end

 

Technically, this generates access methods named ‘view’ and ‘setView’, but in practice one generally accesses the class variable with the dot notation (i.e., ‘self.view’) .  The implementation of this class (minus any explicit methods) would be:

@implementation MyClass

@synthesize view;

@end

 

Accessing the variable with dot notation calls the access methods (as does calling them explicitly, obviously), but simply using ‘view’ (without the ‘self’ reference) accesses the variable directly, omitting any other functionality associated with the accessors, such as (in the above example) retaining the new view.  This is generally a poor practice except in initialization and deallocation routines, where it is preferred.

So, in order to assure that one does not accidentally skip the accessors, the recommended best practice is to use the ability of @synthesize to generate accessors that access a slightly different variable name.  In other words, instead of ‘view’ and ‘setView’ referencing the ‘view’ variable, they can be instead made to access ‘view_’:

@synthesize view = view_;

 

This is, in theory, a good idea because one can only access the variable directly with the explicit addition of an underscore (in this case), and simply referencing ‘view’ instead of ‘self.view’ should produce a compiler error.  (Note that we use a trailing underscore because leading underscores already have a specific meaning in our coding guidelines.)

Problem: If you modify the class implementation as noted above to put this into practice, you introduce a bigger problem into your code.  It turns out that @synthesize actually creates a class variable if none of the specified name exists, but it does not generate a warning or error if the one of the ostensible name does exist.  In other words, the above line would create a new ‘view_’ class variable, and create accessor methods, despite the fact that ‘view’ already exists.  The ‘view’ and ‘setView’ methods modify ‘view_’, so ‘self.view’ does the same, but failing to ‘self’ reference, rather than generating the intended error, actually modifies the orphaned ‘view’ variable.  Instead of having an extra compiler check, you instead have two very similar variables in the same class and any error becomes even harder to diagnose.

If the @property/@synthesize combination essentially replaces normal variable declarations, it obviates the whole issue of these declarations.  This seems rather silly/weird, since declaring [class] variables is a staple of C[++], and the method of doing this in Objective-C is one of the first lessons taught.  Nevertheless…

Solution: To make this idea an actual best practice, at least for simple classes, omit the entire parenthesized section of the class declaration and just declare all variables via @property/@synthesize statements.  You would end up with something like the following:

@interface MyClass
@property (nonatomic, retain) IBOutlet UIView* view;
@end
@implementation MyClass
@synthesize view = view_;

- (id)init
{
    self = [super init];
    if ( self )
    {
        view_ = nil;
    }
    return self;
}

- (void)dealloc
{
    [view_ release];
    [super dealloc];
}

@end

 

All (or most) other references to the class variable would be via dot notation, ‘self.view’, which would (of course) modify the ‘view_’ variable via accessors, as desired.

Happy coding!

API Design Dilemma

Posted on by
2

I need to decide how to define certain parameter types.

The general situation is this:  I am refactoring a piece of C++ code to be part of a separate library, so I am in the process of defining and documenting an API for using the included classes and methods.  A fundamental design consideration is that the library may be called by third parties, without access to the source code, so I need to make the code as close to bulletproof as possible.  (For internal development, at least I know the methods used, how the API will be utilized, and that it will not be abused terribly.)

During this process, I encountered a theoretical dilemma about how to handle certain parameters.  Specifically, I was working on method definitions that included sizes and counts that should never be negative (but, of course, I need to prepare for abuse).  As an example, say I am reviewing a method that is declared like this:

    bool FillBuffer ( byte* pBuffer, int nSize );

Here, pBuffer is a pointer to the buffer to be filled, and nSize is the size of that buffer.  Of course, it is not possible for a buffer to be a negative size, so my initial reaction was to redefine it as:

    bool FillBuffer ( byte* pBuffer, unsigned uSize );

This makes perfect sense from a theoretical standpoint, but then a practical consideration occurred to me.  I always verify parameters with an assertion and, for a public method (as here), abort the routine if verification fails, with an exception or error return as appropriate.  In this case, my original method would assert nSize to be greater than zero (and return false), which would catch any negatives.  The new method would only catch the case where uSize was zero, but if a careless programmer cast a signed integer (or, worse, let the compiler do it), the current validation check would not identify a problem.

So, there were a few obvious solutions that I considered:

  • I could leave the original definition alone, which would catch obvious parameter errors, but would be theoretically incorrect, and if a programmer wanted to pass the size of a static buffer, using sizeof(), there would be a signed/unsigned mismatch.
  • I could use the new method definition, which would be correct in theory, and just trust programmers not to abuse the method with invalid parameters (and let them suffer if they do).
  • I could use the new method definition and add a sanity check so an extremely large buffer size (i.e., likely a negative value cast improperly) would be rejected, but the drawback there is that any such check would be somewhat arbitrary, and it would limit the functionality for any programmer who truly wanted to use an enormous buffer.

Each of these solutions has advantages and drawbacks.  I dislike having a parameter take a type that is not accurate (though not so much as to not have written this code in the first place), but I dislike arbitrary limits even more.  However, I know that defensive design is important here, since a careless programmer is, in my experience, the most likely to complain that the library or API is at fault.  (I was once threatened with physical violence when I produced a critical review of code written by a nominal “programmer”.)

At this point, I am leaning toward a hybrid solution by overloading the method with both (or multiple) definitions, the original checking for negative sizes as usual before doing an explicit cast of the size value and passing processing to the new/correct method.  The advantage is that passing an actual negative number (or signed type) will result in that extra checking, and a programmer could pass a buffer size up to the limit of the unsigned type.  The disadvantages are the additional work needed to create the extra stub(s), loss of type checking during static analysis, and the fact that our careless friend could still cast a value to create problems (but then it should be quite obvious, at least).

This post is an exercise in the process of working through a problem by simply writing down the issues, which often results in a solution (or decision) by the time one is finished with the description.  (It did here.)  I would, however, welcome any comments on my proposed solution, or other suggestions.

Finally, yes, I know that int and unsigned are not ideal parameter types for this in the first place, but I used them for the purpose of illustration.  (The principle also applies to object counts and other similar parameter types.)

Three Steps to Apple Help, Part 3

Posted on by
Reply

Accessing Apple Help from C++ Code (Carbon)

The third/final step in implementing Apple Help is programmatically displaying the main contents or individual topics within your help pages.  This, of course, assumes that you have already created a set of HTML help pages for Apple Help and then indexed and integrated these files into your Xcode project.

Accessing Apple Help from C++ using Carbon is fundamentally simple.  The Apple Help Reference contains only 4 functions (plus one constant enumeration that is no longer used).  There is a little bit of necessary mucking about with bundle references and whatnot that may be unfamiliar to programmers who have not worked with Mac development before, but it is all fairly straightforward.

In order to access Apple Help from the application, you first register your help files using the AHRegisterHelpBook() function.  This only needs to be done once, ideally during program initialization, and we do it something like this:

bool RegisterHelp ( void )
{

    CFBundleRef const bundle = CFBundleGetMainBundle ( );
    if ( !bundle )
        return false;

    CFURLRef const location = CFBundleCopyBundleURL ( bundle );
    if ( !location )
        return false;

    FSRef file;
    if ( !CFURLGetFSRef ( location, &file ) )
    {
        CFRelease ( location );
        return false;
    }

    _Error = AHRegisterHelpBook ( &file );

    CFRelease ( location );

    if ( _Error )
        return false;

    return true;

}

(Additional validity checking and error reporting has been stripped from this sample code for clarity.)

In the above example, most of the code is just to obtain the FSRef (file system reference) of the application bundle from which the help is to be displayed, and it assumes that you want help for the current application.  (Obviously, you could instead pass a reference to any other bundle and access a different help system, but that would be unusual.)

Once the help files are registered, you can display the main help page using the AHGotoPage() function (with default parameters), which we accomplish with a function similar to this:

void ShowHelpContents ( void )
{

    CFBundleRef const bundle = CFBundleGetMainBundle ( );
    if ( !bundle )
        return;

    CFStringRef const key = CFSTR( "CFBundleHelpBookName" );
    CFTypeRef const book =
        CFBundleGetValueForInfoDictionaryKey ( bundle, key );
    if ( !book )
        return;

    CFStringRef const help = (CFStringRef)book;

    _Error = AHGotoPage ( help, NULL, NULL );

}

(Additional validity checking and error reporting has been stripped from this sample code for clarity.)

You can also display a specific help topic by using the AHLookupAnchor() function, for which we use something like this:

void ShowHelpTopic ( CFStringRef topic )
{

    if ( !topic )
        return;

    CFBundleRef const bundle = CFBundleGetMainBundle ( );
    if ( !bundle )
        return;

    CFStringRef const key = CFSTR( "CFBundleHelpBookName" );
    CFTypeRef const book =
        CFBundleGetValueForInfoDictionaryKey ( bundle, key );
    if ( !book )
        return;

    CFStringRef const help = (CFStringRef)book;

    _Error = AHLookupAnchor ( help, topic );

}

(Additional validity checking and error reporting has been stripped from this sample code for clarity.)

In both of these last two examples, the function reads the CFBundleHelpBookName string from the main application bundle and uses that string for the name of the help system, passed as the first parameter to the appropriate Apple Help function.  (You could, of course, hard code this string, but if you were thinking that this is a good idea, shame on you.)

Accessing Apple Help from Objective-C (Cocoa)

If you are using Objective-C and Cocoa, much of the help system handling is done behind the scenes (which is, in part, why some programmers find Objective-C to be objectionable).  If you follow the steps in the previous two posts (Part 1 and Part 2) to insert your Apple Help into a Cocoa project, your main help system will work automatically.

The main help page in a Cocoa application is accessible by the user through the ‘Help->[ApplicationName] Help’ menu option by default.  If you wish to bring up the main page from your Objective-C code, you may need to reference an anchor on that page (see below) or use the Carbon method described above.

To access a specific help topic (anchor) from Objective-C and Cocoa, this is done through the shared NSHelpManager object using the openHelpAnchor:inBook: method.  For example, to open the ‘rules’ topic, you would use the following code:

    NSString *book = [[NSBundle mainBundle]
        objectForInfoDictionaryKey:@"CFBundleHelpBookName"];
    [[NSHelpManager sharedHelpManager]
        openHelpAnchor:@"rules" inBook:book];

The documentation for NSHelpManager is quite clear that all of its functionality is simply a number of wrappers around the functions described in the first section of this post, so you could always use those functions directly, if desired.

There you have it.  At this point, you should know enough to properly implement Apple Help in your Carbon or Cocoa application for Mac OS X.  The process is a little convoluted to suss out from the documentation, so I hope this provides a decent jump start.