Tutorial: Compiling Armory and getting it onto an offline computer

[pf]

The following steps show you how to compile Armory from source code and get it onto your offline computer with Ubuntu Linux.

Why should you compile Armory from source code? Because you can't fully trust yet that the binaries Armory publishes come from the source code they're supposed to be coming from. And also, because it's dead simple to do, so why not just do it?

I have tested these steps for Ubuntu 14.04 LTS and Armory 0.93.2, but I suppose it will work with other systems and versions as well.

Here are the steps:

• On a virtual machine (or a real machine if you want) that is allowed to connect to the internet, do a clean install of the same system that is on your offline computer. In my case, that is Ubuntu 14.04 LTS.
• On this fresh online system, download this Python script by Alan Reiner (the originator of Bitcoin Armory).
• On the Terminal, run "python apt-get-offline.py" followed by a list of all of the dependency packages you see after "sudo apt-get install" on the official Armory "building from source" page. In my case, I typed in python apt-get-offline.py git-core build-essential pyqt4-dev-tools swig libqtcore4 libqt4-dev python-qt4 python-dev python-twisted python-psutil
• Use a USB key to get the resulting folder of .deb files onto your offline computer.
• On your offline computer, use sudo dpkg -i *.deb within that folder to install all these dependencies on your offline computer. (I know, I know. git-core and build-essential are probably not needed on the offline computer. But since the Armory guys haven't really made a distinction between dependencies that are needed for compilation and dependencies that are needed to run the compiled program and I'm not 100% sure which is which, I just throw them all into the offline computer. No big deal.)
• Now go back to your online Ubuntu and compile Armory according to the official instructions. In my case, I just ran these commands: gpg --recv-keys --keyserver keyserver.ubuntu.com 98832223, sudo apt-get install git-core build-essential pyqt4-dev-tools swig libqtcore4 libqt4-dev python-qt4 python-dev python-twisted python-psutil, git clone git://github.com/etotheipi/BitcoinArmory.git, cd BitcoinArmory, git checkout v0.93.2, git tag -v v0.93.2 (and check that the signature matches), make.
• Use a USB key to get the BitcoinArmory folder onto your offline computer.
• On your offline computer, run Armory through the Terminal with python ArmoryQt.py

See also my other tutorials:
Tutorial: Installing R on an offline Ubuntu computer
Tutorial: Using R to statistically test a die for bias
Tutorial: Creating a bulletproof 255-bit entropy Armory wallet

[1714839648]

1714839648

[1714839648]

1714839648

[1714839648]

1714839648

[1714839648]

1714839648

[1714839648]

1714839648

[unamis76]

How do you know the USB key is safe? I'd gladly blind-trust binaries on the Armory page than any USB key. I've had USB keys being used in a countless amount of computers and caught quite a few viruses (fortunately none contaminated any of my machines. So far). There are also keys rumored to be tampered with from their factories and hardware exploits...

I think some questions you've been making on this subforum and the fact you don't trust no one at whatever cost are a good thing, but I had to question this, since you seem to care a lot about security (I do too. But maybe not as much as you, or not as much as I should )

[knahrvorn]

How do you know the USB key is safe?

Then change "USB key" into "SD card", and make sure it's properly erased before use?

[Carlton Banks]

How do you know the USB key is safe?

Then change "USB key" into "SD card", and make sure it's properly erased before use?

CD ROM is best.

Cannot be altered once finalised, so you can use uncompromised systems to check whether the contents of the CD ROM have been burned as per your instructions (and so you can reliably detect whether your Armory dependencies packages are definitely what they purport to be).


Also, as the OP states, these instructions will work for Debian 7 "wheezy" and Debian 8 "jessie". Ubuntu is essentially a bloated fork of Debian, targetting the consumer/business market. Not really necessary for offline Armory as such, Debian will do the job just as well.

[unamis76]

How do you know the USB key is safe?

Then change "USB key" into "SD card", and make sure it's properly erased before use?

Yes, that's better, and putting the SD on read only while on the offline machine is another assurance of safety... Is an SD exploitale through hardware this way?

How do you know the USB key is safe?

Then change "USB key" into "SD card", and make sure it's properly erased before use?

CD ROM is best.

Cannot be altered once finalised, so you can use uncompromised systems to check whether the contents of the CD ROM have been burned as per your instructions (and so you can reliably detect whether your Armory dependencies packages are definitely what they purport to be).


Also, as the OP states, these instructions will work for Debian 7 "wheezy" and Debian 8 "jessie". Ubuntu is essentially a bloated fork of Debian, targetting the consumer/business market. Not really necessary for offline Armory as such, Debian will do the job just as well.

CD is indeed the best, but it will make costs higher. One will probably need an external CD drive and CD's to burn

Cheaper than losing all the coins though, that for sure...

[goatpig]

Yes, that's better, and putting the SD on read only while on the offline machine is another assurance of safety... Is an SD exploitale through hardware this way?

My understanding of SD cards is that they dont have to negotiate a utility class like USB, they are identified only as storage by the OS, and their drivers only allow for that anyways.

On the other hand, USB can negotiate several classes for the same PID&VID, mostly the infamous HID class. The grand majority of USB attacks come from that unrestricted class negotiation allowed by the standard and most of them rely on the power of the HID class.

[pf]

Yes, that's better, and putting the SD on read only while on the offline machine is another assurance of safety... Is an SD exploitale through hardware this way?

My understanding of SD cards is that they dont have to negotiate a utility class like USB, they are identified only as storage by the OS, and their drivers only allow for that anyways.

On the other hand, USB can negotiate several classes for the same PID&VID, mostly the infamous HID class. The grand majority of USB attacks come from that unrestricted class negotiation allowed by the standard and most of them rely on the power of the HID class.

Does anyone know more about this? Is Linux safe from these USB attacks? What about OS X? I assume it's Windows that's most vulnerable?

I wasn't aware of this attack vector. I thought USB sticks were just treated as storage and nothing else. Seems like I was wrong.

Thanks for starting the discussion unamis76. Looks like I may have to start all over from scratch. Sigh. Isn't life fun?

[Carlton Banks]

Yes, that's better, and putting the SD on read only while on the offline machine is another assurance of safety... Is an SD exploitale through hardware this way?

My understanding of SD cards is that they dont have to negotiate a utility class like USB, they are identified only as storage by the OS, and their drivers only allow for that anyways.

On the other hand, USB can negotiate several classes for the same PID&VID, mostly the infamous HID class. The grand majority of USB attacks come from that unrestricted class negotiation allowed by the standard and most of them rely on the power of the HID class.

Does anyone know more about this? Is Linux safe from these USB attacks? What about OS X? I assume it's Windows that's most vulnerable?

I wasn't aware of this attack vector. I thought USB sticks were just treated as storage and nothing else. Seems like I was wrong.

Thanks for starting the discussion unamis76. Looks like I may have to start all over from scratch. Sigh. Isn't life fun?

USB storage vulnerabilities can be mitigated using virtualised OS's and IOMMU. I use Qubes OS, which is a ready-made implementation of that kind of configuration.

[pf]

What bothers me most is that the Armory guys themselves mention USB sticks all the time without any mention at all of this attack vector. Have the Armory guys even thought about this risk at all? I hope so. Please comment.

https://bitcoinarmory.com/tutorials/armory-advanced-features/offline-wallets/

Page contents at the time of this writing:

Offline Wallets

Note: There is no special version of Armory needed for the offline computer, and it does not need to be the same operating system as the online computer. As long as you can install Armory and use USB drives, it will work.

Note: You must be in “Advanced” or “Expert” usermode to use offline wallets. “Advanced” is the default mode when you first install Armory, but some users change to “Standard” to simplify the interface. You can switch modes from the main window menu under “User”.

First and foremost, you will need a computer that you don’t mind keeping disconnected from the internet. Such a computer does not have any particular resource requirements: pretty much any computer that boots into Windows or Linux, can run Armory in offline-mode.

Once you have Armory installed on the offline computer, you create a new wallet. Don’t forget to print or copy by hand a paper backup! Then you “create a watching-only wallet” and load it on the online computer (this part only has to be done once). The nature of Armory wallets is that the online computer will always generate the exact same addresses as the offline computer, but the online computer cannot spend any of the funds!

Load Armory on the offline computer
Create a new wallet (with or without encryption)
Important: Make a paper backup! Connect a printer via USB or copy the paper backup information by hand. Make one or two copies, and store in a secure place. This is a permanent backup of every address your wallet will ever create!
Double click on the wallet and click on Create Watching-Only Copy on the right menu
Save the file to the USB drive, eject, insert into online computer
Load Armory on online computer, and select Import Wallet in the upper-right corner of the main window. Import the wallet file on the USB drive.
In the wallet-properties dialog, click on Belongs To, and click the checkbox that says This wallet is mine. This makes sure that any funds in this wallet are part of your global balance.
Now that the wallets are setup, you can use the watching-only wallet exactly the same way as a regular wallet, except Bitcoins cannot be sent from it. Use the Receive Bitcoins button to generate addresses for receiving payments, and incoming transactions will show up in the ledger with a slightly different color than your other wallets.

To send Bitcoins from your offline wallet, do the following:

On the online computer, click the Offline Transactions button on the right, below the logo. Select Create New Offline Transaction. Alternatively, you can just select Send Bitcoins and select the watching-only/offline wallet.
Create the transaction as you normally would but the “Send” button will be grayed out since the watching-only wallet cannot sign transactions..
Click the button Create Unsigned Transaction on the left side.
A window will open with the unsigned version of the transaction. Press the Save to file… button to save a *.unsigned.tx to the USB key
Insert USB key in offline computer, and click Offline Transactions, then select Sign or Broadcast Tranasaction.
Load the file from the USB key, then press the Sign button. A confirmation window will appear.
Verify the confirmation details before you sign it! The benefits of an offline wallet are lost if you don’t make sure the details are correct!
Click Save to file…. It will overwrite the original *.unsigned.tx file with a *.signed.tx file.
Eject the USB key and plug it into the online computer. If the original window is still open, you can click on Next Step to get to the broadcast window. If you closed Armory since then, you can use the same Offline Transactions button on the main window, and select Sign or Broadcast Transaction. Once the file is loaded, some green text should appear telling you that the signature is valid and the Ready to Broadcast! button should become available.
Press the button and you’re done!
Guidance is given at each step within the Armory software, so you may be fine without referring back to this page. And once you do this a few times, it will become a breeze!

Note: At no point in this process is any private data exposed through the transaction data. It is perfectly safe to transfer the signed or unsigned transaction via email. The biggest threat to an offline wallet is a USB-key virus that executes when plugged in. However, such viruses would have to be highly targeted, and can be mostly mitigated by disabling USB-auto-run on the offline computer.

I'm Scared! Help!

It’s natural to be uncomfortable using new software to store your precious savings, especially with such advanced features. But you know that if you could trust it, it’s a feature you would love! So, how do you calm your nerves about using such advanced features?

Try it out with small amounts of Bitcoins. Any time you think to yourself, “Do I really trust this program?” just pull out your USB key and execute a small offline transaction to yourself (or to make a donation to Armory developers!). Whether it takes you a day or a year, you will eventually come to realize that offline transactions really do work. Every time!

Make a new wallet as described above, but you must make a backup. A paper backup is preferred, because you can visually verify that it is intact, and it’s easier to store (but it will require plugging your computer into your printer via USB cable). A digital backup is fine if you make a couple copies, just in case one becomes corrupted. Generate some addresses by clicking on Receive Bitcoins a few times. Write down the first few letters of each address generated.
DELETE YOUR WALLET. Why did we just delete it? Because you’re about to prove to yourself that your backup works! If you can restore the backup once, you can always restore the backup at any time in future. Just don’t lose it! On the main Armory window, click on Import Wallet in the upper-right corner, and select the type of backup you are restoring. If it’s a paper backup, you’ll have to type it in manually — the time it takes to enter the wallet information is completely worth the peace of mind you get out of it. Generate some addresses with the new wallet. Check that they are the same as the addresses you wrote down earlier.
Using the wallet properties menu, click on Create Watching-Only Copy and save the file to a USB key. Import the watching-only wallet on your online computer. Generate a few addresses and compare to the ones you wrote down earlier. I bet you are starting to feel better… Transfer 0.5 BTC to one of these addresses. Wait for a few confirmations.
Whenever you are near your computer, you may ask yourself “Am I ready to trust this thing?” If the answer is “No,” then get out your USB key and execute an offline transaction. Follow the directions above to create an unsigned transaction for 0.01 BTC to one of your online wallets, transfer it to the offline computer, sign it, then bring it back and broadcast it. You are now one step closer to realizing, it really does work! If the answer is “Yes, I do trust the offline wallets,” well then you’re done! Congratulations on having mastered the most secure Bitcoin wallet functionality in existence!
You'll not only calm your nerves, but you’ll learn how to use the feature efficiently. Once you get the hang of moving transactions around via USB drive, you should be able to execute an offline transaction in less than one minute!

If you do get this far, please consider sending a donation to the Armory developers (the donate button works for offline transactions, too!). This feature was the prime motivation for creating Armory, and took many months of hard work to make it available to you, for free. There are lots of new, innovative features planned, but it won’t be possible without you!

Intro to Offline Wallets
Watching Only Wallet
Send from Online to Offline Wallet

[Carlton Banks]

Have the Armory guys even thought about this risk at all?

They have. In the top right corner of all bitcointalk.org pages, there is a textbox with magnifying glass symbol next to it and a button with the word "Search" to label it. When you type text into this box and click the button, a database query is launched that searches the sub forum for posts that contain the text you entered. Need I continue?


There's a point where Armory's responsibilities to their users end, and where your own responsibilities begin. Secure use of USB hardware is your responsibility, not theirs. They're developing software that can neither improve or deteriorate the security of USB devices, the reason being that none of the current code does anything that involves USB directly.

This is open source culture, not corporation/consumer culture. "Scratch your own itch" is the guiding principle. If you believe you could contribute a better quality of documentation to the project in respect of this issue, you are encouraged to rewrite it yourself and submit it for approval. It would benefit all if you were to do so, providing you do it well, of course.

[goatpig]

We have a lot of internal talks about this, and have even started a best practices security group with other members of the industry, on which the first topic was SD vs USB. That security group didn't go much further but at least we tried.

The issue with presenting SD to our users as a better alternative to USB is how the SD card itself is plugged into your PC. Most SD readers for PC are SD to USB adapters, and even some laptop built-in SD readers are hardware USB wrappers. In this situation, you are not getting extra security, rather you are getting the illusion of better security, which is much worse. Our expert users are aware of the intricacies of their hardware stack and what to expect from them.

Are you? Have you done the research? If you were to read our FAQ which would say something like "SD cards are more secure than USB", would you think twice about using SD cards? Would you research the topic before taking this sentence as truth? Frankly, I expect you in particular would at least poke some questions about it. However, that won't be true for others.

At the protocol layer, SD certainly has a lot less vulnerabilities than USB, but do you have enough hardware and software expertize to benefit from that? Would you not be more exposed to malpractice if you were under the impression of higher security while in reality you are not?

Our website covers how to create and maintain your wallets securely. We believe USB is sufficient for that purpose. Think of the effort needed for an attacker to build a USB root kit that targets Armory cold storage and execute this attack on you. I'm not saying it can't be done, but compare that to the low hanging fruit that are web wallets.

If you do not want to trust the USB protocol, I would suggest you look at smart cards or analog channels rather than SD cards. They are a lot more complicated to setup and will require code on your behalf but that security model is clearly above that of USB or SD. However I can only point you in that directions. After all, Armory is an expert wallet, we expect our users to know their way around the security of their hardware stack.

Before you ask why we don't just integrate with smart cards, let me answer: we are in that kind of business, but that is outside the scope of our free product.

[Carlton Banks]

Before you ask why we don't just integrate with smart cards, let me answer: we are in that kind of business, but that is outside the scope of our free product.

How do you intend to distribute a commercialised product with smart card support, and remain open source? Your own smartcards? Some kind of cryptographic token that's linked to an off-the-shelf smart card?

[pf]

We have a lot of internal talks about this, and have even started a best practices security group with other members of the industry, on which the first topic was SD vs USB. That security group didn't go much further but at least we tried.

The issue with presenting SD to our users as a better alternative to USB is how the SD card itself is plugged into your PC. Most SD readers for PC are SD to USB adapters, and even some laptop built-in SD readers are hardware USB wrappers. In this situation, you are not getting extra security, rather you are getting the illusion of better security, which is much worse. Our expert users are aware of the intricacies of their hardware stack and what to expect from them.

Are you? Have you done the research? If you were to read our FAQ which would say something like "SD cards are more secure than USB", would you think twice about using SD cards? Would you research the topic before taking this sentence as truth? Frankly, I expect you in particular would at least poke some questions about it. However, that won't be true for others.

At the protocol layer, SD certainly has a lot less vulnerabilities than USB, but do you have enough hardware and software expertize to benefit from that? Would you not be more exposed to malpractice if you were under the impression of higher security while in reality you are not?

Our website covers how to create and maintain your wallets securely. We believe USB is sufficient for that purpose. Think of the effort needed for an attacker to build a USB root kit that targets Armory cold storage and execute this attack on you. I'm not saying it can't be done, but compare that to the low hanging fruit that are web wallets.

If you do not want to trust the USB protocol, I would suggest you look at smart cards or analog channels rather than SD cards. They are a lot more complicated to setup and will require code on your behalf but that security model is clearly above that of USB or SD. However I can only point you in that directions. After all, Armory is an expert wallet, we expect our users to know their way around the security of their hardware stack.

Before you ask why we don't just integrate with smart cards, let me answer: we are in that kind of business, but that is outside the scope of our free product.

Thanks for this. I'll probably have to just trust my USB sticks. Here is the thing: I created the Ubuntu bootable USB key from Ubuntu's disk image on a brand new USB stick. The other USB stick that I use to store unsigned/signed/sent transaction files is pretty old - from mid-2009 or so. That's well before Bitcoin was known at all to most. So for someone to attack this setup of mine, there has to be some malware on one of these USB sticks (the new one or the mid-2009 one) that captures my keystrokes to get my wallet password or reads the memory for private keys on my offline computer, stores it on the USB key, and emits it from the network when connected to my online computer. I wonder how much I should really be worrying about this attack vector. I'm also wondering, is Linux (on my offline computer) really vulnerable to these kinds of USB attacks in the first place? I don't know. Do you have thoughts on this?

[goatpig]

Before you ask why we don't just integrate with smart cards, let me answer: we are in that kind of business, but that is outside the scope of our free product.

How do you intend to distribute a commercialised product with smart card support, and remain open source? Your own smartcards? Some kind of cryptographic token that's linked to an off-the-shelf smart card?

That's a business offering, we don't really expect to market this to individual users. Businesses expect a full hardware stack specification, and would rather follow clear instructions than setup Armory on their own and deal with the unknown that is our free support channel.

In this case, we specify what hardware to buy, how to set it up, provide them with the source and generate revenue through licensing and/or support contracts.

[Carlton Banks]

I'm also wondering, is Linux (on my offline computer) really vulnerable to these kinds of USB attacks in the first place? I don't know. Do you have thoughts on this?

There's an entire thread in this sub on that specific subject, and little has changed since then.

[goatpig]

I'm also wondering, is Linux really vulnerable to these kind of stuff in the first place? I don't know. Do you have thoughts on this?

You can negotiate a HID class with any piece of USB hardware. I know that for a fact because I used it to cut corners when I was integrating USB in a piece of hardware at a previous job. HID covers a lot of different utility, among which are mice, keyboards, webcams. This is not an OS specific thing, that's just the USB spec. It's not particularly hard to register a USB device as a keyboard and start running commands in the terminal in Linux.

Obviously Windows is easier to exploit. If I was to do it, I would negotiate both mass storage and keyboard, spawn the "give me admin rights" dialog for something trivial reason, but sounding serious enough that the user would ok it, then spawn a command line prompt in desktop session 0, and you sir are kebab. If I don't get admin rights, I'd register a local user service, use it to register a keyboard hook and go on from there.

It is a lot harder to get admin rights on Linux, but there are quite a few commands you can run without sudoing. After all, Armory is setup by default in a user folder, so you don't need sudo to read/write anything in there. You could very well spawn a terminal in another desktop, start a binary from there and get a bit creative.

I believe SE Linux would be a lot more resilient to this kind of attacks. We use that with our offline signing live CD. But that's really out of the scope of my expertize. I have never worked with SE Linux and I'm not a Linux guru either.

The difficulty in that attack is not to negotiate a HID class on Linux, it's to come up with a root kit that can infect the specific hardware on your USB key. If you were a DIY enthusiast, I'd suggest you buy a hobbyist MCU board like an arduino, flash their software USB stack in there, set it as a storage class, add in a random PID & VID, and physically remove the flash pins, or the commute to write pin, depending on the board's upload port (JTAG, ICSP, sometimes proprietary protocol through an auxiliary UART). That would be really resilient to remote root kit attempts. Attackers need to know the specifics of the firmware to attack it. And without the flashing pins the attacker would have to resort to memory overflows to try to execute arbitrary code.

Or you could try Carlton's crazy Inception style VMs inside VMs. Go deeper, friend.

[Carlton Banks]

Or you could try Carlton's crazy Inception style VMs inside VMs. Go deeper, friend.

No admin rights exist on the OS I use (root account does not prompt for a password, it's considered vestigial). SE Linux is set to "disabled". I am confident.

[pf]

Ok, so it turns out my low-end offline laptop (Linux) has an SD card slot. My online computer (Mac) has an SDXC card slot. This means I have to buy an ordinary SD flash card (max 2GB) don't I? That would work since the Ubuntu disk image only requires 2GB.

Now the question is, if I do everything over again: format hard drive & install Ubuntu on the offline machine from the SD card, and create a new armory wallet from scratch using a new password, does this mean that my offline computer should now be safe? Or is it possible that some USB malware infected my hardware beyond recovery and I have to buy a new laptop?

[pf]

The issue with presenting SD to our users as a better alternative to USB is how the SD card itself is plugged into your PC. Most SD readers for PC are SD to USB adapters, and even some laptop built-in SD readers are hardware USB wrappers. In this situation, you are not getting extra security, rather you are getting the illusion of better security, which is much worse. Our expert users are aware of the intricacies of their hardware stack and what to expect from them.

I have another question about this actually. The malware has to be installed on the device in first place. So the question is, do SD cards themselves actually have the same capability as USB devices for malware installations in the first place? (If not, even if on the computer the SD card connects through the USB interface, wouldn't I still be safer with an SD card?)

[unamis76]

Well, I guess we've got a pretty interesting topic going on here. To start off my post I'd like to say I don't consider myself an expert user. I'd also like to say that I'm using Armory as my offline/cold storage, after a period of testing with very small quantities of Bitcoin and getting used to different wallets in offline mode, I found Armory very useful and it's the one I feel better with.

That being said, back on topic. This has actually made me see the USB issue in a different way. For example, I wasn't aware of the illusion created by USB SD card readers As I wasn't aware of the fact that some laptop readers are connected via USB too.

I know there is a high improbability of me or anyone else (especially people with low amounts of Bitcoin) to be targeted by such hardware attacks. But I do not use USB in my offline machine (Raspberry Pi) just in case. I now also realize my system may be compromised, as I flashed Raspbian on my SD using my laptop's SD reader.

Here's a suggestion to the OP: drop the SD's and the USB's on your offline system and use a webcam (easy way) or the audio interface (hard way). I use a webcam in my Raspberry setup to send transactions to the online computer. For your offline linux machine, I'd recommend qtQR, easy to use and powerful. I've tried the audio interface previously with another Bitcoin client, but I failed to set it up and eventually gave up on the idea.

My system may have flaws, but I think the ease of use of what I have is pretty well balanced with the security of the system (which I think it is secure enough)

The issue with presenting SD to our users as a better alternative to USB is how the SD card itself is plugged into your PC. Most SD readers for PC are SD to USB adapters, and even some laptop built-in SD readers are hardware USB wrappers. In this situation, you are not getting extra security, rather you are getting the illusion of better security, which is much worse. Our expert users are aware of the intricacies of their hardware stack and what to expect from them.

I have another question about this actually. The malware has to be installed on the device in first place. So the question is, do SD cards themselves actually have the same capability as USB devices for malware installations in the first place? (If not, even if on the computer the SD card connects through the USB interface, wouldn't I still be safer with an SD card?)

As far as I understood SD's are more secure, as they do not rely on the HID class (correct me if I'm wrong), which is a vector used for attacks. And no, SD connecting through the USB only gives and illusion of safety.