Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bluenviron/gortsplib/llms.txt

Use this file to discover all available pages before exploring further.

Import path: github.com/bluenviron/gortsplib/v5/pkg/auth

​
Overview

pkg/auth provides two complementary helpers:
  • Sender — client-side: reads a WWW-Authenticate challenge from the server and adds an Authorization header to outgoing requests.
  • Verify — server-side: validates the Authorization header on an incoming request against a known username and password.
Two utility functions, GenerateNonce and GenerateWWWAuthenticate, support server implementations that need to issue challenges.

​
Supported authentication methods

VerifyMethod constantMethodAlgorithm
VerifyMethodBasicBasic—
VerifyMethodDigestMD5DigestMD5
VerifyMethodDigestSHA256DigestSHA-256
VerifyMethodDigestSHA256 is not included in the default method set because it prevents FFmpeg from authenticating. Enable it explicitly when your clients support it.
When methods is nil in Verify or GenerateWWWAuthenticate, the default set is {VerifyMethodBasic, VerifyMethodDigestMD5}.

​
Sender

Sender is used by RTSP clients to respond to a WWW-Authenticate challenge. 
type Sender struct {
    WWWAuth base.HeaderValue
    User    string
    Pass    string
}

​
Fields

​
WWWAuth
base.HeaderValue
required
The raw WWW-Authenticate header value received from the server’s 401 Unauthorized response. May contain multiple challenge entries (one per element of the slice).
​
User
string
required
The username to authenticate with.
​
Pass
string
required
The password to authenticate with.

​
Methods

​
Initialize

func (se *Sender) Initialize() error
Parses the WWWAuth header and selects the strongest available authentication method. Priority order: Digest SHA-256 > Digest MD5 > Basic. Returns an error if no recognized authentication method is found. Must be called once before AddAuthorization.

​
AddAuthorization

func (se *Sender) AddAuthorization(req *base.Request)
Adds an Authorization header to req, computed for the request’s method and URL. For Digest authentication the response hash is recomputed on every call, so the same Sender instance can be reused across multiple requests in the same session.

​
Verify

Verify is a standalone function used by RTSP servers to validate an incoming request. 
func Verify(
    req     *base.Request,
    user    string,
    pass    string,
    methods []VerifyMethod,
    realm   string,
    nonce   string,
) error

​
Parameters

​
req
*base.Request
required
The incoming RTSP request whose Authorization header is to be validated.
​
user
string
required
Expected username.
​
pass
string
required
Expected password.
​
methods
[]VerifyMethod
Allowed authentication methods. Pass nil to use the default set (VerifyMethodBasic + VerifyMethodDigestMD5).
​
realm
string
required
The realm string used when generating the original WWW-Authenticate challenge.
​
nonce
string
required
The nonce string used when generating the original WWW-Authenticate challenge. Generate one with GenerateNonce.
Returns nil on success, or a non-nil error describing why authentication failed.

​
GenerateNonce

func GenerateNonce() (string, error)
Generates a cryptographically random 16-byte nonce encoded as a 32-character lowercase hex string. Use this to create the nonce for GenerateWWWAuthenticate and store it for later use in Verify.

​
GenerateWWWAuthenticate

func GenerateWWWAuthenticate(methods []VerifyMethod, realm string, nonce string) base.HeaderValue
Builds the WWW-Authenticate header value to include in a 401 Unauthorized response. One challenge entry is added per method in methods. Pass nil for methods to use the default set.

​
Server-side example

Handling authentication challenges in a server: 
import (
    "github.com/bluenviron/gortsplib/v5/pkg/auth"
    "github.com/bluenviron/gortsplib/v5/pkg/base"
)

const (
    realm    = "my-server"
    username = "admin"
    password = "secret"
)

// Generate a fresh nonce when the server starts (or per-connection)
nonce, err := auth.GenerateNonce()
if err != nil { ... }

// When a request arrives without credentials, reject it with a challenge
func handleRequest(req *base.Request) *base.Response {
    err := auth.Verify(req, username, password, nil, realm, nonce)
    if err != nil {
        // Authentication failed or no credentials provided — send a challenge
        return &base.Response{
            StatusCode: base.StatusUnauthorized,
            Header: base.Header{
                "WWW-Authenticate": auth.GenerateWWWAuthenticate(nil, realm, nonce),
            },
        }
    }

    // Credentials are valid — proceed normally
    return &base.Response{
        StatusCode: base.StatusOK,
    }
}

​
Client-side example

Responding to a 401 Unauthorized challenge: 
import (
    "github.com/bluenviron/gortsplib/v5/pkg/auth"
    "github.com/bluenviron/gortsplib/v5/pkg/base"
)

// After receiving a 401 response:
sender := &auth.Sender{
    WWWAuth: res.Header["WWW-Authenticate"],
    User:    "admin",
    Pass:    "secret",
}
if err := sender.Initialize(); err != nil { ... }

// Retry the request with credentials attached
sender.AddAuthorization(req)
// send req again
The higher-level ServerConn type exposes a VerifyCredentials convenience method that wraps Verify and nonce management. Use pkg/auth directly only when you need fine-grained control over the authentication flow.

Build docs developers (and LLMs) love

Get started for freeTalk to us