0
# Digest Authentication
1

2
HTTP Digest authentication provider supporting MD5 and other hash algorithms with automatic nonce handling, client nonce generation, and response digest validation for more secure username/password authentication compared to Basic auth.
3

4
## Capabilities
5

6
### Digest Authentication Provider Installation
7

8
Install the Digest authentication provider with configuration for algorithm and credential management.
9

10
```kotlin { .api }
11
/**
12
 * Installs the client's DigestAuthProvider
13
 * @param block Configuration block for Digest authentication
14
 */
15
fun AuthConfig.digest(block: DigestAuthConfig.() -> Unit)
16
```
17

18
**Usage Example:**
19

20
```kotlin
21
import io.ktor.client.*
22
import io.ktor.client.plugins.auth.*
23
import io.ktor.client.plugins.auth.providers.*
24

25
val client = HttpClient {
26
    Auth {
27
        digest {
28
            credentials {
29
                DigestAuthCredentials("username", "password")
30
            }
31
            algorithmName = "MD5"
32
            realm = "ProtectedRealm"
33
        }
34
    }
35
}
36
```
37

38
### Digest Authentication Configuration
39

40
Configuration class for DigestAuthProvider with algorithm selection, credential management, and realm specification.
41

42
```kotlin { .api }
43
/**
44
 * Configuration for DigestAuthProvider
45
 */
46
class DigestAuthConfig {
47
    /**
48
     * Digest algorithm name (default: "MD5")
49
     * Supports MD5 and other cryptographic hash algorithms
50
     */
51
    var algorithmName: String
52
    
53
    /**
54
     * Optional realm specification for Digest authentication
55
     */
56
    var realm: String?
57
    
58
    /**
59
     * Configures authentication credentials provider
60
     * @param block Suspend function that returns Digest credentials or null
61
     */
62
    fun credentials(block: suspend () -> DigestAuthCredentials?)
63
}
64
```
65

66
**Usage Examples:**
67

68
```kotlin
69
digest {
70
    // Static credentials with MD5 algorithm
71
    credentials {
72
        DigestAuthCredentials("alice", "secretpassword")
73
    }
74
    algorithmName = "MD5"
75
    realm = "AdminArea"
76
}
77

78
// Advanced configuration with dynamic credentials
79
digest {
80
    credentials {
81
        val userCredentials = getCurrentUserCredentials()
82
        if (userCredentials != null) {
83
            DigestAuthCredentials(userCredentials.username, userCredentials.password)
84
        } else null
85
    }
86
    
87
    // Use SHA-256 algorithm if supported by server
88
    algorithmName = "SHA-256"
89
    
90
    // Match specific realm
91
    realm = "api.example.com"
92
}
93
```
94

95
### Digest Authentication Credentials
96

97
Container class for Digest authentication credentials.
98

99
```kotlin { .api }
100
/**
101
 * Contains credentials for DigestAuthProvider
102
 * @param username Username for Digest authentication
103
 * @param password Password for Digest authentication (used to generate digest)
104
 */
105
class DigestAuthCredentials(
106
    val username: String,
107
    val password: String
108
)
109
```
110

111
### Digest Authentication Provider
112

113
Authentication provider implementation for the HTTP Digest authentication scheme with automatic nonce handling and digest calculation.
114

115
```kotlin { .api }
116
/**
117
 * Authentication provider for the Digest HTTP authentication scheme
118
 * Digest authentication is a more secure alternative to Basic authentication
119
 * that avoids sending passwords in plain text by using cryptographic hashes
120
 */
121
class DigestAuthProvider(
122
    private val credentials: suspend () -> DigestAuthCredentials?,
123
    private val realm: String? = null,
124
    private val algorithmName: String = "MD5"
125
) : AuthProvider {
126
    
127
    // Note: clearToken() method is available but marked as @InternalAPI
128
    
129
    override fun sendWithoutRequest(request: HttpRequestBuilder): Boolean
130
    override fun isApplicable(auth: HttpAuthHeader): Boolean
131
    override suspend fun addRequestHeaders(request: HttpRequestBuilder, authHeader: HttpAuthHeader?)
132
    override suspend fun refreshToken(response: HttpResponse): Boolean
133
}
134
```
135

136
**Usage Examples:**
137

138
```kotlin
139
import io.ktor.client.*
140
import io.ktor.client.plugins.auth.*
141
import io.ktor.client.plugins.auth.providers.*
142

143
// Basic Digest authentication setup
144
val client = HttpClient {
145
    Auth {
146
        digest {
147
            credentials {
148
                DigestAuthCredentials("user", "password")
149
            }
150
        }
151
    }
152
}
153

154
// Advanced Digest authentication with custom algorithm
155
val secureClient = HttpClient {
156
    Auth {
157
        digest {
158
            credentials {
159
                // Load from secure credential store
160
                loadDigestCredentialsFromVault()
161
            }
162
            algorithmName = "SHA-256"
163
            realm = "secure-api"
164
        }
165
    }
166
}
167

168
// Multiple authentication methods
169
val multiAuthClient = HttpClient {
170
    Auth {
171
        // Digest for secure endpoints
172
        digest {
173
            credentials {
174
                DigestAuthCredentials("admin", "secure-password")
175
            }
176
            realm = "admin"
177
        }
178
        
179
        // Basic for legacy endpoints
180
        basic {
181
            credentials {
182
                BasicAuthCredentials("user", "simple-password")
183
            }
184
            realm = "public"
185
        }
186
    }
187
}
188

189
// Note: clearToken() is available as internal API for clearing cached credentials
190
```
191

192
## Authentication Flow
193

194
1. **Initial Request**: Server responds with 401 Unauthorized containing WWW-Authenticate header with Digest challenge
195
2. **Challenge Processing**: Provider extracts nonce, realm, qop, and other parameters from challenge
196
3. **Algorithm Validation**: Provider verifies that server's algorithm matches configured algorithm
197
4. **Realm Matching**: Provider validates realm from challenge matches configured realm (if specified)
198
5. **Digest Calculation**: Provider calculates digest using:
199
   - Username and password from credentials
200
   - HTTP method and request URI
201
   - Server nonce and optional client nonce
202
   - Configured algorithm (MD5, SHA-256, etc.)
203
6. **Authorization Header**: Provider constructs Authorization header with calculated digest
204
7. **Request Retry**: Request is retried with Digest authorization header
205
8. **Token Caching**: Successful authentication results are cached for subsequent requests to same realm
206

207
## Digest Algorithm Support
208

209
The DigestAuthProvider supports multiple cryptographic algorithms:
210

211
- **MD5** (default): Most widely supported, suitable for most use cases
212
- **SHA-256**: More secure alternative, requires server support
213
- **Other algorithms**: As supported by the Kotlin cryptographic libraries
214

215
The algorithm is negotiated based on the server's WWW-Authenticate challenge and the configured `algorithmName` setting.