| 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 |
|