ExFTP.Auth.DigestAuth (ExFTP v1.0.4)

View Source

When authenticator is ExFTP.Auth.DigestAuth, this authenticator will call out to an HTTP endpoint that implements HTTP Digest Access Auth with the user's supplied credentials.

🔒 Security

This can be used in situations where SSL is not available, though be warned, Digest Access is considered an obsolete protocol.

⚙️ Configuration

Keys

Example

  %{
    # ... ,
    authenticator: ExFTP.Auth.DigestAuth,
    authenticator_config: %{
      login_url: "https://httpbin.dev/digest-auth/auth/replace/me/MD5",
      login_method: :get,
      authenticated_url: "https://httpbin.dev/digest-auth/auth/replace/me/MD5",
      authenticated_method: :get,
      authenticated_ttl_ms: 1000 * 60 * 60
    }
  }

👀 See Also

📖 Resources

Summary

Functions

authenticated?(authenticator_state)

Determines whether this session is still considered authenticated

login(password, authenticator_state)

Requests a login using HTTP Digest Access Auth

valid_user?(username)

Always returns true.

Functions

authenticated?(authenticator_state)

@spec authenticated?(authenticator_state :: ExFTP.Authenticator.authenticator_state()) ::
  boolean()

Determines whether this session is still considered authenticated

🏷️ Params

🧑‍🍳 Workflow

  • Reads the authenticator_config.
  • If the config has authenticated_url,
    • Calls the authenticated_url - receives HTTP 401 with digest headers
    • Performs calculation, calls authenticated_url with proper headers
    • If the response is HTTP 200, success. Otherwise, bad login.
  • If the config does not have authenticated_url,
    • investigate the authenticator_state for authenticated: true

⤵️ Returns

✅ On Success

  `true` or `false`

💻 Examples

iex> alias ExFTP.Auth.DigestAuth
iex> username = "alice"
iex> password = "password1234"
iex> Application.put_env(:ex_ftp, :authenticator, ExFTP.Auth.DigestAuth)
iex> Application.put_env(:ex_ftp, :authenticator_config, %{
iex>  login_url: "https://httpbin.dev/digest-auth/auth/" <> username <> "/" <> password <> "/MD5",
iex>  authenticated_url: "https://httpbin.dev/digest-auth/auth/" <> username <> "/" <> password <> "/MD5",
iex>  authenticated_method: :get,
iex> })
iex> DigestAuth.authenticated?(%{username: username, password: password})
true

👀 See Also

login(password, authenticator_state)

@spec login(
  password :: ExFTP.Authenticator.password(),
  authenticator_state :: ExFTP.Authenticator.authenticator_state()
) :: {:ok, ExFTP.Authenticator.authenticator_state()} | {:error, term()}

Requests a login using HTTP Digest Access Auth

🏷️ Params

🧑‍🍳 Workflow

  • Reads the authenticator_config.
  • Receives a password from the client (a username was supplied earlier)
  • Calls the login_url - receives HTTP 401 with digest headers
  • Performs calculation, calls login_url with proper headers
  • If the response is HTTP 200, success. Otherwise, bad login.

⤵️ Returns

✅ On Success

  {:ok, authenticator_state}

❌ On Failure

  {:error, bad_login}

💻 Examples

iex> alias ExFTP.Auth.DigestAuth
iex> username = "alice"
iex> password = "password1234"
iex> Application.put_env(:ex_ftp, :authenticator, ExFTP.Auth.DigestAuth)
iex> Application.put_env(:ex_ftp, :authenticator_config, %{
iex>  login_url: "https://httpbin.dev/digest-auth/auth/" <> username <> "/" <> password <> "/MD5",
iex>  login_method: :get
iex> })
iex> {:ok, _} = DigestAuth.login(password , %{username: username})

👀 See Also

valid_user?(username)

@spec valid_user?(username :: ExFTP.Authenticator.username()) :: boolean()

Always returns true.

No performance benefit

This method is normally used to short-circuit bad login requests. The performance gain in that short-circuit is negligible for this auth, so it's not used.