These changes add the ability to run 'make asterisk.txt' just like the existing 'make asterisk.pdf' commands to generate a text document from the TeX files we have in the doc/tex/ directory. I've also updated a few of the .tex files because they weren't properly escaping certain characters so they would show up as Unicode characters (like [U+021C]). Made changes to the configure scripts so it would detect the catdvi program which is required to convert the .dvi file generated by latex. I've also added a few lines to the build_tools/prep_tarball script so that the text documentation gets generated and added to future tarballs of Asterisk releases. (closes issue #17220) Reported by: lmadsen Patches: asterisk.txt.patch uploaded by lmadsen (license 10) asterisk.txt.patch-v4 uploaded by pabelanger (license 224) Tested by: lmadsen, pabelanger git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@258351 65c4cc65-6c06-0410-ace0-fbb531ad65f3
251 lines
8.6 KiB
TeX
251 lines
8.6 KiB
TeX
\section{Introduction}
|
|
|
|
Attacks on Voice over IP networks are becoming increasingly more common. It
|
|
has become clear that we must do something within Asterisk to help mitigate
|
|
these attacks.
|
|
|
|
Through a number of discussions with groups of developers in the Asterisk
|
|
community, the general consensus is that the best thing that we can do within
|
|
Asterisk is to build a framework which recognizes and reports events that could
|
|
potentially have security implications. Each channel driver has a different
|
|
concept of what is an "event", and then each administrator has different
|
|
thresholds of what is a "bad" event and what is a restorative event. The
|
|
process of acting upon this information is left to an external program to
|
|
correlate and then take action - block traffic, modify dialing rules, etc. It
|
|
was decided that embedding actions inside of Asterisk was inappropriate, as the
|
|
complexity of construction of such rule sets is difficult and there was no
|
|
agreement on where rules should be enabled or how they should be processed. The
|
|
addition of a major section of code to handle rule expiration and severity
|
|
interpretation was significant. As a final determining factor, there are
|
|
external programs and services which already parse log files and act in concert
|
|
with packet filters or external devices to protect or alter network security
|
|
models for IP connected hosts.
|
|
|
|
\section{Framework Overview}
|
|
|
|
This section discusses the architecture of the Asterisk modifications being
|
|
proposed.
|
|
|
|
There are two main components that we propose for the initial
|
|
implementation of the security framework:
|
|
|
|
\begin{itemize}
|
|
\item Security Event Generation
|
|
\item Security Event Logger
|
|
\end{itemize}
|
|
|
|
\subsection{Security Event Generation}
|
|
|
|
The ast\_event API is used for the generation of security events. That
|
|
way, the events are in an easily interpretable format within Asterisk to
|
|
make it easy to write modules that do things with them. There are also some
|
|
helper data structures and functions to aid Asterisk modules in reporting these
|
|
security events with the proper contents.
|
|
|
|
The next section of this document contains the current list of security events
|
|
being proposed. Each security event type has some required pieces of
|
|
information and some other optional pieces of information.
|
|
|
|
Subscribing to security events from within Asterisk can be done by
|
|
subscribing to events of type AST\_EVENT\_SECURITY. These events have an
|
|
information element, AST\_EVENT\_IE\_SECURITY\_EVENT, which identifies the security
|
|
event sub-type (from the list described in the next section). The result of the
|
|
information elements in the events contain the required and optional meta data
|
|
associated with the event sub-type.
|
|
|
|
\subsection{Security Event Logger}
|
|
|
|
In addition to the infrastructure for generating the events, one module that
|
|
is a consumer of these events has been implemented.
|
|
|
|
Asterisk trunk was recently updated to include support for dynamic logger
|
|
levels. This module takes advantage of this functionality to create a
|
|
custom "security" logger level. Then, when this module is in use, logger.conf
|
|
can be configured to put security events into a file:
|
|
|
|
\begin{verbatim}
|
|
security_log => security
|
|
\end{verbatim}
|
|
|
|
The content of this file is a well defined and easily interpretable
|
|
format for external scripts to read and act upon. The definition for the format
|
|
of the log file is described later in this chapter.
|
|
|
|
\section{Events to Log}
|
|
|
|
\begin{verbatim}
|
|
(-) required
|
|
(+) optional
|
|
|
|
Invalid Account ID
|
|
(-) Local address family/IP address/port/transport
|
|
(-) Remote address family/IP address/port/transport
|
|
(-) Service (SIP, AMI, IAX2, ...)
|
|
(-) System Name
|
|
(+) Module
|
|
(+) Account ID (username, etc)
|
|
(+) Session ID (CallID, etc)
|
|
(+) Session timestamp (required if Session ID present)
|
|
(-) Event timestamp (sub-second precision)
|
|
|
|
Failed ACL match
|
|
-> everything from invalid account ID
|
|
(+) Name of ACL (when we have named ACLs)
|
|
|
|
Invalid Challenge/Response
|
|
-> everything from invalid account ID
|
|
(-) Challenge
|
|
(-) Response
|
|
(-) Expected Response
|
|
|
|
Invalid Password
|
|
-> everything from invalid account ID
|
|
|
|
Successful Authentication
|
|
-> informational event
|
|
-> everything from invalid account ID
|
|
|
|
Invalid formatting of Request
|
|
-> everything from invalid account ID
|
|
-> account ID optional
|
|
(-) Request Type
|
|
(+) Request parameters
|
|
|
|
Session Limit Reached (such as a call limit)
|
|
-> everything from invalid account ID
|
|
|
|
Memory Limit Reached
|
|
-> everything from invalid account ID
|
|
|
|
Maximum Load Average Reached
|
|
-> everything from invalid account ID
|
|
|
|
Request Not Allowed
|
|
-> everything from invalid account ID
|
|
(-) Request Type
|
|
(+) Request parameters
|
|
|
|
Request Not Supported
|
|
-> everything from invalid account ID
|
|
(-) Request Type
|
|
|
|
Authentication Method Not Allowed
|
|
-> everything from invalid account ID
|
|
(-) Authentication Method attempted
|
|
|
|
In dialog message from unexpected host
|
|
-> everything from invalid account ID
|
|
(-) expected host
|
|
\end{verbatim}
|
|
|
|
\section{Security Log File Format}
|
|
|
|
The beginning of each line in the log file is the same as it is for other
|
|
logger levels within Asterisk.
|
|
|
|
\begin{verbatim}
|
|
[Feb 11 07:57:03] SECURITY[23736] res_security_log.c: <...>
|
|
\end{verbatim}
|
|
|
|
The part of the log entry identified by $<$...$>$ is where the security event
|
|
content resides. The security event content is a comma separated list
|
|
of key value pairs. The key is the information element type, and the value is a
|
|
quoted string that contains the associated meta data for that information
|
|
element. Any embedded quotes within the content are escaped with a
|
|
backslash.
|
|
|
|
\begin{verbatim}
|
|
INFORMATION_ELEMENT_1="IE1 content",INFORMATION_ELEMENT_2="IE2 content"
|
|
\end{verbatim}
|
|
|
|
The following table includes potential information elements and what the
|
|
associated content looks like:
|
|
|
|
\begin{verbatim}
|
|
IE: SecurityEvent
|
|
Content: This is the security event sub-type.
|
|
Values: FailedACL, InvalidAccountID, SessionLimit, MemoryLimit, LoadAverageLimit,
|
|
RequestNotSupported, RequestNotAllowed, AuthMethodNotAllowed,
|
|
ReqBadFormat, UnexpectedAddress, ChallengeResponseFailed,
|
|
InvalidPassword
|
|
|
|
IE: EventVersion
|
|
Content: This is a numeric value that indicates when updates are made to the
|
|
content of the event.
|
|
Values: Monotonically increasing integer, starting at 1
|
|
|
|
IE: Service
|
|
Content: This is the Asterisk service that generated the event.
|
|
Values: TEST, SIP, AMI
|
|
|
|
IE: Module
|
|
Content: This is the Asterisk module that generated the event.
|
|
Values: chan_sip
|
|
|
|
IE: AccountID
|
|
Content: This is a string used to identify the account associated with the
|
|
event. In most cases, this would be a username.
|
|
|
|
IE: SessionID
|
|
Content: This is a string used to identify the session associated with the
|
|
event. The format of the session identifier is specific to the
|
|
service. In the case of SIP, this would be the Call-ID.
|
|
|
|
IE: SessionTV
|
|
Content: The time that the session associated with the SessionID started.
|
|
Values: <seconds>-<microseconds> since epoch
|
|
|
|
IE: ACLName
|
|
Content: This is a string that identifies which named ACL is associated with
|
|
this event.
|
|
|
|
IE: LocalAddress
|
|
Content: This is the local address that was contacted for the related event.
|
|
Values: <Address Family>/<Transport>/<Address>/<Port>
|
|
Examples:
|
|
-> IPV4/UDP/192.168.1.1/5060
|
|
-> IPV4/TCP/192.168.1.1/5038
|
|
|
|
IE: RemoteAddress
|
|
Content: This is the remote address associated with the event.
|
|
Examples:
|
|
-> IPV4/UDP/192.168.1.2/5060
|
|
-> IPV4/TCP/192.168.1.2/5038
|
|
|
|
IE: ExpectedAddress
|
|
Content: This is the address that was expected to be the remote address.
|
|
Examples:
|
|
-> IPV4/UDP/192.168.1.2/5060
|
|
-> IPV4/TCP/192.168.1.2/5038
|
|
|
|
IE: EventTV
|
|
Content: This is the timestamp of when the event occurred.
|
|
Values: <seconds>-<microseconds> since epoch
|
|
|
|
IE: RequestType
|
|
Content: This is a service specific string that represents the invalid request
|
|
|
|
IE: RequestParams
|
|
Content: This is a service specific string that represents relevant parameters
|
|
given with a request that was considered invalid.
|
|
|
|
IE: AuthMethod
|
|
Content: This is a service specific string that represents an authentication
|
|
method that was used or requested.
|
|
|
|
IE: Challenge
|
|
Content: This is a service specific string that represents the challenge
|
|
provided to a user attempting challenge/response authentication.
|
|
|
|
IE: Response
|
|
Content: This is a service specific string that represents the response
|
|
received from a user attempting challenge/response authentication.
|
|
|
|
IE: ExpectedResponse
|
|
Content: This is a service specific string that represents the response
|
|
that was expected to be received from a user attempting
|
|
challenge/response authentication.
|
|
|
|
\end{verbatim}
|
|
|