auth_identity(7)

NAME
auth_identity - Securely identify originator of SIP messages.

DESCRIPTION
The auth_identity SER module provides functionalities for securely identifying originators of SIP messages by implementing the mechanism described in RFC 4474 and known as SIP Identity framework.

The module provides two services: The authorizer authorizes a message and adds Identity and Identity-Info headers to forwarded requests. The verifier verifies the identity of a received message.

In order to use the auth_identity module you have to provide a certificate. More information can be found in the section Certificates below.

FUNCTIONS

  auth_add_identity ()
Allowed in request processing only.

The \FCauth_add_identity()\F[] function authorizes a request by adding identity information to it.

It calculates a SHA1 hash over certain components of the message and encrypts it using the private key given through the \FCprivatekey_path\F[] parameter. The resulting cyphertext is appended to the message as the content of the Identity header field.

To allow the receiver to decypher the identity information, it adds the URL where the receiver may find the certificate in the Indentity-Info header field. This URL is set through the \FCcertificate_url\F[] parameter.

Note: After the function has been called, the following header fields must not be modified: From, To, Call-ID, CSeq, Date, Contact. Additionally, the message body must remain unmodified, too.

  auth_date_proc ()
Allowed in request processing only.

The \FCauth_date_proc()\F[] checks the age of a request to be authroized. If the time given in the Date header field of the request differs by more than the amount of seconds given by the \FCmsg_timeout\F[] parameter, the function returns \FCfalse\F[]. It also returns \FCfalse\F[] if the certificate used by the authorizer has expired.

  vrfy_check_callid ()
Allowed in request processing only.

The \FCvrfy_check_callid()\F[] checks whether a request for this call has been processed within the time given by the \FCauth_validity_time\F[] parameter.

The function generates a call identifier from the Call-ID and CSqe header fields and the Tag parameter of the From header field and compares it with the values stored in the Call-ID cache.

It returns \FCfalse\F[] if the value is found and thus the request is replayed or \FCtrue\F[] otherwise.

  vrfy_check_certificate ()
Allowed in request processing only.

The \FCvrfy_check_certificate()\F[] function checks the downloaded certificate and returns \FCtrue\F[] if it is valid or \FCfalse\F[] otherwise.

A certificate is considered valid if it has not yet expired and if its subject is identical to the domain part of the URL.

Before \FCvrfy_check_certificate()\F[] can be called, the function \FCvrfy_check_date()\F[] must have been called and returned \FCtrue\F[].

  vrfy_check_date ()
Allowed in request processing only.

The \FCvrfy_check_date()\F[] function checks the date of the request currently being processed. It returns \FCfalse\F[] if the time in the Date header field of the request differs from the current system time by more than the number of seconds given by the \FCauth_validity_time\F[] parameter.

  vrfy_check_msgvalidity ()
Allowed in request processing only.

The \FCvrfy_check_msgvalidity()\F[] function checks the integrity of the request currently being processed.

It does so by calculating a SHA1 hash over certain parts of the message and comparing it with the hash value that results from decrypting the content of the Identity header field using the certificate previously retrieved using the \FCvrfy_get_certificate()\F[] function.

The function returns \FCtrue\F[] if the two hashes match.

  vrfy_get_certificate ()
Allowed in request processing only.

The \FCvrfy_get_certificate()\F[] tries to get the certificate from the URL given in the Identity-Info header field of the currently processed request.

It returns \FCtrue\F[] if the certifcate was successfully loaded in a format that the module can process or \FCfalse\F[] otherwise.

MODULE PARAMETERS

  accept_pem_certs
Type: boolean
Default: no

The \FCaccept_pem_certs\F[] parameter defines, whether the verifier should process certificates in PEM format.

  auth_validity_time
Type: integer
Default: 3600

The \FCauth_validity_time\F[] parameter sets the maximum age of a verified message.

  cainfo_path
Type: string
Default: ""

The \FCcainfo_path\F[] paramter contains the path and name of a file that contains trusted certificates.

The file should contain one or more certificates in PEM format concatenated together. It is necessary if the verifier should accept self-signed certifcates.

  callid_cache_limit
Type: integer
Default: 262144

The \FCcallid_cache_limit\F[] parameter limits the number of entries in the Call-ID cache.

The Call-IDs of previously verified messages are stored in the Call-ID cache for some time in order to recognize call replay attacks. The cache uses shared memory. Each entry is about 100 bytes in size.

  certificate_cache_limit
Type: integer
Default: 32768

The \FCcertificate_cache_limit\F[] parameter limits the number of entries stored in the certificate cache.

Each retrieved certificate is placed in the certificate cache to speed up processing should it be needed again.

The cahce uses shared memory. Each entry is approximately 600 bytes in size.

  certificate_path
Type: string
Default: ""

The \FCcertificate_path\F[] parameter must be set to path and name of the file that contains the certificate of the authentication service in PEM format.

The parameter is required for the authentication service to work.

  certificate_url
Type: string
Default: ""

The \FCcertificate_url\F[] parameter must be set to the URL where a verifier can retrieve the certificate. The URL will be stored in the Identity-Info header of any authorized request.

The certificate must be available at the given URL in DER format.

The parameter is required for the authentication service to work.

  msg_timeout
Type: int
Default: 600

The \FCmsg_timeout\F[] parameter contains the maximum age of a request to be authorized in seconds.

The authorizer will compare the time given in the Date header field of the request with its own current time.

  privatekey_path
Type: string
Default: ""

The \FCprivatekey_path\F[] must be set to the paht and name of the file that contains the private key of the authentication service in PEM format.

The parameter is required for the authentication service to work.

EXAMPLES
The authentifier is typically included in the part of the routing logic that sends a request to a foreign domain. In the \FCser-oob.cfg\F[] configuration, this is the \FCroute[OUTBOUND]\F[]. With an authentifier included, it looks like this:

\FC
route[OUTBOUND]
{
	if ($f.did && !$t.did) {
		# Authentication service
		if (method=="INVITE" || method=="OPTION") {
			# Identity and Identity-info headers must not exist
			if (@identity) {
				sl_reply("403", "Invalid Identity header");
				drop;
			}
			if (@identity_info) {
				sl_reply("403", "Invalid Identity-info header");
				drop;
			}

			if (!auth_date_proc()) {
				sl_reply("403", "Invalid Date value");
				drop;
			}

			if (!auth_add_identity()) {
				sl_reply("480", "Authentication error");
				drop;
			}
		}
		route(FORWARD);
	}
}
\F[].fi

The verifier should be run after you discovered
that a request originates from a foreign domain (for your own domains,
you should be doing digest authentication instead).

While you should reject any request that does contain an Identity
header but does not verify, it is up to your local policy, what to
do with messages that do not contain an Identity header at all.
You could reject them or divert them to voice mail or any of a number
of other options.

The following config snippet rejects any message that does not have
an Identity header.

\FC
	if (method=="INVITE" || method=="OPTIONS") {
		if (!@identity) {
			sl_reply("428", "Use Identity Header");
			drop;
		}
		if (!@identity_info) {
			sl_reply("436", "Bad Identity-Info");
			drop;
		}

		if (!vrfy_check_date()) {
			sl_reply("403", "Outdated Date header value");
			drop;
		}

		if (!vrfy_get_certificate()) {
			sl_reply("436", "Bad Identity-Info");
			drop;
		}

		if (!vrfy_check_certificate()) {
			sl_reply("437", "Unsupported Certificate");
			drop;
		}

		if (!vrfy_check_msgvalidity()) {
			sl_reply("438", "Invalid Identity Header");
			drop;
		}

		if (!vrfy_check_callid()) {
			sl_reply("403", "Message is replayed");
			drop;
		}
	}
\F[].fi

THE SIP IDENTITY MECHANISM
The SIP Identity Mechanism is defined in RFC 4474 "Enhancements for Authenticated Identity Management in the Session Initiation Protocol (SIP)". Its main purpose is to affirm the identity of the originator of a request as stated in the From header field of the request. While basic SIP provides a mechanism for a user agent to proof its authenticity to the proxy serving the domain of the address used by the user agent, no such mechanism exists to proof the authenticity to other proxies or end points. The SIP Identity Mechanism mends this oversight.

The mechanism allows a proxy to cryptographically sign a message as authentic before sending it to another proxy. It does so after making sure the sender actually is who he claims and is allowed to use the address in the context of the message.

If the proxy is satisfied, it creates two header fields: Identity and Identity-Info. The Identity header field contains a signed hash over the following components of the message:

•   the address given in the From header field,

•   the address given in the To header field,

•   the Call-ID,

•   the content of the CSeq header field,

•   the content of the Date header field,

•   the address given in the Contact header field if present, and

•   the body of the message.

The hash is signed with a certificate for the domain. A URL pointing to a place where an interested party can download a copy of the certificate is placed into the Identity-Info header field.

If the message arrives at a proxy or user agent that wishes to verify the authenticity, this device downloads the certificate and itself forms the hash over the above components. If both hashes match, the message has been authenticated by the proxy of the domain of the certificate and has not been tempered with on the way.

CERTIFICATES
In order to use the auth_identity module, you need a certificate for your domain. There is two options, how to get one: you buy one from a certification authority or you create your own certification authority and use a self-signed certificate. If you plan to provide real inter-domain calls for your domain, you should pick the first option. Although it is more expensive, it guarantees proper interaction between domains.

Either way, you will end up with a private key and a certificate which includes the public key for that private key. You can use the same key and certificate as for the TLS encrypted SIP transport. Because of this, details on the process of acquiring them can be found in \FCtls\F[](7).

Once you have the certificate and private key, you set the module parameter \FCcertificate_path\F[] to point to the file containing the certificate and \FCprivatekey_path\F[] to point to the file with the private key.

Finally, you have to put a public version of your certificate onto a web server somewhere. This version must be DER encoded and, obviously, must not contain the private key. You can create this by issuing

\FC
# openssl x509 -in your_certificate.crt -outform der -out your_certificate.der
\F[].fi

You then place the DER encoded certificate into a publicly
available directory on your webserver and state the URL to the
file in the parameter
\FCcertificate_url\F[].

KNOWN LIMITATIONS
Both authorizer and verifier currently only support SIP requests except for responses to CANCEL and REGISTER requests.

The verifier does not support the subjectAltName extension of certificates.

AUTHORS
Written by Gergely Kovacs and Martin Hoffmann.

SEE ALSO
\FCser\F[](8), \FCser.cfg\F[](5)