# libopaque Python bindings
These bindings provide access to libopaque which implements the
[IRTF CFRG RFC draft](https://github.com/cfrg/draft-irtf-cfrg-opaque)
or you can read the [original paper](https://eprint.iacr.org/2018/163).
## Dependencies
These bindings depend on the following:
- libopaque: https://github.com/stef/libopaque/
- libsodium
- pysodium
## API
There is one data structure that is used by libopaque:
### `Ids`
The IDs of the peers are passed around as a struct:
```python
# wrap the IDs into an opaque.Ids struct:
ids=opaque.Ids("user", "server")
```
## 1-step registration
1-step registration is only specified in the original paper. It is not specified by the IRTF
CFRG draft. 1-step registration has the benefit that the supplied password (`pwdU`) can be checked
on the server for password rules (e.g., occurrence in common password
lists). It has the drawback that the password is exposed to the server.
```python
rec, export_key = opaque.Register(pwdU, ids, skS)
```
- `pwdU` is the user's password.
- `ids` is an `Ids` struct that contains the IDs of the user and the server.
- `skS` is an optional server long-term private-key
## 4-step registration
Registration as specified in the IRTF CFRG draft consists of the
following 4 steps:
### Step 1: The user creates a registration request.
```python
secU, M = opaque.CreateRegistrationRequest(pwdU)
```
- `pwdU` is the user's password.
The user should hold on to `secU` securely until step 3 of the registration process.
`M` needs to be passed to the server running step 2.
### Step 2: The server responds to the registration request.
```python
secS, pub = opaque.CreateRegistrationResponse(M, skS)
```
- `M` comes from the user running the previous step.
- `skS` is an optional server long-term private-key
The server should hold onto `secS` securely until step 4 of the registration process.
`pub` should be passed to the user running step 3.
### Step 3: The user finalizes the registration using the response from the server.
```python
rec0, export_key = opaque.FinalizeRequest(secU, pub, ids)
```
- `secU` contains sensitive data and should be disposed securely after usage in this step.
- `pub` comes from the server running the previous step.
- `ids` is an `Ids` struct that contains the IDs of the user and the server.
- `rec0` should be passed to the server running step 4.
- `export_key` is an extra secret that can be used to encrypt
additional data that you might want to store on the server next to
your record.
### Step 4: The server finalizes the user's record.
```python
rec1 = opaque.StoreUserRecord(secS, rec0)
```
- `rec0` comes from the user running the previous step.
- `secS` contains sensitive data and should be disposed securely after usage in this step.
- `rec1` should be stored by the server associated with the ID of the user.
**Important Note**: Confusingly this function is called `StoreUserRecord`, yet it
does not do any storage. How you want to store the record (`rec1`) is up
to the implementor using this API.
## Establishing an opaque session
After a user has registered with a server, the user can initiate the
AKE and thus request its credentials in the following 3(+1)-step protocol:
### Step 1: The user initiates a credential request.
```python
pub, secU = opaque.CreateCredentialRequest(pwdU)
```
- `pwdU` is the user's password.
The user should hold onto `secU` securely until step 3 of the protocol.
`pub` needs to be passed to the server running step 2.
### Step 2: The server responds to the credential request.
```python
resp, sk, secS = opaque.CreateCredentialResponse(pub, rec, ids, context)
```
- `pub` comes from the user running the previous step.
- `rec` is the user's record stored by the server at the end of the registration protocol.
- `ids` is an `Ids` struct that contains the IDs of the user and the server.
- `context` is a string distinguishing this instantiation of the protocol from others, e.g. "MyApp-v0.2"
- `resp` needs to be passed to the user running step 3.
- `sk` is a shared secret, the result of the AKE.
- The server should hold onto `secS` securely until the optional step
4 of the protocol, if needed. otherwise this value should be
discarded securely.
### Step 3: The user recovers its credentials from the server's response.
```python
sk, authU, export_key = opaque.RecoverCredentials(resp, secU, ctx, ids)
```
- `resp` comes from the server running the previous step.
- `secU` contains sensitive data and should be disposed securely after usage in this step.
- `context` is a string distinguishing this instantiation of the protocol from others, e.g. "MyApp-v0.2"
- `sk` is a shared secret, the result of the AKE.
- `authU` is an authentication tag that can be passed in step 4 for explicit user authentication.
- `export_key` can be used to decrypt additional data stored by the server.
### Step 4 (Optional): The server authenticates the user.
This step is only needed if there is no encrypted channel setup
towards the server using the shared secret.
```python
opaque.UserAuth(secS, authU)
```
- `secS` contains sensitive data and should be disposed securely after usage in this step.
- `authU` comes from the user running the previous step.
Raw data
{
"_id": null,
"home_page": "https://github.com/stef/libopaque",
"name": "opaque",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "cryptography API libopaque OPAQUE PAKE AKE key-exchange",
"author": "Stefan Marsiske",
"author_email": "pyopaque@ctrlc.hu",
"download_url": "https://files.pythonhosted.org/packages/ce/47/0269e26df66f407b758d77b73648b150b920c1f093c018ca93dffd619162/opaque-1.0.0.tar.gz",
"platform": null,
"description": "# libopaque Python bindings\n\nThese bindings provide access to libopaque which implements the\n[IRTF CFRG RFC draft](https://github.com/cfrg/draft-irtf-cfrg-opaque)\nor you can read the [original paper](https://eprint.iacr.org/2018/163).\n\n## Dependencies\n\nThese bindings depend on the following:\n - libopaque: https://github.com/stef/libopaque/\n - libsodium\n - pysodium\n\n## API\n\nThere is one data structure that is used by libopaque:\n\n### `Ids`\nThe IDs of the peers are passed around as a struct:\n```python\n# wrap the IDs into an opaque.Ids struct:\nids=opaque.Ids(\"user\", \"server\")\n```\n\n## 1-step registration\n\n1-step registration is only specified in the original paper. It is not specified by the IRTF\nCFRG draft. 1-step registration has the benefit that the supplied password (`pwdU`) can be checked\non the server for password rules (e.g., occurrence in common password\nlists). It has the drawback that the password is exposed to the server.\n\n```python\nrec, export_key = opaque.Register(pwdU, ids, skS)\n```\n - `pwdU` is the user's password.\n - `ids` is an `Ids` struct that contains the IDs of the user and the server.\n - `skS` is an optional server long-term private-key\n\n## 4-step registration\n\nRegistration as specified in the IRTF CFRG draft consists of the\nfollowing 4 steps:\n\n### Step 1: The user creates a registration request.\n\n```python\nsecU, M = opaque.CreateRegistrationRequest(pwdU)\n```\n\n- `pwdU` is the user's password.\n\nThe user should hold on to `secU` securely until step 3 of the registration process.\n`M` needs to be passed to the server running step 2.\n\n### Step 2: The server responds to the registration request.\n\n```python\nsecS, pub = opaque.CreateRegistrationResponse(M, skS)\n```\n\n - `M` comes from the user running the previous step.\n - `skS` is an optional server long-term private-key\n\nThe server should hold onto `secS` securely until step 4 of the registration process.\n`pub` should be passed to the user running step 3.\n\n### Step 3: The user finalizes the registration using the response from the server.\n\n```python\nrec0, export_key = opaque.FinalizeRequest(secU, pub, ids)\n```\n\n - `secU` contains sensitive data and should be disposed securely after usage in this step.\n - `pub` comes from the server running the previous step.\n - `ids` is an `Ids` struct that contains the IDs of the user and the server.\n\n - `rec0` should be passed to the server running step 4.\n - `export_key` is an extra secret that can be used to encrypt\n additional data that you might want to store on the server next to\n your record.\n\n### Step 4: The server finalizes the user's record.\n\n```python\nrec1 = opaque.StoreUserRecord(secS, rec0)\n```\n\n - `rec0` comes from the user running the previous step.\n - `secS` contains sensitive data and should be disposed securely after usage in this step.\n\n - `rec1` should be stored by the server associated with the ID of the user.\n\n**Important Note**: Confusingly this function is called `StoreUserRecord`, yet it\ndoes not do any storage. How you want to store the record (`rec1`) is up\nto the implementor using this API.\n\n## Establishing an opaque session\n\nAfter a user has registered with a server, the user can initiate the\nAKE and thus request its credentials in the following 3(+1)-step protocol:\n\n### Step 1: The user initiates a credential request.\n\n```python\npub, secU = opaque.CreateCredentialRequest(pwdU)\n```\n\n - `pwdU` is the user's password.\n\nThe user should hold onto `secU` securely until step 3 of the protocol.\n`pub` needs to be passed to the server running step 2.\n\n### Step 2: The server responds to the credential request.\n\n```python\nresp, sk, secS = opaque.CreateCredentialResponse(pub, rec, ids, context)\n```\n\n - `pub` comes from the user running the previous step.\n - `rec` is the user's record stored by the server at the end of the registration protocol.\n - `ids` is an `Ids` struct that contains the IDs of the user and the server.\n - `context` is a string distinguishing this instantiation of the protocol from others, e.g. \"MyApp-v0.2\"\n\n - `resp` needs to be passed to the user running step 3.\n - `sk` is a shared secret, the result of the AKE.\n - The server should hold onto `secS` securely until the optional step\n 4 of the protocol, if needed. otherwise this value should be\n discarded securely.\n\n### Step 3: The user recovers its credentials from the server's response.\n\n```python\nsk, authU, export_key = opaque.RecoverCredentials(resp, secU, ctx, ids)\n```\n\n - `resp` comes from the server running the previous step.\n - `secU` contains sensitive data and should be disposed securely after usage in this step.\n - `context` is a string distinguishing this instantiation of the protocol from others, e.g. \"MyApp-v0.2\"\n\n - `sk` is a shared secret, the result of the AKE.\n - `authU` is an authentication tag that can be passed in step 4 for explicit user authentication.\n - `export_key` can be used to decrypt additional data stored by the server.\n\n### Step 4 (Optional): The server authenticates the user.\n\nThis step is only needed if there is no encrypted channel setup\ntowards the server using the shared secret.\n\n```python\nopaque.UserAuth(secS, authU)\n```\n\n - `secS` contains sensitive data and should be disposed securely after usage in this step.\n - `authU` comes from the user running the previous step.\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "python libopaque wrapper",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/stef/libopaque"
},
"split_keywords": [
"cryptography",
"api",
"libopaque",
"opaque",
"pake",
"ake",
"key-exchange"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ce470269e26df66f407b758d77b73648b150b920c1f093c018ca93dffd619162",
"md5": "ca645a4aeaf819b4edc683c244c0ea7e",
"sha256": "5b8a3e52624e6c9a43c784116cffac6af31788afdece3aa625eb7f99a20ebe32"
},
"downloads": -1,
"filename": "opaque-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ca645a4aeaf819b4edc683c244c0ea7e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10913,
"upload_time": "2025-02-18T00:09:12",
"upload_time_iso_8601": "2025-02-18T00:09:12.668403Z",
"url": "https://files.pythonhosted.org/packages/ce/47/0269e26df66f407b758d77b73648b150b920c1f093c018ca93dffd619162/opaque-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-18 00:09:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stef",
"github_project": "libopaque",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "opaque"
}
JSON
