Ktor Server 中的 Digest 驗證
必要的相依性: io.ktor:ktor-server-auth
程式碼範例: auth-digest
原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。支援: ✖️
Digest 驗證機制是 HTTP 架構的一部分,用於存取控制與驗證。在此機制中,使用者名稱和密碼在透過網路傳送之前會先經過雜湊函式處理。
Ktor 支援 RFC 7616(HTTP Digest 存取驗證),它透過現代安全性功能強化了較舊的 RFC 2617,包含更強大的雜湊演算法、保護品質(Quality of Protection)選項,以及用於保護隱私的使用者名稱雜湊。
Ktor 允許您使用 Digest 驗證來讓使用者登入並保護特定的路由。您可以在 Ktor Server 中的驗證與授權章節中取得關於 Ktor 驗證的一般資訊。
新增相依性
若要啟用 digest 驗證,您需要在組建指令碼中包含 ktor-server-auth 構件:
Digest 驗證流程
Digest 驗證流程如下所示:
用戶端向伺服器應用程式中的特定路由發出不帶
Authorization標頭的請求。伺服器向用戶端回傳
401(Unauthorized) 回應狀態,並使用WWW-Authenticate回應標頭提供資訊,表明使用 Digest 驗證機制來保護路由。典型的WWW-Authenticate標頭如下所示:WWW-Authenticate: Digest realm="Access to the '/' path", nonce="e4549c0548886bc2", algorithm=SHA-512-256, qop="auth"在 Ktor 中,您可以在設定
digest驗證提供者時,指定 realm、支援的演算法、保護品質以及產生 nonce 值的方式。通常用戶端會顯示登入對話方塊讓使用者輸入憑據。接著,用戶端會發出帶有以下
Authorization標頭的請求:Authorization: Digest username="jetbrains", realm="Access to the '/' path", nonce="e4549c0548886bc2", uri="/", algorithm=SHA-512-256, qop=auth, nc=00000001, cnonce="0a4f113b", response="6629fae49393a05397450978507c4ef1"response值的產生方式如下:HA1 = H(username:realm:password),其中H為設定的雜湊演算法(例如 SHA-512-256)
這部分會儲存在伺服器上,Ktor 可用其來驗證使用者憑據。
HA2 = H(method:digestURI)(適用於qop=auth)或HA2 = H(method:digestURI:H(entityBody))(適用於qop=auth-int)response = H(HA1:nonce:nc:cnonce:qop:HA2)
伺服器驗證用戶端傳送的憑據,並回應所請求的內容。在包含 QoP 的驗證成功時,伺服器還會回傳
Authentication-Info標頭以進行雙向驗證。
安裝 Digest 驗證
若要安裝 digest 驗證提供者,請在 install 區塊內呼叫 digest 函式:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
digest {
// Configure digest authentication
}
}設定 Digest 驗證
若要大致了解如何在 Ktor 中設定不同的驗證提供者,請參閱設定驗證。在本節中,我們將介紹 digest 驗證提供者的具體設定細節。
步驟 1:選擇雜湊演算法
Ktor 支援多種用於 Digest 驗證的雜湊演算法。您可以使用 algorithms 屬性來設定伺服器接受哪些演算法:
| 演算法 | 常數 | 安全性等級 | 附註 |
|---|---|---|---|
| SHA-512-256 | DigestAlgorithm.SHA_512_256 | 建議 | 最強安全性,建議用於新實作 |
| SHA-512-256-sess | DigestAlgorithm.SHA_512_256_SESS | 建議 | 工作階段變形 - 在 HA1 中包含用戶端 nonce |
| SHA-256 | DigestAlgorithm.SHA_256 | 良好 | 正式環境的最低建議標準 |
| SHA-256-sess | DigestAlgorithm.SHA_256_SESS | 良好 | 工作階段變形 - 在 HA1 中包含用戶端 nonce |
| MD5 | DigestAlgorithm.MD5 | 已棄用 | 僅用於回溯相容性 |
| MD5-sess | DigestAlgorithm.MD5_SESS | 已棄用 | 工作階段變形 - 僅用於舊版相容性 |
install(Authentication) {
digest("auth-digest") {
realm = "Access to the '/' path"
algorithms = listOf(
DigestAlgorithm.SHA_512_256,
DigestAlgorithm.MD5
)
// ...
}
}當設定了多個演算法時,伺服器會傳送多個 WWW-Authenticate 標頭,允許用戶端選擇其支援的最強演算法。
預設演算法為 SHA-512-256 和 MD5(用於與較舊的用戶端維持回溯相容性)。
工作階段演算法(-sess 變形)
-sess 演算法變形(例如 SHA-512-256-sess、SHA-256-sess、MD5-sess)修改了計算 HA1 雜湊的方式。工作階段演算法不是儲存 H(username:realm:password),而是計算 H(H(username:realm:password):nonce:cnonce),其中 cnonce 是用戶端提供的 nonce。
優點:
- 工作階段專屬的雜湊可防止預先計算的字典攻擊
- 單一工作階段的雜湊遭到破解不會洩漏密碼,也不會對其他工作階段造成危害
缺點:
- 伺服器必須為每次驗證請求計算雜湊(無法使用預先計算的值)
對於大多數應用程式而言,標準(非工作階段)演算法已經足夠,特別是與 SHA-512-256 等強雜湊函式一起使用時。
步驟 2:提供包含摘要的使用者資料表
digest 驗證提供者使用 Digest 訊息的 HA1 部分來驗證使用者憑據,因此您可以提供一個包含使用者名稱及其對應 HA1 雜湊的使用者資料表。
由於不同的演算法會產生不同的雜湊值,您需要為支援的每個演算法儲存相應的雜湊,或者根據用戶端所請求的演算法動態計算雜湊:
val userPasswords: Map<String, String> = mapOf(
"jetbrains" to "foobar",
"admin" to "password"
)
fun computeHash(
userName: String,
realm: String,
password: String,
algorithm: DigestAlgorithm
): ByteArray =
algorithm.toDigester()
.digest("$userName:$realm:$password".toByteArray(UTF_8))步驟 3:設定 Digest 提供者
digest 驗證提供者透過 DigestAuthenticationProvider.Config 類別公開其設定。在以下範例中,指定了以下設定:
realm屬性設定要在WWW-Authenticate標頭中傳遞的 realm。algorithms屬性指定要接受哪些雜湊演算法。digestProvider函式為指定的使用者名稱和演算法擷取 Digest 的HA1部分。- (選用)
validate函式允許您將憑據對應到自訂 Principal。
install(Authentication) {
digest("auth-digest") {
realm = myRealm
// 同時支援現代 SHA-512-256 與舊版 MD5 用戶端
algorithms = listOf(
DigestAlgorithm.SHA_512_256,
DigestAlgorithm.MD5
)
digestProvider { userName, realm, algorithm ->
// 使用請求的演算法計算 H(username:realm:password)
userPasswords[userName]?.let { password ->
computeHash(
userName, realm, password, algorithm
)
}
}
validate { credentials ->
if (credentials.userName.isNotEmpty()) {
CustomPrincipal(
credentials.userName,
credentials.realm
)
} else {
null
}
}
}
}型別安全驗證機制 API 為實驗功能。它隨時可能被移除或變更,需要明確選擇加入(Opt-in)。如需更多詳細資訊,請參閱 型別安全驗證文件。
digest() 函式為您所選擇的 Principal 型別建立機制。這裡沒有 install(Authentication) 步驟:該機制是一個由您傳遞給需要它的路由的值。
data class CustomPrincipal(
val userName: String,
val realm: String
)
val digestAuth = digest<CustomPrincipal>("auth-digest") {
realm = myRealm
// 同時支援現代 SHA-512-256 與舊版 MD5 用戶端
algorithms = listOf(
DigestAlgorithm.SHA_512_256,
DigestAlgorithm.MD5
)
digestProvider { userName, realm, algorithm ->
// 使用請求的演算法計算 H(username:realm:password)
userPasswords[userName]?.let { password ->
computeHash(userName, realm, password, algorithm)
}
}
validate { credentials ->
if (credentials.userName.isNotEmpty()) {
CustomPrincipal(
credentials.userName,
credentials.realm
)
} else {
null
}
}
}型別安全的 digest() 函式僅適用於 JVM。如需完整的 API,請參閱型別安全驗證。
digestProvider 函式接收三個參數:
userName– 來自用戶端請求的使用者名稱realm– 設定的 realmalgorithm– 用戶端使用的雜湊演算法
您應該回傳使用指定演算法計算出的 HA1 雜湊;如果找不到該使用者,則回傳 null。
您也可以使用 nonceManager 屬性來指定如何產生 nonce 值。
步驟 4:設定保護品質
保護品質(Quality of Protection, QoP)決定了 Digest 計算中包含的內容:
DigestQop.AUTH– 僅驗證(預設)。Digest 包含請求方法和 URI。DigestQop.AUTH_INT– 具備完整性保護的驗證。Digest 還包含請求內文,提供防竄改保護。
install(Authentication) {
digest("auth-digest") {
realm = "Secure API"
supportedQop = listOf(
DigestQop.AUTH,
DigestQop.AUTH_INT
)
// ...
}
}使用 auth-int 時,請求內文會在驗證期間被耗盡。若您需要在路由處理常式中存取內文,請安裝 DoubleReceive 外掛程式。
步驟 5:保護特定資源
設定好 digest 提供者後,您可以使用 authenticate 函式保護應用程式中的特定資源。在驗證成功的情況下,您可以在路由處理常式內使用 call.principal 函式擷取經過驗證的 Principal,並取得經過驗證的使用者名稱。
routing {
authenticate("auth-digest") {
get("/") {
val user = call.principal<CustomPrincipal>()
call.respondText("Hello, ${user?.userName}!")
}
}
}將該機制傳遞給 authenticateWith()。在區塊內,call.principal 即為您的 Principal 型別且絕不會為 null,因此無需進行型別轉換或 null 檢查:
routing {
authenticateWith(digestAuth) {
get("/") {
val user = call.principal
call.respondText("Hello, ${user.userName}!")
}
}
}進階設定
使用者雜湊支援
RFC 7616 引進了使用者名稱雜湊(userhash)以保護隱私。啟用後,用戶端可以傳送使用者名稱的雜湊版本,而非純文字的使用者名稱。
若要支援使用者名稱雜湊,請設定 userHashResolver:
val users = listOf("alice", "bob", "charlie")
install(Authentication) {
digest("auth-digest") {
realm = "Private API"
userHashResolver { userhash, realm, algorithm ->
// 從雜湊中找出實際的使用者名稱
users.find { username ->
val digester = algorithm.toDigester()
val bytes = "$username:$realm".toByteArray()
hex(digester.digest(bytes)) == userhash
}
}
digestProvider { userName, realm, algorithm ->
// ...
}
}
}當設定了 userHashResolver 時,伺服器會在 WWW-Authenticate 質詢標頭中宣告 userhash=true。
嚴格 RFC 7616 模式
若要在沒有舊版用戶端需求的新應用程式中實現最高安全性,請使用 strictRfc7616Mode():
install(Authentication) {
digest("auth-digest") {
realm = "Secure Zone"
strictRfc7616Mode()
digestProvider { userName, realm, algorithm ->
// 在嚴格模式下,演算法絕不會是 MD5
}
}
}嚴格模式:
- 移除 MD5 演算法(僅允許 SHA-256、SHA-512-256 及其工作階段變形)
- 強制使用 UTF-8 字元集
UTF-8 字元集支援
digest 驗證提供者支援 UTF-8 字元集,以處理包含非 ASCII 字元的使用者名稱和密碼:
install(Authentication) {
digest("auth-digest") {
realm = "My App"
charset = Charsets.UTF_8 // 這是預設值
// ...
}
}Authentication-Info 標頭
在包含 QoP 的驗證成功時,伺服器會自動回傳包含以下內容的 Authentication-Info 標頭:
rspauth- 用於雙向驗證的回應驗證值nextnonce- 供用戶端使用的下一個 nonceqop、nc、cnonce- 驗證參數的回顯
這允許用戶端驗證伺服器的身分(雙向驗證)。
安全性建議
使用 SHA-512-256 或 SHA-256 – 在正式環境中應避免使用 MD5;它僅為了舊版相容性而保留。
使用
strictRfc7616Mode()– 適用於沒有舊版用戶端需求的新應用程式。實作適當的 nonce 管理 – 在分散式環境中使用自訂的
NonceManager以防止重放攻擊。考慮使用
auth-int– 當請求內文的完整性對應用程式至關重要時。啟用
userhash– 保護使用者名稱的隱私。一律使用 HTTPS – 單靠 Digest 驗證並不能加密流量;在正式環境中務必使用 TLS。
