Asterisk PJSIP digest authentication: roles, realms and algorithms

Assign the UAS and UAC roles for each exchange

Digest authentication begins with a challenge, not with a completed login. When Asterisk receives a request and acts as the user-agent server, an endpoint's auth object supplies the challenge policy and expected credential. When Asterisk sends a request and acts as the user-agent client, outbound_auth supplies a response to the remote server's challenge. A trunk can involve both directions, but they are independent relationships.

Do not treat an outbound registration, a challenged INVITE and an identified endpoint as the same event. Preserve method, direction, Call-ID, CSeq, status code, realm, algorithm and selected endpoint or registration. A 401 or 407 can be a normal intermediate response; success requires the authorized retry and the intended final result.

Use distinct auth objects when the realm semantics differ

For inbound authentication, Asterisk sends the auth object's realm in the challenge, falling back to the global default realm when none is specified. For outbound authentication, the realm selects a credential for the challenge received from the remote server; it can be the known exact realm or a blank or wildcard match. Asterisk explicitly advises against reusing one auth object for both directions because those empty-realm meanings differ.

Record the provider or phone's observed realm rather than guessing it from a host name, account label or From domain. If several outbound auth objects are present, realm matching also helps choose one. Changing the realm changes the input used by a pre-computed digest, so update the credential through the authorized secret-management path and coordinate both sides.

Bind algorithm policy to the running build

Asterisk added SHA-256 and SHA-512-256 digest support in 20.12.0, 21.7.0 and 22.2.0 with PJProject 2.15.1. The Asterisk guide says support also depends on the PJProject and OpenSSL versions present at build and runtime, and directs operators to pjproject show buildopts for the running capability. Version labels, a configuration example or a stronger peer offer do not prove that one installed binary supports the algorithm.

RFC 8760 extends SIP digest authentication beyond MD5 and says MD5 remains only for backward compatibility and is not recommended. Migration is still an interoperability change: inventory the algorithms every approved peer actually accepts, prefer stronger mutually supported algorithms, and remove MD5 only after successful and negative tests on the exact paths. Do not weaken TLS, network controls or authorization because the digest hash changed.

Keep the configured credential form and algorithm set consistent

Current Asterisk documentation uses auth_type=digest; legacy userpass and md5 values are deprecated and converted. A plaintext password lets Asterisk calculate a response for a supported requested algorithm. password_digest stores a pre-computed value for one named algorithm and binds it to the exact username and realm used to create it. A hash for MD5 cannot be transformed into a SHA-256 or SHA-512-256 credential.

Every algorithm allowed by supported_algorithms_uas or supported_algorithms_uac needs either a matching pre-computed digest or access to the plaintext password. Asterisk documents a load failure when that requirement is not met. Never place a real password, digest, Authorization header or complete challenge-response exchange in a public test plan or shared ticket.

Interpret preference and fallback without claiming protection

As a UAS, Asterisk can send one challenge per allowed algorithm in preferred order. As a UAC, it evaluates the remote server's ordered challenges against the locally allowed algorithms and available credential material. The final defaults remain MD5 when neither auth-level nor global algorithm settings are supplied, preserving older behavior. An administrator who assumes a stronger implicit default can therefore overstate the deployed policy.

Inspect the actual challenge and authorized retry. Record which algorithm was offered first, which one was selected and whether an unexpected fallback occurred. Digest authentication does not encrypt SIP headers, SDP, calling metadata or media; separately verify signaling transport, certificate validation and SRTP policy on every call leg.

Stage, observe and accept the change

Capture the running version, build options, loaded auth and endpoint relationships, current realm and a redacted control exchange before editing. Apply the configuration through its owner, confirm that it loaded without errors, then run an inbound or outbound authentication case appropriate to the object. Include a wrong-secret test, an unsupported-algorithm test and the expected failure when no permitted credential matches.

Accept only when the intended endpoint or registration is selected, the desired algorithm appears in the wire exchange, the authorized retry receives its intended final response and unrelated identities remain rejected. Remove temporary protocol logging immediately. No Asterisk build, PJProject or OpenSSL library, auth object, endpoint, registration, provider, credential, challenge, protected transport, call or interoperability combination was inspected or tested for this guide.

core show version
pjproject show buildopts
pjsip show endpoint <endpoint>
pjsip show auth <auth-object>
pjsip show registrations

Map digest transactions to typed security evidence carefully

Use the security-event logging guide to correlate the exact PJSIP exchange with event subtype, service, account, session and addresses without treating every challenge as failure.