Skip to content

Document hashing of credentials #1416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rytilahti wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document hashing of credentials #1416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions docs/source/codeinfo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,15 @@

:::{note}
The library is fully async and methods that perform IO need to be run inside an async coroutine.

The main entry point for the API is {meth}`~kasa.Discover.discover` and
{meth}`~kasa.Discover.discover_single` which return Device objects.
Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.

:::{important}
All of your code needs to run inside the same event loop so only call `asyncio.run` once.
:::

Comment on lines +4 to +12
Copy link
Collaborator

@sdb9696 sdb9696 Jan 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The main entry point for the API is {meth}`~kasa.Discover.discover` and
{meth}`~kasa.Discover.discover_single` which return Device objects.
Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.
:::{important}
All of your code needs to run inside the same event loop so only call `asyncio.run` once.
:::
The main entry point for the API is {meth}`~kasa.Discover.discover` and
{meth}`~kasa.Discover.discover_single` which return Device objects.
Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.
**All of your code needs to run inside the same event loop so only call `asyncio.run` once.**

I think this looked better as a self contained note which separated it from the rest of the details on each page. Making the asyncio.run seems to end the note and breaks up the whole thing.

Before:

image

After:

image

Perhaps the note should self-contain all the details about the async, and then a subsequent important section contains everything about the credentials.

Code examples assume you are following them inside `asyncio REPL`:
```
$ python -m asyncio
Expand All @@ -11,16 +20,14 @@ import asyncio
from kasa import Discover

async def main():
dev = await Discover.discover_single("127.0.0.1",username="un@example.com",password="pw")
dev = await Discover.discover_single("127.0.0.1", username="un@example.com", password="pw")
await dev.turn_on()
await dev.update()

if __name__ == "__main__":
asyncio.run(main())
```
**All of your code needs to run inside the same event loop so only call `asyncio.run` once.**

*The main entry point for the API is {meth}`~kasa.Discover.discover` and
{meth}`~kasa.Discover.discover_single` which return Device objects.
Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.*
::::{include} ../creds_hashing.md

:::
4 changes: 4 additions & 0 deletions docs/source/creds_hashing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
:::{important}
Most transports hash the credentials, so both *username* (e-mail) and *password* are case-sensitive.
If you are unable to authenticate with the device, verify they match to your account.
Comment on lines +2 to +3
Copy link
Collaborator

@sdb9696 sdb9696 Jan 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Most transports hash the credentials, so both *username* (e-mail) and *password* are case-sensitive.
If you are unable to authenticate with the device, verify they match to your account.
Credentials are required by newer Kasa devices and all Tapo devices.
They are the TPLink cloud *username* (e-mail) and *password* used to provision the device in the native app, and they are usually both case-sensitive.
Some firmware versions of Tapo Cameras will not authenticate unless you enable Tapo Lab > Third-Party Compatibility in the native Tapo app.

Users probably don't need to know about hashing or transports, just that credentials are usually case sensitive. Probably makes sense to have all the relevant credentials information in the one snippet.

:::
3 changes: 3 additions & 0 deletions kasa/deviceconfig.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@
>>> print(device.alias) # Alias is None because update() has not been called
None

.. include:: ../creds_hashing.md
:parser: myst_parser.sphinx_

>>> config_dict = device.config.to_dict()
>>> # DeviceConfig.to_dict() can be used to store for later
>>> print(config_dict)
Expand Down
7 changes: 5 additions & 2 deletions kasa/discover.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
>>> [dev.model for dev in found_devices.values()]
['KP303', 'HS110', 'L530E', 'KL430', 'HS220']

You can pass username and password for devices requiring authentication
You can pass username and password for devices requiring authentication:

>>> devices = await Discover.discover(
>>> username="user@example.com",
Expand All @@ -33,13 +33,16 @@
>>> print(len(devices))
5

You can also pass a :class:`kasa.Credentials`
You can also pass a :class:`kasa.Credentials`:

>>> creds = Credentials("user@example.com", "great_password")
>>> devices = await Discover.discover(credentials=creds)
>>> print(len(devices))
5

.. include:: ../creds_hashing.md
:parser: myst_parser.sphinx_

Comment on lines +43 to +45
Copy link
Collaborator

@sdb9696 sdb9696 Jan 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. include:: ../creds_hashing.md
:parser: myst_parser.sphinx_

This is repeated at the top of the page. We should either remove it from codeinfo.md or remove it here. Maybe it's better to remove it from codeinfo.md so we can place it where it's most relevant.

Discovery can also be targeted to a specific broadcast address instead of
the default 255.255.255.255:

Expand Down
Loading