Difference between revisions of "Libygsm library"

From YateBTS
Jump to: navigation, search
(Description)
 
(8 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
This library provides encoders and decoders for Mobile Radio Interface Layer 3 messages according to ETSI TS 124 007 and ETSI TS 124 008. Messages are decoded to XML format. Encoders also expect XML format for encoding messages.
 
This library provides encoders and decoders for Mobile Radio Interface Layer 3 messages according to ETSI TS 124 007 and ETSI TS 124 008. Messages are decoded to XML format. Encoders also expect XML format for encoding messages.
  
       
+
The following details a proposal for decoded XML messages:
  
 +
* a Mobility Management message
 +
 +
<MM>
 +
  <SkipIndicator>0</SkipIndicator>
 +
  <NSD>0</NSD>
 +
  <Message type="LocationUpdatingRequest">
 +
    <LocationUpdatingType>
 +
      <FOR>false</FOR>
 +
      <LUT>normal-location-updating</LUT>
 +
    </LocationUpdatingType>
 +
    <CipheringKeySequenceNumber>0</CipheringKeySequenceNumber>
 +
    <LAI>
 +
      <PLMNidentity>26203</PLMNidentity>
 +
      <LAC>011b</LAC>
 +
    </LAI>
 +
    <MobileStationClassmark>
 +
      <RFPowerCapability>class4</RFPowerCapability>
 +
      <RevisionLevel>GSM-phase2</RevisionLevel>
 +
      <Flags>ES-IND</Flags>
 +
    </MobileStationClassmark>
 +
    <MobileIdentity>
 +
      <TMSI>9b055efc</TMSI>
 +
    </MobileIdentity>
 +
    <AdditionalUpdateParameters>CSMT,CSMO</AdditionalUpdateParameters>
 +
        <DeviceProperties>NAS-low-priority</DeviceProperties>
 +
    <MSNetworkFeatureSupport>MS-supports-the-extended-periodic-timer-in-this-domain</MSNetworkFeatureSupport>
 +
  </Message>
 +
</MM>
 +
 +
 +
* a Call Control message
 +
 +
<CC>
 +
  <TID TIFlag="false">0</TID>
 +
  <NSD>1</NSD>
 +
  <Message type="Setup">
 +
    <BearerCapability1>
 +
      <ITC>speech</ITC>
 +
      <TransferMode>circuit-mode</TransferMode>
 +
      <CodingStandard>GSM</CodingStandard>
 +
      <RadioChannelRequirement>FR-and-HR-speech-version1-supported/FR-speech-preferred</RadioChannelRequirement>
 +
      <SpeechVersions>GSM-FR-speech-version3,GSM-FR-speech-version2,GSM-FR-speech-version1,GSM-HR-speech-version3,GSM-HR-speech-version1</SpeechVersions>
 +
    </BearerCapability1>
 +
    <CalledPartyBCDNumber nature="unknown" plan="isdn">122</CalledPartyBCDNumber>
 +
    <SSVersion>SS-protocol-version-3-and-phase2-error-handling-supported</SSVersion>
 +
    <CCCapabilities>
 +
      <Flags>DTMF</Flags>
 +
      <MaxSupportedBearers>1</MaxSupportedBearers>
 +
      <MaxSpeechBearers>1</MaxSpeechBearers>
 +
    </CCCapabilities>
 +
    <StreamIdentifier>17</StreamIdentifier>
 +
  </Message>
 +
</CC>
 +
 +
 +
* EPS Mobility Management Message
 +
 +
<EPS_MM>
 +
  <SecurityHeader>integrity-protected</SecurityHeader>
 +
  <MAC>03522c19</MAC>
 +
  <SequenceNumber>8</SequenceNumber>
 +
  <EPS_MM>
 +
    <SecurityHeader>plain-NAS-message</SecurityHeader>
 +
    <Message type="AttachRequest">
 +
      <EPSAttachType>combined-EPS-IMSI-attach</EPSAttachType>
 +
      <NASKeySetIdentifier>
 +
        <TSC>native-security-context-for-KSI_ASME</TSC>
 +
        <NASKeySetId>0</NASKeySetId>
 +
      </NASKeySetIdentifier>
 +
      <EPSMobileIdentity>
 +
        <GUTI>
 +
          <PLMNidentity>46089</PLMNidentity>
 +
          <MMEGroupID>32769</MMEGroupID>
 +
          <MMECode>1</MMECode>
 +
          <M_TMSI>0000002b</M_TMSI>
 +
        </GUTI>
 +
      </EPSMobileIdentity>
 +
      <UENetworkCapability>128-EIA2,128-EIA1,EIA0,128-EEA2,128-EEA1,EEA0,UEA1,UEA0,UIA1</UENetworkCapability>
 +
      <ESMMessageContainer>
 +
        <EPS_SM>
 +
          <EPSBearerIdentity>00</EPSBearerIdentity>
 +
          <PTID>01</PTID>
 +
          <Message type=\"PDNConnectivityRequest\">
 +
            <RequestType>initialRequest</RequestType>
 +
            <PDNType>IPv4</PDNType>
 +
            <ESMInformationTransferFlag>security-protected-ESM-information-transfer-required</ESMInformationTransferFlag>
 +
            <ProtocolConfigurationOptions>8080211001</ProtocolConfigurationOptions>
 +
          </Message>
 +
        </EPS_SM>
 +
      </ESMMessageContainer>
 +
      <LastVisitedRegisteredTAI>
 +
        <PLMNidentity>46099</PLMNidentity>
 +
        <TAC>0001</TAC>
 +
      </LastVisitedRegisteredTAI>
 +
      <DRXParameter>
 +
        <SplitPGCycleCode>10</SplitPGCycleCode>
 +
        <NonDRXTimer>no-non-DRX-mode</NonDRXTimer>
 +
        <SplitOnCCCH>false</SplitOnCCCH>
 +
        <CNSpecificDRXCycleLength>not-specified-by-the-MS</CNSpecificDRXCycleLength>
 +
      </DRXParameter>
 +
      <MSNetworkCapability>e5e034</MSNetworkCapability>
 +
      <TMSIStatus>no-valid-TMSI-available</TMSIStatus>
 +
      <MobileStationClassmark2>
 +
        <RFPowerCapability>irrelevant</RFPowerCapability>
 +
        <RevisionLevel>R99-or-later</RevisionLevel>
 +
        <SSScreeningIndicator>ellipsis-notation-and-phase2-error-handling</SSScreeningIndicator>
 +
        <Flags>ES-IND,MT-sms-point-to-point-capability,pseudo-sync-capability,A5/3-support,CMSP-support,LCS-VA-support,CM3-support</Flags>
 +
      </MobileStationClassmark2>
 +
      <VoiceDomainPreferenceAndUEsUsageSetting>
 +
        <UEUsageSetting>voice-centric</UEUsageSetting>
 +
        <VoiceDomainPreference>CS-voice-preferred</VoiceDomainPreference>
 +
      </VoiceDomainPreferenceAndUEsUsageSetting>
 +
      <OldGUTIType>native-GUTI</OldGUTIType>
 +
    </Message>
 +
  </EPS_MM>
 +
</EPS_MM>
 +
 +
 +
General format for XML would be:
 +
<protocol_tag>
 +
    <header_IE_1/>
 +
    <header_IE_2/>
 +
    ...
 +
    <message_type_tag>
 +
        <message_type_IE_1/>
 +
        <message_type_IE_2/>
 +
        ...
 +
    </message_type_tag>
 +
</protocol_tag>
 +
 +
Unknown IEs will be added as:
 +
<ie>02510140</ie>
 +
 +
where the value of the ''ie'' element will be a octet string dump of the IE, including IEI.
  
 
== Testing ==
 
== Testing ==
Line 11: Line 145:
 
== Implementation ==
 
== Implementation ==
  
 +
Decoders and encoders will be implemented in a dynamic library found in Yate source directory libs/ygsm.
 +
 +
A class RL3Codec will offer coding and decoding functionality for messages:
 +
* the decoding function will expect as parameters the input buffer, its length and a XMLElement*&. On return, the XMLElement will contain the decoded message. The function will also return 0 if decoding succeeded or a error indication (value different of 0)
 +
* the encoding function will expect and XMLElement and a DataBlock into which the XMLElement should be encoded. On return, the DataBlock will contain the encoded message. The function will also return 0 if encoding succeeded or a error indication (value different of 0).
 +
* the codec will also allow setting some decoding options (like dumping the whole RL3 message buffer into the XML).
 +
* the codec will use IE descriptions to decode/encode the input data into XML/DataBlock
 +
* the codec will be able to parse unknown IEs.
  
 
== Documentation ==
 
== Documentation ==
  
 
Documentation will be found on this wiki page.
 
Documentation will be found on this wiki page.

Latest revision as of 17:54, 10 February 2014

Description

This library provides encoders and decoders for Mobile Radio Interface Layer 3 messages according to ETSI TS 124 007 and ETSI TS 124 008. Messages are decoded to XML format. Encoders also expect XML format for encoding messages.

The following details a proposal for decoded XML messages:

  • a Mobility Management message
<MM>
 <SkipIndicator>0</SkipIndicator>
 <NSD>0</NSD>
 <Message type="LocationUpdatingRequest">
   <LocationUpdatingType>
     <FOR>false</FOR>
     <LUT>normal-location-updating</LUT>
   </LocationUpdatingType>
   <CipheringKeySequenceNumber>0</CipheringKeySequenceNumber>
   <LAI>
     <PLMNidentity>26203</PLMNidentity>
     <LAC>011b</LAC>
   </LAI>
   <MobileStationClassmark>
     <RFPowerCapability>class4</RFPowerCapability>
     <RevisionLevel>GSM-phase2</RevisionLevel>
     <Flags>ES-IND</Flags>
   </MobileStationClassmark>
   <MobileIdentity>
     <TMSI>9b055efc</TMSI>
   </MobileIdentity>
   <AdditionalUpdateParameters>CSMT,CSMO</AdditionalUpdateParameters>
       <DeviceProperties>NAS-low-priority</DeviceProperties>
   <MSNetworkFeatureSupport>MS-supports-the-extended-periodic-timer-in-this-domain</MSNetworkFeatureSupport>
 </Message>
</MM>


  • a Call Control message
<CC>
 <TID TIFlag="false">0</TID>
 <NSD>1</NSD>
 <Message type="Setup">
   <BearerCapability1>
     <ITC>speech</ITC>
     <TransferMode>circuit-mode</TransferMode>
     <CodingStandard>GSM</CodingStandard>
     <RadioChannelRequirement>FR-and-HR-speech-version1-supported/FR-speech-preferred</RadioChannelRequirement>
     <SpeechVersions>GSM-FR-speech-version3,GSM-FR-speech-version2,GSM-FR-speech-version1,GSM-HR-speech-version3,GSM-HR-speech-version1</SpeechVersions>
   </BearerCapability1>
   <CalledPartyBCDNumber nature="unknown" plan="isdn">122</CalledPartyBCDNumber>
   <SSVersion>SS-protocol-version-3-and-phase2-error-handling-supported</SSVersion>
   <CCCapabilities>
     <Flags>DTMF</Flags>
     <MaxSupportedBearers>1</MaxSupportedBearers>
     <MaxSpeechBearers>1</MaxSpeechBearers>
   </CCCapabilities>
   <StreamIdentifier>17</StreamIdentifier>
 </Message>
</CC>


  • EPS Mobility Management Message
<EPS_MM>
 <SecurityHeader>integrity-protected</SecurityHeader>
 <MAC>03522c19</MAC>
 <SequenceNumber>8</SequenceNumber>
 <EPS_MM>
   <SecurityHeader>plain-NAS-message</SecurityHeader>
   <Message type="AttachRequest">
     <EPSAttachType>combined-EPS-IMSI-attach</EPSAttachType>
     <NASKeySetIdentifier>
       <TSC>native-security-context-for-KSI_ASME</TSC>
       <NASKeySetId>0</NASKeySetId>
     </NASKeySetIdentifier>
     <EPSMobileIdentity>
       <GUTI>
         <PLMNidentity>46089</PLMNidentity>
         <MMEGroupID>32769</MMEGroupID>
         <MMECode>1</MMECode>
         <M_TMSI>0000002b</M_TMSI>
       </GUTI>
     </EPSMobileIdentity>
     <UENetworkCapability>128-EIA2,128-EIA1,EIA0,128-EEA2,128-EEA1,EEA0,UEA1,UEA0,UIA1</UENetworkCapability>
     <ESMMessageContainer>
       <EPS_SM>
         <EPSBearerIdentity>00</EPSBearerIdentity>
         <PTID>01</PTID>
         <Message type=\"PDNConnectivityRequest\">
           <RequestType>initialRequest</RequestType>
           <PDNType>IPv4</PDNType>
           <ESMInformationTransferFlag>security-protected-ESM-information-transfer-required</ESMInformationTransferFlag>
           <ProtocolConfigurationOptions>8080211001</ProtocolConfigurationOptions>
         </Message>
       </EPS_SM>
     </ESMMessageContainer>
     <LastVisitedRegisteredTAI>
       <PLMNidentity>46099</PLMNidentity>
       <TAC>0001</TAC>
     </LastVisitedRegisteredTAI>
     <DRXParameter>
       <SplitPGCycleCode>10</SplitPGCycleCode>
       <NonDRXTimer>no-non-DRX-mode</NonDRXTimer>
       <SplitOnCCCH>false</SplitOnCCCH>
       <CNSpecificDRXCycleLength>not-specified-by-the-MS</CNSpecificDRXCycleLength>
     </DRXParameter>
     <MSNetworkCapability>e5e034</MSNetworkCapability>
     <TMSIStatus>no-valid-TMSI-available</TMSIStatus>
     <MobileStationClassmark2>
       <RFPowerCapability>irrelevant</RFPowerCapability>
       <RevisionLevel>R99-or-later</RevisionLevel>
       <SSScreeningIndicator>ellipsis-notation-and-phase2-error-handling</SSScreeningIndicator>
       <Flags>ES-IND,MT-sms-point-to-point-capability,pseudo-sync-capability,A5/3-support,CMSP-support,LCS-VA-support,CM3-support</Flags>
     </MobileStationClassmark2>
     <VoiceDomainPreferenceAndUEsUsageSetting>
       <UEUsageSetting>voice-centric</UEUsageSetting>
       <VoiceDomainPreference>CS-voice-preferred</VoiceDomainPreference>
     </VoiceDomainPreferenceAndUEsUsageSetting>
     <OldGUTIType>native-GUTI</OldGUTIType>
   </Message>
 </EPS_MM>
</EPS_MM>


General format for XML would be:

<protocol_tag>
    <header_IE_1/>
    <header_IE_2/>
    ...
    <message_type_tag>
       <message_type_IE_1/>
       <message_type_IE_2/>
       ...
    </message_type_tag>
</protocol_tag>

Unknown IEs will be added as:

<ie>02510140</ie>

where the value of the ie element will be a octet string dump of the IE, including IEI.

Testing

Implementation

Decoders and encoders will be implemented in a dynamic library found in Yate source directory libs/ygsm.

A class RL3Codec will offer coding and decoding functionality for messages:

  • the decoding function will expect as parameters the input buffer, its length and a XMLElement*&. On return, the XMLElement will contain the decoded message. The function will also return 0 if decoding succeeded or a error indication (value different of 0)
  • the encoding function will expect and XMLElement and a DataBlock into which the XMLElement should be encoded. On return, the DataBlock will contain the encoded message. The function will also return 0 if encoding succeeded or a error indication (value different of 0).
  • the codec will also allow setting some decoding options (like dumping the whole RL3 message buffer into the XML).
  • the codec will use IE descriptions to decode/encode the input data into XML/DataBlock
  • the codec will be able to parse unknown IEs.

Documentation

Documentation will be found on this wiki page.