pyrad 2.4__py3-none-any.whl → 2.5.1__py3-none-any.whl

pyrad/packet.py

@@ -5,18 +5,26 @@
 # A RADIUS packet as defined in RFC 2138
 
 from collections import OrderedDict
+from pyrad import tools
+import hmac
 import struct
+import sys
+
 try:
     import secrets
     random_generator = secrets.SystemRandom()
 except ImportError:
     import random
     random_generator = random.SystemRandom()
-import hmac
 
-import sys
+
+def _hmac_md5(*args, **kwargs):
+    """Py3 hmac.new() wrapper with explicit MD5 digestmod."""
+    return hmac.new(*args, digestmod='MD5', **kwargs)
+
+
 if sys.version_info >= (3, 0):
-    hmac_new = lambda *x, **y: hmac.new(*x, digestmod='MD5', **y)
+    hmac_new = _hmac_md5
 else:
     hmac_new = hmac.new
 
@@ -27,8 +35,6 @@ except ImportError:
     # BBB for python 2.4
     import md5
     md5_constructor = md5.new
-import six
-from pyrad import tools
 
 # Packet codes
 AccessRequest = 1
@@ -60,7 +66,7 @@ class Packet(OrderedDict):
     attributes the value will always be a sequence. pyrad makes sure
     to preserve the ordering when encoding and decoding packets.
 
-    There are two ways to use the map intereface: if attribute
+    There are two ways to use the map interface: if attribute
     names are used pyrad take care of en-/decoding data. If
     the attribute type number (or a vendor ID/attribute type
     tuple for vendor attributes) is used you work with the
@@ -70,7 +76,7 @@ class Packet(OrderedDict):
     :obj:`AuthPacket` or :obj:`AcctPacket` classes.
     """
 
-    def __init__(self, code=0, id=None, secret=six.b(''), authenticator=None,
+    def __init__(self, code=0, id=None, secret=b'', authenticator=None,
                  **attributes):
         """Constructor
 
@@ -91,13 +97,14 @@ class Packet(OrderedDict):
             self.id = id
         else:
             self.id = CreateID()
-        if not isinstance(secret, six.binary_type):
+        if not isinstance(secret, bytes):
             raise TypeError('secret must be a binary string')
         self.secret = secret
         if authenticator is not None and \
-                not isinstance(authenticator, six.binary_type):
+                not isinstance(authenticator, bytes):
             raise TypeError('authenticator must be a binary string')
         self.authenticator = authenticator
+        self.request_authenticator = None      # used for storing request authenticator in reply packets
         self.message_authenticator = None
         self.raw_packet = None
 
@@ -124,7 +131,7 @@ class Packet(OrderedDict):
 
         self.message_authenticator = True
         # Maintain a zero octets content for md5 and hmac calculation.
-        self['Message-Authenticator'] = 16 * six.b('\00')
+        self['Message-Authenticator'] = 16 * b'\00'
 
         if self.id is None:
             self.id = self.CreateID()
@@ -141,7 +148,7 @@ class Packet(OrderedDict):
         hmac_constructor = hmac_new(self.secret)
 
         # Maintain a zero octets content for md5 and hmac calculation.
-        self['Message-Authenticator'] = 16 * six.b('\00')
+        self['Message-Authenticator'] = 16 * b'\00'
         attr = self._PktEncodeAttributes()
 
         header = struct.pack('!BBH', self.code, self.id,
@@ -150,7 +157,7 @@ class Packet(OrderedDict):
         hmac_constructor.update(header[0:4])
         if self.code in (AccountingRequest, DisconnectRequest,
                          CoARequest, AccountingResponse):
-            hmac_constructor.update(16 * six.b('\00'))
+            hmac_constructor.update(16 * b'\00')
         else:
             # NOTE: self.authenticator on reply packet is initialized
             #       with request authenticator by design.
@@ -197,9 +204,9 @@ class Packet(OrderedDict):
         # attributes exactly as sent.
         if self.raw_packet:
             attr = self.raw_packet[20:]
-            attr = attr.replace(prev_ma[0], 16 * six.b('\00'))
+            attr = attr.replace(prev_ma[0], 16 * b'\00')
         else:
-            self['Message-Authenticator'] = 16 * six.b('\00')
+            self['Message-Authenticator'] = 16 * b'\00'
             attr = self._PktEncodeAttributes()
 
         header = struct.pack('!BBH', self.code, self.id,
@@ -211,7 +218,7 @@ class Packet(OrderedDict):
                          CoARequest, AccountingResponse):
             if original_code is None or original_code != StatusServer:
                 # TODO: Handle Status-Server response correctly.
-                hmac_constructor.update(16 * six.b('\00'))
+                hmac_constructor.update(16 * b'\00')
         elif self.code in (AccessAccept, AccessChallenge,
                            AccessReject):
             if original_authenticator is None:
@@ -241,6 +248,10 @@ class Packet(OrderedDict):
                       **attributes)
 
     def _DecodeValue(self, attr, value):
+        if attr.encrypt == 2:
+            # salt decrypt attribute
+            value = self.SaltDecrypt(value)
+
         if attr.values.HasBackward(value):
             return attr.values.GetBackward(value)
         else:
@@ -283,7 +294,7 @@ class Packet(OrderedDict):
             return key
 
         attr = self.dict.attributes[key]
-        if attr.vendor and not attr.is_sub_attribute:  #sub attribute keys don't need vendor
+        if attr.vendor and not attr.is_sub_attribute:  # sub attribute keys don't need vendor
             return (self.dict.vendors.GetForward(attr.vendor), attr.code)
         else:
             return attr.code
@@ -324,7 +335,7 @@ class Packet(OrderedDict):
         return res
 
     def __getitem__(self, key):
-        if not isinstance(key, six.string_types):
+        if not isinstance(key, str):
             return OrderedDict.__getitem__(self, key)
 
         values = OrderedDict.__getitem__(self, self._EncodeKey(key))
@@ -355,7 +366,7 @@ class Packet(OrderedDict):
         OrderedDict.__delitem__(self, self._EncodeKey(key))
 
     def __setitem__(self, key, item):
-        if isinstance(key, six.string_types):
+        if isinstance(key, str):
             (key, item) = self._EncodeKeyValues(key, item)
             OrderedDict.__setitem__(self, key, item)
         else:
@@ -374,14 +385,10 @@ class Packet(OrderedDict):
         :return: valid packet authenticator
         :rtype: binary string
         """
-
-        data = []
-        for _ in range(16):
-            data.append(random_generator.randrange(0, 256))
-        if six.PY3:
-            return bytes(data)
-        else:
-            return ''.join(chr(b) for b in data)
+        return bytes(
+            random_generator.randrange(0, 256)
+            for _ in range(16)
+        )
 
     def CreateID(self):
         """Create a packet ID.  All RADIUS requests have a ID which is used to
@@ -403,8 +410,8 @@ class Packet(OrderedDict):
         :return: raw packet
         :rtype:  string
         """
-        assert(self.authenticator)
-        assert(self.secret is not None)
+        assert (self.authenticator)
+        assert (self.secret is not None)
 
         if self.message_authenticator:
             self._refresh_message_authenticator()
@@ -417,14 +424,14 @@ class Packet(OrderedDict):
 
         return header + authenticator + attr
 
-    def VerifyReply(self, reply, rawreply=None):
+    def VerifyReply(self, reply, rawreply=None, enforce_ma=False):
         if reply.id != self.id:
             return False
 
         if rawreply is None:
             rawreply = reply.ReplyPacket()
 
-        attr = reply._PktEncodeAttributes()
+        _ = reply._PktEncodeAttributes()
         # The Authenticator field in an Accounting-Response packet is called
         # the Response Authenticator, and contains a one-way MD5 hash
         # calculated over a stream of octets consisting of the Accounting
@@ -438,6 +445,13 @@ class Packet(OrderedDict):
 
         if hash != rawreply[4:20]:
             return False
+
+        if enforce_ma:
+            if self.message_authenticator is None:
+                return False
+            if not self.verify_message_authenticator():
+                return False
+
         return True
 
     def _PktEncodeAttribute(self, key, value):
@@ -450,11 +464,11 @@ class Packet(OrderedDict):
 
     def _PktEncodeTlv(self, tlv_key, tlv_value):
         tlv_attr = self.dict.attributes[self._DecodeKey(tlv_key)]
-        curr_avp = six.b('')
+        curr_avp = b''
         avps = []
         max_sub_attribute_len = max(map(lambda item: len(item[1]), tlv_value.items()))
         for i in range(max_sub_attribute_len):
-            sub_attr_encoding = six.b('')
+            sub_attr_encoding = b''
             for (code, datalst) in tlv_value.items():
                 if i < len(datalst):
                     sub_attr_encoding += self._PktEncodeAttribute(code, datalst[i])
@@ -470,7 +484,7 @@ class Packet(OrderedDict):
             value = struct.pack('!BB', tlv_attr.code, (len(avp) + 2)) + avp
             tlv_avps.append(value)
         if tlv_attr.vendor:
-            vendor_avps = six.b('')
+            vendor_avps = b''
             for avp in tlv_avps:
                 vendor_avps += struct.pack(
                     '!BBL', 26, (len(avp) + 6),
@@ -481,10 +495,9 @@ class Packet(OrderedDict):
             return b''.join(tlv_avps)
 
     def _PktEncodeAttributes(self):
-        result = six.b('')
+        result = b''
         for (code, datalst) in self.items():
-            attribute = self.dict.attributes.get(self._DecodeKey(code))
-            if attribute and attribute.type == 'tlv':
+            if self._PktIsTlvAttribute(code):
                 result += self._PktEncodeTlv(code, datalst)
             else:
                 for data in datalst:
@@ -498,21 +511,20 @@ class Packet(OrderedDict):
             return [(26, data)]
 
         (vendor, atype, length) = struct.unpack('!LBB', data[:6])[0:3]
-        attribute = self.dict.attributes.get(self._DecodeKey((vendor, atype)))
         try:
-            if attribute and attribute.type == 'tlv':
+            if self._PktIsTlvAttribute((vendor, atype)):
                 self._PktDecodeTlvAttribute((vendor, atype), data[6:length + 4])
                 tlvs = []  # tlv is added to the packet inside _PktDecodeTlvAttribute
             else:
                 tlvs = [((vendor, atype), data[6:length + 4])]
-        except:
+        except Exception:
             return [(26, data)]
 
         sumlength = 4 + length
         while len(data) > sumlength:
             try:
                 atype, length = struct.unpack('!BB', data[sumlength:sumlength+2])[0:2]
-            except:
+            except Exception:
                 return [(26, data)]
             tlvs.append(((vendor, atype), data[sumlength+2:sumlength+length]))
             sumlength += length
@@ -527,6 +539,10 @@ class Packet(OrderedDict):
             sub_attributes.setdefault(atype, []).append(data[loc+2:loc+length])
             loc += length
 
+    def _PktIsTlvAttribute(self, code):
+        attr = self.dict.attributes.get(self._DecodeKey(code))
+        return (attr is not None and attr.type == 'tlv')
+
     def DecodePacket(self, packet):
         """Initialize the object from raw packet data.  Decode a packet as
         received from the network and decode it.
@@ -555,11 +571,9 @@ class Packet(OrderedDict):
                 raise PacketError('Attribute header is corrupt')
 
             if attrlen < 2:
-                raise PacketError(
-                        'Attribute length is too small (%d)' % attrlen)
+                raise PacketError('Attribute length is too small (%d)' % attrlen)
 
             value = packet[2:attrlen]
-            attribute = self.dict.attributes.get(self._DecodeKey(key))
             if key == 26:
                 for (key, value) in self._PktDecodeVendorAttribute(value):
                     self.setdefault(key, []).append(value)
@@ -567,63 +581,82 @@ class Packet(OrderedDict):
                 # POST: Message Authenticator AVP is present.
                 self.message_authenticator = True
                 self.setdefault(key, []).append(value)
-            elif attribute and attribute.type == 'tlv':
-                self._PktDecodeTlvAttribute(key,value)
+            elif self._PktIsTlvAttribute(key):
+                self._PktDecodeTlvAttribute(key, value)
             else:
                 self.setdefault(key, []).append(value)
 
             packet = packet[attrlen:]
 
+    def _salt_en_decrypt(self, data, salt):
+        result = b''
+        if self.request_authenticator is not None:
+            last = self.request_authenticator + salt
+        else:
+            last = self.authenticator + salt
+        while data:
+            hash = md5_constructor(self.secret + last).digest()
+            for i in range(16):
+                result += bytes((hash[i] ^ data[i],))
+
+            last = result[-16:]
+            data = data[16:]
+        return result
+
     def SaltCrypt(self, value):
-        """Salt Encryption
+        """SaltEncrypt
 
         :param value:    plaintext value
-        :type password:  unicode string
+        :type:           unicode string
         :return:         obfuscated version of the value
         :rtype:          binary string
         """
 
-        if isinstance(value, six.text_type):
+        if isinstance(value, str):
             value = value.encode('utf-8')
 
         if self.authenticator is None:
             # self.authenticator = self.CreateAuthenticator()
-            self.authenticator = 16 * six.b('\x00')
+            self.authenticator = 16 * b'\x00'
 
+        # create salt
         random_value = 32768 + random_generator.randrange(0, 32767)
-        if six.PY3:
-            salt_raw = struct.pack('!H', random_value )
-            salt = chr(salt_raw[0]) + chr(salt_raw[1])
-        else:
-            salt = struct.pack('!H', random_value )
-            salt = chr(ord(salt[0]) | 1 << 7)+salt[1]
-
-        result = six.b(salt)
+        salt_raw = struct.pack('!H', random_value)
 
+        # length prefixing
         length = struct.pack("B", len(value))
-        buf = length + value
-        if len(buf) % 16 != 0:
-            buf += six.b('\x00') * (16 - (len(buf) % 16))
+        value = length + value
 
-        last = self.authenticator + six.b(salt)
-        while buf:
-            hash = md5_constructor(self.secret + last).digest()
-            if six.PY3:
-                for i in range(16):
-                    result += bytes((hash[i] ^ buf[i],))
-            else:
-                for i in range(16):
-                    result += chr(ord(hash[i]) ^ ord(buf[i]))
+        # zero padding
+        if len(value) % 16 != 0:
+            value += b'\x00' * (16 - (len(value) % 16))
 
-            last = result[-16:]
-            buf = buf[16:]
+        return salt_raw + self._salt_en_decrypt(value, salt_raw)
 
-        return result
+    def SaltDecrypt(self, value):
+        """ SaltDecrypt
+
+        :param value:   encrypted value including salt
+        :type:          binary string
+        :return:        decrypted plaintext string
+        :rtype:         unicode string
+        """
+        # extract salt
+        salt = value[:2]
+
+        # decrypt
+        value = self._salt_en_decrypt(value[2:], salt)
+
+        # remove padding
+        length = value[0]
+        value = value[1:length+1]
+
+        return value
 
 
 class AuthPacket(Packet):
-    def __init__(self, code=AccessRequest, id=None, secret=six.b(''),
-            authenticator=None, auth_type='pap', **attributes):
+    def __init__(self, code=AccessRequest, id=None, secret=b'',
+                 authenticator=None, auth_type='pap', **attributes):
         """Constructor
 
         :param code:   packet type code
@@ -692,34 +725,39 @@ class AuthPacket(Packet):
         return header + attr
 
     def PwDecrypt(self, password):
-        """Obfuscate a RADIUS password. RADIUS hides passwords in packets by
+        """De-Obfuscate a RADIUS password. RADIUS hides passwords in packets by
         using an algorithm based on the MD5 hash of the packet authenticator
         and RADIUS secret. This function reverses the obfuscation process.
 
+        Although RFC2865 does not explicitly state UTF-8 for the password field,
+        the rest of RFC2865 defines UTF-8 as the encoding expected for the decrypted password.
+
+
         :param password: obfuscated form of password
         :type password:  binary string
         :return:         plaintext password
         :rtype:          unicode string
         """
         buf = password
-        pw = six.b('')
+        pw = b''
 
         last = self.authenticator
         while buf:
             hash = md5_constructor(self.secret + last).digest()
-            if six.PY3:
-                for i in range(16):
-                    pw += bytes((hash[i] ^ buf[i],))
-            else:
-                for i in range(16):
-                    pw += chr(ord(hash[i]) ^ ord(buf[i]))
-
+            for i in range(16):
+                pw += bytes((hash[i] ^ buf[i],))
             (last, buf) = (buf[:16], buf[16:])
 
-        while pw.endswith(six.b('\x00')):
+        # This is safe even with UTF-8 encoding since no valid encoding of UTF-8
+        # (other than encoding U+0000 NULL) will produce a bytestream containing 0x00 byte.
+        while pw.endswith(b'\x00'):
             pw = pw[:-1]
 
-        return pw.decode('utf-8')
+        # If the shared secret with the client is not the same, then de-obfuscating the password
+        # field may yield illegal UTF-8 bytes. Therefore, in order not to provoke an Exception here
+        # (which would be not consistently generated since this will depend on the random data
+        # chosen by the client) we simply ignore un-parsable UTF-8 sequences.
+        return pw.decode('utf-8', errors="ignore")
 
     def PwCrypt(self, password):
         """Obfuscate password.
@@ -738,25 +776,20 @@ class AuthPacket(Packet):
         if self.authenticator is None:
             self.authenticator = self.CreateAuthenticator()
 
-        if isinstance(password, six.text_type):
+        if isinstance(password, str):
             password = password.encode('utf-8')
 
         buf = password
         if len(password) % 16 != 0:
-            buf += six.b('\x00') * (16 - (len(password) % 16))
+            buf += b'\x00' * (16 - (len(password) % 16))
 
-        result = six.b('')
+        result = b''
 
         last = self.authenticator
         while buf:
             hash = md5_constructor(self.secret + last).digest()
-            if six.PY3:
-                for i in range(16):
-                    result += bytes((hash[i] ^ buf[i],))
-            else:
-                for i in range(16):
-                    result += chr(ord(hash[i]) ^ ord(buf[i]))
-
+            for i in range(16):
+                result += bytes((hash[i] ^ buf[i],))
             last = result[-16:]
             buf = buf[16:]
 
@@ -774,16 +807,14 @@ class AuthPacket(Packet):
         if not self.authenticator:
             self.authenticator = self.CreateAuthenticator()
 
-        if isinstance(userpwd, six.text_type):
+        if isinstance(userpwd, str):
             userpwd = userpwd.strip().encode('utf-8')
 
         chap_password = tools.DecodeOctets(self.get(3)[0])
         if len(chap_password) != 17:
             return False
 
-        chapid = chap_password[0]
-        if six.PY3:
-            chapid = chr(chapid).encode('utf-8')
+        chapid = chap_password[:1]
         password = chap_password[1:]
 
         challenge = self.authenticator
@@ -794,11 +825,11 @@ class AuthPacket(Packet):
     def VerifyAuthRequest(self):
         """Verify request authenticator.
 
-        :return: True if verification failed else False
+        :return: True if verification passed else False
         :rtype: boolean
         """
-        assert(self.raw_packet)
-        hash = md5_constructor(self.raw_packet[0:4] + 16 * six.b('\x00') +
+        assert (self.raw_packet)
+        hash = md5_constructor(self.raw_packet[0:4] + 16 * b'\x00' +
                                self.raw_packet[20:] + self.secret).digest()
         return hash == self.authenticator
 
@@ -808,7 +839,7 @@ class AcctPacket(Packet):
     of the generic :obj:`Packet` class for accounting packets.
     """
 
-    def __init__(self, code=AccountingRequest, id=None, secret=six.b(''),
+    def __init__(self, code=AccountingRequest, id=None, secret=b'',
                  authenticator=None, **attributes):
         """Constructor
 
@@ -837,12 +868,12 @@ class AcctPacket(Packet):
     def VerifyAcctRequest(self):
         """Verify request authenticator.
 
-        :return: False if verification failed else True
+        :return: True if verification passed else False
         :rtype: boolean
         """
-        assert(self.raw_packet)
+        assert (self.raw_packet)
 
-        hash = md5_constructor(self.raw_packet[0:4] + 16 * six.b('\x00') +
+        hash = md5_constructor(self.raw_packet[0:4] + 16 * b'\x00' +
                                self.raw_packet[20:] + self.secret).digest()
 
         return hash == self.authenticator
@@ -864,7 +895,7 @@ class AcctPacket(Packet):
 
         attr = self._PktEncodeAttributes()
         header = struct.pack('!BBH', self.code, self.id, (20 + len(attr)))
-        self.authenticator = md5_constructor(header[0:4] + 16 * six.b('\x00') +
+        self.authenticator = md5_constructor(header[0:4] + 16 * b'\x00' +
                                              attr + self.secret).digest()
 
         ans = header + self.authenticator + attr
@@ -877,8 +908,8 @@ class CoAPacket(Packet):
     of the generic :obj:`Packet` class for CoA packets.
     """
 
-    def __init__(self, code=CoARequest, id=None, secret=six.b(''),
-            authenticator=None, **attributes):
+    def __init__(self, code=CoARequest, id=None, secret=b'',
+                 authenticator=None, **attributes):
         """Constructor
 
         :param dict:   RADIUS dictionary
@@ -906,11 +937,11 @@ class CoAPacket(Packet):
     def VerifyCoARequest(self):
         """Verify request authenticator.
 
-        :return: False if verification failed else True
+        :return: True if verification passed else False
         :rtype: boolean
         """
-        assert(self.raw_packet)
-        hash = md5_constructor(self.raw_packet[0:4] + 16 * six.b('\x00') +
+        assert (self.raw_packet)
+        hash = md5_constructor(self.raw_packet[0:4] + 16 * b'\x00' +
                                self.raw_packet[20:] + self.secret).digest()
         return hash == self.authenticator
 
@@ -929,13 +960,13 @@ class CoAPacket(Packet):
             self.id = self.CreateID()
 
         header = struct.pack('!BBH', self.code, self.id, (20 + len(attr)))
-        self.authenticator = md5_constructor(header[0:4] + 16 * six.b('\x00') +
+        self.authenticator = md5_constructor(header[0:4] + 16 * b'\x00' +
                                              attr + self.secret).digest()
 
         if self.message_authenticator:
             self._refresh_message_authenticator()
             attr = self._PktEncodeAttributes()
-            self.authenticator = md5_constructor(header[0:4] + 16 * six.b('\x00') +
+            self.authenticator = md5_constructor(header[0:4] + 16 * b'\x00' +
                                                  attr + self.secret).digest()
 
         return header + self.authenticator + attr

pyrad/proxy.py

@@ -25,7 +25,7 @@ class Proxy(Server):
         self._proxyfd = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
         self._fdmap[self._proxyfd.fileno()] = self._proxyfd
         self._poll.register(self._proxyfd.fileno(),
-                (select.POLLIN | select.POLLPRI | select.POLLERR))
+                            (select.POLLIN | select.POLLPRI | select.POLLERR))
 
     def _HandleProxyPacket(self, pkt):
         """Process a packet received on the reply socket.
@@ -41,7 +41,7 @@ class Proxy(Server):
         pkt.secret = self.hosts[pkt.source[0]].secret
 
         if pkt.code not in [packet.AccessAccept, packet.AccessReject,
-                packet.AccountingResponse]:
+                            packet.AccountingResponse]:
             raise ServerPacketError('Received non-response on proxy socket')
 
     def _ProcessInput(self, fd):

pyrad/server.py

@@ -114,7 +114,7 @@ class Server(host.Host):
         """
         results = set()
         try:
-            tmp = socket.getaddrinfo(addr, 'www')
+            tmp = socket.getaddrinfo(addr, 80)
         except socket.gaierror:
             return []
 
@@ -123,10 +123,9 @@ class Server(host.Host):
 
         return results
 
-
     def BindToAddress(self, addr):
-        """Add an address to listen to.
-        An empty string indicated you want to listen on all addresses.
+        """Add an address to listen on a specific interface.
+        String "0.0.0.0" indicates you want to listen on all interfaces.
 
         :param addr: IP address to listen on
         :type  addr: string
@@ -151,7 +150,6 @@ class Server(host.Host):
                 coafd.bind((address, self.coaport))
                 self.coafds.append(coafd)
 
-
     def HandleAuthPacket(self, pkt):
         """Authentication packet handler.
         This is an empty function that is called when a valid
@@ -247,7 +245,6 @@ class Server(host.Host):
         :type  pkt: Packet class instance
         """
         self._AddSecret(pkt)
-        pkt.secret = self.hosts[pkt.source[0]].secret
         if pkt.code == packet.CoARequest:
             self.HandleCoaPacket(pkt)
         elif pkt.code == packet.DisconnectRequest:
@@ -255,7 +252,6 @@ class Server(host.Host):
         else:
             raise ServerPacketError('Received non-coa packet on coa port')
 
-
     def _GrabPacket(self, pktgen, fd):
         """Read a packet from a network connection.
         This method assumes there is data waiting for to be read.