client-guide

   1 Prerequisites for installation:
   2 ===============================
   3
   4 GPG, and if you compile yourself, compiler.
   5
   6 Generating keypair:
   7 ===================
   8
   9 To use keypair authentication, you need to first generate a keypair. The
  10 generated keypair can be shared between many servers, but each client
  11 you access repositories from should have its own.
  12
  13 To generate keypair, do:
  14
  15 'gits-generate-keypair'
  16
  17 The program is interactive. Answer the prompts it gives.
  18
  19 One special feature is sealing keys. Currently supported sealing methods
  20 are unsealed, password (gpg) and keypair (gpg):
  21
  22 Unsealed:
  23 ---------
  24 Nothing protects keypair file except host file permissions. This can be
  25 convinient, but its also insecure, as if somebody gains access to your
  26 account or to admin account, they can freely misuse or steal your key.
  27
  28 Password (gpg):
  29 ---------------
  30 This is pretty much equivalent to password-protecting the key. The
  31 password protecting stolen key must be cracked before key can be misused.
  32 Note however that the password needs to be typed every time you push,
  33 which can become cumbersome.
  34
  35 Keypair (gpg):
  36 --------------
  37 You can use your main gpg key to protect the keypair. When it
  38 asks for key to use, enter the name you have on key, email address or
  39 key ID (anything that gpg can uniquely identify your key with).
  40
  41 If you don't have gpg-agent set up, you still need to type the pass-
  42 phrase for key every time you push (so you should have that set up).
  43
  44
  45 Note that the program asks name of key and not filename to save it as.
  46 Keep the generated keys well-protected, and most importantly do
  47 not send them anywhere or allow them to be modified (modified keypairs
  48 can run who knows what if used).
  49
  50 After keypair has been generated, use 'gits-get-key-id' to get ID of
  51 the key. If key is sealed, you need to unseal it (using password or key
  52 passphrase). Write down what it gives, you are going to need it later (it
  53 isn't secret information anyway, and its handier to be able to look it up
  54 as opposed to asking the program to give you the name again).
  55
  56 The key ID is then to be given to repo hosting admins in order to give
  57 you access.
  58
  59 Generating SRP verifier:
  60 ========================
  61
  62 To authenticate using password authentication, you need to genrate
  63 SRP verifier. This can be done with
  64
  65 'gits-generate-srp-verifier'
  66
  67 The program prompts you for username (this can be gotten from
  68 repo host admin).
  69
  70 Then it may or may not prompt for some junk/garbage. Just hit
  71 keys quickly to give some gibberish to computer. This way the
  72 needed 32 characters fills up very quickly. You don't need to
  73 ever rember what you entered as junk. Note that at least on
  74 Linux, this prompt probably does not appear (since computer
  75 generated some garbage data for itself). Terminal echo is off
  76 in this prompt.
  77
  78 Then it prompts for password twice (terminal echo is off),
  79 so nothing shows up. The entered passwords must match or it
  80 will complain.
  81
  82 It finally asks filename to save the verifier to. If you want
  83 to save it to file, enter name. If you want it to be shown on
  84 screen, just hit enter.
  85
  86 The verifier is quite long so it has been split to multiple
  87 lines. Last character of each line except last is '\' (that
  88 has special signaficance of telling that next line contionues
  89 this line).
  90
  91 The generated verifier is then to be given to repo host admins
  92 in order to allow repo system to authenticate you. If you change
  93 your password, you need to have the verifier in repo system
  94 updated. Note that verifiers are somewhat sensitive. Although
  95 it isn't trivial to recover password from one, trying to brute
  96 force one is possible.
  97
  98 Using ssh keys:
  99 ===============
 100 For now, using encrypted SSH keypairs for client authentication
 101 requires ssh-agent or something comparable (unencrypted keys
 102 are supported without)
 103
 104 The ID of SSH key can be gotten using:
 105
 106 'gits-get-key-id --ssh <keyname>'. The <keyname> is e.g. 'id_dsa'
 107 (the key is '~/.ssh/<keyname>' and '~/.ssh/<keyname>.pub').
 108
 109 These IDs work server-side just like IDs of OpenPGP keys.
 110
 111 hostkeys:
 112 =========
 113 Optionally, you can verify fingerprint for connected host (e.g.
 114 to ensure confidentiality of what is pushed). This can be
 115 done using unique server ID field in URL. Specify the hostkey
 116 ID as value, connect will fail if the value does not match
 117 what server shows.
 118
 119 This can't be used on git:// (unencrypted) connections.
 120
 121 The <keyID> value can be gotten from repo host admin, often
 122 when you send your key name in (they look just like your
 123 keynames: type followed by dash followed by long string of
 124 hexadecimal numbers).
 125
 126 If the hostkey entry for given host doesn't exist or is
 127 incorrect, trying to connect to that host fails.
 128
 129
 130 git / gits:// URL syntax:
 131 =========================
 132
 133 Full syntax:
 134
 135 Host specification <host>:
 136 --------------------------
 137 <host> can be symbolic address or numeric address. It can
 138 be prefixed with '<protocol>/<addresspace>~' to override
 139 default protocol of 'tcp' and address space autoselect.
 140
 141 Valid address spaces are:
 142 'unspecified': Autoselect.
 143 'ipv6': IPv6 (if supported).
 144 'ipv4': IPv4.
 145 'unix': Unix domain sockets.
 146
 147 Alternatively, prefix can be '<protocol>[<afletter>]~',
 148 where <afletter> can be:
 149 '4': IPv4
 150 '6': IPv6
 151 '_': Autoselect
 152
 153 If protocol name does end in '4', '6' or '_', the
 154 address family postfix needs to be present.
 155
 156 Part before '~' can also be special string 'unix'. This means
 157 unix domain sockets (address space 'unix').
 158
 159 Unix domain sockets are specified by absolute path. Abstract
 160 namespace sockets are prefixed with '@/' (the '/' goes into
 161 socket name).
 162
 163 If address space is forced to be 'unix', the socket path
 164 can be relative and abstract namespace names can start with
 165 characters other than '/' (the '@' prefix is mandatory for
 166 abstract namespace sockets).
 167
 168 If unique server ID is specified, it comes before protocol/
 169 address space override and is separated by '@'. E.g.
 170
 171 [12345@tcp4~gits.example.com]
 172
 173 To use unique server ID 12345 (the escape is required as
 174 name contains '@').
 175
 176 gits::git://<host>[:<port>]/path
 177 --------------------------------
 178
 179 Unencrypted and completely unauthenticated connection to
 180 port <port> (if not specified, defaults to 9418) of <host>,
 181 requesting repository <path>.
 182
 183 This protocol can connect to git:// and non-immediate-TLS
 184 gits:// ports.
 185
 186 gits://[<username>@]<host>[:<port>]/path
 187 ----------------------------------------
 188
 189 Encrypted connection. Server is always authenticated using
 190 hostkey entry in hostkey database. Connection starts clear
 191 but is immediately upgraded to encrpypted connection.
 192
 193 If <username> is absent, client does not authenticate. Otherwise
 194 it uses key or username given to authenticate.
 195
 196 If the username doesn't start with 'srp-' or 'key-' client
 197 first looks for key with name of key matching username, and
 198 if not found, prompts for password.
 199
 200 If you for some reason want to use password authentication
 201 with name that's name of some key, prefix the username
 202 with 'srp-' (e.g. 'foo' -> 'srp-foo'). This forces password
 203 authentication.
 204
 205 To use SSH keypair authentication (ssh-agent is needed for
 206 encrypted keys), prefix name of key in '~/.ssh/' with 'ssh-',
 207 e.g 'ssh-id_rsa' to use '~/.ssh/id_rsa' (and '~/.ssh/id_rsa.pub').
 208
 209 If name of key for some reason starts with 'key-', 'srp-' or
 210 'ssh-', prefix 'key-' to username (e.g. 'key-foo' -> 'key-key-foo')
 211 to prevent it from interpretting the username wrong.
 212
 213 This protocol can connect to non-immediate-TLS gits:// ports.
 214
 215 Default port is 'git' (9418).
 216
 217 gits::tls://[<username>@]<host>[:<port>]/path
 218 ---------------------------------------------
 219
 220 Same as gits://, but connection starts encrypted, as opposed
 221 to being upgraded. Default port is 'gits' (usually not assigned,
 222 so port number has to be specified).
 223
 224 This protocol can connect to immediate-TLS gits::tls:// ports.
 225
 226
 227 Environment variable GITS_VERBOSE:
 228 ----------------------------------
 229 Setting environment variable GITS_VERBOSE activates verbose
 230 mode where steps of initiating connection are printed for
 231 debugging problems related to starting connection.
 232
 233
 234 Transport debugging output:
 235 ---------------------------
 236 Sending SIGUSR1 to git-remote-gits causes debugging output
 237 of transport code status to be printed. This is useful for
 238 debugging problems manifesting during transfer.