diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/swagger.yaml | 47 | ||||
| -rw-r--r-- | docs/swagger.go | 2 | ||||
| -rw-r--r-- | docs/user_guide/password_management.md | 19 |
3 files changed, 68 insertions, 0 deletions
diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml index 77a150a9a..72c543a3a 100644 --- a/docs/api/swagger.yaml +++ b/docs/api/swagger.yaml @@ -3362,6 +3362,51 @@ paths: summary: See public statuses/posts that your instance is aware of. tags: - timelines + /api/v1/user/password_change: + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. + The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. + operationId: userPasswordChange + parameters: + - description: User's previous password. + in: formData + name: old_password + required: true + type: string + x-go-name: OldPassword + - description: |- + Desired new password. + If the password does not have high enough entropy, it will be rejected. + See https://github.com/wagslane/go-password-validator + in: formData + name: new_password + required: true + type: string + x-go-name: NewPassword + produces: + - application/json + responses: + "200": + description: Change successful + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "500": + description: internal error + security: + - OAuth2 Bearer: + - write:user + summary: Change the password of authenticated user. + tags: + - user /users/{username}/statuses/{status}/replies: get: description: |- @@ -3437,12 +3482,14 @@ securityDefinitions: read:search: grant read access to searches read:statuses: grants read access to statuses read:streaming: grants read access to streaming api + read:user: grants read access to user-level info write: grants write access to everything write:accounts: grants write access to accounts write:blocks: grants write access to blocks write:follows: grants write access to follows write:media: grants write access to media write:statuses: grants write access to statuses + write:user: grants write access to user-level info tokenUrl: https://example.org/oauth/token type: oauth2 swagger: "2.0" diff --git a/docs/swagger.go b/docs/swagger.go index a30700e4d..422a4ac57 100644 --- a/docs/swagger.go +++ b/docs/swagger.go @@ -40,12 +40,14 @@ // read:search: grant read access to searches // read:statuses: grants read access to statuses // read:streaming: grants read access to streaming api +// read:user: grants read access to user-level info // write: grants write access to everything // write:accounts: grants write access to accounts // write:blocks: grants write access to blocks // write:follows: grants write access to follows // write:media: grants write access to media // write:statuses: grants write access to statuses +// write:user: grants write access to user-level info // admin: grants admin access to everything // admin:accounts: grants admin access to accounts // OAuth2 Application: diff --git a/docs/user_guide/password_management.md b/docs/user_guide/password_management.md new file mode 100644 index 000000000..f6e2de1b2 --- /dev/null +++ b/docs/user_guide/password_management.md @@ -0,0 +1,19 @@ +# Password Management + +GoToSocial stores hashes of user passwords in its database using the secure [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) function in the [Go standard libraries](https://pkg.go.dev/golang.org/x/crypto/bcrypt). + +This means that the plaintext value of your password is safe even if the database of your GoToSocial instance is compromised. It also means that your instance admin does not have access to your password. + +To check whether a password is sufficiently secure before accepting it, GoToSocial uses [this library](https://github.com/wagslane/go-password-validator) with entropy set to 60. This means that passwords like `password` are rejected, but something like `verylongandsecurepasswordhahaha` would be accepted, even without special characters/upper+lowercase etc. + +We recommend following the EFF's guidelines on [creating strong passwords](https://ssd.eff.org/en/module/creating-strong-passwords). + +## Change Your Password + +### API method + +If you are logged in (ie., you have a valid oauth token), you can change your password by making a POST request to `/api/v1/user/password_change`, using your token as authentication, and giving your old password and desired new password as parameters. Check the [API documentation](../api/swagger.md) for more details. + +## Reset Your Password + +todo |