(LOGO.JPG) Python for OpenVMS

(go to: table of contents, index, list of vms_sys, prev: GETUTC, next: GRANTID)


GET_SECURITY - Get Security Characteristics


Retrieves the security characteristics of an object.

vms_sys.get_security() does _not_ raise an exception when the SYS$GET_SECURITY routine returns an error. You must check 'status' in the dictionary that is returned.

Format:

    dict = vms_sys.get_security \
                  ([clsnam], [objnam], [objhan], [flags], \
                   [itmlst], [contxt] ,[acmode])
Returns:
dict
A dictionary that has the following keys:
'status'
the condition value returned from SYS$GET_SECURITY.
'contxt'
the context value if and only if the 'contxt' argument was specified.

It is only put into the dictionary, when SYS$GET_SECURITY returns a success status.

'OSS$_name'
Any output item that has been specified in the item-list and that is supported by SYS$GET_SECURITY.

It is only put into the dictionary, when SYS$GET_SECURITY returns a success status.

Warning! The dictionary can contain binary strings - do not use the print command to output them on the terminal!

Arguments:
clsnam
Name of the object class. E.g.: "FILE" or "QUEUE". Please see the system services reference manual for a complete list.
objnam
Name of the protected object whose associated security profile is going to be retrieved. See the system services reference manual for details.
objhan
"object handle" - this is a Python (32-bit) integer. Please see the system services reference manual for how this is passed.
@@ Argument not tested.
flags
Mask specifying processing options. Symbolic names (OSS_M_name) are available in module 'vms_ossdef'.
itmlst
Item list specifying which information about the object(s) is to be returned.
contxt
Value used to maintain the processing context when dealing with a single protected object across multiple vms_sys.get_security() or vms_sys.set_security() calls.

Don't forget to release the context after use - see the examples section below.

acmode
According to the documentation, this argument should not be used.
special notes about some item codes:
OSS$_ACCESS_NAMES
Returns a 'vmsobj__access_names' object.
OSS$_ACL_FIND_ENTRY
Expects a binary ACE. See the examples section below and the comments about 'ACL + ACE' in the 'programming' section of the 'General Manual'.
OSS$_ACL_FIND_NEXT
Internally, this is a 'boolean item' - you just specify the item code in the Python item list.
OSS$_ACL_FIND_TYPE
@@ Unknown. Not tested, yet.
OSS$_ACL_GRANT_ACE
You must check the status code - see the examples section below.
OSS$_ACL_POSITION_BOTTOM + OSS$_ACL_POSITION_TOP
Are boolean item codes like OSS$_ACL_FIND_NEXT, above.
OSS$_ACL_READ
Returns the entire ACL as a Python string. Note that the string contains binary data - do not print this to your terminal!
OSS$_ACL_READ_ENTRY
Returns a single ACE as a Python string. Note that the string contains binary data - do not print this to your terminal!
OSS$_OWNER
This is the object's owner UIC - a 32-bit Python integer.
OSS$_PROTECTION
This is the object's UIC-based protection code - a 16-bit value that is returned in a 32-bit Python integer.

No tests have been done with profile related item codes. Be aware that this system service is not very good documented (I have filed a complaint) and it does not fill in the returned length of several items. That is the reason that several 'converter functions' are defined in file VMSDEF_$OSSDEF.DAT

Examples:

$ copy _NLA0: ACL.DAT
$ set ACL ACL.DAT -
      /ACL= ( (default_protection, s:rwed, o:wd, g:r, w:e), -
              (alarm= security, options=default, access=write+failure), -
              (identifier= [1,4], access= read+write), -
              (identifier= [2,5], access= delete+execute), -
              (identifier= [3,6], access= control)          )
$!
$ directory /acl ACL.DAT

Directory DKA100:[PYTHON.PYTHON-1_5_2.VMS]

ACL.DAT;1
          (ALARM=SECURITY,OPTIONS=DEFAULT,ACCESS=WRITE+FAILURE)
          (DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:WD,GROUP:R,WORLD:E)
          (IDENTIFIER=[G1,SYSTEM],ACCESS=READ+WRITE)
          (IDENTIFIER=[2,5],ACCESS=EXECUTE+DELETE)
          (IDENTIFIER=[3,6],ACCESS=CONTROL)

Total of 1 file.
$!

----------------------------------------

----- get the entire ACL

>>> import vms_ossdef, vms_sys
>>> contxt = 0
>>> flags  = 0
>>> itmlst = (('OSS$_ACL_READ',),)
>>> dict = vms_sys.get_security ('FILE', 'ACL.DAT', None, \
...                              flags, itmlst, contxt)
>>>
>>> status = dict.get ('status')
>>> print vms_sys.getmsg (status) [0]
%SYSTEM-S-NORMAL, normal successful completion
>>>
>>> aclstr = dict.get ('OSS$_ACL_READ')
>>> print repr (aclstr)
'\020\006\002\001\002\000\000\000SECURITY\030\011\000\000
\000\000\000\000\020\000\000\000\025\000\000\000\036\000\
000\000\033\000\000\000\014\001\000\000\003\000\000\000\0
04\000\001\000\014\001\000\000\014\000\000\000\005\000\00
2\000\014\001\000\000\020\000\000\000\006\000\003\000'
>>>
>>> # release the context
>>> contxt = dict.get ('contxt')
>>> flags  = vms_ossdef.OSS_M_RELCTX
>>>
>>> dict   = vms_sys.get_security (None, None, None, flags, \
...                                None, contxt)
>>>
>>> status = dict.get ('status')
>>> print vms_sys.getmsg (status) [0]
%SYSTEM-S-NORMAL, normal successful completion
>>> contxt = dict.get ('contxt')
>>> print contxt
0        <-- context has been released
>>>

----- locate a particular ACE and read the one after it

>>> import vms_ossdef, vms_sys
>>>
>>> acetxt = '(IDENTIFIER=[1,4],ACCESS=READ+WRITE)'
>>> status, errpos, acestr = vms_sys.parse_acl (acetxt)
>>> print vms_sys.getmsg (status) [0]
%SYSTEM-S-NORMAL, normal successful completion
>>>
>>> contxt = 0
>>> flags  = 0
>>>
>>> itmlst = ( ('OSS$_ACL_FIND_ENTRY',acestr), \
...            ('OSS$_ACL_FIND_NEXT',),        \
...            ('OSS$_ACL_READ_ENTRY',)        )
>>>
>>> dict = vms_sys.get_security ('FILE', 'ACL.DAT', None, \
...                              flags, itmlst, contxt)
>>> status = dict.get ('status')
>>> print vms_sys.getmsg (status) [0]
%SYSTEM-S-NORMAL, normal successful completion
>>>
>>> acestr = dict.get ('OSS$_ACL_READ_ENTRY')
>>> print vms_sys.format_acl (acestr, 90, '*', 2)
(1, '  (IDENTIFIER=[2,5],ACCESS=EXECUTE+DELETE)')
>>>
>>> # release the context
>>> contxt = dict.get ('contxt')
>>> flags  = vms_ossdef.OSS_M_RELCTX
>>>
>>> dict   = vms_sys.get_security (None, None, None, flags, \
...                                None, contxt)
>>>
>>> status = dict.get ('status')
>>> print vms_sys.getmsg (status) [0]
%SYSTEM-S-NORMAL, normal successful completion
>>> contxt = dict.get ('contxt')
>>> print contxt
0        <-- context has been released
>>>

----- try to find out if an ACE grants or denies access

>>> import vms_ossdef, vms_sys
>>>
>>> contxt = 0
>>> flags  = 0
>>> itmlst = ( ('OSS$_ACL_GRANT_ACE',),)
>>>
>>> dict   = vms_sys.get_security ('FILE', 'ACL.DAT', None, \
...                                flags, itmlst, contxt)
>>>
>>> status = dict.get ('status')
>>> print vms_sys.getmsg (status) [0]
%SYSTEM-W-NOENTRY, access control entry not found
>>>
>>> contxt = dict.get ('contxt')
>>> print contxt
0        <-- no context was established
>>>

(go to: table of contents, index, list of vms_sys, prev: GETUTC, next: GRANTID)

19-JUL-1999 ZE.