<p>neels <strong>merged</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-msc/+/15021">View Change</a></p><div style="white-space:pre-wrap">Approvals:
  Jenkins Builder: Verified
  fixeria: Looks good to me, but someone else must approve
  neels: Looks good to me, approved

</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">manual: adjust and fix auth and ciph docs<br><br>Change-Id: Iffe159d4c0e0e9439f8719e0ddd28f06d4c80d9f<br>---<br>M doc/manuals/chapters/net.adoc<br>1 file changed, 54 insertions(+), 14 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/chapters/net.adoc b/doc/manuals/chapters/net.adoc</span><br><span>index 06be4ba..431455d 100644</span><br><span>--- a/doc/manuals/chapters/net.adoc</span><br><span>+++ b/doc/manuals/chapters/net.adoc</span><br><span>@@ -101,32 +101,56 @@</span><br><span> </span><br><span> === Authentication</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Authorized subscribers must be entered in the HLR database, see the _OsmoHLR</span><br><span style="color: hsl(0, 100%, 40%);">-reference manual_ <<userman-osmohlr>>. If authentication tokens (such as KI for</span><br><span style="color: hsl(0, 100%, 40%);">-2G, or K and OP/OPC for UMTS) are present in the HLR, OsmoMSC will only attach</span><br><span style="color: hsl(0, 100%, 40%);">-a subscriber after successful authentication.</span><br><span style="color: hsl(120, 100%, 40%);">+A subscriber's IMSI must be entered in the HLR database to be able to attach. A</span><br><span style="color: hsl(120, 100%, 40%);">+subscriber-create-on-demand feature is also available, see the _OsmoHLR</span><br><span style="color: hsl(120, 100%, 40%);">+reference manual_ <<userman-osmohlr>>.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-If no authentication keys are present in the HLR for a given subscriber,</span><br><span style="color: hsl(0, 100%, 40%);">-OsmoMSC will attach the subscriber _without_ authentication. You can reject</span><br><span style="color: hsl(0, 100%, 40%);">-subscribers that lack authentication info in the HLR with this setting:</span><br><span style="color: hsl(120, 100%, 40%);">+A known IMSI in the HLR may or may not have authentication keys associated,</span><br><span style="color: hsl(120, 100%, 40%);">+which profoundly affects the ability to attach and the algorithms used to</span><br><span style="color: hsl(120, 100%, 40%);">+negotiate authentication, as the following sections explain for 2G and 3G.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Authentication on 2G</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If authentication tokens (such as KI for 2G, or K and OP/OPC for UMTS) are</span><br><span style="color: hsl(120, 100%, 40%);">+present in the HLR, OsmoMSC will only attach a subscriber after successful</span><br><span style="color: hsl(120, 100%, 40%);">+authentication. Note that the 3G authentication keys are also used on 2G when</span><br><span style="color: hsl(120, 100%, 40%);">+the MS indicates UMTS AKA capability, in which case the full UMTS style mutual</span><br><span style="color: hsl(120, 100%, 40%);">+authentication may indeed take place on 2G (GERAN).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On 2G, if no authentication keys are present in the HLR for a given subscriber,</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoMSC will attach the subscriber _without_ authentication. Subscribers that</span><br><span style="color: hsl(120, 100%, 40%);">+lack authentication keys can always be rejected with this setting:</span><br><span> </span><br><span> ----</span><br><span> network</span><br><span>  authentication required</span><br><span> ----</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+==== Authentication on 3G</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+3G (UTRAN) always requires authentication (a.k.a. Integrity Protection) by</span><br><span style="color: hsl(120, 100%, 40%);">+specification, and hence authentication keys must be present in the HLR for a</span><br><span style="color: hsl(120, 100%, 40%);">+subscriber to be able to attach on 3G.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoMSC always indicates UIA1 and UIA2 as permitted Integrity Protection</span><br><span style="color: hsl(120, 100%, 40%);">+algorithms on 3G.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> === Ciphering</span><br><span> </span><br><span> To enable ciphering on the radio link, authentication must take place first:</span><br><span style="color: hsl(0, 100%, 40%);">-the Kc resulting from authentication is the key used for ciphering. Hence, all</span><br><span style="color: hsl(0, 100%, 40%);">-subscribers must have authentication tokens available in the HLR for ciphering.</span><br><span style="color: hsl(120, 100%, 40%);">+the Kc resulting from authentication is the key used for ciphering. Hence, to</span><br><span style="color: hsl(120, 100%, 40%);">+be able to use ciphering, a subscriber must have authentication tokens</span><br><span style="color: hsl(120, 100%, 40%);">+available in the HLR.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Ciphering on 2G</span><br><span> </span><br><span> The MS, BTS and MSC must agree on a ciphering algorithm to use.</span><br><span> </span><br><span> - The MS sends its supported ciphering algorithms via Classmark IEs during</span><br><span>   Location Updating.</span><br><span> - Typically the BSC needs to know which A5 ciphers are supported by connected</span><br><span style="color: hsl(0, 100%, 40%);">-  BTSes.</span><br><span style="color: hsl(120, 100%, 40%);">+  BTSes, see the `network / encryption a5` configuration item for OsmoBSC</span><br><span style="color: hsl(120, 100%, 40%);">+  <<vty-ref-osmobsc>>.</span><br><span> - Finally, OsmoMSC may impose that specific A5 ciphers shall not be considered.</span><br><span> </span><br><span> It is the responsibility of the BSC to then pick an A5 cipher that satisfies</span><br><span>@@ -143,12 +167,28 @@</span><br><span> +</span><br><span> ----</span><br><span> network</span><br><span style="color: hsl(0, 100%, 40%);">- encryption a5 3</span><br><span style="color: hsl(120, 100%, 40%);">+ encryption a5 1 3</span><br><span> ----</span><br><span> </span><br><span> - Never use A5/2: it is an "export grade cipher" and has been deprecated for</span><br><span>   its low ciphering strength.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-NOTE: At the time of writing, OsmoMSC supports setting only a single A5 cipher,</span><br><span style="color: hsl(0, 100%, 40%);">-while it should be able to allow a set of ciphers. This is subject to ongoing</span><br><span style="color: hsl(0, 100%, 40%);">-development.</span><br><span style="color: hsl(120, 100%, 40%);">+- To allow either no encryption or any of A5/1 or A5/3 based on the presence of</span><br><span style="color: hsl(120, 100%, 40%);">+  authentication keys and abilities of the MS, SIM and BSC configuration, it is</span><br><span style="color: hsl(120, 100%, 40%);">+  recommended to enable all ciphers in OsmoMSC. The highest available A5 cipher</span><br><span style="color: hsl(120, 100%, 40%);">+  will be used; the order in which the A5 options are configured does not</span><br><span style="color: hsl(120, 100%, 40%);">+  affect the choice.</span><br><span style="color: hsl(120, 100%, 40%);">++</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+network</span><br><span style="color: hsl(120, 100%, 40%);">+ encryption a5 0 1 3</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== Ciphering on 3G</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+While authentication is always required on 3G, ciphering is optional.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+So far OsmoMSC lacks explicit configuration for ciphering on 3G. As an interim</span><br><span style="color: hsl(120, 100%, 40%);">+solution, ciphering is always enabled on 3G.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoMSC indicates UEA1 and UEA2 as permitted encryption algorithms on 3G.</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-msc/+/15021">change 15021</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-msc/+/15021"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-msc </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: Iffe159d4c0e0e9439f8719e0ddd28f06d4c80d9f </div>
<div style="display:none"> Gerrit-Change-Number: 15021 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: neels <nhofmeyr@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: fixeria <axilirator@gmail.com> </div>
<div style="display:none"> Gerrit-Reviewer: laforge <laforge@gnumonks.org> </div>
<div style="display:none"> Gerrit-Reviewer: neels <nhofmeyr@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>