# SIP Authenticated Identity Module

## Admin Guide

### Overview

Auth Identity module provides functionalities for securely identifying originators of SIP messages. It implements the SIP Identity standard where a SIP proxy signs messages that is sent to other domains. This module has two basic services:

- authorizer - authorizes a message and adds Identity and Identity-Info headers

- verifier - verifies an authorized message

Known limitations in this version:

- authorizer and verifier support all SIP requests except for CANCEL and REGISTER

- verifier does not support the subjectAltName extension of certificates

### Dependencies

This module does not depend any other module.

### Compilation

This module needs the following headers and libraries:

- OpenSSL (version 0.9.8 or higher) for cryptographic functions

- libcurl for HTTP, HTTPS functions

If you'd like to use TLS module too then use the corresponding LIB line in auth_identity's Makefile

### Installation And Running

the Authorizer service needs to make the public key, which conveyed in a certificate, available over HTTPS or HTTP for verifiers. The domain the authorizer is responsible for and the domain part of the URL of the certificate must be the same. This service needs access to the private key too.

### Authorizer service examples

    ...
    route[INIT]
    {
    	# we process new transactions only
    	if (!t_newtran()) {
    		sl_reply("500", "Internal error newtran");
    		drop;
    	}
    ...
    route[OUTBOUND]
    {
    	# If we are responsible for the domain of the sender of this message
    	if ($f.did && !$t.did) {
    		# Authentication service
    		if (method=="INVITE" || method=="BYE"
    			|| method=="OPTION" || method=="ACK") {
    			# Identity and Identity-info headers must not exist
    			if (@identity) {
    				t_reply("403", "Invalid Identity header");
    				drop;
    			}
    			if (@identity_info) {
    				t_reply("403", "Invalid Identity-info header");
    				drop;
    			}

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

    			if (!auth_add_identity()) {
    				t_reply("480", "Authentication error");
    				drop;
    			}
    		}
    		route(FORWARD);
    	}
    }
    ...

### Verifier service examples

    ...
    route[INIT]
    {
    	# we process new transactions only
    	if (!t_newtran()) {
    		sl_reply("500", "Internal error newtran");
    		drop;
    	}
    ...
    route[VERIFY]
    {
    	# if we've already processed this message then we drop it
    	if (!t_newtran()) {
    		sl_reply("500", "Internal error newtran");
    		drop;
    	}

    	if (method=="INVITE" || method=="BYE"
    		|| method=="OPTION" || method=="ACK") {
    		# Identity and Identity-info are required for verification
    		if (!@identity) {
    			t_reply("428", "Use Identity Header");
    			drop;
    		}
    		if (!@identity_info) {
    			t_reply("436", "Bad Identity-Info");
    			drop;
    		}

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

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

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

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

    		if (!vrfy_check_callid()) {
    			t_reply("403", "Message is replayed");
    			drop;
    		}
    	}
    }
    ...

### Remarks

Note: libcurl leak in CentOS 6 - this module uses libcurl library and in case if you are using CentOS 6, be aware that standard libcurl-7.19.7-52 has a memory leak. To fix this memory, install libcurl from city-fan repository. More details at: https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in-centos6