From ec6b0a110c9e71897c0cbf8a5a62ea37e9c7733a Mon Sep 17 00:00:00 2001 From: Daniel-Constantin Mierla Date: Tue, 24 May 2022 12:19:38 +0200 Subject: [PATCH] auth_identity: removed auth_identity.xml from source folder - there is one in doc/ subfolder (cherry picked from commit 9155a53bccd090e51b274802d140f363aca6d4b7) --- src/modules/auth_identity/auth_identity.xml | 629 -------------------- 1 file changed, 629 deletions(-) delete mode 100644 src/modules/auth_identity/auth_identity.xml diff --git a/src/modules/auth_identity/auth_identity.xml b/src/modules/auth_identity/auth_identity.xml deleted file mode 100644 index 9c149c08920..00000000000 --- a/src/modules/auth_identity/auth_identity.xml +++ /dev/null @@ -1,629 +0,0 @@ - - - - - - - auth_identity - 7 - - - 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 - - - - <function>auth_add_identity</function> - () - - - Allowed in request processing only. - - - The auth_add_identity() 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 - privatekey_path - 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 - certificate_url - 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. - - - - - - <function>auth_date_proc</function> - () - - - Allowed in request processing only. - - - The auth_date_proc() 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 - msg_timeout - parameter, the function returns false. It also - returns false if the certificate used by the - authorizer has expired. - - - - - - <function>vrfy_check_callid</function> - () - - - Allowed in request processing only. - - - The vrfy_check_callid() checks whether a - request for this call has been processed within the - time given by the - auth_validity_time - 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 false if the value is found and thus - the request is replayed or true otherwise. - - - - - - <function>vrfy_check_certificate</function> - () - - - Allowed in request processing only. - - - The vrfy_check_certificate() function - checks the downloaded certificate and returns true - if it is valid or false 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 vrfy_check_certificate() can be called, - the function vrfy_check_date() must have been - called and returned true. - - - - - - <function>vrfy_check_date</function> - () - - - Allowed in request processing only. - - - The vrfy_check_date() function checks - the date of the request currently being processed. It returns - false 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 - auth_validity_time - parameter. - - - - - - <function>vrfy_check_msgvalidity</function> - () - - - Allowed in request processing only. - - - The vrfy_check_msgvalidity() 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 - vrfy_get_certificate() function. - - - The function returns true if the two hashes - match. - - - - - - <function>vrfy_get_certificate</function> - () - - - Allowed in request processing only. - - - The vrfy_get_certificate() tries to get - the certificate from the URL given in the Identity-Info header - field of the currently processed request. - - - It returns true if the certifcate was - successfully loaded in a format that the module can process or - false otherwise. - - - - - - - - Module Parameters - - - <parameter>accept_pem_certs</parameter> - - boolean - no - - - The accept_pem_certs parameter defines, - whether the verifier should process certificates in PEM format. - - - - - <parameter>auth_validity_time</parameter> - - integer - 3600 - - - The auth_validity_time parameter - sets the maximum age of a verified message. - - - - - <parameter>cainfo_path</parameter> - - string - "" - - - The cainfo_path 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. - - - - - <parameter>callid_cache_limit</parameter> - - integer - 262144 - - - The callid_cache_limit 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. - - - - - <parameter>certificate_cache_limit</parameter> - - integer - 32768 - - - The certificate_cache_limit 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. - - - - - <parameter>certificate_path</parameter> - - string - "" - - - The certificate_path 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. - - - - - <parameter>certificate_url</parameter> - - string - "" - - - The certificate_url 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. - - - - - <parameter>msg_timeout</parameter> - - int - 600 - - - The msg_timeout 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. - - - - - <parameter>privatekey_path</parameter> - - string - "" - - - The privatekey_path 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 - ser-oob.cfg configuration, this is the - route[OUTBOUND]. With an authentifier included, - it looks like this: - - - - 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. - - - - - - 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 - tls. - - - Once you have the certificate and private key, you set the module - parameter - certificate_path - to point to the file containing the certificate and - privatekey_path - 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 - - - - 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 - certificate_url. - - - - - - Compilation - - This auth_identity 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 the TLS module, too, - you will have to change LIB variable in the - Makefile to the value that is by default commented out. - - - - - 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 - - ser - ser.cfg - - - - - -