openc2lib.types.basetypes

  1""" OpenC2 structures
  2
  3	Definition of the base types (structures) in the OpenC2 DataModels (Sec. 3.1.1)
  4	Each OpenC2 object must derive from these classes, which
  5	affects serialization operations
  6
  7"""
  8
  9import aenum
 10import inspect
 11import logging
 12
 13logger = logging.getLogger('openc2lib')
 14""" openc2lib logger """
 15
 16
 17class Openc2Type():
 18	""" OpenC2 Language Element
 19		
 20		This class is currently unused and is only provided to have a common ancestor for all
 21		OpenC2 basic types. It may be used in the future to implement common methods or arguments.
 22	"""
 23	pass
 24
 25
 26#@register_basetype
 27class Record(Openc2Type):
 28	""" OpenC2 Record
 29
 30		Implements OpenC2 Record: 
 31			>An ordered map from a list of keys with positions to values with 
 32			positionally-defined semantics. Each key has a position and name, 
 33			and is mapped to a type.
 34
 35		It expect keys to be public class attributes. All internal attributes 
 36		must be kept private by prefixing it with an '_'.
 37
 38	"""
 39	def todict(self, e):
 40		""" Converts to dictionary 
 41		
 42			It is used to convert this object to an intermediary representation during 
 43			serialization. It takes an `Encoder` argument that is used to recursively
 44			serialize inner data and structures (the `Encoder` provides standard methods
 45			for converting base types to dictionaries).. 
 46
 47			:param e: The `Encoder` that is being used.
 48			:return: A dictionary compliants to the Language Specification's serialization
 49			rules.
 50		"""
 51		objdic = vars(self)
 52
 53		dic = {}
 54		for k,v in objdic.items():
 55			# Fix keywords corresponding to variable names that clash with Python keywords
 56			if isinstance(k, str) and k.endswith('_'):
 57				k = k.rstrip('_')
 58			# Remove empty and private elements; do not include non-string keys
 59			if not v is None and not k.startswith('_') and isinstance(k, str):
 60				dic[k] = v	
 61
 62		return e.todict(dic)
 63
 64	@classmethod
 65	def fromdict(clstype, dic, e):
 66		""" Builds instance from dictionary 
 67
 68			It is used during deserialization to create an openc2lib instance from the text message.
 69			It takes an `Encoder` instance that is used to recursively build instances of the inner
 70			objects (the `Encoder` provides standard methods to create instances of base objects like
 71			strings, integers, boolean).
 72
 73			:param dic: The intermediary dictionary representation from which the object is built.
 74			:param e: The `Encoder that is being used.
 75			:return: An instance of this class initialized from the dictionary values.
 76		"""
 77		objdic = {}
 78		# Retrieve class type for each field in the dictionary
 79		fielddesc = None
 80		for tpl in inspect.getmembers(clstype):
 81			if tpl[0] == '__annotations__':
 82				fielddesc = tpl[1]
 83
 84		for k,v in dic.items():
 85			if k not in fielddesc:
 86				raise Exception("Unknown field '" + k + "' from message")
 87			objdic[k] = e.fromdict(fielddesc[k], v)
 88
 89
 90		# A record should always have more than one field, so the following statement 
 91		# should not raise exceptions
 92		return clstype(**objdic)
 93
 94
 95
 96class Choice(Openc2Type):
 97	""" OpenC2 Choice
 98		Implements the OpenC2 Choice:
 99		>One field selected from a set of named fields. The API value has a name and a type.
100
101		It expect all allowed values to be provided in a `Register` class, which must be defined
102		as class attribute `register` in all derived classes (see `Target` and `Actuator` as examples).
103	"""
104	register = None
105	""" List of registered name/class options available """
106
107	def __init__(self, obj):
108		""" Initialize the `Choice` object
109
110			Objects used as `Choice` must be registered in advance in the `register` dictionary.
111
112			:arg obj: An object among those defined in the `register`.
113		"""
114		self.choice: str = self.register.getName(obj.__class__)
115		""" Selected name for the `Choice` """
116		self.obj = obj
117		""" Class corresponding to the `choice` """
118
119	def getObj(self):
120		""" Returns the objet instance embedded in the `register`."""
121		return self.obj
122	
123	def getName(self):
124		"""Returns the name of the choice
125
126			Returns the name of object, which is the selector carried by the `Choice` element. 
127			This does not include the object itself.
128		"""
129		return self.choice
130
131	@classmethod
132	def getClass(cls, choice):
133		""" Get the class corresponding to the current `choice` 
134			
135			It may be implemented by any derived class, if a different logic than the `Register` class 
136			is followed to store the name/class bindings.
137			:param choice: The name of the alternative that is being looked for.
138			:return: The class corresponding to the provided `choice`.
139		"""
140		return cls.register.get(choice)
141
142	def __str__(self):
143		return self.choice
144
145	def __repr__(self):
146		return str(self.obj)
147
148	def todict(self, e):
149		""" Converts to dictionary 
150		
151			It is used to convert this object to an intermediary representation during 
152			serialization. It takes an `Encoder` argument that is used to recursively
153			serialize inner data and structures (the `Encoder` provides standard methods
154			for converting base types to dictionaries).. 
155
156			:param e: The `Encoder` that is being used.
157			:return: A dictionary compliants to the Language Specification's serialization
158			rules.
159		"""
160		# In case of Choice, the specific choice may be the implementation of an additional type,
161		# which affects its representation. So, first of all, get the representation of the inner
162		# data type
163		dic = {}
164		dic[self.choice] = e.todict(self.obj)
165		return dic
166
167	@classmethod
168	def fromdict(cls, dic, e):
169		""" Builds instance from dictionary 
170
171			It is used during deserialization to create an openc2lib instance from the text message.
172			It takes an `Encoder` instance that is used to recursively build instances of the inner
173			objects (the `Encoder` provides standard methods to create instances of base objects like
174			strings, integers, boolean).
175
176			:param dic: The intermediary dictionary representation from which the object is built.
177			:param e: The `Encoder that is being used.
178			:return: An instance of this class initialized from the dictionary values.
179		"""
180		if not len(dic) == 1:
181			raise ValueError("Unexpected dict: ", dic)
182
183		for k, v in dic.items():
184			# Expected to run one time only!
185			objtype = cls.getClass(k)
186			return cls(e.fromdict(objtype, v))
187
188class Enumerated(Openc2Type, aenum.Enum):
189	""" OpenC2 Enumerated
190
191		Implements OpenC2 Enumerated:
192		>A set of named integral constants. The API value is a name.
193
194		The constants may be anything, including strings, integers, classes.
195	"""
196
197	# Convert enumerations to str
198	def todict(self, e):
199		""" Converts to dictionary 
200		
201			It is used to convert this object to an intermediary representation during 
202			serialization. It takes an `Encoder` argument that is used to recursively
203			serialize inner data and structures (the `Encoder` provides standard methods
204			for converting base types to dictionaries).. 
205
206			:param e: The `Encoder` that is being used.
207			:return: A dictionary compliants to the Language Specification's serialization
208			rules.
209		"""
210		return self.name
211
212	@classmethod
213	def fromdict(cls, dic, e):
214		""" Builds instance from dictionary 
215
216			It is used during deserialization to create an openc2lib instance from the text message.
217			It takes an `Encoder` instance that is used to recursively build instances of the inner
218			objects (the `Encoder` provides standard methods to create instances of base objects like
219			strings, integers, boolean).
220
221			:param dic: The intermediary dictionary representation from which the object is built.
222			:param e: The `Encoder that is being used.
223			:return: An instance of this class initialized from the dictionary values.
224		"""
225		try:
226			return cls[str(dic)]
227		except:
228			raise TypeError("Unexpected enum value: ", dic)
229	
230# This class should check the names are integers.
231# The enum syntax only allows to define <str = int> pairs,
232# so to use this class it is necessary to define mnemonic label
233# TODO: Test this code
234class EnumeratedID(Enumerated):
235	""" OpenC2 EnumeratedID
236
237		Implements OpenC2 EnumeratedID: 
238		>A set of unnamed integral constants. The API value is an id.
239
240		The current implementation does not check the values to be integer.
241		However, coversion to/from integer is explicitly done during the
242		intermediary dictionary serialization, hence throwing an Exception if
243		the IDs are not integers.
244	"""
245
246	def todict(self, e):
247		""" Converts to dictionary 
248		
249			It is used to convert this object to an intermediary representation during 
250			serialization. It takes an `Encoder` argument that is used to recursively
251			serialize inner data and structures (the `Encoder` provides standard methods
252			for converting base types to dictionaries).. 
253
254			:param e: The `Encoder` that is being used.
255			:return: A dictionary compliants to the Language Specification's serialization
256			rules.
257		"""
258		return int(self.value)
259
260	@classmethod
261	def fromdict(cls, dic, e):
262		""" Builds instance from dictionary 
263
264			It is used during deserialization to create an openc2lib instance from the text message.
265			It takes an `Encoder` instance that is used to recursively build instances of the inner
266			objects (the `Encoder` provides standard methods to create instances of base objects like
267			strings, integers, boolean).
268
269			:param dic: The intermediary dictionary representation from which the object is built.
270			:param e: The `Encoder that is being used.
271			:return: An instance of this class initialized from the dictionary values.
272		"""
273		try:
274			return cls(int(dic))
275		except:
276			raise TypeError("Unexpected enum value: ", dic)
277
278class Array(Openc2Type, list):
279	""" OpenC2 Array
280
281		Implements OpenC2 Array:
282		>An ordered list of unnamed fields with positionally-defined semantics. 
283		Each field has a position, label, and type.
284
285		However, position does not matter in this implementation.
286
287		Derived classes must provide a `fieldtypes` dictionary that associate each field name
288		to its class. This is strictly required in order to instantiate the object at
289		deserialization time. However, no check is performed when new items are inserted.
290	"""
291	fieldtypes = None
292	""" Field types
293
294		A `dictionary` which keys are field names and which values are the corresponding classes.
295		Must be provided by any derived class.
296	"""
297
298	def todict(self, e):
299		""" Converts to dictionary 
300		
301			It is used to convert this object to an intermediary representation during 
302			serialization. It takes an `Encoder` argument that is used to recursively
303			serialize inner data and structures (the `Encoder` provides standard methods
304			for converting base types to dictionaries).. 
305
306			:param e: The `Encoder` that is being used.
307			:return: A dictionary compliants to the Language Specification's serialization
308			rules.
309		"""
310		lis = []
311		for i in self:
312			lis.append = e.todict(i)
313		return lis
314
315	def fromdict(cls, dic, e):
316		""" !!! WARNING !!!
317			Currently not implemented because there are no examples of usage of this
318			type (only Array/net, which is not clear)
319		"""
320		raise Exception("Function not implemented")
321
322class ArrayOf:
323	""" OpenC2 ArrayOf
324
325		Implements OpenC2 ArrayOf(*vtype*):
326		>An ordered list of fields with the same semantics. 
327		Each field has a position and type *vtype*.
328
329		It extends the `Array` type. However, to make its usage simpler and compliant 
330		to the description given in the
331		Language Specification, the implementation is quite different.
332		Note that in many cases `ArrayOf` is only used to create arrays without the need
333		to derive an additional data type.
334	"""
335
336	def __new__(self, fldtype):
337		""" `ArrayOf` builder
338
339			Creates a unnamed derived class from `Array`, which `fieldtypes` is set to `fldtype`.
340			:param fldtype: The type of the fields stored in the array (indicated as *vtype* in 
341					the Language Specification.
342			:return: A new unnamed class definition.
343		"""
344		class ArrayOf(Array):
345			""" OpenC2 unnamed `ArrayOf`
346
347				This class inherits from `Array` and sets its `fieldtypes` to a given type.
348		
349				One might like to check the type of the elements before inserting them.
350				However, this is not the Python-way. Python use the duck typing approach:
351				https://en.wikipedia.org/wiki/Duck_typing
352				We ask for the type of objects just to keep this information according to
353				the OpenC2 data model.
354
355				Note: no `todict()` method is provided, since `Array.todict()` is fine here.
356			"""
357			fieldtype = fldtype
358			""" The type of values stored in this container """
359
360			@classmethod
361			def fromdict(cls, lis, e):
362				""" Builds instance from dictionary 
363		
364					It is used during deserialization to create an openc2lib instance from the text message.
365					It takes an `Encoder` instance that is used to recursively build instances of the inner
366					objects (the `Encoder` provides standard methods to create instances of base objects like
367					strings, integers, boolean).
368		
369					:param lis: The intermediary dictionary representation from which the object is built.
370					:param e: The `Encoder that is being used.
371					:return: An instance of this class initialized from the dictionary values.
372				"""
373				objlis = cls()
374				logger.debug('Building %s from %s in ArrayOf', cls, lis)
375				logger.debug('-> instantiating: %s', cls.fieldtype)
376				for k in lis:
377					objlis.append(e.fromdict(cls.fieldtype, k))
378		
379				return objlis
380			
381			# This is the code if I would like to do type checking
382			# when inserting data
383#			def append(self, item):
384#				if isinstance(item, self.fieldtype):
385#					super().append(item)
386#				else:
387#					raise ValueError(self.fieldtype,' allowed only')
388#			
389#			def insert(self, index, item):
390#				if isinstance(item, self.fieldtype):
391#					super().insert(index, item)
392#				else:
393#					raise ValueError(self.fieldtype,' allowed only')
394#			
395#			def __add__(self, item):
396#				if isinstance(item, self.fieldtype):
397#					super().__add__(item)
398#				else:
399#					raise ValueError(self.fieldtype,' allowed only')
400#			
401#			def __iadd__(self, item):
402#				if isinstance(item, self.fieldtype):
403#					super().__iadd__(item)
404#				else:
405#					raise ValueError(self.fieldtype,' allowed only')
406
407		return ArrayOf
408
409
410class Map(Openc2Type, dict):
411	""" OpenC2 Map
412
413		Implements OpenC2 Map:
414		>An unordered map from a set of specified keys to values with semantics 
415			bound to each key. Each field has an id, name and type.
416
417		However, the id is not considered in this implementation.
418
419		The implementation follows a similar logic than `Array`. Each derived class
420		is expected to provide a `fieldtypes` class attribute that associate field names 
421		with their class definition. 
422		
423		Additionally, according to the Language Specification, `Map`s may be extended by
424		Profiles. Such extensions must use the `extend` and `regext` class attributes to 
425		bind to the base element they extend and the `Profile` in which they are defined.
426	"""
427	fieldtypes: dict = None
428	""" Field types
429
430		A `dictionary` which keys are field names and which values are the corresponding classes.
431		Must be provided by any derived class.
432	"""
433	extend = None
434	""" Base class
435
436		Data types defined in the Language Specification shall not set this field. Data types defined in
437		Profiles that extends a Data Type defined in the Language Specification, must set this field to
438		the corresponding class of the base Data Type.
439
440		Note: Extensions defined in the openc2lib context are recommended to use the same name of the base
441		Data Type, and to distinguish them through appropriate usage of the namespacing mechanism.
442	"""
443	regext = {}
444	""" Registered extensions
445
446		Classes that implement a Data Type defined in the Language Specification will use this field to
447		register extensions defined by external Profiles. Classes that define extensions within Profiles
448		shall register themselves according to the specific documentation of the base type class, but 
449		shall not modify this field.
450	"""
451
452	def todict(self, e):
453		""" Converts to dictionary 
454		
455			It is used to convert this object to an intermediary representation during 
456			serialization. It takes an `Encoder` argument that is used to recursively
457			serialize inner data and structures (the `Encoder` provides standard methods
458			for converting base types to dictionaries).. 
459
460			:param e: The `Encoder` that is being used.
461			:return: A dictionary compliants to the Language Specification's serialization
462			rules.
463		"""
464		newdic=dict()
465
466		# This is necessary because self.extend.fieldtypes does
467		# not exist for non-extended classes
468		if self.extend is None:
469			return e.todict(dict(self))
470			
471		for k,v in self.items():
472			if k not in self.fieldtypes:
473				raise ValueError('Unknown field: ', k)
474			if k in self.extend.fieldtypes:
475				newdic[k] = v
476			else:
477				if self.nsid not in newdic:
478					newdic[self.nsid]={}
479				newdic[self.nsid][k]=v
480			
481		return e.todict(newdic)
482
483	@classmethod
484	def fromdict(cls, dic, e):
485		""" Builds instance from dictionary 
486
487			It is used during deserialization to create an openc2lib instance from the text message.
488			It takes an `Encoder` instance that is used to recursively build instances of the inner
489			objects (the `Encoder` provides standard methods to create instances of base objects like
490			strings, integers, boolean).
491
492			:param dic: The intermediary dictionary representation from which the object is built.
493			:param e: The `Encoder that is being used.
494			:return: An instance of this class initialized from the dictionary values.
495		"""
496		objdic = {}
497		extension = None
498		logger.debug('Building %s from %s in Map', cls, dic)
499		for k,v in dic.items():
500			if k in cls.fieldtypes:
501				objdic[k] = e.fromdict(cls.fieldtypes[k], v)
502			elif k in cls.regext:
503				logger.debug('   Using profile %s to decode: %s', k, v)
504				extension = cls.regext[k]
505				for l,w in v.items():
506					objdic[l] = e.fromdict(extension.fieldtypes[l], w)
507			else:
508				raise TypeError("Unexpected field: ", k)
509
510		if extension is not None:
511			cls = extension
512
513		return cls(objdic)
514
515class MapOf:
516	""" OpenC2 MapOf
517
518		Implements OpenC2 MapOf(*ktype, vtype*):
519		>An unordered set of keys to values with the same semantics. 
520			Each key has key type *ktype* and is mapped to value type *vtype*.
521
522		It extends `Map` with the same approach already used for `ArrayOf`.
523		`MapOf` for specific types are created as anonymous classes by passing
524		`ktype` and `vtype` as arguments.
525
526		Note: `MapOf` implementation currently does not support extensins!.
527	"""
528
529	def __new__(self,ktype, vtype):
530		""" `MapOf` builder
531
532			Creates a unnamed derived class from `Map`, which `fieldtypes` is set to a single value
533		 	`ktype: vtype`.
534			:param ktype: The key type of the items stored in the map.
535			:param vtype: The value type of the items stored in the map.
536			:return: A new unnamed class definition.
537		"""
538		class MapOf(Map):
539			""" OpenC2 unnamed `MapOf`
540
541				This class inherits from `Map` and sets its `fieldtypes` to a given type.
542		
543				Note: no `todict()` method is provided, since `Map.todict()` is fine here.
544			"""
545			fieldtypes = {ktype: vtype}
546			""" The type of values stored in this container """
547
548			@classmethod
549			def fromdict(cls, dic, e):
550				""" Builds instance from dictionary 
551		
552					It is used during deserialization to create an openc2lib instance from the text message.
553					It takes an `Encoder` instance that is used to recursively build instances of the inner
554					objects (the `Encoder` provides standard methods to create instances of base objects like
555					strings, integers, boolean).
556		
557					:param dic: The intermediary dictionary representation from which the object is built.
558					:param e: The `Encoder that is being used.
559					:return: An instance of this class initialized from the dictionary values.
560				"""
561				objdic = {}
562				logger.debug('Building %s from %s in MapOf', cls, dic)
563				for k,v in dic.items():
564					kclass = list(cls.fieldtypes)[0]
565					objk = e.fromdict(kclass, k)
566					objdic[objk] = e.fromdict(cls.fieldtypes[kclass], v)
567				return objdic
568
569		return MapOf