This document describes the utility "ADASCR".
The following topics are covered:
The security utility ADASCR creates, modifies and deletes file protection levels and user passwords, and enables the security capabilities of individual passwords. Additionally, the utility is used to display file and password security information. The output of the export functionality of ADASCR can be used to apply some of all of the security definitions of a database to another database.
Access to this utility should be strictly limited to the person or persons responsible for database security (DBA).
Multiple functions may be specified within a single run of ADASCR. There is no restriction on the number of functions which may be specified.
The affected database(s) must be online.
All updates resulting from ADASCR take effect immediately.
This utility is a multi-function utility.
Note:
To copy existing security definitions from one hardware architecture
or operating system to another you must use the EXPORT control parameter. You
cannot copy the security definitions from one hardware architecture to another
by using ADAULD/ADADCU and ADACMP/ADAMUP - this is because the data stored in
the security file are stored in a platform-dependent internal format.
| Data Set | Logical Name/ Environment variable |
Storage Medium | Additional Information |
|---|---|---|---|
| Control Statements | stdin/ SYS$INPUT |
Utilities Manual | |
| ADASCR Messages | stdout/ SYS$OUTPUT |
Messages and Codes | |
| Exported Security Definitions | SCROUT | Disk | Utilities Manual |
The utility writes no checkpoints.
The following control parameters are available:
CHANGE {=|:} (string, string)
M DBID = number
DELETE = string
DISPLAY = [PASSWORDS,
PERMISSIONS, PASSWORD = {* | string} |
FILE = {* | (number[-number][,number[-number]]...)} |
VALUE_CRITERIA, PASSWORD = {* | string}]
EXPORT = {PASSWORDS,
D [TARGET_ARCHITECTURE = KEYWORD,]
PASSWORD = {* | string} |
PROTECTIONS,
D [TARGET_ARCHITECTURE = KEYWORD,]
FILE = {* | (number[-number][,number[-number]]...)} |
VALUE_CRITERIA,
D [TARGET_ARCHITECTURE = KEYWORD,]
FILE = {* | (number[-number][,number[-number]]...)}
PASSWORD = {* | string}}
INSERT {=|:} string, FILE = (number[-number][,number[-number]]...)
,ACCESS = (number[,number]...)
,UPDATE = (number[,number]...)
PROTECT = (number[-number][,number[-number]]...)
,ACCESS = (number[,number]...)
,UPDATE = (number[,number]...)
SECURITY_BY_VALUE {=|:} string, FILE = number
,ACCESS_CRITERION
,SEARCH_BUFFER = string *
,VALUE_BUFFER = string *
,UPDATE_CRITERION
,SEARCH_BUFFER = string *
,VALUE_BUFFER = string *
*The search/access buffer string parameters must be followed by <Newline> with no preceding comma.
CHANGE {=|:} (string, string)
This function changes an existing password.
The password specified by the first string must be an existing password.
The value specified by the second string must not be the same as an existing password. A password may be between 1 and 8 characters long. If less than 8 characters are specified, trailing blanks are added. The password may not contain any special characters or embedded blanks.
If you specify an equals sign, the value given for 'string' will be converted to upper case; if you specify a colon, no upper-case conversion is performed.
All entries in effect for the password specified by the first string remain in effect for the new password.
adascr: change = (oldpw1,newpw1)
The password OLDPW1 is changed to NEWPW1.
DBID = number
This parameter selects the current database.
Note:
The nucleus must be running.
adascr: dbid = 155
The database currently being used is database 155.
DELETE = string
This function deletes the existing password specified by the string, together with its associated permission levels and Security by Value criteria.
adascr: delete = userpw1
The password USERPW1 is deleted.
DISPLAY = [PASSWORDS |
PERMISSIONS, PASSWORD = {* | string} |
PROTECTIONS,
FILE = {* | (number[-number][,number[-number]]...)} |
VALUE_CRITERIA, PASSWORD = {* | string}]
This function shows current security information for files and passwords, as defined by the ADASCR utility.
Details of file protection levels, passwords, password permission levels and Security by Value criteria may be displayed.
The FILE parameter provides the list, range or ranges of files for which the preceding DISPLAY function is to be applied.
The PASSWORDS parameter prints a list of the passwords currently contained in the security file in ascending, alphanumeric sequence.
adascr: display = passwords
List of defined passwords for Database 155 ("ALPHA-TS")
FORTYTWO
G6MON
USERPW1
VOYAGER
Total of 4 defined passwords
The PERMISSIONS parameter prints a list of the access and update capabilities of the specified password for each currently loaded file, by comparing the password permission information against the current file protection levels.
Where respective access or update capability is granted, this is shown by the letter Y; conversely, where the capability is not granted, this is shown by the letter N.
Where access or update permissions for a given file are granted and additional Security by Value restrictions apply to that file, this is indicated by enclosing brackets, i.e. (Y).
adascr: display = permissions, password = fortytwo Password : "FORTYTWO" FILE | ACCESS | UPDATE -----|--------|------- 1 | N | N 2 | Y | N 3 | N | N 4 | N | (Y) 6 | Y | Y 10 | (Y) | (Y) -----|--------|------- ( ) Further value restrictions apply where brackets shown.
The PROTECTIONS parameter prints file protection information for the specified range of files, irrespective of whether or not the files specified are currently loaded.
display = protections, file = (4-10) FILE | ACCESS | UPDATE -----|--------|------- 4 | 1 | 3 6 | 0 | 0 10 | 3 | 6 -----|--------|-------
The VALUE_CRITERIA parameter prints all Security by Value criteria currently defined for the specified password.
display = value_criteria, password = * Password : "FORTYTWO" | File | Security by Value criterion |-------|----------------------------------------------------- | 4 | ACCESS_CRITERION | | SEARCH_BUFFER=. | | VALUE_BUFFER= | | UPDATE_CRITERION | | SEARCH_BUFFER=AA,4,A,GE. | | VALUE_BUFFER=LENA | 10 | ACCESS_CRITERION | | SEARCH_BUFFER=CA,4,U,LT. | | VALUE_BUFFER=1707 | | UPDATE_CRITERION | | SEARCH_BUFFER=CA,4,S,CA,4,D,AA,O,AA. | | VALUE_BUFFER=01001599MS |-------|----------------------------------------------------- Password : "G6MON" | File | Security by Value criterion |-------|----------------------------------------------------- | 4 | ACCESS_CRITERION | | SEARCH_BUFFER=. | | VALUE_BUFFER= | | UPDATE_CRITERION | | SEARCH_BUFFER=AA,3. | | VALUE_BUFFER=HAM |-------|----------------------------------------------------- No value criteria defined for password "USERPWD1". No value criteria defined for password "VOYAGER".
EXPORT = {PASSWORDS,
[TARGET_ARCHITECTURE = keyword,]
PASSWORD = {* | string} |
PROTECTIONS,
[TARGET_ARCHITECTURE = keyword,]
FILE = {* | (number[-number][,number[-number]]...)} |
VALUE_CRITERIA,
[TARGET_ARCHITECTURE = keyword,]
FILE = {* | (number[-number][,number[-number]]...)},
PASSWORD = {* | string}}
This function exports the current security settings (password definitions, file protection levels and security by value criteria) to the sequential file SCROUT. The output in the file SCROUT can be used as ADASCR input in order to import the security definitions into another database.
The security definitions may be exported either in mainframe syntax to import them on to mainframe platforms or in open systems syntax to import them on to open systems platforms.
The following examples for the EXPORT parameter assume that the following security definitions have already been made:
INSERT=MYSECRET,FILE=(9,12,13),ACCESS=(7,2,4),UPDATE=(11,2,4) PROTECT=9,ACCESS=7,UPDATE=11 PROTECT=12,ACCESS=2,UPDATE=2 PROTECT=13,ACCESS=4,UPDATE=4 SECURITY_BY_VALUE=MYSECRET,FILE=13,ACCESS_CRITERION,SEARCH_BUFFER=B0,GE. VALUE_BUFFER=0x01000000 UPDATE_CRITERION,SEARCH_BUFFER=B0,3,GE. VALUE_BUFFER=0xFF0201 SECURITY_BY_VALUE=MYSECRET,FILE=12,ACCESS_CRITERION,SEARCH_BUFFER=AM,3,GE. VALUE_BUFFER=0x33000C UPDATE_CRITERION,SEARCH_BUFFER=AM,3,GE. VALUE_BUFFER=0x50000C SECURITY_BY_VALUE=MYSECRET,FILE=9,ACCESS_CRITERION,SEARCH_BUFFER=AZ,2,GE. VALUE_BUFFER=FR UPDATE_CRITERION,SEARCH_BUFFER=AH,8,GE,D,AH,8,LE,D,AA,8,LE. VALUE_BUFFER=195201011952020160000000
PASSWORDS,
TARGET_ARCHITECTURE = keyword,
PASSWORD = {*|string}
The PASSWORDS parameter exports password permission levels (access and update) and the associated file or file list for the given password/passwords.
The TARGET_ARCHITECTURE parameter defines the syntax of the target platform. The following keywords can be used:
| Keyword | Meaning |
|---|---|
| MAINFRAME | Export the defined password/passwords in mainframe syntax. |
| OPEN_SYSTEMS | Export the defined password/passwords in open systems syntax. |
The default TARGET_ARCHITECTURE is OPEN_SYSTEMS.
The PASSWORD parameter specifies the password for the security settings have to be exported. It is also possible to export all defined passwords in the database - this can be done by specifying an asterisk for this parameter.
adascr: export = passwords, target_architecture = open_systems adascr: password = mysecret
This results in the following output for SCROUT:
INSERT=MYSECRET,FILE=(9,12,13),ACCESS=(7,2,4),UPDATE=(11,2,4)
adascr: export = passwords, target_architecture = mainframe, password = mysecret
This results in the following output for SCROUT:
ADASCR INSERT PW=MYSECRET,FILE=9,12,13,ACC=7,2,4,UPD=11,2,4
PROTECTIONS,
TARGET_ARCHITECTURE = keyword,
FILE = {*|(number[-number][,number[-number]]…)}
The PROTECTIONS parameter exports the protection levels of the given file, file range or ranges.
The TARGET_ARCHITECTURE parameter defines the syntax of the target platform. The following keywords can be used:
| Keyword | Meaning |
|---|---|
| MAINFRAME | Export the defined password/passwords in mainframe syntax. |
| OPEN_SYSTEMS | Export the defined password/passwords in open systems syntax. |
The default TARGET_ARCHITECTURE is OPEN_SYSTEMS.
The FILE parameter specifies the files for which protection levels are to be exported.
adascr: export = protections, target_architecture = open_systems, file = (9,12,13)
This results in the following output for SCROUT:
PROTECT=(9,12,13),ACCESS=(7,2,4),UPDATE=(11,2,4)
adascr: export = protections, target_architecture = mainframe, file = (9,12,13)
This results in the following output for SCROUT:
ADASCR PROTECT FILE=9,12,13,ACC=7,2,4,UPD=11,2,4
VALUE_CRITERIA,
TARGET_ARCHITECTURE = (keyword [,keyword]),
FILE = {*|(number[-number][,number[-number]]…)},
PASSWORD = {*|string}
The VALUE_CRITERIA parameter exports defined security-by-value settings for a specific file, for the password specified by ‘string’.
The TARGET_ARCHITECTURE parameter defines the syntax and also the byte order of the target platform. The following keywords can be used:
| Keyword Group | Valid Keywords |
|---|---|
| Syntax | MAINFRAME OPEN_SYSTEMS |
| Byte Order | HIGH_ORDER_BYTE_FIRST LOW_ORDER_BYTE_FIRST |
The default TARGET_ARCHITECTURE is OPEN_SYSTEMS.
The default byte order corresponds to the architecture of the machine on which ADASCR is running.
Note:
If you export security-by-value definitions from open systems to
mainframe platforms, a warning will be issued if the search buffer contains
W-formatted fields. This is because W-formatted fields are not supported on
mainframe platforms in security-by-value definitions. Any search buffer that
contains W-formatted fields will not be exported.
The FILE parameter specifies the file list or range(s) of files for which security-by-value definitions are to be exported. Multiple specifications of the same file number are not permitted.
The PASSWORD parameter specifies the password for which security-by-value definitions are to be exported. If you specify an asterisk, the export will be for all defined passwords.
adascr: export = value_criteria adascr: target_architecture = (open_systems, low_order_byte_first) adascr: file = 9 adascr: password = mysecret
This results in the following output for SCROUT:
SECURITY_BY_VALUE=MYSECRET,FILE=9,ACCESS_CRITERION,SEARCH_BUFFER=AH,8,GE. VALUE_BUFFER=19520130 UPDATE_CRITERION,SEARCH_BUFFER=AH,8,GE,D,AH,8,LE,D,AA,8,LE. VALUE_BUFFER=195201011952020160000000
adascr: export = value_criteria adascr: target_architecture = mainframe adascr: file = 9 adascr: password = mysecret
This results in the following output for SCROUT:
ADASCR SBYVALUE PW=MYSECRET,FILE=9, CRITACC=’A=AH,GE.’, VALACC=’19520130’, CRITUPD=’A=AH,GE,D,AH,LE,D,AA,LE.’, VALUPD=’19520101,19520201,A(60000000)’
This example shows how to export of existing security settings of a Windows Adabas database 33 in order to subsequently import them into a Unix Adabas database 34.
The export function of ADASCR is used as follows:
set SCROUT=scrout.txt adascr adascr: db=33 adascr: export=passwords,password=MYSECRET adascr: export=protections, file=(9,12,13) adascr: export=VALUE_CRITERIA,target_architecture=(open_systems, high_order_byte_first),file=(9,12,13),password=MYSECRET
The file “scrout.txt” can now be edited as required, for example, to secure more files other than the ones exported with the given password.
Now copy the exported text file “scrout.txt” to the desired target platform, in this case to a Unix platform. Import the exported security settings using ADASCR with the following statement:
adascr db=34 + < scrout.txt %ADASCR-I-DBON, database 34 accessed online %ADASCR-I-PWINS, password "MYSECRET" inserted %ADASCR-I-FILPRO, protections (access 7, update 11) set for file 9 %ADASCR-I-FILPRO, protections (access 2, update 2) set for file 12 %ADASCR-I-FILPRO, protections (access 4, update 4) set for file 13 %ADASCR-I-SEVINS, Value criteria for file 13 added to password "MYSECRET" %ADASCR-I-SEVINS, Value criteria for file 12 added to password "MYSECRET" %ADASCR-I-SEVINS, Value criteria for file 9 added to password "MYSECRET"
You can check the imported security settings with the DISPLAY control parameter of ADASCR:
adascr
adascr: dbid=34 display=passwords
List of defined passwords for Database 34 ("GENERAL_DATABASE")
MYSECRET
Total of 1 defined password
adascr: dbid=34 display=permissions,password=MYSECRET
password : "MYSECRET"
FILE | ACCESS | UPDATE
-----------------------
1 | Y | Y
2 | Y | Y
3 | Y | Y
9 | (Y) | (Y)
11 | N | N
12 | (Y) | (Y)
13 | (Y) | (Y)
14 | N | N
-----------------------
( ) Further value restrictions apply where brackets shown.
Adascr: db=34 display=protections,file=(9,12,13)
FILE | ACCESS | UPDATE
-----------------------
9 | 7 | 11
12 | 2 | 2
13 | 4 | 4
-----------------------
adascr: db=34 display=value_criteria,password=MYSECRET
password : "MYSECRET"
| File | Security by Value criterion
|------+----------------------------------------------------------------------
| 9 | ACCESS_CRITERION
| | SEARCH_BUFFER: "AZ,2,GE."
| | VALUE_BUFFER: "FR"
| | UPDATE_CRITERION
| | SEARCH_BUFFER: "AH,8,GE,D,AH,8,LE,D,AA,8,LE. "
| | VALUE_BUFFER: "195201011952020160000000"
| 12 | ACCESS_CRITERION
| | SEARCH_BUFFER: "AM,3,GE."
| | VALUE_BUFFER: 0x33000C
| | UPDATE_CRITERION
| | SEARCH_BUFFER: "AM,3,GE."
| | VALUE_BUFFER: 0x50000C
| 13 | ACCESS_CRITERION
| | SEARCH_BUFFER: "B0,GE."
| | VALUE_BUFFER: 0x01000000
| | UPDATE_CRITERION
| | SEARCH_BUFFER: "B0,3,GE."
| | VALUE_BUFFER: 0xFF0201
|-----------------------------------------------------------------------------
INSERT {=|:} string, FILE = (number[-number][,number[-number]]...)
,ACCESS = (number[,number]...)
,UPDATE = (number[,number]...)
This function inserts a password specified by 'string' into the password table.
If you specify an equals sign, the value given for 'string' will be converted to upper case; if you specify a colon, no upper-case conversion is performed.
The password may be between 1 and 8 characters long. If less than 8 characters are specified, trailing blanks are added. The password may not contain any special characters or embedded blanks.
The ACCESS parameter specifies the access protection levels to be associated with the files or file ranges specified in the FILE parameter. Each protection level corresponds to one file or one file range. A value may be specified in the range 0 - 14. The protection levels must be specified in the same order as the corresponding files or file ranges in the FILE parameter.
The FILE parameter specifies the file list or range(s) of files for which permission levels are being provided. Multiple specifications of the same file number are not permitted.
The UPDATE parameter specifies the update protection levels to be associated with the files or file ranges specified in the FILE parameter. Each protection level corresponds to one file or one file range. A value may be specified in the range 0 - 14. The protection levels must be specified in the same order as the corresponding files or file ranges in the FILE parameter.
adascr: insert = userpwx, file = (1,2,3),
access = (7,7,7), update = (0,8,8)
adascr: insert = userpwy, file = (1,2,3),
access = (7,2,2), update = (8,0,0)
adascr: insert = userpwz, file = (1-3,5),
access = (2,3), update = (4,6)
PROTECT = (number[-number][,number[-number]]...)
,ACCESS = (number[,number]...)
,UPDATE = (number[,number]...)
This function inserts (or updates) the access and/or update protection levels for the file, list or range(s) specified. Multiple specifications of the same file number are not permitted.
The ACCESS parameter specifies the access protection levels to be associated with the files or file ranges specified in the PROTECT parameter. Each protection level corresponds to one file or one file range. A value may be specified in the range 0 - 15. The protection levels must be specified in the same order as the corresponding files or file ranges in the PROTECT parameter.
Note that the maximum protection level for access for the PROTECT function is 15, whereas the INSERT function allows a maximum of only 14. Therefore, with ACCESS=15, a file can be protected to prevent any user from accessing it.
The UPDATE parameter specifies the update protection levels to be associated with the files or file ranges specified in the PROTECT parameter. Each protection level corresponds to one file or one file range. A value may be specified in the range 0 - 15. The protection levels must be specified in the same order as the corresponding files or file ranges in the PROTECT parameter.
Note that the maximum protection level for update for the INSERT function is 14, whereas the PROTECT function allows a maximum of 15. Therefore, with UPDATE=15, a file can be protected to prevent any user from updating it.
adascr: protect = 25, access = 7, update = 11 adascr: protect = (1,2,3), access = (7,7,7), update = (8,8,8) adascr: protect = (4-6), access = 10, update = 12
If the file number of a security-protected file is subsequently changed as a result of running the RENUMBER function of the ADADBM utility, the PROTECT function has to be reexecuted in order to reestablish the security protection levels for the file. The passwords also have to be reestablished, since they reflect the old file number.
SECURITY_BY_VALUE {=|:} string, FILE = number
,ACCESS_CRITERION
,SEARCH_BUFFER = string *
,VALUE_BUFFER = string *
,UPDATE_CRITERION
,SEARCH_BUFFER = string *
,VALUE_BUFFER = string *
* The search/access buffer string parameters must be followed by <Newline> with no preceding comma.
This function inserts (or updates) the Security by Value criteria for a specific file, for the given password specified by `string'. The password must already have been inserted into the security file, using the INSERT function. Each password can have Security by Value criteria defined for a maximum of 99 files.
If you specify an equals sign, the value given for 'string' will be converted to upper case; if you specify a colon, no upper-case conversion is performed.
The ACCESS_CRITERION keyword must precede the search buffer and value buffer which will define the criterion for restricting access to data using the provided password.
In order for the access value criterion to be specified, the ACCESS password permission level for the file must also have previously been set (i.e. non-zero); in the case where the level is not set, the ACCESS_CRITERION keyword cannot be specified.
The FILE parameter specifies the file for which the value criteria are to be defined. Exactly one file must be specified and the file must be currently loaded in the database.
The UPDATE_CRITERION keyword must precede the search buffer and value buffer which will define the criterion for restricting the update of data using the provided password.
In order for the update value criterion to be specified, the UPDATE password permission level for the file must also have previously been set (i.e. non-zero); in the case where the level is not set, the UPDATE_CRITERION keyword cannot be specified.
The SEARCH_BUFFER parameter is used to provide the search expressions for the access/update criterion. Syntax and examples of search buffer construction are provided in Command Reference, Calling Adabas, Search and Value Buffers.
Certain restrictions apply to the search buffer when used for defining Security by Value criteria; soft coupling and sub-, super-, hyper- and phonetic descriptors are not supported.
If the required criterion is that no restrictions should apply, then the associated search buffer should be specified containing only the terminator, i.e.:
SEARCH_BUFFER = .
In this case, the VALUE_BUFFER parameter is not required and does not need to be supplied.
The VALUE_BUFFER parameter is used to provide the corresponding values for the search expressions for the access/update value criterion, specified in the preceding search buffer. The string may be specified either directly, as an alphanumeric string or as a string using hexadecimal notation.
adascr: security_by_value = fortytwo, file = 10,
access_criterion, search_buffer = CA,4,U,LT.
adascr: value_buffer = 1707
adascr: update_criterion, search_buffer = A,4,S,CA,4,D,AA,O,AA.
adascr: value_buffer = 01001599MS
adascr: security_by_value = g6mon, file = 3 adascr: access_criterion, search_buffer = . adascr: update_criterion, search_buffer = AC,3. adascr: value_buffer = HAM
If the either the access or update protection level for the specified file is zero, the associated value criterion will not be tested when the password is used for accessing/updating records for that file.