Class Reference
Cache for UNIX 2018.1.2
InterSystems: The power behind what matters   
Documentation  Search
Private  Storage  

persistent class Security.System extends %Persistent, %SYSTEM.Help, %XML.Adaptor

Manipulate the System security settings.

The table for this class should be manipulated only through object access, the published API's or through the System Management Portal. It should not be updated through direct SQL access.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
60 28


Summary

Properties
AuditEnabled AuditEncrypt AuditFlags AutheEnabled
ConfigurationSecurityEnabled DBEncCacheTemp DBEncDefaultKeyID DBEncJournal
DBEncJournalKeyID DefaultSecurityDomain DefaultSignatureHash InactiveLimit
InvalidLoginAction InvalidLoginLimit LDAPAttributeComment LDAPAttributeFullName
LDAPAttributeNameSpace LDAPAttributeRoles LDAPAttributeRoutine LDAPAttributes
LDAPBaseDN LDAPCACertFile LDAPClientTimeout LDAPDomainName
LDAPFlags LDAPHostNames LDAPSearchPassword LDAPSearchUsername
LDAPServerTimeout LDAPUniqueDNIdentifier LoginCookieTimeout PasswordExpirationDays
PasswordPattern PasswordValidationRoutine PercentGlobalWrite RequiredRole
SMTPPassword SMTPServer SMTPUsername SSLSuperServer
SecurityDomains TwoFactorFrom TwoFactorPWIssuer TwoFactorTimeout

Methods
%AddToSaveSet %AddToSyncSet %BMEBuilt %CheckConstraints
%CheckConstraintsForExtent %ClassIsLatestVersion %ClassName %ComposeOid
%ConstructClone %Delete %DeleteExtent %DeleteId
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Exists
%ExistsId %Extends %GUID %GUIDSet
%GetLock %GetParameter %GetSwizzleObject %Id
%InsertBatch %IsA %IsModified %IsNull
%KillExtent %KillExtentData %LoadFromMemory %LockExtent
%LockId %New %NormalizeObject %ObjectIsNull
%ObjectModified %Oid %OnBeforeAddToSync %OnDetermineClass
%Open %OpenId %OriginalNamespace %PackageName
%PhysicalAddress %PurgeIndices %Reload %RemoveFromSaveSet
%ResolveConcurrencyConflict %RollBack %Save %SaveDirect
%SaveIndices %SerializeObject %SetModified %SortBegin
%SortEnd %SyncObjectIn %SyncTransport %UnlockExtent
%UnlockId %ValidateIndices %ValidateObject Exists
Export ExportAll Get GetInstallationSecuritySetting
GetProperties Help Import ImportAll
Modify XMLDTD XMLExport XMLExportToStream
XMLExportToString XMLNew XMLSchema XMLSchemaNamespace
XMLSchemaType


Properties

• property AuditEnabled as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Enable auditing.
Setting this to property to 1 will turn on the audit subsystem, and cause audit records to be written to the audit file. Installing with "Minimal" security will cause auditing to be off (0). Installing with "Normal" or "Locked Down" security will cause auditing to be turned on.
• property AuditEncrypt as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Encrypt audit file.
Setting this property to 1 will cause the audit database to be encrypted. In order to encrypt the audit database, a valid database encryption key must be loaded on the system. Note that if encryption is enabled, the existing audit database and any data it contains will be deleted as soon as the property is modified. If encryption is changed from enabled to disabled, the existing audit database and any data it contains will also be deleted. By default, this property is set to 0 during installation.
• property AuditFlags as %Integer [ InitialExpression = 0 ];
Flags to govern audit behavior.
Bit 0 - Freeze system on audit write failure.
If the freeze system bit is turned on, any failure to write to the audit file will cause the system to freeze by setting the WDSTOP bit. Failures could include a file full, disk full, or disk write error condition. To fix this condition, you must force the system down, and either free up disk space, or replace the audit CACHE.DAT file with a new, smaller one. If you enable this parameter, make sure that you have lots of disk space allocated for the audit database. You probably also do not want to set a max size on the audit database either (i.e. leave the max database size set to its default of 0.)
• property AutheEnabled as Security.Datatype.Authentication;
Authentication and CSP Session options enabled for the system.
Bit 0 = AutheK5CCache
Bit 1 = AutheK5Prompt
Bit 2 = AutheK5API
Bit 3 = AutheK5KeyTab
Bit 4 = AutheOS
Bit 5 - AutheCache
Bit 6 = AutheUnauthenticated
Bit 7 = AutheKB
Bit 8 = AutheKBEncryption
Bit 9 = AutheKBIntegrity
Bit 10 = AutheSystem
Bit 11 = AutheLDAP
Bit 12 = AutheLDAPCache
Bit 13 = AutheDelegated
Bit 14 = LoginToken
Bit 15-19 reserved
Bit 20 = TwoFactorSMS
Bit 21 = TwoFactorPW
Depending on the installation security options selected, these different authentication and CSP Session options may be either enabled or disabled. These options govern at the system wide level what authentication and CSP session options are available for the system. If an authentication or CSP session option is disabled at the system level, it will also be disabled for all the services and CSP applications. If the authentication or CSP Session option is enabled at the system level, it may be individually enabled or disabled for each service and CSP application on the system, if the service or CSP application supports that method. See the Security.Services class for enabling/disabling authentication for each individual service, and the Security.Applications class for CSP applications. Note that these bits correspond to the same bit numbers in the Security.Services and Security.Applications class.
• property ConfigurationSecurityEnabled as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Configuration security enabled.
If configuration security is enabled, then if the system detects that the CACHE.CPF file has been changed externally (outside of the Management Portal), the system will inform the user that the configuration has changed, and will prompt for a username/password when it next starts up. The username entered must own the %Admin_Manage:Use resource in order for the new configuration to start. If they do not, or the authentication fails, the previous good configuration is used to start the system, and the new configuration changes which were not activated are written to a backup file. By default, this property is set to 0 during installation.
• property DBEncCacheTemp as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Encrypt CacheTemp database.
If the encrypt CacheTemp database property is enabled, the next time the system is restarted the CacheTemp database will be recreated as encrypted. In order to encrypt the CacheTemp database, a valid database encryption key must be loaded on the system. If this parameter is changed from enabled to disabled, the next time the system restarts the database will be created unencrypted. By default, this property is set to 0 during installation.
• property DBEncDefaultKeyID as %String;
Database encryption key ID to use for new encrypted databases.
• property DBEncJournal as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Encrypt Journal files.
If the encrypt journal files property is enabled, the journal file will be switched, and the new journal file will be created as encrypted. In order to encrypt the journal file, a valid database encryption key must be loaded on the system. If this parameter is changed from enabled to disabled, the journal file is switched, and the new journal file will be created unencrypted. By default, this property is set to 0 during installation.
• property DBEncJournalKeyID as %String;
Database encryption key ID to use for encrypting journal files.
• property DefaultSecurityDomain as %String(MAXLEN=64,MINLEN=1);
Default domain system belongs to.
This property is the default kerberos security domain which the system will use for kerberos authentication. During installation, the system will attempt to set this property to the correct value. If you decide to use kerberos authentication, you may need to modify this value. If you are not using kerberos, do not change this value.
• property DefaultSignatureHash as %String(VALUELIST=",SHA1,SHA256,SHA384,SHA512,") [ InitialExpression = "SHA256" ];
The default hashing algorithm to use for digital signatures if no hashing algorithm is explicitely specified which is the usual case. This default is used for creating signatures based on RSA keys or HMAC and the default is set during signature creation.
The valid values for DefaultSignatureHash are SHA1, SHA256, SHA384 and SHA512. Previously the default was SHA1, but is now changed to SHA256 in accord with the NIST recommendation.
- The default digest method is used as the DigestMethod for each referenced element to sign.
    %XML.Security.Signature.DigestMethodAlgorithm defaults based on the value of DefaultSignatureHash
    SHA1:   $$$SOAPWSsha1   ("http://www.w3.org/2000/09/xmldsig#sha1")
    SHA256: $$$SOAPWSsha256 ("http://www.w3.org/2001/04/xmlenc#sha256")
    SHA384: $$$SOAPWSsha384 ("http://www.w3.org/2001/04/xmldsig-more#sha384")
    SHA512: $$$SOAPWSsha512 ("http://www.w3.org/2001/04/xmlenc#sha512")
- Signature based based on RSA keys is created by %XML.Security.Signature:CreateX509.
    %XML.Security.Signature.SignatureMethod.Algorithm defaults based on the value of DefaultSignatureHash
    This is the signing algorithm to be used.
    SHA1:   $$$SOAPWSrsasha1   ("http://www.w3.org/2000/09/xmldsig#rsa-sha1")
    SHA256: $$$SOAPWSrsasha256 ("http://www.w3.org/2001/04/xmldsig-more#rsa-sha256")
    SHA384: $$$SOAPWSrsasha384 ("http://www.w3.org/2001/04/xmldsig-more#rsa-sha384")
    SHA512: $$$SOAPWSrsasha512 ("http://www.w3.org/2001/04/xmldsig-more#rsa-sha512")
- Signature based based on HMAC is created by %XML.Security.Signature:Create.
    %XML.Security.Signature.SignatureMethod.Algorithm defaults based on the value of DefaultSignatureHash
    This is the signing algorithm to be used.
    SHA1:   $$$SOAPWShmacsha1   ("http://www.w3.org/2000/09/xmldsig#hmac-sha1")
    SHA256: $$$SOAPWShmacsha256 ("http://www.w3.org/2001/04/xmldsig-more#hmac-sha256")
    SHA384: $$$SOAPWShmacsha384 ("http://www.w3.org/2001/04/xmldsig-more#hmac-sha384")
    SHA512: $$$SOAPWShmacsha512 ("http://www.w3.org/2001/04/xmldsig-more#hmac-sha512")
• property InactiveLimit as %Integer(MINVAL=0) [ InitialExpression = 90,Required ];
Inactive login limit.
This property is the number of days a Cache security user account can be inactive before it is disabled. Setting this property to 0 will disable account inactivation.
• property InvalidLoginAction as %Integer(MAXVAL=1,MINVAL=0) [ InitialExpression = 0 ];
Action to take when the InvalidLoginLimit is reached for a user.
Bit 0 - Disable user account
• property InvalidLoginLimit as %Integer(MINVAL=0) [ InitialExpression = 5,Required ];
Invalid login limit.
This property is the number of consecutive times a user can attempt to log into a Cache security account and fail. Once this limit is reached, the process attempting to log in will start to "hang" for longer periods of time before an access denied message is returned to the user. Setting this property to 0 will disable this feature.
• property LDAPAttributeComment as %String(MAXLEN=64);
LDAP attribute name where the "Comment" field is retrieved.
• property LDAPAttributeFullName as %String(MAXLEN=64);
LDAP attribute name where the "FullName" field is retrieved.
• property LDAPAttributeNameSpace as %String(MAXLEN=64);
LDAP attribute name where the "NameSpace" field is retrieved.
• property LDAPAttributeRoles as %String(MAXLEN=64);
LDAP attribute name where the "Roles" field is retrieved.
• property LDAPAttributeRoutine as %String(MAXLEN=64);
LDAP attribute name where the "Routine" field is retrieved.
• property LDAPAttributes as list of %String(MAXLEN=64);
List of additional LDAP attributes to return from LDAP Server.
This property contains a list of additional LDAP User attributes for which you want values returned when a user authenticates himself via LDAP. For example, you may want to return a user's mail address from the LDAP server. You would set one of the list values to "mail" which is an LDAP attribute for a user. The values for the set of attributes are written to the user's authentication record, and may be retrieved by using the Security.Users class, Attributes property.
• property LDAPBaseDN as %String(MAXLEN=128);
• property LDAPCACertFile as %String(MAXLEN=256);
• property LDAPClientTimeout as %Integer [ InitialExpression = $$$LDAPDefaultClientTimeout ];
• property LDAPDomainName as %String(MAXLEN=128);
• property LDAPFlags as %Integer [ InitialExpression = 0 ];
• property LDAPHostNames as %String(MAXLEN=128);
• property LDAPSearchPassword as Security.Datatype.Password(MAXLEN=64);
• property LDAPSearchUsername as %String(MAXLEN=256);
• property LDAPServerTimeout as %Integer [ InitialExpression = $$$LDAPDefaultServerTimeout ];
• property LDAPUniqueDNIdentifier as %String(MAXLEN=128);
• property LoginCookieTimeout as %Integer [ InitialExpression = 0 ];
• property PasswordExpirationDays as %Integer [ InitialExpression = 0,Required ];
Password expiration period.
This property governs how long a password for a user can be used before it expires. Once a password expires, the user must change their password before they can log in the next time. If this property is set to 0, passwords will not expire on the system.
• property PasswordPattern as %String(MAXLEN=64) [ InitialExpression = "3.32ANP" ];
Password Pattern.
When a user is created in the Cache security database, or a user changes their password, the password is pattern matched against the pattern stored in this property to determine if it matches. If it matches, then the password is allowed. By default, the password must be between 3 and 32 characters, with alphanumerics and punctuations. A security setting of "locked down" selected during install requires it to be a minimum of 8 characters long. The Password pattern may be set to null meaning no pattern match on the password.
• property PasswordValidationRoutine as %String(MAXLEN=128);
Password validation routine.
When a user is created in the Cache security database, or a user changes their password, the specified routine is called to validate the password. A tag reference may also be included in the property. The routine should be provided by the user, and must exist in the %SYS namespace (it may be mapped to a different database however.) The routine will take 2 parameters, a Username and new password, and should return a %Status code of $$$OK for successful password validation, or an error code formatted into a %Status variable. The username passed into the function will be in all lowercase, and will contain the domain name if multiple domains are enabled for the system.

Here is an example of a password validation routine. Enter CHECK^PASSWORD into this property to call it:
PASSWORD ; Validate a user's password
#include %occInclude
CHECK(Username,Password) PUBLIC {
  ; See if the password was previously used. If it was, return an error.
  ; Allow the user to change it to the same one as current.
  ; Store the list of previously used passwords for the user as a hashed value.
  s PasswordHash=$System.Encryption.SHA1Hash(Password)
  i $d(^PASSWORDLIST(Username,PasswordHash)){
    i ^PASSWORDLIST(Username,"Current")'=PasswordHash {
      q $$$ERROR($$$GeneralError,"Password was previously used")
    }
  }
  s ^PASSWORDLIST(Username,PasswordHash)=$h
  s ^PASSWORDLIST(Username,"Current")=PasswordHash
  q $$$OK
}
• property PercentGlobalWrite as %Integer [ InitialExpression = 0 ];
Allow writing to % globals.
When this property is set to 1, any user on the system is allowed to write to any "%" global (like ^%IS) mapped to the CACHESYS database. When this property is set to 0, only users with write access to the %DB_CACHESYS resource can write to "%" globals. During intallation this is set to 1 for "Minimal" security, 0 for "Normal" and "Locked Down" security. Note that in versions prior to Cache 5.1, any user could always write to "%" globals, so users migrating to later versions may want to set this property to 1.
• property RequiredRole as %String(MAXLEN=64);
Required role to log into system.
Setting this value to a valid role will require any user logging into the system to own this role as part of their login roles. If the user does not own this role, they will receive an "Access denied" message when they try to log in. This is usually used when the system is confiured for LDAP or User defined authentication to restrict unauthorized users from accessing a system. When using LDAP or user defined authentication, user roles are assigned from the LDAP database or the user defined security database. For example, if this property is set to "ACCOUNTSPAYABLE", then the user logging in must be assigned the ACCOUNTSPAYABLE role on the LDAP server, or from the user defined database. Leave as "" if not required. Note that if the user logging in is assigned the "%All" role from the LDAP server or user defined database, then that will override any role entered here.
• property SMTPPassword as %String;
Password for sending email
• property SMTPServer as %String;
Server DNS name for sending email
• property SMTPUsername as %String;
Username for sending email
• property SSLSuperServer as %Integer(MAXVAL=2,MINVAL=0) [ InitialExpression = 0 ];
Use SSL/TLS for SuperServer connections.
0 = None
1 = Accept
2 = Require
• property SecurityDomains as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Allow multiple security domains.
This property should only be set to 1 if you are using kerberos, and wish to allow cross domain realm authentication. Turning it on will cause all usernames to include the domain from which they are logging in. Thus a $username such as "Steve" will then be displayed and used as Steve@domainname.com.
• property TwoFactorFrom as %String;
"From:" field for two-factor security token messages
• property TwoFactorPWIssuer as %String(MAXLEN=256) [ InitialExpression = $p($zv," ",1)_"-"_$zu(110)_"-"_$p($zu(86),"*",2) ];
• property TwoFactorTimeout as %Integer [ InitialExpression = 180 ];
Timeout for receiving security token in two-factor authentication, in seconds

Methods

• classmethod Exists(Name As %String = $$$SystemSecurityName, ByRef System As %ObjectHandle, ByRef Status As %Status) as %Boolean
System security configuration exists.
Used to get a handle to the Security.System object.
Parameters:
Name - Always "SYSTEM".
Return values:
If Value of the method = 0 (System config does not exist, or some error occured)
System = Null
Status = System does not exist, or other error message

If Value of the method = 1 (System config exists)
System = Object handle to System config
Status = $$$OK
• classmethod Export(FileName As %String = "SystemExport.xml", ByRef NumExported As %Integer) as %Status
This method exports the System security record to a file in xml format.
Parameters:
Filename - Output file name
NumExported (byref) - Returns number of records exported.
• classmethod ExportAll(FileName As %String = "SecurityExport.xml", ByRef NumExported As %String, Flags As %Integer = -1) as %Status
Export All Security records to an xml file.
Parameters:
FileName - Output file name
NumExported (byref) - Returns number of records exported for each type of security record:
NumExported("System")
NumExported("Event")
NumExported("Service")
NumExported("Domain")
NumExported("Resource")
NumExported("Role")
NumExported("User")
NumExported("Application")
NumExported("SSLConfig")
NumExported("PhoneProvider")
NumExported("X509Credentials")
NumExported("OpenAMIdentityService")
NumExported("SQLPrivileges")
NumExported("X509Users")
NumExported("DocDB")
NumExported("LDAPConfig")
NumExported("KMIPConfig")
Flags - What type of records to export to the file, -1 = ALL
Bit 0 - System
Bit 1 - Events
Bit 2 - Services
Bit 3 - Domains
Bit 4 - Resources
Bit 5 - Roles
Bit 6 - Users
Bit 7 - Applications
Bit 8 - SSL Configs
Bit 9 - PhoneProvider
Bit 10 - X509Credential
Bit 11 - OpenAMIdentityService
Bit 12 - SQL privileges
Bit 13 - X509Users Bit 14 - DocDBs Bit 15 - LDAPConfig Bit 16 - KMIPServer
• classmethod Get(Name As %String = $$$SystemSecurityName, ByRef Properties As %String) as %Status
Get the system security properties.
Parameters:
Name - Name of system parameter record, currently always "SYSTEM"
Properties (byref) - Array of system properties
• classmethod GetInstallationSecuritySetting(ByRef SecuritySetting As %String) as %Status
Return the Security settings which the instance was initially installed with.
Security Setting - (by ref) Contains the security setting installed, one of these possible values:
"None" - Minimal settings selected
"Normal" - Normal settings selected
"Locked Down" - Locked down setting selected
"Unknown" - Cannot determine settings. This would only be the case if the system was initially installed as 2010.2 or earlier, and the settings cannot be determined by examining the security database.
• classmethod GetProperties(System As %ObjectHandle, ByRef Properties As %String) as %Status
Get the system security properties.
• classmethod Import(FileName As %String = "SystemExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0) as %Status
Import System security record from an xml file.
Parameters:
FileName - Filename to import System security record from
NumImported (byref) - Returns number of records imported
Flags - Control import
Bit 0 - Do not import records, just return count
Note: On failure, no records will be imported
• classmethod ImportAll(FileName As %String = "SecurityExport.xml", ByRef NumImported As %String, Type As %Integer = -1, Flags As %Integer = 0) as %Status
Import All Security records from an xml file.
Parameters:
FileName - Filename to import security records from
NumImported (byref) - Returns number of records imported for each type of security record:
NumImported("System")
NumImported("Event")
NumImported("Service")
NumImported("Domain")
NumImported("Resource")
NumImported("Role")
NumImported("User")
NumImported("Application")
NumImported("SSLConfig")
NumImported("PhoneProvider")
NumImported("X509Credentials")
NumImported("OpenAMIdentityService")
NumImported("SQLPrivileges")
NumImported("X509Users")
NumImported("DocDB")
NumImported("LDAPConfig")
NumImported("KMIPServer")
Type - What type of records to import from the file, -1 = ALL
Bit 0 - System
Bit 1 - Events
Bit 2 - Services
Bit 3 - Domains
Bit 4 - Resources
Bit 5 - Roles
Bit 6 - Users
Bit 7 - Applications
Bit 8 - SSL Configs
Bit 9 - PhoneProvider
Bit 10 - X509Credential
Bit 11 - OpenAMIdentityService
Bit 12 - SQL privileges
Bit 13 - Login Rules
Bit 14 - X509Users
Bit 16 - KMIPServer
Flags - Control import
Bit 0 - Do not import records, just return counts
Note: On failure, no records will be imported
• classmethod Modify(Name As %String = $$$SystemSecurityName, ByRef Properties As %String) as %Status
Modify the system security properties.
Modifies the system security properties from the security database.
Parameters:
Name - Name of system parameter record, currently always "SYSTEM"
Properties - Array of properties to modify.
See the Get() method for a description of the Properties parameter.
If a specific property is not passed in the properties array, then the property is not modified.


Copyright © 1997-2019, InterSystems Corporation