///

## Password hashing { #password-hashing }

"Hashing" means converting some content (a password in this case) into a sequence of bytes (just a string) that looks like gibberish.

Whenever you pass exactly the same content (exactly the same password) you get exactly the same gibberish.

But you cannot convert from the gibberish back to the password.

### Why use password hashing { #why-use-password-hashing }

If the passwords don't match, we return the same error.

#### Password hashing { #password-hashing }

"Hashing" means: converting some content (a password in this case) into a sequence of bytes (just a string) that looks like gibberish.

Whenever you pass exactly the same content (exactly the same password) you get exactly the same gibberish.

## Log Message Guidelines

- Logger: `LogManager.getLogger(ClassName.class)`
- Format: `key=value` (e.g., `userId={}`, `url={}`)
- Prefix with `[name]` when context identification is needed
- Mask sensitive values (passwords, tokens)

## i18n / Localization

* Make sure you have well defined Pydantic models for your request bodies and responses.
* Configure any required permissions and roles using dependencies.
* Never store plaintext passwords, only password hashes.
* Implement and use well-known cryptographic tools, like pwdlib and JWT tokens, etc.
* Add more granular permission controls with OAuth2 scopes where needed.
* ...etc.

* The **input model** needs to be able to have a password.
* The **output model** should not have a password.
* The **database model** would probably need to have a hashed password.

/// danger

Never store user's plaintext passwords. Always store a "secure hash" that you can then verify.

If you don't know, you will learn what a "password hash" is in the [security chapters](security/simple-oauth2.md#password-hashing).

///

/// tip

This is how you would handle **passwords**. Receive them, but don't return them in the API.

You would also **hash** the values of the passwords before storing them, **never store them in plain text**.

///

The fields of `HeroCreate` are:

* `name`
* `age`
* `secret_name`

Now, whenever a browser is creating a user with a password, the API will return the same password in the response.

In this case, it might not be a problem, because it's the same user sending the password.

But if we use the same model for another *path operation*, we could be sending our user's passwords to every client.

/// danger

更多內容可參考 [PyJWT 安裝文件](https://pyjwt.readthedocs.io/en/latest/installation.html)。

///

## 密碼雜湊 { #password-hashing }

「雜湊」是指把某些內容（此處為密碼）轉換成一串看起來像亂碼的位元組序列（其實就是字串）。

每當你輸入完全相同的內容（完全相同的密碼），就會得到完全相同的亂碼。

但你無法從這串亂碼再反推回原本的密碼。

### 為什麼要用密碼雜湊 { #why-use-password-hashing }

如果你的資料庫被偷了，竊賊拿到的不是使用者的明文密碼，而只是雜湊值。

因此，竊賊無法直接拿該密碼去嘗試登入其他系統（由於許多使用者在各處都用同一組密碼，這會很危險）。

可以在 [PyJWT 安装文档](https://pyjwt.readthedocs.io/en/latest/installation.html)中了解更多。

///

## 密码哈希 { #password-hashing }

“哈希”是指把一些内容（这里是密码）转换成看起来像乱码的一串字节（其实就是字符串）。

当你每次传入完全相同的内容（完全相同的密码）时，都会得到完全相同的“乱码”。

但你无法从这个“乱码”反向还原出密码。

### 为什么使用密码哈希 { #why-use-password-hashing }

如果你的数据库被盗，窃贼拿到的不会是用户的明文密码，而只是哈希值。

因此，窃贼无法把该密码拿去尝试登录另一个系统（很多用户在各处都用相同的密码，这将非常危险）。

## 安装 `pwdlib` { #install-pwdlib }

Nunca deberías guardar passwords en texto plano, así que, usaremos el sistema de hash de passwords (falso).

Si los passwords no coinciden, devolvemos el mismo error.

#### Hashing de passwords { #password-hashing }

"Hacer hash" significa: convertir algún contenido (un password en este caso) en una secuencia de bytes (solo un string) que parece un galimatías.