Review Board 1.7.16

Create best practices documentation

Review Request #507 - Created Feb. 16, 2010 and submitted

Leif Madsen
16808, 16810
oej, russell
This is a best practices document, which was spurned from the discussion on the asterisk-dev and asterisk-users list. It discusses how to utilize FILTER() in the dialplan to only accept characters that you expect to accept. There are also additional sections in the document that discusses proper device names, secure passwords, and reducing typing errors in dialplans.

It should be noted this document is not just about security issues, but rather is a document framework for all best practices information that may be deemed appropriate from the community, for the community.
Reviewed the document a few times, hoping to correct any grammatical errors, etc...
Review request changed
Updated (Feb. 16, 2010, 2:14 p.m.)
Set asterisk-dev as a review group, not user, to get this to show up on the -dev list.
Posted (Feb. 16, 2010, 7:05 p.m.)
I think we should also mention IAX2 and XMPP/Jabber somewhere in the document, just to make it clear that it's not only SIP we're talking about.
  1. Added this above the first example:
    [NOTE: We use SIP in this example, but is not limited to SIP only; protocols
           such as Jabber/XMPP or IAX2 are also susceptible to the same sort of
           injection problem.]
/README-SERIOUSLY.bestpractices.txt (Diff revision 1)
Both examples just ignore errors. I think we should also handle errors - show how to go about if the EXTEN and SAFE_EXTEN is not the same - and play "invalid" or something.
  1. OK, I've added this suggestion because it's a good one! :)  Here is the modified section of text with a new example of how to handle checking that ${EXTEN} and ${SAFE_EXTEN} match:
    exten => _X.,1,Verbose(2,Incoming call to extension ${EXTEN})
    exten => _X.,n,Dial(SIP/${FILTER(0-9,${EXTEN})})
    exten => _X.,n,Hangup()
    Note how we've wrapped the ${EXTEN} channel variable with the FILTER() function
    which will then only pass back characters that fit into the numerical range that
    we've defined.
    Alternatively, if we didn't want to utilize the FILTER() function within the
    Dial() application directly, we could save the value to a channel variable,
    which has a side effect of being usable in other locations of your dialplan if
    necessary, and to handle error checking in a separate location.
    exten => _X.,1,Verbose(2,Incoming call to extension ${EXTEN})
    exten => _X.,n,Set(SAFE_EXTEN=${FILTER(0-9,${EXTEN})})
    exten => _X.,n,Dial(SIP/${SAFE_EXTEN})
    exten => _X.,n,Hangup()
    Now we can use the ${SAFE_EXTEN} channel variable anywhere throughout the rest
    of our dialplan, knowing we've already filtered it. We could also perform an
    error check to verify that what we've received in ${EXTEN} also matches the data
    passed back by FILTER(), and to fail the call if things do not match.
    exten => _X.,1,Verbose(2,Incoming call to extension ${EXTEN})
    exten => _X.,n,Set(SAFE_EXTEN=${FILTER(0-9,${EXTEN})})
    exten => _X.,n,GotoIf($[${EXTEN} != ${SAFE_EXTEN}]?error,1)
    exten => _X.,n,Dial(SIP/${SAFE_EXTEN})
    exten => _X.,n,Hangup()
    exten => error,1,Verbose(2,Values of EXTEN and SAFE_EXTEN did not match.)
    exten => error,n,Verbose(2,EXTEN: "${EXTEN}" -- SAFE_EXTEN: "${SAFE_EXTEN}")
    exten => error,n,Playback(silence/1&invalid)
    exten => error,n,Hangup()
    Another example would be using FILTER() to control the characters we accept when
    we're expecting to get a SIP URI for dialing.
/README-SERIOUSLY.bestpractices.txt (Diff revision 1)
Internet with capital i - twice in this paragraph.
  1. Actually, I left internet uncapitalized on purpose, for the reasons quoted in this wikipedia entry:
    "However, critics argue that some things that are unique yet distributed, such as "the power grid", "the telephone network", and even "the sky", are not considered proper nouns, and are thus not capitalized. Since at least 2002 it has been theorized that Internet has been changing from a proper noun to a generic term.[1] Words for new technologies, such as Phonograph in the 19th century, are sometimes capitalized at first, later becoming uncapitalized.[1] It was suggested as early as 1999 that Internet might, like some other commonly used proper nouns, lose its capital letter.[2]"
/README-SERIOUSLY.bestpractices.txt (Diff revision 1)
Hmm. Either two sentences or a comma after the URL.
  1. Actually I removed the comma after "generators" as I don't like having a comma after URLs if I can avoid it. In this case the commas are not really necessary. runs on a server provided by Digium, Inc. and uses bandwidth donated to the open source Asterisk community by API Digital Communications in Huntsville, AL USA.
Please report problems with this site to