<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2172/18/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Named+ACLs">Named ACLs</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~jrose">Jonathan Rose</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
Added consumer examples.<br />
</div>
<br/>
<h4>Changes (5)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h5. Example configuration: <br>{newcode:language=none|title=acl.conf}[profile1] <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">;whitelist everything from 128.128.128.* <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">;block everything then whitelist everything from 128.128.128.* <br></td></tr>
<tr><td class="diff-unchanged" >deny=0.0.0.0/0.0.0.0 <br>permit=128.128.128.0/255.255.255.0 <br> <br>[profile2] <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">;blacklist evrything from 10.24.*.* and 10.20.*.* <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">;allow everything then blacklist everything from 10.24.*.* and 10.20.*.* <br></td></tr>
<tr><td class="diff-unchanged" >permit=0.0.0.0/0.0.0.0 <br>deny=10.24.0.0/255.255.0.0 <br>deny=10.20.0.0/255.255.0.0{newcode} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> <br>h3. Consumer Configuration <br>Consumers use named ACLs in a similar fashion to how they use ACLs normally with the permit/deny options. The actual keyword used to append a named ACL is determined by the consumer (and can be context sensitive, like with sip.conf which can configure a number of ACLs for a given category/peer), but the standard established for now is that for any option containing ACLs set with [prefix]permit/[prefix]deny, a similar [prefix]acl option will be made. Multiple uses of this should be allowed in order to attach multiple named ACLs. Currently, the project is running with the idea that the order of named ACL use should cause the evaluation behavior to work as though all of the permits/denies associated with that address are evaluated then, but that isn't set in stone. <br> <br>h5. Example configurations <br>{newcode:language=none|title=sip.conf}[peer1] <br>... <br>deny=0.0.0.0/0.0.0.0 <br>acl=peer1ACL ; Uses a named ACL profile from acl.conf named peer1ACL <br> <br>directmediadeny=0.0.0.0/0.0.0.0 <br>directmediaacl=peer1DMACL ; Uses a named ACL profile from acl.conf named peer1DMACL <br>... <br>{newcode} <br> <br>{newcode:language=none|title=manager.conf}[admin] <br>... <br>deny=0.0.0.0/0.0.0.0 <br>; We want to accept connections to this manager account from any device at the main building. <br>ACL=whitelist_main_building ; uses a named ACL profile from acl.conf named whitelist_main_building <br>; Also, John Doe's phone should be accepted. <br>ACL=whitelist_JohnDoePhone <br>; We don't have a profile for it, but Bob Person wants access from a specific IP address. <br>permit=10.1.1.128 <br>... <br>{newcode} <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="NamedACLs-Overview"></a>Overview</h1>
<p>The primary goal for Named ACLs (Access Control Lists) is to provide users with a way to create commonly used ACL profiles and to be able to use those profiles wherever ACLs are consumed without the need to duplicate the list each time it is used (often with varying keywords for defining the ACLs). This will make the creation and maintainence of complex ACLs an easier, less error prone process. An implementation of this concept exists within a team branch written by Olle E. Johansson, though to what degree the scope of the current implementation will match that of Olle's is still uncertain.</p>
<h1><a name="NamedACLs-TableofContents"></a>Table of Contents</h1>
<style type='text/css'>/*<![CDATA[*/
div.rbtoc1339537566498 {margin-left: 1.5em;padding: 0px;}
div.rbtoc1339537566498 ul {list-style: disc;margin-left: 0px;padding-left: 20px;}
div.rbtoc1339537566498 li {margin-left: 0px;padding-left: 0px;}
/*]]>*/</style><div class='rbtoc1339537566498'>
<ul>
<li><a href='#NamedACLs-Overview'>Overview</a></li>
<li><a href='#NamedACLs-TableofContents'>Table of Contents</a></li>
<li><a href='#NamedACLs-UseCases%28desiredforrevisionI%29'>Use Cases (desired for revision I)</a></li>
<ul>
<li><a href='#NamedACLs-Noteonusecases%3A'>Note on use cases:</a></li>
<ul>
<li><a href='#NamedACLs-I.NamedACLandconsumerstartup'>I. Named ACL and consumer startup</a></li>
<ul>
<li><a href='#NamedACLs-Actors'>Actors</a></li>
<li><a href='#NamedACLs-Preconditions'>Preconditions</a></li>
<li><a href='#NamedACLs-Scenario'>Scenario</a></li>
<ul>
<li><a href='#NamedACLs-Theconsumer%27sconfigurationemploysanamedACLoption%28acl%3D%27aclname%27%29'>The consumer's configuration employs a named ACL option (acl = 'aclname')</a></li>
</ul>
<li><a href='#NamedACLs-PostConditions'>Post Conditions</a></li>
</ul>
<li><a href='#NamedACLs-II.NamedACLmoduleisreloaded'>II. Named ACL module is reloaded</a></li>
<ul>
<li><a href='#NamedACLs-Actors'>Actors</a></li>
<li><a href='#NamedACLs-Preconditions'>Preconditions</a></li>
<li><a href='#NamedACLs-Scenario'>Scenario</a></li>
<ul>
<li><a href='#NamedACLs-UsingNamedACLconsumerstoragemethodM1orM2'>Using Named ACL consumer storage method M1 or M2</a></li>
<li><a href='#NamedACLs-UsingNamedACLConsumerstoragemethodM3%2Cnochangeswouldneedtobemadeatthisjunction.'>Using Named ACL Consumer storage method M3, no changes would need to be made at this junction.</a></li>
</ul>
<li><a href='#NamedACLs-Postconditions'>Postconditions</a></li>
</ul>
</ul>
</ul>
<li><a href='#NamedACLs-Configuration'>Configuration</a></li>
<ul>
<ul>
<li><a href='#NamedACLs-NamedACLConfiguration%28acl.conf%29'>Named ACL Configuration (acl.conf)</a></li>
<ul>
<li><a href='#NamedACLs-Exampleconfiguration%3A'>Example configuration:</a></li>
</ul>
<li><a href='#NamedACLs-ConsumerConfiguration'>Consumer Configuration</a></li>
<ul>
<li><a href='#NamedACLs-Exampleconfigurations'>Example configurations</a></li>
</ul>
</ul>
</ul>
</ul></div>
<h1><a name="NamedACLs-UseCases%28desiredforrevisionI%29"></a>Use Cases (desired for revision I)</h1>
<h2><a name="NamedACLs-Noteonusecases%3A"></a>Note on use cases:</h2>
<p>The method for using named ACLs with consumers is currently something of an open question. In the reviewboard prototype, the named ACL will immediately be searched from the ACL subsystem and if it's found, the real ACL defined in configuration will then be appended to whatever ACL structure the consumer is currently using (M1). Another method that is in discussion is to change the current ACLs into a container that can hold the natural ACL defined in the consumer's configuration with permit and deny as well as an arbitrary number of named ACLs (M2). Another option still would be to have a similar container that can hold an arbitrary number of ACL objects which could either be the names of relevant named ACLs or ast_ha structs. The last approach would require that the full container be iteratively copied into a new standard ast_ha structure at the time of consumption (which would stay alive for the duration of whatever dialog its used for) (M3). The first two methods however require an event setup where consumers are notified of changes to the ACL system so that they can react to them (to update consumer ACLs).</p>
<h3><a name="NamedACLs-I.NamedACLandconsumerstartup"></a>I. Named ACL and consumer startup</h3>
<h5><a name="NamedACLs-Actors"></a>Actors</h5>
<ol>
<li>Named ACL Subsystem</li>
<li>Arbitrary Consumer (There can be any number of them and will include modules and other Asterisk subsystems like manager)</li>
</ol>
<h5><a name="NamedACLs-Preconditions"></a>Preconditions</h5>
<ol>
<li>Configuration files exist for the named ACL subsystem (acl.conf) and consumers (consumer.conf for the sake of the example)</li>
</ol>
<h5><a name="NamedACLs-Scenario"></a>Scenario</h5>
<ol>
<li>The Named ACL Subsystem is initialized</li>
<li>The Named ACL Subsystem loads configuration information from acl.conf</li>
<li>Categories in acl.conf become names for named ACLs while individual instances of permit/deny options within those categories become the rules that define those named ACLs.</li>
<li>A consumer is initialized (from here, steps are repeated for each consumer)</li>
<li>The consumer loads configuration information from consumer.conf
<h6><a name="NamedACLs-Theconsumer%27sconfigurationemploysanamedACLoption%28acl%3D%27aclname%27%29"></a>The consumer's configuration employs a named ACL option (acl = 'aclname')</h6></li>
<li>The named ACL will be appended to whatever ACL/container the consumer is modifying with that option.</li>
</ol>
<h5><a name="NamedACLs-PostConditions"></a>Post Conditions</h5>
<ol>
<li>The consumers will either have ACLs that can be used in their immediate state or will have an ACL container from which an ACL can be readily preparred depending on the implementation above.</li>
</ol>
<h3><a name="NamedACLs-II.NamedACLmoduleisreloaded"></a>II. Named ACL module is reloaded</h3>
<h5><a name="NamedACLs-Actors"></a>Actors</h5>
<ol>
<li>Named ACL Subsystem</li>
<li>Arbitrary Consumers</li>
</ol>
<h5><a name="NamedACLs-Preconditions"></a>Preconditions</h5>
<ol>
<li>A valid configuration exists for the named ACL subsystem (acl.conf) which has been changed.</li>
</ol>
<h5><a name="NamedACLs-Scenario"></a>Scenario</h5>
<ol>
<li>The named ACL subsystem reloads configuration information from acl.conf. At this point, ACLs from the previous configuration may be gone or altered and new ones may be introduced.
<h6><a name="NamedACLs-UsingNamedACLconsumerstoragemethodM1orM2"></a>Using Named ACL consumer storage method M1 or M2</h6></li>
<li>An ACL_CHANGE event is triggered by the named ACL subsystem which has been subscribed to by consumers that currently make use of the named ACL system.</li>
<li>The consumer will read the event. How it is handled by the consumer at this point isn't definite, but possible options are for the consumer to force a reload or if the consumer has the ability to examine specific ACLs for named ACLs, to simply repopulate named ACLs.
<h6><a name="NamedACLs-UsingNamedACLConsumerstoragemethodM3%2Cnochangeswouldneedtobemadeatthisjunction."></a>Using Named ACL Consumer storage method M3, no changes would need to be made at this junction.</h6></li>
</ol>
<h5><a name="NamedACLs-Postconditions"></a>Postconditions</h5>
<ol>
<li>Any active dialogs that were running before the named ACL subsystem reload would continue to use the original ACL until those dialogs expired. (consistent with current behavior for reloads)</li>
<li>New dialogs will use the refreshed named ACL. (also consistent with current behavior for reloads)</li>
<li>The structure storing the master ACL or ACL container will be update with the new named ACLs (if necessary).</li>
</ol>
<h1><a name="NamedACLs-Configuration"></a>Configuration</h1>
<h3><a name="NamedACLs-NamedACLConfiguration%28acl.conf%29"></a>Named ACL Configuration (acl.conf)</h3>
<p>acl.conf defines ACL profiles. Use of the configuration is very simple and consists only of categories (name of the category determines the name of the ACL and must not be 'general' since that's a reserved word for Asterisk configurations) with two options, permit and deny, which may be used in sequence to build an ACL. Order is important as it is for all ACLs.<br/>
Like all uses of ACLs in configurations, the named ACL configuration supports ipv6 addresses.</p>
<h5><a name="NamedACLs-Exampleconfiguration%3A"></a>Example configuration:</h5>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>acl.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[profile1]
;block everything then whitelist everything from 128.128.128.*
deny=0.0.0.0/0.0.0.0
permit=128.128.128.0/255.255.255.0
[profile2]
;allow everything then blacklist everything from 10.24.*.* and 10.20.*.*
permit=0.0.0.0/0.0.0.0
deny=10.24.0.0/255.255.0.0
deny=10.20.0.0/255.255.0.0</pre>
</div></div>
<h3><a name="NamedACLs-ConsumerConfiguration"></a>Consumer Configuration</h3>
<p>Consumers use named ACLs in a similar fashion to how they use ACLs normally with the permit/deny options. The actual keyword used to append a named ACL is determined by the consumer (and can be context sensitive, like with sip.conf which can configure a number of ACLs for a given category/peer), but the standard established for now is that for any option containing ACLs set with <a href="/wiki/pages/createpage.action?spaceKey=AST&title=prefix&linkCreation=true&fromPageId=20185274" class="createlink">prefix</a>permit/<a href="/wiki/pages/createpage.action?spaceKey=AST&title=prefix&linkCreation=true&fromPageId=20185274" class="createlink">prefix</a>deny, a similar <a href="/wiki/pages/createpage.action?spaceKey=AST&title=prefix&linkCreation=true&fromPageId=20185274" class="createlink">prefix</a>acl option will be made. Multiple uses of this should be allowed in order to attach multiple named ACLs. Currently, the project is running with the idea that the order of named ACL use should cause the evaluation behavior to work as though all of the permits/denies associated with that address are evaluated then, but that isn't set in stone.</p>
<h5><a name="NamedACLs-Exampleconfigurations"></a>Example configurations</h5>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>sip.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[peer1]
...
deny=0.0.0.0/0.0.0.0
acl=peer1ACL ; Uses a named ACL profile from acl.conf named peer1ACL
directmediadeny=0.0.0.0/0.0.0.0
directmediaacl=peer1DMACL ; Uses a named ACL profile from acl.conf named peer1DMACL
...</pre>
</div></div>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>manager.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[admin]
...
deny=0.0.0.0/0.0.0.0
; We want to accept connections to this manager account from any device at the main building.
ACL=whitelist_main_building ; uses a named ACL profile from acl.conf named whitelist_main_building
; Also, John Doe's phone should be accepted.
ACL=whitelist_JohnDoePhone
; We don't have a profile for it, but Bob Person wants access from a specific IP address.
permit=10.1.1.128
...</pre>
</div></div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Named+ACLs">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=20185274&revisedVersion=4&originalVersion=3">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Named+ACLs?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>