Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 236 lines (168 sloc) 9.928 kB
0cf7f9b Reformat README using Markdown. Change licence to BSD.
Gleb Dolgich authored
1 # Overview
2
3 CocoaFob is a set of helper code snippets for registration code generation and
4 verification in Objective-C applications, integrated with registration code
5 generation in Potion Store <http://www.potionfactory.com/potionstore> and FastSpring <http://fastspring.com>.
6
7 The current implementation uses DSA to generate registration keys, which
8 significantly reduces chances of crackers producing key generators for your
9 software. Unfortunately, it also means the registration code can be quite long
10 and has variable length.
11
12 To make registration codes human-readable, CocoaFob encodes them using a
13 slightly modified base32 to avoid ambiguous characters. It also groups codes
14 in sets of five characters separated by dashes. A sample registration code
15 produced using a 512-bit DSA key looks like this:
16
17 `GAWQE-FCUGU-7Z5JE-WEVRA-PSGEQ-Y25KX-9ZJQQ-GJTQC-CUAJL-ATBR9-WV887-8KAJM-QK7DT-EZHXJ-CR99C-A`
18
19 One of the advantages of DSA is that for a given registration name, each
20 generated code is different, as there is a random element introduced during
21 the process.
22
23 The name 'CocoaFob' is a combination of 'Cocoa' (the Mac and iOS programming framework) and 'Fob' (a key fob is something you keep your keys on).
24
25 # Features
26
27 CocoaFob provides the following for your application:
28
29 - Secure asymmetric cryptography-based registration key generation and
30 verification using DSA.
31
32 - Support for key generation in Objective-C and Ruby and verification in
33 Objective-C for integration in both your Cocoa application and Potion Store.
34
35 - Support for custom URL scheme for automatic application registration.
36
37 There is no framework or a library to link against. You include the files you
38 need in your application project directly and are free to modify the code in
39 any way you need.
40
41 You may also find other snippets of code useful, such as base32 and base64
42 encoding/decoding functions, as well as categories extending `NSString` and
43 `NSData` classes with base32 and base64 methods.
44
45 # Usage
46
47 The best way to get the latest version of the code is to clone the main Git
48 repository:
49
50 `git://github.com/glebd/cocoafob.git`
51
52 You can also download the latest version from the CocoaFob home page at
53 <http://github.com/glebd/cocoafob/>.
54
55 For more complete examples of how to use CocoaFob, look at the following
56 projects by Alex Clarke: CodexFab <https://github.com/machinecodex/CodexFab/>
57 and LicenseExample <https://github.com/machinecodex/CodexFab_LicenseExample/>.
58
59 ## Providing a Registration Source String
60
61 To register an application that uses CocoaFob, it is necessary to provide a
62 string of source information, which may be as simple as a registration name
63 or arbitrarily complex in case your application is processing the included
64 information in a user-friendly way. For example, as suggested in the sample
65 implementation of Potion Store licence generator, a source string may contain
66 application name, user name and number of copies:
67
68 `myapp|Joe Bloggs|1`
69
70 When sending registration mail, you need to provide both the source string and
71 the registration code. Potion Store does this for you. However, small
72 modifications are needed to make automatic activation work.
73
74 ## Generating automatic activation URLs
75
76 Potion Store supports automatic activation of an installed application by
77 clicking on a special link in a registration email or on the Thank You store
78 page. For this to work, you need to:
79
80 - make your application support a registration URL scheme;
81
82 - modify Potion Store so that automatic activation link contains not only
83 registration code, but registration source string as well.
84
85 The stock implementation of Potion Store registration code support assumes a
86 registration code is all that is needed to register an application. However,
87 CocoaFob needs to know both registration name and registration code in order
88 to verify the licence. This means when Potion Store generates an automatic
89 registration URL for your application, it needs to include registration source
90 string in it. One of the possible solutions is as follows:
91
92 - In your database migration `001_create_tables.rb`, increase the length of
93 `license_key` column in `line_items` table to 128 characters:
94
ba91e68 Fix formatting in README
Gleb Dolgich authored
95 `t.column "license_key", :string, :limit => 128`
0cf7f9b Reformat README using Markdown. Change licence to BSD.
Gleb Dolgich authored
96
97 - In the file `app/models/line_item.rb`, add the following line at the top:
98
99 `require "base64"`
100
101 - In the same file find function called `license_url` near the bottom of the
102 file. Replace it with the following (or modify to your heart's content):
103
104 <pre>
105 def license_url
106 licensee_name_b64 = Base64.encode64(self.order.licensee_name)
107 return "#{self.product.license_url_scheme}://#{licensee_name_b64}/#{self.license_key}" rescue nil
108 end
109 </pre>
110
111 This will make generated registration codes to contain base64-encoded licensee
112 name. When your application is opened by clicking on the registration link, it
113 will parse the code, extract the registration name and use it to verify the
114 licence.
115
116 ## Supporting registration URL schema in your app
117
118 The following files in objc directory provide a sample implementation of
119 support for custom URL schema for application registration. The code is almost
120 literally taken from [3].
121
122 To support registration URLs in your application:
123
124 - Add files `MyApp.scriptSuite` and `MyApp.scriptTerminology` to your project's
125 resources, adjusting strings inside appropriately.
126
127 - Add the following to your application's `Info.plist` file under `/plist/dict`
128 key (replace *mycompany* and *myapp* with strings appropriate for your company
129 and application):
130
131 <pre>
132 &lt;key&gt;NSAppleScriptEnabled&lt;/key&gt;
133 &lt;string&gt;YES&lt;/string&gt;
134 &lt;key&gt;CFBundleURLTypes&lt;/key&gt;
135 &lt;array&gt;
136 &lt;dict&gt;
137 &lt;key&gt;CFBundleURLSchemes&lt;/key&gt;
138 &lt;array&gt;
139 &lt;string&gt;com.mycompany.myapp.lic&lt;/string&gt;
140 &lt;/array&gt;
141 &lt;/dict&gt;
142 &lt;/array&gt;
143 </pre>
144
145 - Add the files `URLCommand.h` and `URLCommand.m` to your project, paying
146 attention to the `TODO:` comments in them. Specifically, you may want to save
147 registration information to your application's preferences, and also
148 broadcast a notification of a changed registration information after
149 verifying the supplied registration URL.
150
151 - Be sure the URL scheme name in the `Info.plist` file
152 (`com.mycompany.myapp.lic`) is the same as the one in the database generation
153 script for Potion Store. It is the file `db/migrate/001_create_tables.rb`, and
154 the variable is called `license_url_scheme`.
155
156 Test the URL schema support by making a test purchase which results in
157 displaying an activation link, and clicking on it. If you are running your
158 application in debugger, place a breakpoint in the instance method
159 `performWithURL:` of the class `URLCommand`. The breakpoint will be triggered
160 when you click on the registration link. You can extract the link into a
161 standalone HTML file so that is available for testing without making any
162 additional test purchases.
163
164 # Generating Keys
165
166 IMPORTANT NOTE: Included keys are for demonstration and testing purposes only.
167 DO NOT USE THE INCLUDE KEYS IN YOUR SOFTWARE. Before incorporating CocoaFob
168 into your application, you need to generate a pair of your own DSA keys. I
169 used key length of 512 bit which I thought was enough for the registration
170 code generation purposes.
171
172 (0) Make sure OpenSSL is installed. (If you're using Mac OS X, it already is.)
173
174 (1) Generate DSA parameters:
175
176 openssl dsaparam -out dsaparam.pem 512
177
178 (2) Generate an unencrypted DSA private key:
179
180 openssl gendsa -out privkey.pem dsaparam.pem
181
182 (3) Extract public key from private key:
183
184 openssl dsa -in privkey.pem -pubout -out pubkey.pem
185
186 See [2] for more information.
187
188 # Licence
189
190 Written by Gleb Dolgich
191 Twitter: @glebd
192 Web: <http://pixelespressoapps.com>
193
194 CocoaFob is distributed under the BSD License
195 <http://www.opensource.org/licenses/bsd-license.php>
196
197 Copyright &copy; 2009-2011, PixelEspresso. All rights reserved.
198
199 Redistribution and use in source and binary forms, with or without modification,
200 are permitted provided that the following conditions are met:
201
202 Redistributions of source code must retain the above copyright notice, this list
203 of conditions and the following disclaimer. Redistributions in binary form must
204 reproduce the above copyright notice, this list of conditions and the following
205 disclaimer in the documentation and/or other materials provided with the
206 distribution.
207
208 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
209 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
210 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
211 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
212 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
213 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
214 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
215 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
216 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
217 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
218
219 # Credits
220
221 [0] The Mac developer community that continues to amaze me.
222
223 [1] Base32 implementation is Copyright (C) 2007 by Samuel Tesla and comes from
224 Ruby base32 gem: <http://rubyforge.org/projects/base32/>. Samuel Tesla's blog is
225 at <http://blog.alieniloquent.com/tag/base32/>.
226
227 [2] OpenSSL key generation HOWTO: <http://www.openssl.org/docs/HOWTO/keys.txt>
228
229 [3] Handling URL schemes in Cocoa: a blog post by Kimbro Staken
230 <http://www.xmldatabases.org/WK/blog/1154?t=item>
231
232 [4] Registering a protocol handler for an App: a post on CocoaBuilder mailing
233 list, <http://www.cocoabuilder.com/archive/message/cocoa/2009/2/2/229297>
234
235 [5] PHP implementation courtesy of Sandro Noel, <http://gesosoft.com>
Something went wrong with that request. Please try again.