Merge pull request #52 from charlieok/prefer_ssh_forwarding

Prefer ssh-agent forwarding

README.md

@@ -82,7 +82,7 @@ https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration
 
 
 
-## Decide on an ssh keypair for gitian to use when connecting to github
+## Decide on an ssh keypair to use when uploading build signatures to github
 
 You can generate a keypair specifically for connecting to github like this:
 
@@ -128,7 +128,7 @@ Some explanation of the arguments used in the above example:
 
 [Add the new key to your github account.](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/)
 
-Add an entry to ~/.ssh/config (create this file if necessary) telling ssh to use the keypair you
+Add an entry to `~/.ssh/config` (create this file if necessary) telling ssh to use the keypair you
 generated above when connecting to github.com.
 
 For instance:
@@ -165,7 +165,7 @@ $ git clone git@github.com:zcash/zcash-gitian.git
 
 
 
-## Add git and ssh config values to gitian.yml
+## Add git config values to gitian.yml
 
 The `gitian.yml` file in the root of the project has some blank values that need to be updated or
 filled in:
@@ -173,8 +173,6 @@ filled in:
 - `zcash_version`: The git tag name of the version of zcash you want to build
 - `git_name`: You probably want the output from `git config user.name`
 - `git_email`: You probably want the output from `git config user.email`
-- `ssh_key_name`: The filename of your private key. In the steps above we used the name
-`github_id_rsa`.
 
 
 
@@ -240,14 +238,67 @@ the actual builds.
 Use `git stash` to save one's local customizations to `gitian.yml`.
 
 
+Load your ssh key into ssh-agent
+--------------------------------
+
+Load your ssh key (for pushing signatures to github) into ssh-agent. The approach here is to allow
+programs in the zcash-build VM to connect to ssh-agent to perform operations with the private key.
+This way, we don't need to copy ssh keys into the VM. You can verify that the key is loaded by
+running `ssh-add -l`.
+
+```
+$ ssh-add -l
+The agent has no identities.
+
+$ ssh-add ~/.ssh/github_id_rsa
+Identity added: /home/hpotter/.ssh/github_id_rsa (/home/hpotter/.ssh/github_id_rsa)
+
+$ ssh-add -l
+4096 SHA256:4fFdwJ71VIpF5cW0dqrsU7jxjctaFcAKmdQZPEqR0Y4 /home/hpotter/.ssh/github_id_rsa (RSA)
+```
+
+
+SSH into the VM
+---------------
+
+Vagrant should now show that the new VM is in the 'running' state:
+
+```
+$ vagrant status
+Current machine states:
+
+zcash-build               running (virtualbox)
+
+The VM is running. To stop this VM, you can run `vagrant halt` to
+shut it down forcefully, or you can run `vagrant suspend` to simply
+suspend the virtual machine. In either case, to restart it again,
+simply run `vagrant up`.
+```
+
+Use the `vagrant ssh` command to start a shell session in the VM. Once in that session, you can use
+ssh-add again to see that your forwarded key is available, and check that you can use that key to
+authenticate to github.
+
+```
+$ vagrant ssh zcash-build
+[...]
+
+# on the virtualbox vm
+$ ssh-add -l
+4096 d1:43:75:a7:95:65:9e:d4:8e:57:d8:98:58:7d:92:4c /home/hpotter/.ssh/github_id_rsa (RSA)
+
+$ ssh -T git@github.com
+Warning: Permanently added the RSA host key for IP address '192.30.253.112' to the list of known hosts.
+Hi harrypotter! You've successfully authenticated, but GitHub does not provide shell access.
+```
+
 
 Building Zcash
 --------------
 
+Once in a shell session in the VM, we're ready to run the gitian build.
+
 ```
-# on your host machine
-$ vagrant ssh zcash-build
-[...]
 # on the virtualbox vm
 $ ./gitian-build.sh
 ```
@@ -265,14 +316,12 @@ After the build successfully completes, the gitian command `gsign` will be calle
 
 Signatures can be verified by running `gitian-build.sh --verify`, but set `build=false` in the script to skip building. Run a `git pull` beforehand on `gitian.sigs` so you have the latest. The provisioning includes a task which imports Zcash developer public keys to the Vagrant user's keyring and sets them to ultimately trusted, but they can also be found at `contrib/gitian-downloader` within the Zcash source repository.
 
-Working with GPG and SSH
---------------------------
+Working with GPG
+----------------
 
-We provide two options for automatically importing keys into the VM, or you may choose to copy them manually. Keys are needed A) to sign the manifests which get pushed to [gitian.sigs](https://github.com/zcash/gitian.sigs) and B) to interact with GitHub, if you choose to use an SSH instead of HTTPS remote. The latter would entail always providing your GitHub login and [access token](https://github.com/settings/tokens) in order to push from within the VM.
+We provide two options for automatically importing keys into the VM, or you may choose to copy them manually. GPG keys are needed to sign the manifests which get pushed to [gitian.sigs](https://github.com/zcash/gitian.sigs).
 
-Your local SSH agent is automatically forwarded into the VM via a configuration option. If you run ssh-agent, your keys should already be available.
-
-GPG is trickier, especially if you use a smartcard and can't copy the secret key. We have a script intended to forward the gpg-agent socket into the VM, `forward_gpg_agent.sh`, but it is not currently working. If you want your full keyring to be available, you can use the following workaround involving `sshfs` and synced folders:
+GPG is tricky, especially if you use a smartcard and can't copy the secret key. We have a script intended to forward the gpg-agent socket into the VM, `forward_gpg_agent.sh`, but it is not currently working. If you want your full keyring to be available, you can use the following workaround involving `sshfs` and synced folders:
 
     vagrant plugin install vagrant-sshfs
 

gitian.yml

@@ -9,7 +9,6 @@
     git_name: ''
     git_email: ''
     gpg_key_id: ''
-    ssh_key_name: '' # optional
   roles:
     - role: common
       tags: common

roles/gitian/tasks/main.yml

@@ -211,11 +211,6 @@
   become: no
   when: gpg_key_id is defined and gpg_key_id != ''
 
-- include_tasks: ssh.yml
-  tags: ssh
-  become: no
-  when: ssh_key_name is defined and ssh_key_name != ''
-
 - name: Display help message.
   debug:
     msg: >-

roles/gitian/tasks/ssh.yml

@@ -1,24 +0,0 @@
----
-- name: Check that the SSH key exists locally.
-  local_action: "stat path={{ lookup('env', 'HOME') }}/.ssh/{{ ssh_key_name }}"
-  become: no
-  register: ssh_key
-
-- name: Make SSH home directory.
-  file:
-    path: "/home/{{ gitian_user }}/.ssh"
-    state: directory
-    mode: "0700"
-    owner: "{{ gitian_user }}"
-    group: "{{ gitian_user }}"
-
-- name: Copy the SSH public and private key.
-  synchronize:
-    src: "{{ lookup('env', 'HOME') }}/.ssh/{{ item }}"
-    dest: "/home/{{ gitian_user }}/.ssh/{{ item }}"
-    archive: yes
-    owner: yes
-  with_items:
-    - "{{ ssh_key_name }}"
-    - "{{ ssh_key_name }}.pub"
-  when: ssh_key.stat.exists