base.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453
  1. # -*- encoding: utf8 -*-
  2. #
  3. # The Qubes OS Project, http://www.qubes-os.org
  4. #
  5. # Copyright (C) 2017 Marek Marczykowski-Górecki
  6. # <marmarek@invisiblethingslab.com>
  7. #
  8. # This program is free software; you can redistribute it and/or modify
  9. # it under the terms of the GNU Lesser General Public License as published by
  10. # the Free Software Foundation; either version 2 of the License, or
  11. # (at your option) any later version.
  12. #
  13. # This program is distributed in the hope that it will be useful,
  14. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16. # GNU Lesser General Public License for more details.
  17. #
  18. # You should have received a copy of the GNU Lesser General Public License along
  19. # with this program; if not, see <http://www.gnu.org/licenses/>.
  20. '''Base classes for managed objects'''
  21. import qubesadmin.exc
  22. DEFAULT = object()
  23. class PropertyHolder(object):
  24. '''A base class for object having properties retrievable using mgmt API.
  25. Warning: each (non-private) local attribute needs to be defined at class
  26. level, even if initialized in __init__; otherwise will be treated as
  27. property retrievable using mgmt call.
  28. '''
  29. #: a place for appropriate Qubes() object (QubesLocal or QubesRemote),
  30. # use None for self
  31. app = None
  32. def __init__(self, app, method_prefix, method_dest):
  33. #: appropriate Qubes() object (QubesLocal or QubesRemote), use None
  34. # for self
  35. self.app = app
  36. self._method_prefix = method_prefix
  37. self._method_dest = method_dest
  38. self._properties = None
  39. self._properties_help = None
  40. self._properties_cache = {}
  41. def qubesd_call(self, dest, method, arg=None, payload=None,
  42. payload_stream=None):
  43. '''
  44. Call into qubesd using appropriate mechanism. This method should be
  45. defined by a subclass.
  46. Only one of `payload` and `payload_stream` can be specified.
  47. :param dest: Destination VM name
  48. :param method: Full API method name ('admin...')
  49. :param arg: Method argument (if any)
  50. :param payload: Payload send to the method
  51. :param payload_stream: file-like object to read payload from
  52. :return: Data returned by qubesd (string)
  53. '''
  54. if dest is None:
  55. dest = self._method_dest
  56. # have the actual implementation at Qubes() instance
  57. if self.app:
  58. return self.app.qubesd_call(dest, method, arg, payload,
  59. payload_stream)
  60. raise NotImplementedError
  61. @staticmethod
  62. def _parse_qubesd_response(response_data):
  63. '''Parse response from qubesd.
  64. In case of success, return actual data. In case of error,
  65. raise appropriate exception.
  66. '''
  67. if response_data == b'':
  68. raise qubesadmin.exc.QubesDaemonNoResponseError(
  69. 'Got empty response from qubesd. See journalctl in dom0 for '
  70. 'details.')
  71. if response_data[0:2] == b'\x30\x00':
  72. return response_data[2:]
  73. if response_data[0:2] == b'\x32\x00':
  74. (_, exc_type, _traceback, format_string, args) = \
  75. response_data.split(b'\x00', 4)
  76. # drop last field because of terminating '\x00'
  77. args = [arg.decode() for arg in args.split(b'\x00')[:-1]]
  78. format_string = format_string.decode('utf-8')
  79. exc_type = exc_type.decode('ascii')
  80. try:
  81. exc_class = getattr(qubesadmin.exc, exc_type)
  82. except AttributeError:
  83. if exc_type.endswith('Error'):
  84. exc_class = __builtins__.get(exc_type,
  85. qubesadmin.exc.QubesException)
  86. else:
  87. exc_class = qubesadmin.exc.QubesException
  88. # TODO: handle traceback if given
  89. raise exc_class(format_string, *args)
  90. raise qubesadmin.exc.QubesDaemonCommunicationError(
  91. 'Invalid response format')
  92. def property_list(self):
  93. '''
  94. List available properties (their names).
  95. :return: list of strings
  96. '''
  97. if self._properties is None:
  98. properties_str = self.qubesd_call(
  99. self._method_dest,
  100. self._method_prefix + 'List',
  101. None,
  102. None)
  103. self._properties = properties_str.decode('ascii').splitlines()
  104. # TODO: make it somehow immutable
  105. return self._properties
  106. def property_help(self, name):
  107. '''
  108. Get description of a property.
  109. :return: property help text
  110. '''
  111. help_text = self.qubesd_call(
  112. self._method_dest,
  113. self._method_prefix + 'Help',
  114. name,
  115. None)
  116. return help_text.decode('ascii')
  117. def property_is_default(self, item):
  118. '''
  119. Check if given property have default value
  120. :param str item: name of property
  121. :return: bool
  122. '''
  123. if item.startswith('_'):
  124. raise AttributeError(item)
  125. # pre-fill cache if enabled
  126. if self.app.cache_enabled and not self._properties_cache:
  127. self._fetch_all_properties()
  128. # cached value
  129. if item in self._properties_cache:
  130. return self._properties_cache[item][0]
  131. # cached properties list
  132. if self._properties is not None and item not in self._properties:
  133. raise AttributeError(item)
  134. property_str = self.qubesd_call(
  135. self._method_dest,
  136. self._method_prefix + 'Get',
  137. item,
  138. None)
  139. is_default, value = self._deserialize_property(property_str)
  140. if self.app.cache_enabled:
  141. self._properties_cache[item] = (is_default, value)
  142. return is_default
  143. def property_get_default(self, item):
  144. '''
  145. Get default property value, regardless of the current value
  146. :param str item: name of property
  147. :return: default value
  148. '''
  149. if item.startswith('_'):
  150. raise AttributeError(item)
  151. property_str = self.qubesd_call(
  152. self._method_dest,
  153. self._method_prefix + 'GetDefault',
  154. item,
  155. None)
  156. if not property_str:
  157. raise AttributeError(item + ' has no default')
  158. (prop_type, value) = property_str.split(b' ', 1)
  159. return self._parse_type_value(prop_type, value)
  160. def clone_properties(self, src, proplist=None):
  161. '''Clone properties from other object.
  162. :param PropertyHolder src: source object
  163. :param list proplist: list of properties \
  164. (:py:obj:`None` or omit for all properties)
  165. '''
  166. if proplist is None:
  167. proplist = self.property_list()
  168. for prop in proplist:
  169. try:
  170. setattr(self, prop, getattr(src, prop))
  171. except AttributeError:
  172. continue
  173. def __getattr__(self, item):
  174. if item.startswith('_'):
  175. raise AttributeError(item)
  176. # pre-fill cache if enabled
  177. if self.app.cache_enabled and not self._properties_cache:
  178. self._fetch_all_properties()
  179. # cached value
  180. if item in self._properties_cache:
  181. value = self._properties_cache[item][1]
  182. if value is AttributeError:
  183. raise AttributeError(item)
  184. return value
  185. # cached properties list
  186. if self._properties is not None and item not in self._properties:
  187. raise AttributeError(item)
  188. try:
  189. property_str = self.qubesd_call(
  190. self._method_dest,
  191. self._method_prefix + 'Get',
  192. item,
  193. None)
  194. except qubesadmin.exc.QubesDaemonNoResponseError:
  195. raise qubesadmin.exc.QubesPropertyAccessError(item)
  196. is_default, value = self._deserialize_property(property_str)
  197. if self.app.cache_enabled:
  198. self._properties_cache[item] = (is_default, value)
  199. if value is AttributeError:
  200. raise AttributeError(item)
  201. return value
  202. def _deserialize_property(self, api_response):
  203. """
  204. Deserialize property.Get response format
  205. :param api_response: bytes, as retrieved from qubesd
  206. :return: tuple(is_default, value)
  207. """
  208. (default, prop_type, value) = api_response.split(b' ', 2)
  209. assert default.startswith(b'default=')
  210. is_default_str = default.split(b'=')[1]
  211. is_default = is_default_str.decode('ascii') == "True"
  212. value = self._parse_type_value(prop_type, value)
  213. return is_default, value
  214. def _parse_type_value(self, prop_type, value):
  215. '''
  216. Parse `type=... ...` qubesd response format. Return a value of
  217. appropriate type.
  218. :param bytes prop_type: 'type=...' part of the response (including
  219. `type=` prefix)
  220. :param bytes value: 'value' part of the response
  221. :return: parsed value
  222. '''
  223. # pylint: disable=too-many-return-statements
  224. prop_type = prop_type.decode('ascii')
  225. if not prop_type.startswith('type='):
  226. raise qubesadmin.exc.QubesDaemonCommunicationError(
  227. 'Invalid type prefix received: {}'.format(prop_type))
  228. (_, prop_type) = prop_type.split('=', 1)
  229. value = value.decode()
  230. if prop_type == 'str':
  231. return str(value)
  232. if prop_type == 'bool':
  233. if value == '':
  234. return AttributeError
  235. return value == "True"
  236. if prop_type == 'int':
  237. if value == '':
  238. return AttributeError
  239. return int(value)
  240. if prop_type == 'vm':
  241. if value == '':
  242. return None
  243. return self.app.domains.get_blind(value)
  244. if prop_type == 'label':
  245. if value == '':
  246. return None
  247. return self.app.labels.get_blind(value)
  248. raise qubesadmin.exc.QubesDaemonCommunicationError(
  249. 'Received invalid value type: {}'.format(prop_type))
  250. def _fetch_all_properties(self):
  251. """
  252. Retrieve all properties values at once using (prefix).property.GetAll
  253. method. If it succeed, save retrieved values in the properties cache.
  254. If the request fails (for example because of qrexec policy), do nothing.
  255. Exceptions when parsing received value are not handled.
  256. :return: None
  257. """
  258. def unescape(line):
  259. """Handle \\-escaped values, generates a list of character codes"""
  260. escaped = False
  261. for char in line:
  262. if escaped:
  263. assert char in (ord('n'), ord('\\'))
  264. if char == ord('n'):
  265. yield ord('\n')
  266. elif char == ord('\\'):
  267. yield char
  268. escaped = False
  269. elif char == ord('\\'):
  270. escaped = True
  271. else:
  272. yield char
  273. assert not escaped
  274. try:
  275. properties_str = self.qubesd_call(
  276. self._method_dest,
  277. self._method_prefix + 'GetAll',
  278. None,
  279. None)
  280. except qubesadmin.exc.QubesDaemonNoResponseError:
  281. return
  282. for line in properties_str.splitlines():
  283. # decode newlines
  284. line = bytes(unescape(line))
  285. name, property_str = line.split(b' ', 1)
  286. name = name.decode()
  287. is_default, value = self._deserialize_property(property_str)
  288. self._properties_cache[name] = (is_default, value)
  289. self._properties = list(self._properties_cache.keys())
  290. @classmethod
  291. def _local_properties(cls):
  292. '''
  293. Get set of property names that are properties on the Python object,
  294. and must not be set on the remote object
  295. '''
  296. if "_local_properties_set" not in cls.__dict__:
  297. props = set()
  298. for class_ in cls.__mro__:
  299. for key in class_.__dict__:
  300. props.add(key)
  301. cls._local_properties_set = props
  302. return cls._local_properties_set
  303. def __setattr__(self, key, value):
  304. if key.startswith('_') or key in self._local_properties():
  305. return super(PropertyHolder, self).__setattr__(key, value)
  306. if value is qubesadmin.DEFAULT:
  307. try:
  308. self.qubesd_call(
  309. self._method_dest,
  310. self._method_prefix + 'Reset',
  311. key,
  312. None)
  313. except qubesadmin.exc.QubesDaemonNoResponseError:
  314. raise qubesadmin.exc.QubesPropertyAccessError(key)
  315. else:
  316. if isinstance(value, qubesadmin.vm.QubesVM):
  317. value = value.name
  318. if value is None:
  319. value = ''
  320. try:
  321. self.qubesd_call(
  322. self._method_dest,
  323. self._method_prefix + 'Set',
  324. key,
  325. str(value).encode('utf-8'))
  326. except qubesadmin.exc.QubesDaemonNoResponseError:
  327. raise qubesadmin.exc.QubesPropertyAccessError(key)
  328. def __delattr__(self, name):
  329. if name.startswith('_') or name in self._local_properties():
  330. return super(PropertyHolder, self).__delattr__(name)
  331. try:
  332. self.qubesd_call(
  333. self._method_dest,
  334. self._method_prefix + 'Reset',
  335. name
  336. )
  337. except qubesadmin.exc.QubesDaemonNoResponseError:
  338. raise qubesadmin.exc.QubesPropertyAccessError(name)
  339. class WrapperObjectsCollection(object):
  340. '''Collection of simple named objects'''
  341. def __init__(self, app, list_method, object_class):
  342. '''
  343. Construct manager of named wrapper objects.
  344. :param app: Qubes() object
  345. :param list_method: name of API method used to list objects,
  346. must return simple "one name per line" list
  347. :param object_class: object class (callable) for wrapper objects,
  348. will be called with just two arguments: app and a name
  349. '''
  350. self.app = app
  351. self._list_method = list_method
  352. self._object_class = object_class
  353. #: names cache
  354. self._names_list = None
  355. #: returned objects cache
  356. self._objects = {}
  357. def clear_cache(self):
  358. '''Clear cached list of names'''
  359. self._names_list = None
  360. def refresh_cache(self, force=False):
  361. '''Refresh cached list of names'''
  362. if not force and self._names_list is not None:
  363. return
  364. list_data = self.app.qubesd_call('dom0', self._list_method)
  365. list_data = list_data.decode('ascii')
  366. assert list_data[-1] == '\n'
  367. self._names_list = [str(name) for name in list_data[:-1].splitlines()]
  368. for name, obj in list(self._objects.items()):
  369. if obj.name not in self._names_list:
  370. # Object no longer exists
  371. del self._objects[name]
  372. def __getitem__(self, item):
  373. if not self.app.blind_mode and item not in self:
  374. raise KeyError(item)
  375. return self.get_blind(item)
  376. def get_blind(self, item):
  377. '''
  378. Get a property without downloading the list
  379. and checking if it's present
  380. '''
  381. if item not in self._objects:
  382. self._objects[item] = self._object_class(self.app, item)
  383. return self._objects[item]
  384. def __contains__(self, item):
  385. self.refresh_cache()
  386. return item in self._names_list
  387. def __iter__(self):
  388. self.refresh_cache()
  389. for key in self._names_list:
  390. yield key
  391. def keys(self):
  392. '''Get list of names.'''
  393. self.refresh_cache()
  394. return list(self._names_list)
  395. def items(self):
  396. '''Get list of (key, value) pairs'''
  397. self.refresh_cache()
  398. return [(key, self.get_blind(key)) for key in self._names_list]
  399. def values(self):
  400. '''Get list of objects'''
  401. self.refresh_cache()
  402. return [self.get_blind(key) for key in self._names_list]