Permalink
Browse files

Added files to support custom URL scheme for application registration…

…; README updated with instructions
  • Loading branch information...
1 parent 2edd097 commit 1d9c1ec6d11fa71f3a05af9b4f64c4e0827421d4 Gleb Dolgich committed Mar 20, 2009
Showing with 215 additions and 24 deletions.
  1. +109 −24 README
  2. +12 −0 objc/MyApp.scriptSuite
  3. +11 −0 objc/MyApp.scriptTerminology
  4. +22 −0 objc/URLCommand.h
  5. +61 −0 objc/URLCommand.m
View
133 README
@@ -5,10 +5,11 @@ TABLE OF CONTENTS
=================
1. DESCRIPTION
-2. USAGE
-3. GENERATING KEYS
-4. LICENCE
-5. CREDITS
+2. FEATURES
+3. USAGE
+4. GENERATING KEYS
+5. LICENCE
+6. CREDITS
1. DESCRIPTION
==============
@@ -33,12 +34,28 @@ One of the advantages of DSA is that for a given registration name, each
generated code is different, as there is a random element introduced during
the process.
+2. FEATURES
+===========
+
+(to be written)
+
+3. USAGE
+========
+
+The best way to get the latest version of the code is to clone the main Git
+repository:
+
+git://github.com/gbd/cocoafob.git
+
+You can also download the latest version from the CocoaFob home page at
+<http://github.com/gbd/cocoafob/>.
+
Providing a Registration Source String
--------------------------------------
To register an application that uses CocoaFob, it is necessary to provide a
string of source information, which may be as simple as a registration name
-and arbitrarily complex in case your application is processing the included
+or arbitrarily complex in case your application is processing the included
information in a user-friendly way. For example, as suggested in the sample
implementation of Potion Store licence generator, a source string may contain
application name, user name and number of copies:
@@ -49,8 +66,8 @@ When sending registration mail, you need to provide both the source string and
the registration code. Potion Store does this for you. However, small
modifications are needed to make automatic activation work.
-Automatic Activation
---------------------
+Generating automatic activation URLs
+------------------------------------
Potion Store supports automatic activation of an installed application by
clicking on a special link in a registration email or on the Thank You store
@@ -61,35 +78,97 @@ page. For this to work, you need to:
- modify Potion Store so that automatic activation link contains not only
registration code, but registration source string as well.
-<more info coming>
+The stock implementation of Potion Store registration code support assumes a
+registration code is all that is needed to register an application. However,
+CocoaFob needs to know both registration name and registration code in order
+to verify the licence. This means when Potion Store generates an automatic
+registration URL for your application, it needs to include registration source
+string in it. One of the possible solutions is as follows:
-2. USAGE
-========
+- In the file app/models/line_item.rb, add the following line at the top:
+
+ require base64
+
+- In the same file find function called license_url--it's near the bottom of
+ the file. Replace it with the following (or modify to your heart's content):
+
+ def license_url
+ licensee_name_b64 = Base64.encode64(self.order.licensee_name)
+ return "#{self.product.license_url_scheme}://#{licensee_name_b64}/#{self.license_key}" rescue nil
+ end
+
+This will make generated registration codes to contain base64-encoded licensee
+name. When your application is opened by clicking on the registration link, it
+will parse the code, extract the registration name and use it to verify the
+licence.
-<to be written>
+Supporting registration URL schema in your app
+----------------------------------------------
-3. GENERATING KEYS
+The following files in objc directory provide a sample implementation of
+support for custom URL schema for application registration. The code is almost
+literally taken from [3].
+
+To support registration URLs in your application:
+
+- Add files MyApp.scriptSuite and MyApp.scriptTerminology to your project's
+ resources, adjusting strings inside appropriately.
+
+- Add the following to your application's Info.plist file under /plist/dict
+ key (replace mycompany and myapp with strings appropriate for your company
+ and application):
+
+ <key>NSAppleScriptEnabled</key>
+ <string>YES</string>
+ <key>CFBundleURLTypes</key>
+ <array>
+ <dict>
+ <key>CFBundleURLSchemes</key>
+ <array>
+ <string>com.mycompany.myapp.lic</string>
+ </array>
+ </dict>
+ </array>
+
+- Add the files URLCommand.h and URLCommand.m to your project, paying
+ attention to the TODO: comments in them. Specifically, you may want to save
+ registration information to your application's preferences, and also
+ broadcast a notification of a changed registration information after
+ verifying the supplied registration URL.
+
+- Be sure the URL scheme name in the Info.plist file (com.mycompany.myapp.lic)
+ is the same as the one in the database generation script for Potion Store.
+ It is the file db/migrate/001_create_tables.rb, and the variable is called
+ license_url_scheme.
+
+Test the URL schema support by making a test purchase which results in displaying an activation link, and clicking on it. If you are running your application in debugger, place a breakpoint in the
+
+4. GENERATING KEYS
==================
-NOTE: Included keys are for demonstration and testing purposes only. DO NOT
-USE THE INCLUDE KEYS IN YOUR SOFTWARE. Before incorporating CocoaFob into your
-application, you need to generate a pair of your own DSA keys. I used key
-length of 512 bit which I thought was enough for the registration code
-generation purposes.
+IMPORTANT NOTE: Included keys are for demonstration and testing purposes only.
+DO NOT USE THE INCLUDE KEYS IN YOUR SOFTWARE. Before incorporating CocoaFob
+into your application, you need to generate a pair of your own DSA keys. I
+used key length of 512 bit which I thought was enough for the registration
+code generation purposes.
+
+(0) Make sure OpenSSL is installed. (If you're using Mac OS X, it is.)
(1) Generate DSA parameters:
-openssl dsaparam -out dsaparam.pem 512
+ openssl dsaparam -out dsaparam.pem 512
(2) Generate an unencrypted DSA private key:
-openssl gendsa -out privkey.pem dsaparam.pem
+ openssl gendsa -out privkey.pem dsaparam.pem
(3) Extract public key from private key:
-openssl dsa -in privkey.pem -pubout -out pubkey.pem
+ openssl dsa -in privkey.pem -pubout -out pubkey.pem
-4. LICENCE
+See [2] for more information.
+
+5. LICENCE
==========
CocoaFob is Copyright (C) 2009 PixelEspresso
@@ -100,11 +179,17 @@ CocoaFob is distributed under Creative Commons Attribution 3.0 License
<http://creativecommons.org/licenses/by/3.0/>. Attribution may take form of a
mention in your application About box or other documentation.
-5. CREDITS
+6. CREDITS
==========
-Base32 implementation is Copyright (C) 2007 by Samuel Tesla and comes from
+[1] Base32 implementation is Copyright (C) 2007 by Samuel Tesla and comes from
Ruby base32 gem: <http://rubyforge.org/projects/base32/>. Samuel Tesla's blog
is at <http://blog.alieniloquent.com/tag/base32/>.
-OpenSSL key generation HOWTO: <http://www.openssl.org/docs/HOWTO/keys.txt>
+[2] OpenSSL key generation HOWTO: <http://www.openssl.org/docs/HOWTO/keys.txt>
+
+[3] Handling URL schemes in Cocoa: a blog post by Kimbro Staken
+<http://www.xmldatabases.org/WK/blog/1154?t=item>
+
+[4] Registering a protocol handler for an App: a post on CocoaBuilder mailing
+list, <http://www.cocoabuilder.com/archive/message/cocoa/2009/2/2/229297>
View
12 objc/MyApp.scriptSuite
@@ -0,0 +1,12 @@
+// Decloner.scriptSuite:
+{
+ Name = Decloner;
+ AppleEventCode = "DeCl";
+ Commands = {
+ "GetURL" = {
+ CommandClass = DCDeclonerCommand;
+ AppleEventCode = GURL;
+ AppleEventClassCode = GURL;
+ };
+ };
+}
View
11 objc/MyApp.scriptTerminology
@@ -0,0 +1,11 @@
+// Decloner.scriptTerminology:
+{
+ Name = "Decloner commands";
+ Description = "Commands to handle a URL";
+ Commands = {
+ "GetURL" = {
+ "Name" = "get URL";
+ "Description" = "Open a URL";
+ };
+ };
+}
View
22 objc/URLCommand.h
@@ -0,0 +1,22 @@
+//
+// CocoaFob
+//
+// URLCommand.h
+//
+// Support for custom URL scheme for app registration
+//
+// Created by Gleb Dolgich on 20/03/2009.
+// Follow me on Twitter @gbd
+// Copyright (C) 2009 PixelEspresso. All rights reserved.
+// Licensed under CC Attribution License 3.0 <http://creativecommons.org/licenses/by/3.0/>
+//
+// Based on "Handling URL schemes in Cocoa", a blog post by Kimbro Staken
+// <http://www.xmldatabases.org/WK/blog/1154?t=item>
+//
+
+#import <Foundation/Foundation.h>
+
+@interface URLCommand : NSScriptCommand {
+}
+
+@end
View
61 objc/URLCommand.m
@@ -0,0 +1,61 @@
+//
+// CocoaFob
+//
+// URLCommand.h
+//
+// Support for custom URL scheme for app registration.
+// Pay attention to the TODO: comments below.
+//
+// Created by Gleb Dolgich on 20/03/2009.
+// Follow me on Twitter @gbd
+// Copyright (C) 2009 PixelEspresso. All rights reserved.
+// Licensed under CC Attribution License 3.0 <http://creativecommons.org/licenses/by/3.0/>
+//
+// Based on "Handling URL schemes in Cocoa", a blog post by Kimbro Staken
+// <http://www.xmldatabases.org/WK/blog/1154?t=item>
+//
+
+#import "URLCommand.h"
+#import "NSString+PECrypt.h"
+
+@interface URLCommand ()
+
+- (id)performWithURL:(NSString *)url;
+
+@end
+
+
+@implementation URLCommand
+
+- (id)performDefaultImplementation {
+ NSString *url = [self directParameter];
+ NSLog(@"URL = %@", url);
+ return [self performWithURL:url];
+}
+
+- (id)performWithURL:(NSString *)url {
+ // URL has the following format:
+ // com.mycompany.myapp.lic://<base64-encoded-username>/<serial-number>
+ NSArray *protocolAndTheRest = [url componentsSeparatedByString:@"://"];
+ if ([protocolAndTheRest count] != 2) {
+ NSLog(@"License URL is invalid (no protocol)");
+ return nil;
+ }
+ // Separate user name and serial number
+ NSArray *userNameAndSerialNumber = [[protocolAndTheRest objectAtIndex:1] componentsSeparatedByString:@"/"];
+ if ([userNameAndSerialNumber count] != 2) {
+ NSLog(@"License URL is invalid (missing parts)");
+ return nil;
+ }
+ // Decode base64-encoded user name
+ NSString *usernameb64 = (NSString *)[userNameAndSerialNumber objectAtIndex:0];
+ NSString *username = [usernameb64 base64Decode];
+ NSLog(@"User name: %@", username);
+ NSString *serial = (NSString *)[userNameAndSerialNumber objectAtIndex:1];
+ NSLog(@"Serial: %@", serial);
+ // TODO: Save registration to preferences.
+ // TODO: Broadcast notification of a changed registration information.
+ return nil;
+}
+
+@end

0 comments on commit 1d9c1ec

Please sign in to comment.