Debian Codegraph @

mercurial_keyring.egg-info/PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: mercurial-keyring
3 Version: 1.4.4
4 Summary: Mercurial Keyring Extension
5 Home-page: https://foss.heptapod.net/mercurial/mercurial_keyring
6 Author: Marcin Kasperski
7 Author-email: [email protected]
8 License: BSD
9 Keywords: mercurial hg keyring password
10 Platform: UNKNOWN
11 Classifier: Development Status :: 4 - Beta
12 Classifier: Environment :: Console
13 Classifier: Intended Audience :: Developers
14 Classifier: License :: DFSG approved
15 Classifier: License :: OSI Approved :: BSD License
16 Classifier: Programming Language :: Python :: 2
17 Classifier: Programming Language :: Python :: 3
18 Classifier: Operating System :: OS Independent
19 Classifier: Topic :: Software Development :: Libraries
20 Classifier: Topic :: Software Development :: Libraries :: Python Modules
21 Classifier: Topic :: Software Development :: Version Control
22 License-File: LICENSE.txt
23
24 .. -*- mode: rst; compile-command: "rst2html README.rst README.html" -*-
25
26 =======================================================
27 Mercurial Keyring
28 =======================================================
29
30 Mercurial Keyring is a Mercurial_ extension used to securely save HTTP
31 and SMTP authentication passwords in password databases (Gnome
32 Keyring, KDE KWallet, OSXKeyChain, Windows Vault etc).
33
34 With ``mercurial_keyring`` active, Mercurial remembers your passwords
35 and reuses them without prompting (as if you stored them in ``.hgrc``),
36 but password storage is reasonably secure.
37
38 Actual password storage is implemented by the keyring_ library, this
39 extension glues it to Mercurial.
40
41 .. contents::
42 :local:
43 :depth: 2
44
45 .. sectnum::
46
47 .. _keyring: http://pypi.python.org/pypi/keyring
48
49 How does it work
50 =======================================================
51
52 On your first pull or push to HTTP url (or first email sent via given
53 SMTP server), you are prompted for the password, just like bare
54 Mercurial does. But the password you entered is saved to appropriate
55 password database. On successive runs, whenever the password is
56 needed, ``mercurial_keyring`` checks for password in password
57 database, and uses it without troubling you.
58
59 In case password turns out to be incorrect (for example, because you
60 changed it, or entered it incorrectly), ``mercurial_keyring`` prompts
61 you again, and overwrites the password.
62
63 You can use many passwords (for various remote urls). Saved passwords
64 are identified by pair of username and url prefix. See below for
65 information how to configure those properly.
66
67 Installation
68 =======================================================
69
70 Prerequisites
71 -------------
72
73 This extension requires keyring_ and `mercurial_extension_utils`_ to
74 work. In many cases both will be installed automatically while you
75 install ``mercurial_keyring``, but you may need to control the process.
76
77 The keyring_ library can usually be installed by::
78
79 pip install --user keyring
80
81 (or ``easy_install keyring``), but on some systems it is preferable to
82 use official distribution archive. For example, on Debian and Ubuntu,
83 you may install ``python-keyring`` and either ``python-keyring-gnome``
84 or ``python-keyring-kwallet`` packages::
85
86 sudo apt-get install python-keyring python-keyring-gnome
87
88 (this will save you the need to provide working compiler and various
89 development libraries).
90
91 The `mercurial_extension_utils`_ module is tiny Python-only module,
92 which can be installed by::
93
94 pip install --user mercurial_extension_utils
95
96 but in some cases (Windows…) requires more care. See
97 `mercurial_extension_utils`_ documentation.
98
99
100 Extension installation
101 ----------------------
102
103 There are two possible ways of installing the extension: using PyPi package,
104 or using source clone.
105
106 To install as a package::
107
108 pip install --user mercurial_keyring
109
110 (or ``sudo pip install mercurial_keyring`` for system-wide
111 installation) and then enable it in ``~/.hgrc`` (or
112 ``/etc/mercurial/hgrc`` or ``Mercurial.ini``) using::
113
114 [extensions]
115 mercurial_keyring =
116
117 To install using source clone, install keyring_ according to the
118 instructions above, then clone::
119
120 hg clone https://foss.heptapod.net/mercurial/mercurial_keyring/
121 hg clone https://foss.heptapod.net/mercurial/mercurial-extension_utils/
122
123 and configure Mercurial using full path to the extension module::
124
125 [extensions]
126 mercurial_keyring = /path/to/mercurial_keyring/mercurial_keyring.py
127
128 .. _the code:
129 .. _mercurial_keyring.py: https://foss.heptapod.net/mercurial/mercurial_keyring/src/tip/mercurial_keyring.py
130
131 Password backend configuration
132 =======================================================
133
134 The most appropriate password backend should usually be picked without
135 configuration (considering installed libraries, operating system,
136 active desktop session). Still, if necessary, it can be configured
137 using ``keyringrc.cfg`` file. Refer to keyring_ docs for more
138 details.
139
140 .. note::
141
142 With current (as I write) keyring (5.6), this file is (on Linux)
143 located at ``~/.local/share/python_keyring/keyringrc.cfg`` and
144 it's example content looks like::
145
146 [backend]
147 default-keyring=keyring.backends.Gnome.Keyring
148 # default-keyring=keyring.backends.kwallet.Keyring
149
150 For list of known backends run ``pydoc keyring.backends`` or
151 ``keyring --list-backends`` (which of those commands work,
152 depends on the keyring_ version).
153
154
155 ``hgrc`` configuration (HTTP)
156 =======================================================
157
158 Mercurial Keyring uses standard Mercurial ``[auth]`` configuration to
159 detect your username (on given remote) and url prefix. You are
160 strongly advised to configure both.
161
162 Without the username ``mercurial_keyring`` can't save or restore
163 passwords, so it disables itself.
164
165 Without url prefix ``mercurial_keyring`` works, but binds passwords to
166 repository urls. That means you will have to (re)enter password for
167 every repository cloned from given remote (and that there will be many
168 copies of this password in secure storage).
169
170 Repository level configuration
171 ------------------------------------
172
173 Edit repository-local ``.hg/hgrc`` and save there the remote
174 repository path and the username, but do not save the password. For
175 example:
176
177 ::
178
179 [paths]
180 myremote = https://my.server.com/hgrepo/someproject
181
182 [auth]
183 myremote.prefix = https://my.server.com/hgrepo
184 myremote.username = John
185
186 Simpler form with url-embedded name can also be used:
187
188 ::
189
190 [paths]
191 bitbucket = https://[email protected]/hgrepo/someproject/
192
193 but is not recommended.
194
195 Note that all repositories sharing the same ``prefix`` share the same
196 password.
197
198 Mercurial allows also for password in ``.hg/hgrc`` (either given by
199 ``«prefix».password``, or embedded in url). If such password is found,
200 Mercurial Keyring disables itself.
201
202
203 Account-level configuration
204 ---------------------------
205
206 If you are consistent about remote repository nicknames, you can
207 configure the username in your `~/.hgrc` (`.hgrc` in your home
208 directory). For example, write there::
209
210 [auth]
211 acme.prefix = hg.acme.com/repositories
212 acme.username = johnny
213 acme.schemes = http https
214 heptapod.prefix = https://foss.heptapod.net
215 heptapod.username = Mekk
216 mydep.prefix = https://dev.acmeorg.com
217 mydep.username = drmartin
218
219 and as long as you use ``acme`` alias for repositories like
220 ``https://hg.acme.com/repositories/my_beautiful_app``, username
221 ``johnny`` will be used, and the same password reused. Similarly
222 any ``hg push heptapod`` will assume username ``Mekk`` and share
223 the same password.
224
225 With such config repository-level ``.hg/hgrc`` need only contain
226 ``[paths]``.
227
228 Additional advantage of this method is that it works also during
229 `clone`.
230
231
232 .. note::
233
234 Mercurial Keyring works well with `Path Pattern`_. On my setup I use
235 prefix as above, and::
236
237 [path_pattern]
238 heptapod.local = ~/devel/mercurial/{below}
239 heptapod.remote = https://foss.heptapod.net/mercurial/{below:/=-}
240
241 so all my repositories understand ``hg push bitbucket`` without
242 any repository-level configuration.
243
244
245 ``hgrc`` configuration (SMTP)
246 =======================================================
247
248 Edit either repository-local ``.hg/hgrc``, or ``~/.hgrc`` and set
249 there all standard email and smtp properties, including SMTP
250 username, but without SMTP password. For example:
251
252 ::
253
254 [email]
255 method = smtp
256 from = Joe Doe <[email protected]>
257
258 [smtp]
259 host = smtp.gmail.com
260 port = 587
261 username = [email protected]
262 tls = true
263
264 Just as in case of HTTP, you *must* set username, but *must not* set
265 password here to use the extension, in other cases it will revert to
266 the default behavior.
267
268 Usage
269 ======================================================
270
271 Saving and restoring passwords
272 -------------------------------------------------------
273
274 Configure the repository as above, then just ``hg pull``, ``hg push``,
275 etc. You should be asked for the password only once (per every
276 username and remote repository prefix or url combination).
277
278 Similarly, for email, configure as above and just ``hg email``.
279 Again, you will be asked for the password once (per every username and
280 email server address combination).
281
282 Checking password status (``hg keyring_check``)
283 -------------------------------------------------------
284
285 The ``keyring_check`` command can be used to check whether/which
286 password(s) are saved. It can be used in three ways:
287
288 - without parameters, it prints info related to all HTTP paths
289 defined for current repository (everything from ``hg paths``
290 that resolves to HTTP url)::
291
292 hg keyring_check
293
294 - given alias as param, it prints info about this alias::
295
296 hg keyring_check work
297
298 - finally, any path can be checked::
299
300 hg keyring_check https://foss.heptapod.net/mercurial/mercurial_keyring
301
302 Deleting saved password (``hg keyring_clear``)
303 -------------------------------------------------------
304
305 The ``keyring_clear`` command removes saved password related to given
306 path. It can be used in two ways:
307
308 - given alias as param, it drops password used by this alias::
309
310 hg keyring_clear work
311
312 - given full path, it drops password related to this path::
313
314 hg keyring_clear https://foss.heptapod.net/mercurial/mercurial_keyring
315
316 Managing passwords using GUI tools
317 ------------------------------------------------------
318
319 Many password backends provide GUI tools for password management,
320 for example Gnome Keyring passwords can be managed using ``seahorse``,
321 and KDE Wallet using ``kwalletmanager``. Those GUI tools can be used
322 to review, edit, or delete saved passwords.
323
324 Unfortunately, as I write, keyring_ library does not allow one to
325 configure how/where exactly saved passwords are put in the hierarchy,
326 and the place is not always intuitive. For example, in KDE Wallet, all
327 passwords saved using ``mercurial_keyring`` show up in the folder
328 named ``Python``.
329
330 .. note::
331
332 This is slightly problematic in case ``mercurial_keyring`` is not
333 the only program using keyring_ library. Passwords saved by another
334 Python application or script (which also uses keyring_) will be put
335 into the same place, and it may be unclear which password belongs
336 to which program. To remedy this, ``mercurial_keyring`` applies
337 slightly unusual labels of the form
338 ``«username»@@«urlprefix»@Mercurial`` - for example my bitbucket
339 password is labelled ``Mekk@@https://bitbucket.org@Mercurial``.
340
341 Implementation details
342 =======================================================
343
344 The extension is monkey-patching the mercurial ``passwordmgr`` class
345 to replace the ``find_user_password`` method. Detailed order of operations
346 is described in the comments inside `the code`_.
347
348 Frequent problems
349 =======================================================
350
351 Most problems people face while using ``mercurial_keyring`` are in
352 fact problems with ``keyring`` library and it's backends. In
353 particular, those can manifest by:
354
355 - technical errors mentioning sentences like ``No recommended backend
356 was available. Install the keyrings.alt package…`` (or similar),
357
358 - warnings like ``keyring: keyring backend doesn't seem to work…``
359
360 - password prompts on every action (= passwords not being saved).
361
362 Those almost always mean that *natural* keyring backend for given
363 desktop type doesn't work, or is not present at all. For example,
364 some necessary runtime component can be down (say, you use Linux, but
365 neither Gnome Keyring, nor KDE Wallet, is running). Or appropriate
366 backend is not installed because it could not be build during keyring_
367 library installation (maybe because some required library was not
368 present at the moment of keyring installation, or maybe because
369 compiler as such is not present on the system).
370
371 To diagnose such problems, try using ``keyring`` utility, as described
372 on keyring_ documentation page, for example by::
373
374 keyring --list-backends
375 keyring -b keyrings.alt.Gnome.Keyring set testsvc testuser
376 keyring -b keyrings.alt.Gnome.Keyring get testsvc testuser
377
378 (of course using appropriate backend). If you miss the ``keyring`` command
379 as such, try ``python -m keyring`` instead::
380
381 python -m keyring --list-backends
382 python -m keyring -b keyrings.alt.Gnome.Keyring set testsvc testuser
383 python -m keyring -b keyrings.alt.Gnome.Keyring get testsvc testuser
384
385 If appropriate backend is missing (not listed), or doesn't work
386 (second or third command fails), your keyring is broken. Try looking
387 for further pointers in keyring_ documentation, that project mailing
388 list, or issue tracker. Typically it will turn out, that you need to
389 install some missing tool, or library, and reinstall keyring.
390
391 .. note::
392
393 Depending on keyring_ version, installation of some dependency may
394 resolve problem. For example (as of late 2018), I got KDE Wallet
395 backend working with pip-installed keyring after::
396
397 pip install dbus-python
398
399 Note also, that recent versions of keyring library (since version 12) use Python
400 entrypoints to find available backends. Those are incompatible with
401 some binary packaging methods (like ``py2app``) and may cause
402 problems. In particular there were packaged installations of TortoiseHG_
403 which were unable to load keyring backends. See `#61 <https://foss.heptapod.net/mercurial/mercurial_keyring/issues/61/tortoisehg-encounters-unknown-exception>`_ for some more details.
404
405
406 If ``keyring`` command works, but mercurial with mercurial_keyring does not,
407 try enforcing proper backend (by means of ``keyringrc.cfg``, see above).
408 Only if this doesn't help, there may be a bug in mercurial_keyring.
409
410 By far easiest way to have properly working keyring is to use packaged
411 binary version (like ``python-keyring`` Ubuntu package, or keyring
412 bundled with TortoiseHG_ on some systems). If you pip-installed keyring
413 and it doesn't work, you may consider removing it via ``pip uninstall
414 keyring`` and looking for binary package instead.
415
416
417
418
419 History
420 =======================================================
421
422 See `HISTORY.rst`_.
423
424 Repository, bug reports, enhancement suggestions
425 ===================================================
426
427 Development is tracked on HeptaPod, see
428 https://foss.heptapod.net/mercurial/mercurial_keyring/
429
430 Use issue tracker there for bug reports and enhancement
431 suggestions.
432
433 Thanks to Octobus_ and `Clever Cloud`_ for hosting this service.
434
435
436
437 Additional notes
438 =======================================================
439
440 Information about this extension is also available
441 on Mercurial Wiki: https://www.mercurial-scm.org/wiki/KeyringExtension
442
443 Check also `other Mercurial extensions I wrote`_.
444
445 .. _Octobus: https://octobus.net/
446 .. _Clever Cloud: https://www.clever-cloud.com/
447
448 .. _other Mercurial extensions I wrote: http://code.mekk.waw.pl/mercurial.html
449
450 .. _HISTORY.rst: https://foss.heptapod.net/mercurial/mercurial_keyring/src/tip/HISTORY.rst
451 .. _TortoiseHg: https://foss.heptapod.net/mercurial/tortoisehg/thg
452 .. _Mercurial: https://www.mercurial-scm.org/
453 .. _mercurial_extension_utils: https://foss.heptapod.net/mercurial/mercurial-extension_utils/
454 .. _Path Pattern: https://foss.heptapod.net/mercurial/mercurial-path_pattern/
455
456