system-lock

How to legally submit an app to Apple’s App Store when it uses encryption (or how to obtain an ERN)

Disclaimer: I am not a lawyer, this is not legal advice. 


Shameless plug: I am available for hire doing Ruby, Clojure, Python or many of my other skills including managing developers.


There’s a lot of conflicting information out there about whether you need an ERN or not to publish an app in the App Store. I spoke to Apple representatives as well as various employees of a couple of US agencies. As painful as it is, if your app is capable of the simplest, most standard, of encryptions such as SSL/HTTPS then you need to answer your export compliance questions like this:

Mac App Store questions and answers about encryption

The conclusion from selecting the above answers:

To make your app available on the App Store, you must submit a copy of your U.S. Encryption Registration (ERN) approval from the U.S. Bureau of Industry (BIS).

In some places, you’ll see CCATS instead of ERN. I’m not 100% sure, but it seems CCATS was a previous more bureaucratic version of the ERN. Right now, what you need is an ERN and this is our journey to get it. We are publishing as much detail as possible so that you can replicate it for your own application. There are some other blog posts that explain how to do it, but we found that over the years, some of the steps changed and we had to find a new path. Since this is going to happen again, we are adding as much information as possible so that should your path be slightly different, you won’t have much trouble finding your way through it.

Starting at the beginning

After being utterly confused by both Apple’s as well as BIS’ FAQ and how to pages, I decided to go the homepage for the Bureau of Industry and Security and see where it took me:

Homepage for the Bureau of Industry and Security

At this point I new SNAP-R was relevant to my needs. I was almost under the impression of needing one, even though I didn’t know what it was. Going through that page I found this:

BIS Would you like to

Yes! I’d like to submit an application (SNAP-R) – fourth item in the list. That takes you to this page: http://www.bis.doc.gov/index.php/licensing/simplified-network-application-process-redesign-snap-r, which defines what a SNAP-R is. It stands for Simplified Network Application Process – Redesign. I think a SNAP-R is sort of an account with the BIS. There’s no mention of ERN in that page, but it says:

You must have a Company Identification Number (CIN) and an active user account to access SNAP-R. The procedures and requirements for obtaining a CIN and user account are set forth below.

You need to obtain a CIN before you can proceed. If you scroll all the way to the bottom of the page, you’ll see:

BIS Obtaining a CIN for a SNAP-R for an ERN

And that link, ladies and gentlemen, is the most promising I’ve seen so far. It takes you to https://snapr.bis.doc.gov/registration/Register.do which looks like this:

BIS SNAP-R Company Registration for an ERN

The SNAP-R Company Registration process

After completing and submitting that form you’ll get an email to confirm your email address. I recommend limiting yourself to ASCII characters here, as the é and á in my name got mangled. That email took only a few minutes to arrive but the confirmation page claims the next step might take up to five days:

BIS SNAP-R Email confirmation

Some people claim to have been finished in 30 minutes or even less. I suppose it depends where you or your company is located. In my case, the five days elapsed so I sent them an email and two days later I got a reply telling me to call their support number: +1-202-482-2227 (later on I learned that another phone number that might help is +1-202-482-0707). When I talked to a representative, he said that I should have received the activation email already and just re-triggered it. Maybe calling them after a couple of days would have been a good approach to speed things up. Shortly after my call I got this email:

BIS SNAP-R Account Invitation email - for ERN

That link takes you to a page to set up your log in and password:

BIS SNAP-R Login ID and Password Setup

After entering those details, voila! you have an account:

BIS SNAP-R Login ID and Password Setup - account created

You may now log in:

BIS SNAP-R login in - for ERN

After logging in, you are now in your SNAP-R Home page:

Creating a new work item within your SNAP-R account

The next step is to create a new work item, which you can do from the sidebar. That takes you to a page that looks like this:

BIS SNAP-R Create Work Item

The type of work item that you want, to be able to distribute apps with encryption, is an Encryption Registration:

BIS SNAP-R Create Work Item Type Encryption Registration

Now, about the Reference Number, the question mark next to it sends you to https://snapr.bis.doc.gov/snapr/docs/fieldHelp.html#NewWrkItem1 where it says:

Enter a valid reference number for the Work Item. Reference numbers must be in the format “AAA1111”.

which didn’t really answer what a reference number is. I decided to call them again and when I asked the question they put me on hold for 25 minutes. I hung up, called them again and I was speaking with someone else in less than 3 minutes and she answered. The reference number is just something you make up, for yourself. It’s not something you obtain and it seems as long as you follow their convention, it’s fine:

BIS SNAP-R - Create Work Item - Encryption Registration and reference number

After creating the work item, you are invited to edit it. It starts partially populated and it’s straight forward:

BIS SNAP-R Edit Work Item Encryption Registration

Well, it’s straightforward until the last part: Documents. You need to attach the Encryption Registration Supplement No. 5 to Part 742.

Creating the Encryption Registration Supplement

Creating the supplement, thankfully, is easier than it looks; that is, when you know what you have to do. There’s a document number 742 that you can download from https://www.bis.doc.gov/index.php/forms-documents/doc_download/1208-742 and  on page 60 it has the Supplement No. 5: Encryption Registration. These are the contents of that page:

SUPPLEMENT NO. 5 TO PART 742 – ENCRYPTION REGISTRATION

Certain classification requests and self-classification reports for encryption items must be supported by an encryption registration, i.e., the information as described in this Supplement, submitted as a support documentation attachment to an application in accordance with the procedures described in §§ 740.17(b), 740.17(d), 742.15(b), 748.1, 748.3 and Supplement No. 2 to part 748 of the EAR.

(1) Point of Contact Information

(a) Contact Person

(b) Telephone Number

(c) Fax Number

(d) E-mail address

(e) Mailing Address

(2) Company Overview (approximately 100 words).

(3) Identify which of the following categories apply to your companys technology/families of products:

(a) Wireless

(i) 3G cellular

(ii) 4G cellular/WiMax/LTE

(iii) Short-range wireless / WLAN

(iv) Satellite

(v) Radios

(vi) Mobile communications, n.e.s.

(b) Mobile applications

(c) Computing platforms

(d) Multimedia over IP

(e) Trusted computing

(f) Network infrastructure

(g) Link layer encryption

(h) Smartcards or other identity management

(i) Computer or network forensics

(j) Software

(i) Operating systems

(ii) Applications

(k) Toolkits / ASICs / components

(l) Information security including secure storage

(m) Gaming

(n) Cryptanalytic tools

(o) “Open cryptographic interface” (or other support for user-supplied or non-standard cryptography)

(p) Other (identify any not listed above)

(q) Not Applicable (Not a producer of encryption or information technology items)

(4) Describe whether the products incorporate or use proprietary, unpublished or non-standard cryptographic functionality, including encryption algorithms or protocols that have not been adopted or approved by a duly recognized international standards body. (If unsure, please explain)

(5) Will your company be exporting “encryption source code”?

(6) Do the products incorporate encryption components produced or furnished by non-U.S. sources or vendors? (If unsure, please explain)

(7) With respect to your companys encryption products, are any of them manufactured outside the United States? If yes, provide manufacturing locations. (Insert “not applicable”, if you are not the principal producer of encryption products)

All you have to do is create a PDF file answering these questions for your application and upload it. I couldn’t find this information anywhere so I called them once again and that’s how I learned that all matters related to encryption were handled by the department… never mind the name, the phone number is +1-202-482-0707. Next time I’m calling them directly – there was no wait, no menu, just a person picking up the phone.

I created a document for my case saying:

Screensaver Ninja Encryption Registration Supplement No. 5 to Part 742

(1) Point of Contact Information

(a) José Pablo Fernández Silva

(b) +44XXXXXXXX

(c)

(d) pupeno@carouselapps.com

(e) 20-22 Wenlock Road, London, N1 7GU, United Kingdom

(2) Carousel Apps is a small London based company producing software apps such as Screensaver Ninja. Our main use of encryption (and so far all of it) is the standard SSL (https), OpenSSH, etc. You can learn more about us at https://CarouselApps.com

(3) We produce

(j) Software

(ii) Applications

(4) Our products use standard off the shelf encryption libraries and tools, such as https (SSL). We don’t develop or intend to develop any proprietary encryption mechanisms

(5) We don’t plan on exporting “encryption source code”.

(6) Screensaver Ninja uses Apple’s Safari component that allows https encrypted communication. This is provided by Apple. I understand that Apple uses OpenSSL which is an open source project and thus may have contributions from all around the world.

(7) We produce software, so, no manufacturing process are involved. All our software is produced outside the United States. The reason for this application is to distributed an app through Apple’s App store.

I cannot vouch for this content, I’m not sure this is the appropriate file to submit, this is only what I did. The next step is to click on “View and Manage Supporting Documents” which will take you to a page that looks like this:

BIS SNAP-R Document Management Encryption Registration Supplement No. 5 to Part 742

There, click “Upload Supporting Document” and you’ll be greeted by this form:

BIS SNAP-R Upload document for Encryption Registration Supplement No. 5 to Part 742

I just came up with a title and keywords, entered the current date and my name as author. I think the only really important field is the document type:

BIS SNAP-R Upload document for Encryption Registration Supplement No. 5 to Part 742 f

Submitting the ERN

With that document in place and attached, we seem to have passed some sort of automatic verification procedure.

BIS SNAP-R Encryption Registration All party addresses have passed verification

I clicked on “Preview Work Item to Submit” and I was given a last chance to look at the application and verify its correctness:

BIS SNAP-R ERN Application with document

The submission process, triggered by the “Submit” button of course, asks you for your name, in a special format, one more time:

BIS SNAP-R Encryption Registration Submit Work Item

And we you click “Submit Work Item” you are done:

BIS SNAP-R Encryption Registration Submitted - Thank you

Uploading Encryption Registration to Apple

I almost immediately got a message in the SNAP-R website:

Screen Shot 2015-11-19 at 10.36.00

And the message was the acceptance of the application including the ERN code (blacked out):

BIS SNAP-R Encryption Registration Accepted

That is the document you need to upload to Apple. Take a screenshot of that page and save it for your records. Back at Apple’s iTunes connect, when you answer the questions stating that you use encryption, you get an upload box for the document:

iTunes Connect Encryption upload ERN

If the upload button doesn’t appear, this is what an Apple representative suggested: “If you do not see the prompt, there could be a glitch in the website. One possible workaround is to change the answer to question 4 to “Yes”. By doing this the upload field should appear.”

Once you upload it, the “Submit” button will become enabled and you are ready to rock. Click it and your app will be on its way to fame and fortune. Well… that is… after they review your export compliance. For now, your app will be “Waiting for Export Compliance”:

iTunes Connect - Waiting for Export Compliance

From Apple’s version statuses, that means: “Your app is reviewed and ready for sale, but your CCATS file is in review with Export Compliance.” CCATS seems to be an older or bigger version of the ERN and in some places we can still find CCATS instead of ERN. Don’t worry, an ERN is all you need if your situation is similar to mine. When the status reaches to “Waiting for Review”:

mac app waiting for review

Congratulations! Your ERN was accepted.  You are done with this bit of bureaucracy.

If this blog post was useful or you find differences in the process, please, let us know in the comment section.

Picture by Yuri Samoilov

safe

Forcing SSL in a Luminus application

We tend to be very security conscious at Carousel Apps and one thing we often do is force all our applications to run over TLS (aka SSL), that is, when you go to http://example.com we redirect you to https://example.com. This little article will show you how to do it in a Luminus application.

First, add Ring SSL to your project by editing project.clj , finding the list of dependencies and adding:

[ring/ring-ssl "0.2.1"]

That library provides various Ring middleware functions to deal with SSL. The first one you care about is wrap-ssl-redirect  that will cause an HTTP request to be redirected to the equivalent HTTPS one.

In your middleware.clj  file, find the function wrap-base  which will look something like:

(defn wrap-base [handler]
  (-> handler
      wrap-dev
      wrap-auth
      (wrap-idle-session-timeout
        {:timeout          (* 60 30)
         :timeout-response (redirect "/")})
      wrap-formats
      (wrap-defaults
        (-> site-defaults
            (assoc-in [:security :anti-forgery] false)
            (assoc-in [:session :store] (memory-store session/mem))))
      wrap-servlet-context
      wrap-internal-error))

Depending on which options you added, you might have fewer or more middleware functions in your project. You can start simple by adding wrap-ssl-redirect  to it, like this:

(defn wrap-base [handler]
  (-> handler
      wrap-ssl-redirect
      wrap-dev
      ...))

Redirecting to SSL should happen as early as possible to avoid leaking any information over a non-secure channel. With that code you’ll immediately run into trouble when running your project locally, because neither your development environment nor your test one are likely to support TLS, so you’ll get redirected to HTTPS and it won’t work.

That’s easy to solve by creating a function, let’s call it enforce-ssl , that will skip the enforcement when developing or testing:

(defn enforce-ssl [handler]
  (if (or (env :dev) (env :test))
    handler
    (-> handler
        wrap-ssl-redirect)))

and then in your middleware configuration:

(defn wrap-base [handler]
  (-> handler
      enforce-ssl
      wrap-dev
      ...))

The function wrap-ssl-redirect obviously checks whether you are already accessing the site over SSL and if that’s the case, it doesn’t redirect you; otherwise you’d have a redirect loop.

If your application is sitting behind a proxy or a load balancer, like in the case of Heroku, Linode’s Load Balance, AWS Elastic Load Balancing, etc. the proxy will be terminating the HTTPS connection and then it’ll issue an HTTP (non-S) connection to your application because since now you are in an internal secure network, encryption is no longer required and HTTP is faster. Thus, your application after forwarding to HTTPS will still receive connections to HTTP and forward again and it’ll be stuck in an infinite forwarding loop.

The convention for this situation is that those proxies will add the header X-Forwarded-Proto with the original protocol, either http  or https. There’s another middleware function called wrap-forwarded-scheme  that will look at X-Forwarded-Proto (or another header entry of your choosing) and set that as the actual scheme in the request so a simple check for http  or https would suffice:

(defn enforce-ssl [handler]
  (if (or (env :dev) (env :test))
    handler
    (-> handler
        wrap-ssl-redirect
        wrap-forwarded-scheme)))

Doing the scheme forwarding should be the first thing you do, so that wrap-ssl-redirect  can use the correct scheme.

IMPORTANT: if your application is not behind a trusted proxy, or the proxy is using a different header, then blindly applying wrap-forwarded-scheme would be dangerous as your application could be easily deceived into believing a connection is secure which would enable a man‐in‐the‐middle attack.

One last thing that we do is add wrap-hsts  which makes sure the browser from now on will only use HTTPS for this domain, even if the user types http (which would result in a redirect anyway). The final code looks like this:

(defn enforce-ssl [handler]
  (if (or (env :dev) (env :test))
    handler
    (-> handler
        wrap-hsts
        wrap-ssl-redirect
        wrap-forwarded-scheme)))

And that’s it, your application now uses TLS/SSL by default, something that you should always consider and definitely do if there’s any kind of auth at all.

Redirect to SSL in Rails applications

I’ve looked at the various ssl_requirement repositories out there. I concluded the most modern and maintained version is yardstick’s which is released as a gem called sslrequirement, but I’ve failed to use it properly. So I just did it by hand.

First, we need a simple method that will let us know whether SSL is enabled or not. We don’t want to redirect to SSL in development mode because it’ll fail. In the application controller I’ve created:

  def ssl_enabled?
    !(Rails.env.development? || Rails.env.test?)
  end

Switching to SSL is not only a matter of redirecting. If you show a login or signup form in your homepage, like I do in Restraq, you want that to point to https even if the page was loaded as http. So I’ve added this helper method in the application controller:

  def https
    ssl_enabled? ? "https://" : "http://"
  end
  helper_method :https

and then for the forms I just do this:

form_for ..., :url => session_url(resource_name, :protocol => https)

and

form_for ..., :url => registration_url(resource_name, :protocol => https)

And then the redirection part, which is a before filter in the application controller because I want to redirect when hitting Devise controllers:

  def enforce_ssl_if_needed
    if request.protocol == "http://" && ssl_enabled? &&
            (controller_name == "registrations" || controller_name == "sessions")
      redirect_to :protocol => https
    end
    return true
  end

and that’s it. I’m not actually testing it yet. For a similar solution with tests you might want to check out SSLShopper’s article about this.

SSL with multiple virtual hosts and only one IP

Image taken from http://www.artlebedev.com/everything/defendius/

I was writing this long post about how to use rewrite rules to make Apache query itself and serve various sites through the same SSLed virtual host using only one IP. After about four hours of struggling with it I thought I was done but then while writing this article I found out I was wrong. Something was not working as expected. Did I face another 4 hours of Apache struggling? Continue reading