mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
538 lines
14 KiB
538 lines
14 KiB
SIP Authenticated Identity Module
|
|
|
|
Gergely Kovacs
|
|
|
|
Iptel.org
|
|
|
|
Copyright © 2007 Iptel.org
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
3. Compilation
|
|
4. Installation And Running
|
|
5. Parameters
|
|
|
|
5.1. privatekey_path (string)
|
|
5.2. certificate_path (string)
|
|
5.3. certificate_url (string)
|
|
5.4. msg_timeout (integer)
|
|
5.5. auth_validity_time (integer)
|
|
5.6. callid_cache_limit (integer)
|
|
5.7. certificate_cache_limit (integer)
|
|
5.8. cainfo_path (string)
|
|
5.9. accept_pem_certs ([0|1])
|
|
|
|
6. Functions
|
|
|
|
6.1. auth_date_proc()
|
|
|
|
6.1.1. Dependencies
|
|
|
|
6.2. auth_add_identity()
|
|
|
|
6.2.1. Dependencies
|
|
|
|
6.3. vrfy_check_date()
|
|
|
|
6.3.1. Dependencies
|
|
|
|
6.4. vrfy_get_certificate()
|
|
|
|
6.4.1. Dependencies
|
|
|
|
6.5. vrfy_check_certificate()
|
|
|
|
6.5.1. Dependencies
|
|
|
|
6.6. vrfy_check_msgvalidity()
|
|
|
|
6.6.1. Dependencies
|
|
|
|
6.7. vrfy_check_callid()
|
|
|
|
6.7.1. Dependencies
|
|
|
|
7. Authorizer service examples
|
|
8. Verifier service examples
|
|
|
|
List of Examples
|
|
|
|
1.1. Set privatekey_path parameter
|
|
1.2. Set certificate_path parameter
|
|
1.3. Set certificate_url parameter
|
|
1.4. Set msg_timeout parameter
|
|
1.5. Set auth_validity_time parameter
|
|
1.6. Set auth_validity_time parameter
|
|
1.7. Set certificate_cache_limit parameter
|
|
1.8. Set cainfo_path parameter
|
|
1.9. Set accept_pem_certs parameter
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
3. Compilation
|
|
4. Installation And Running
|
|
5. Parameters
|
|
|
|
5.1. privatekey_path (string)
|
|
5.2. certificate_path (string)
|
|
5.3. certificate_url (string)
|
|
5.4. msg_timeout (integer)
|
|
5.5. auth_validity_time (integer)
|
|
5.6. callid_cache_limit (integer)
|
|
5.7. certificate_cache_limit (integer)
|
|
5.8. cainfo_path (string)
|
|
5.9. accept_pem_certs ([0|1])
|
|
|
|
6. Functions
|
|
|
|
6.1. auth_date_proc()
|
|
|
|
6.1.1. Dependencies
|
|
|
|
6.2. auth_add_identity()
|
|
|
|
6.2.1. Dependencies
|
|
|
|
6.3. vrfy_check_date()
|
|
|
|
6.3.1. Dependencies
|
|
|
|
6.4. vrfy_get_certificate()
|
|
|
|
6.4.1. Dependencies
|
|
|
|
6.5. vrfy_check_certificate()
|
|
|
|
6.5.1. Dependencies
|
|
|
|
6.6. vrfy_check_msgvalidity()
|
|
|
|
6.6.1. Dependencies
|
|
|
|
6.7. vrfy_check_callid()
|
|
|
|
6.7.1. Dependencies
|
|
|
|
7. Authorizer service examples
|
|
8. Verifier service examples
|
|
|
|
1. 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
|
|
|
|
2. Dependencies
|
|
|
|
This module does not depend any other module.
|
|
|
|
3. 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
|
|
|
|
4. 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.
|
|
|
|
5. Parameters
|
|
|
|
5.1. privatekey_path (string)
|
|
5.2. certificate_path (string)
|
|
5.3. certificate_url (string)
|
|
5.4. msg_timeout (integer)
|
|
5.5. auth_validity_time (integer)
|
|
5.6. callid_cache_limit (integer)
|
|
5.7. certificate_cache_limit (integer)
|
|
5.8. cainfo_path (string)
|
|
5.9. accept_pem_certs ([0|1])
|
|
|
|
5.1. privatekey_path (string)
|
|
|
|
Note: this parameter is for authorizer service.
|
|
|
|
The path of private key of the authentication service. The key must be
|
|
in PEM format.
|
|
|
|
This parameter is required by authentication service.
|
|
|
|
Example 1.1. Set privatekey_path parameter
|
|
...
|
|
modparam("auth_identity","privatekey_path","/etc/ssl/private/key.pem")
|
|
...
|
|
|
|
5.2. certificate_path (string)
|
|
|
|
Note: this parameter is for authorizer service.
|
|
|
|
The path of certificate of the authentication service. The certificate
|
|
must be in PEM format.
|
|
|
|
This parameter is required by authentication service.
|
|
|
|
Example 1.2. Set certificate_path parameter
|
|
...
|
|
modparam("auth_identity","certificate_path","/var/www/ssl/mycert.pem")
|
|
...
|
|
|
|
5.3. certificate_url (string)
|
|
|
|
Note: this parameter is for authorizer service.
|
|
|
|
The url where certificate is available for other verifier services.
|
|
(value of Identity-info header) The certificate should be in DER
|
|
format.
|
|
|
|
This parameter is required by authentication service.
|
|
|
|
Example 1.3. Set certificate_url parameter
|
|
...
|
|
modparam("auth_identity","certificate_url","https://foo.bar/mycert.der")
|
|
...
|
|
|
|
5.4. msg_timeout (integer)
|
|
|
|
Note: this parameter is for authorizer service.
|
|
|
|
If the Date header of message which is needed to be authenticated
|
|
contains a time different by more than this seconds from the current
|
|
time noted by the authentication service then it rejects the message.
|
|
|
|
This parameter is optional. The default value is "600".
|
|
|
|
Example 1.4. Set msg_timeout parameter
|
|
...
|
|
modparam("auth_identity","msg_timeout",600)
|
|
...
|
|
|
|
5.5. auth_validity_time (integer)
|
|
|
|
Note: this parameter is for verifier service.
|
|
|
|
The validity time of an authenticated message. The message will be
|
|
refused if it contains a time different by more than this seconds from
|
|
the current time noted by the verification service.
|
|
|
|
This parameter is optional. The default value is "3600".
|
|
|
|
Example 1.5. Set auth_validity_time parameter
|
|
...
|
|
modparam("auth_identity","auth_validity_time",3600)
|
|
...
|
|
|
|
5.6. callid_cache_limit (integer)
|
|
|
|
Note: this parameter is for verifier service.
|
|
|
|
The number of Call-IDs stored in order to recognize call replay
|
|
attacks. A Call-ID is stored auth_validity_time long and uses
|
|
approximately 100 bytes memory.
|
|
|
|
This parameter is optional. The default value is "32768". (you should
|
|
increase the size of shared memory with -m command line switch if you
|
|
liked to store more callid than 10000)
|
|
|
|
Example 1.6. Set auth_validity_time parameter
|
|
...
|
|
modparam("auth_identity","callid_cache_limit",32768)
|
|
...
|
|
|
|
5.7. certificate_cache_limit (integer)
|
|
|
|
Note: this parameter is for verifier service.
|
|
|
|
The number of certificates stored in order to avoid needless download.
|
|
A certificate is stored until its expiration date and uses
|
|
approximately 600 bytes memory.
|
|
|
|
This parameter is optional. The default value is "4096".
|
|
|
|
Example 1.7. Set certificate_cache_limit parameter
|
|
...
|
|
modparam("auth_identity","certificate_cache_limit",4096)
|
|
...
|
|
|
|
5.8. cainfo_path (string)
|
|
|
|
Note: this parameter is for verifier service.
|
|
|
|
A file of trusted certificates. The file should contain multiple
|
|
certificates in PEM format concatenated together. It could be useful
|
|
for verifying a certificate signed by a private CA.
|
|
|
|
This parameter is optional. It has not got default value.
|
|
|
|
Example 1.8. Set cainfo_path parameter
|
|
...
|
|
modparam("auth_identity","cainfo_path","/etc/ssl/certs/ca-certificates.crt")
|
|
...
|
|
|
|
5.9. accept_pem_certs ([0|1])
|
|
|
|
Note: this parameter is for verifier service.
|
|
|
|
Enables the acquired certificate processing if it is in PEM format.
|
|
|
|
This parameter is optional. The default value is "0".
|
|
|
|
Example 1.9. Set accept_pem_certs parameter
|
|
...
|
|
modparam("auth_identity","accept_pem_certs",1)
|
|
...
|
|
|
|
6. Functions
|
|
|
|
6.1. auth_date_proc()
|
|
|
|
6.1.1. Dependencies
|
|
|
|
6.2. auth_add_identity()
|
|
|
|
6.2.1. Dependencies
|
|
|
|
6.3. vrfy_check_date()
|
|
|
|
6.3.1. Dependencies
|
|
|
|
6.4. vrfy_get_certificate()
|
|
|
|
6.4.1. Dependencies
|
|
|
|
6.5. vrfy_check_certificate()
|
|
|
|
6.5.1. Dependencies
|
|
|
|
6.6. vrfy_check_msgvalidity()
|
|
|
|
6.6.1. Dependencies
|
|
|
|
6.7. vrfy_check_callid()
|
|
|
|
6.7.1. Dependencies
|
|
|
|
6.1. auth_date_proc()
|
|
|
|
Note: this function is for authorizer service.
|
|
|
|
If a message, the auth service should authorize, contains Date header
|
|
then this function checks whether it falls in message timeout (set by
|
|
msg_timeout parameter). If there is not any Date header then the module
|
|
adds one. This function also checks whether the certificate of the
|
|
authentication service (set by certificate_path parameter) has been
|
|
expired.
|
|
|
|
6.1.1. Dependencies
|
|
|
|
No dependencies
|
|
|
|
6.2. auth_add_identity()
|
|
|
|
Note: this function is for authorizer service.
|
|
|
|
Assembles digest-string from the message, calculates its SHA1 hash,
|
|
encrypts it with the private key (set by privatekey_path parameter) of
|
|
the authorizer service, base64 encodes it and adds to the outgoing
|
|
message as the value of Identity header. This function also adds
|
|
Identity-Info header which contains an URI (set by certificate_url
|
|
parameter) from which the certificate of auth service can be acquired.
|
|
|
|
Note: this function needs the final outgoing message for authorization,
|
|
so no module may modify any digest string related headers (From, To,
|
|
Call-ID, CSeq, Date, Contact) and body after auth_add_identity()'s been
|
|
called
|
|
|
|
6.2.1. Dependencies
|
|
|
|
auth_date_proc() must be called before
|
|
|
|
6.3. vrfy_check_date()
|
|
|
|
Note: this function is for verifier service.
|
|
|
|
Checks Date header of the incoming message whether falls in validity
|
|
time (set by auth_validity_time parameter)
|
|
|
|
6.3.1. Dependencies
|
|
|
|
No dependencies
|
|
|
|
6.4. vrfy_get_certificate()
|
|
|
|
Note: this function is for verifier service.
|
|
|
|
Tries to get certificate defined by the value of Identity-info header
|
|
from certificate table (which size is set by certificate_cache_limit
|
|
parameter). If the required certificate is not found there then this
|
|
function downloads it.
|
|
|
|
6.4.1. Dependencies
|
|
|
|
No dependencies
|
|
|
|
6.5. vrfy_check_certificate()
|
|
|
|
Note: this function is for verifier service.
|
|
|
|
Checks whether the downloaded certificate is valid (is not expired, its
|
|
subject and the domain part of the URL are the same) and adds it to
|
|
certificate table.
|
|
|
|
6.5.1. Dependencies
|
|
|
|
vrfy_get_certificate() must be called before
|
|
|
|
6.6. vrfy_check_msgvalidity()
|
|
|
|
Note: this function is for verifier service.
|
|
|
|
Assembles digest-string from the message, create SHA1 hash and compares
|
|
it with the decrypted value of Identity header.
|
|
|
|
6.6.1. Dependencies
|
|
|
|
vrfy_get_certificate() must be called before and
|
|
vrfy_check_certificate() should be called before
|
|
|
|
6.7. vrfy_check_callid()
|
|
|
|
Note: this function is for verifier service.
|
|
|
|
Checks whether the current call's been already processed in validity
|
|
time (set by auth_validity_time) to recognize call replay attacks. If
|
|
this call (identified by Call-id, Cseq, and tag of From header triple)
|
|
has not been replayed then adds it to callid table (which size is set
|
|
by callid_cache_limit parameter).
|
|
|
|
6.7.1. Dependencies
|
|
|
|
This function should be called for the last time.
|
|
|
|
7. 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);
|
|
}
|
|
}
|
|
...
|
|
|
|
8. 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;
|
|
}
|
|
}
|
|
}
|
|
...
|