Pelco Developer Network (PDN)

Pelco IP Camera Authentication

As of 1.8.2, Sarix supports the ONVIF standard. The Pelco API implements ONVIF calls for certain features, such as upgrading device firmware. Some ONVIF calls require HTTP or WS-Security authentication, as documented in the ONVIF Core Spec and other docs. This article describes the requirements for the following authentication mechanisms: HTTP Basic, HTTP Digest, WS-Security Basic, and WS-Security Digest.

 

HTTP Basic Authentication

When the API call is sent to the camera without authentication, the camera replies with HTTP status 401 (Authorization Required), along with a WWW-Authenticate header set to Basic realm="Sarix" . Browsers typically respond to a status like this by popping up an authentication window asking for user and password. API tools that support HTTP basic authentication will have a mechanism where one can set user and password. The client will respond to the status 401 with another API call, this time with an Authorization header containing the user and password encoded with the base64 algorithm. For example user admin with password secure is concatenated to admin:secure and then encoded to YWRtaW46c2VjdXJl. The HTTP header will look something like this:

POST http://10.220.228.100:80/onvif/device_service HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/soap+xml;charset=UTF-8;action="http://www.onvif.org/ver10/device/wsdl/GetNetworkInterfaces"
Authorization: YWRtaW46c2VjdXJl

Alternatively, the client can always include the Authorization header, in which case it doesn't have to go through the status 401 step.

HTTP basic authentication is not secure without using TLS (Transport Layer Security, where the API is sent to the HTTPS port rather than the HTTP port). The user and password is sent over the network in the clear. Encoding user and password with base64 is not a secure encoding.

 

HTTP Digest Authentication

HTTP digest authentication is supported by Sarix cameras as of 1.9. If the camera is using local users, it will return a WWW-Authenticate header with Digest realm="Sarix" , along with additional parameters. If the camera is using LDAP-based users, the camera reverts to HTTP basic authentication.

HTTP digest authentication doesn't send the password across the wire, which makes it a much better choice for non-HTTPS authentication. A typical challenge looks like this:

WWW-Authenticate: Digest realm="Sarix" nonce="40348f31eb8ea656bdf1d4704b054064", qop="auth,auth-int"

The nonce (short for number used once) is unique for each challenge. The nonce is remembered by the camera for the next five minutes, after which it expires (i.e., goes stale).

The client constructs the Authorization header for the next request using the nonce. The algorithm is described in detail in RFC 2617. Here is a quick example.

First, the username, realm, and password are concatenated with colons, then passed through md5sum:

HA1 = MD5(admin:Sarix:secure) = efd83201b93b72f10211d7b51b0d4460

The client then chooses one of the advertised qop (quality of protection) methods. auth includes only header information, and auth-int (authentication with integrity) includes both header and body information. Using auth, it calculates a sum based on the HTTP method and URI:

HA2 = MD5(POST:/onvif/device_service) = bb7214af296c80b7b6e7d4b2e47f4ae6

Finally, it calculates a third md5sum using these two values along with a client-chosen nonce value and a nonce count value (in hex) that is higher than any previously sent counts for this particular server nonce, for example:

client nonce = 4215345dc8eb9396
nonce count = 00000001
response = HA1:server nonce:nonce count:client nonce:qop:HA2
 = efd83201b93b72f10211d7b51b0d4460:40348f31eb8ea656bdf1d4704b054064:00000001:4215345dc8eb9396:auth:bb7214af296c80b7b6e7d4b2e47f4ae6
 = 4c7fed898c7e565896c9a4b0b5802c85

The client packages all this up in an Authorization header:

Authorization: Digest username="admin" realm="Sarix" nonce="40348f31eb8ea656bdf1d4704b054064" uri="/onvif/device_service" response="4c7fed898c7e565896c9a4b0b5802c85" qop=auth nc=00000001 cnonce="4215345dc8eb9396"

The camera performs the same calculations to validate the response. It also rejects the request if the nonce has expired or if the nonce count has already been used.

It would be annoying to have to re-enter a username and password every time the nonce expires, so if the response value is valid but the nonce is stale, the WWW-Authenticate response header includes the parameter stale=TRUE. The client can simply calculate with the new nonce without having to prompt again for credentials.

SoapUI doesn't easily support HTTP Digest, but does use WS-Security digest authentication. It is recommended to use HTTP digest or WS-Security digest over HTTP, and only use HTTP basic or WS-Security basic over HTTPS.

 

WS-Security Basic Authentication

Authentication can also be included as part of the API call's SOAP header. A SOAP request with a WS-Security basic authentication element looks something like this:


    <s:Header>
        <w:Security soap:mustUnderstand="true" xmlns:w="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secex...
            <w:UsernameToken u:Id="UsernameToken-35" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utili...
                <w:Username>admin</w:Username>
                    secure
                </wsse:Password>
            </w:UsernameToken>
        </w:Security>
  </s:Header>
  <s:Body>
      <d:GetNetworkInterfaces/>
  </s:Body>
</s:Envelope>

As with HTTP basic authentication, WS-Security basic authentication is not secure without using TLS.

 

WS-Security Digest Authentication

As with WS-Security basic authentication, digest authentication is sent as part of the API call's SOAP header. For digest authentication to work, both the client and the camera must have their clocks synchronized. Part of the digest protocol is to send the time along with the user and password. If the camera disagrees with what the client believes the time to be, it rejects the authentication.

The digest protocol also sends a binary value known as a nonce. This is a pattern that can only be used once. If a subsequent API call is made with an already-used nonce value, the camera rejects the authentication.

A SOAP request with a WS-Security digest authentication element looks something like this:


<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:d="http://www.onvif.org/ver10/device/wsdl">
    <s:Header>
        <w:Security soap:mustUnderstand="true" xmlns:w="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secex...
            <w:UsernameToken u:Id="UsernameToken-42" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utili...
                <w:Username>admin</w:Username>
                <w:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-p...
                    D61ueIkzbC38W2tOcWKS6jtiuiE=
                </w:Password>
                <w:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-sec...
                    X8AE6l7NxqXnKCf3AGBAYg==
                </w:Nonce>
                <u:Created>2012-06-25T16:51:43.796Z</u:Created>
            </w:UsernameToken>
        </w:Security>
    </s:Header>
    <s:Body>
        <d:GetNetworkInterfaces/>
    </s:Body>
</s:Envelope>

WS-Security digest is secure over plain-text (non-TLS) connections, because the password is not sent in the clear. It is combined by the client with the nonce and time values, and then a fingerprint (or digest) is sent to the camera. The camera must know the user's password; it creates the same combination of password, nonce, and time, and generates its own digest. It then compares that digest to the one sent by the client. If they are the same, the user is authenticated.