Manipulate the System security settings. More...

Inheritance diagram for System:

[legend]

Collaboration diagram for System:

[legend]

Public Member Functions
_.Library.Status	OnAddToSaveSet (_.Library.Integer depth, _.Library.Integer insert, _.Library.Integer callcount)
	This callback method is invoked when the current object is added to the SaveSet,. More...

Static Public Member Functions
_.Library.Boolean	Exists (_.Library.String Name, _.Library.ObjectHandle System, _.Library.Status Status)
	System security configuration exists. More...

_.Library.Status	Export (_.Library.String FileName, _.Library.Integer NumExported)
	This method exports the System security record to a file in xml format. More...

_.Library.Status	ExportAll (_.Library.String FileName, _.Library.String NumExported, _.Library.Integer Flags)
	Export All Security records to an xml file. More...

_.Library.Status	Get (_.Library.String Name, _.Library.String Properties)
	Get the system security properties. More...

_.Library.Status	GetInstallationSecuritySetting (_.Library.String SecuritySetting)
	Return the Security settings which the instance was initially installed with. More...

_.Library.Status	GetProperties (_.Library.ObjectHandle System, _.Library.String Properties)
	Get the system security properties. More...

_.Library.Status	Import (_.Library.String FileName, _.Library.Integer NumImported, _.Library.Integer Flags)
	Import System security record from an xml file. More...

_.Library.Status	ImportAll (_.Library.String FileName, _.Library.String NumImported, _.Library.Integer Type, _.Library.Integer Flags)
	Import All Security records from an xml file. More...

_.Library.Status	Modify (_.Library.String Name, _.Library.String Properties)
	Modify the system security properties. More...

Public Attributes
	AuditEnabled
	Enable auditing. More...

	AuditEncrypt
	Encrypt audit file. More...

	AuditFlags
	Flags to govern audit behavior. More...

	AutheEnabled
	Authentication and CSP Session options enabled for the system. More...

	ConfigurationSecurityEnabled
	Configuration security enabled. More...

	DBEncDefaultKeyID
	Database encryption key ID to use for new encrypted databases. More...

	DBEncIRISTemp
	Encrypt IRISTemp database. More...

	DBEncJournal
	Encrypt Journal files. More...

	DBEncJournalKeyID
	Database encryption key ID to use for encrypting journal files. More...

	DefaultSecurityDomain
	Default domain system belongs to. More...

	DefaultSignatureHash
	The default hashing algorithm to use for digital signatures if no hashing. More...

	InactiveLimit
	Inactive login limit. More...

	InvalidLoginAction
	Action to take when the InvalidLoginLimit is reached for a user. More...

	InvalidLoginLimit
	Invalid login limit. More...

	JWTIssuer
	More...

	JWTSigAlg
	More...

	LoginCookieTimeout
	More...

	PasswordExpirationDays
	Password expiration period. More...

	PasswordHashAlgorithm
	Target hash algorithm for storing PBKDF2 password hashes. More...

	PasswordHashWorkFactor
	Target work factor for storing PBKDF2 password hashes. More...

	PasswordPattern
	Password Pattern. More...

	PasswordValidationRoutine
	Password validation routine. More...

	PercentGlobalWrite
	Allow writing to % globals. More...

	PrivateJWKS
	More...

	PublicJWKS
	More...

	RequiredRole
	Required role to log into system. More...

	SMTPPassword
	Password for sending email. More...

	SMTPServer
	Server DNS name for sending email. More...

	SMTPUsername
	Username for sending email. More...

	SSLECPServer
	Use SSL/TLS for ECP Server connections. More...

	SSLTelnetServer
	Use SSL/TLS for Telnet Server connections (Windows only.) More...

	SecurityDomains
	Allow multiple security domains. More...

	TwoFactorFrom
	"From:" field for two-factor security token messages More...

	TwoFactorPWIssuer
	More...

	TwoFactorTimeout
	Timeout for receiving security token in two-factor authentication, in seconds. More...

Detailed Description

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.

Member Function Documentation

◆ OnAddToSaveSet()

_.Library.Status OnAddToSaveSet	(	_.Library.Integer	depth,
		_.Library.Integer	insert,
		_.Library.Integer	callcount
	)

This callback method is invoked when the current object is added to the SaveSet,.

either because Save() was invoked on this object or on an object that references this object. OnAddToSaveSet can modify the current object. It can also add other objects to the current SaveSet by invoking AddToSaveSet or remove objects by calling RemoveFromSaveSet.

If this method returns an error status then Save() will fail and the transaction will be rolled back.

◆ Exists()

_.Library.Boolean Exists	(	_.Library.String	Name,
		_.Library.ObjectHandle	System,
		_.Library.Status	Status
	)

static

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<br>
If Value of the method = 1 (System config exists)
System = Object handle to System config
Status = $$$OK

◆ Export()

_.Library.Status Export	(	_.Library.String	FileName,
		_.Library.Integer	NumExported
	)

static

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.

◆ ExportAll()

_.Library.Status ExportAll	(	_.Library.String	FileName,
		_.Library.String	NumExported,
		_.Library.Integer	Flags
	)

static

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("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 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
Bit 17 - Servers

To export records for a particular area, specify a value of Flags that is 2 to the number of the relevant bit. For example, to export only a list of all roles (Bit 5), specify 32 (2**5, that is, 2 to the 5th power) as the value of Flags; for all applications (Bit 7), specify a value of 128 (2**7).

To export records for multiple areas, sum the values for the relevant areas. For example, to export both roles and applications, specify a value of 160 (32 for roles plus 128 for applications); to export roles, users, and applications, specify a value of 224 (32 for roles, plus 64 for users, plus 128 for applications).

◆ Get()

_.Library.Status Get	(	_.Library.String	Name,
		_.Library.String	Properties
	)

static

Get the system security properties.

Parameters:
Name - Name of system parameter record, currently always "SYSTEM"
Properties (byref) - Array of system properties

◆ GetInstallationSecuritySetting()

_.Library.Status GetInstallationSecuritySetting ( _.Library.String SecuritySetting )

static

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.

◆ GetProperties()

_.Library.Status GetProperties	(	_.Library.ObjectHandle	System,
		_.Library.String	Properties
	)

static

Get the system security properties.

◆ Import()

_.Library.Status Import	(	_.Library.String	FileName,
		_.Library.Integer	NumImported,
		_.Library.Integer	Flags
	)

static

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

◆ ImportAll()

_.Library.Status ImportAll	(	_.Library.String	FileName,
		_.Library.String	NumImported,
		_.Library.Integer	Type,
		_.Library.Integer	Flags
	)

static

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("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")
NumImported("Server")
Type - What type of records to import from the file, -1 = ALL
Bit 0 - System
Bit 1 - Events
Bit 2 - Services
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 - LDAPConfigs
Bit 16 - KMIPServer
Bit 17 - Servers
Flags - Control import
Bit 0 - Do not import records, just return counts
Note: On failure, no records will be imported

◆ Modify()

_.Library.Status Modify	(	_.Library.String	Name,
		_.Library.String	Properties
	)

static

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.

Member Data Documentation

◆ AuditEnabled

AuditEnabled

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.

◆ AuditEncrypt

AuditEncrypt

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.

◆ AuditFlags

AuditFlags

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 IRIS.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.)

◆ AutheEnabled

AutheEnabled

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 - AuthePassword
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
Bit 22-24 reserved
Bit 25 = MutualTLS
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.

◆ ConfigurationSecurityEnabled

ConfigurationSecurityEnabled

Configuration security enabled.

If configuration security is enabled, then if the system detects that the .CPF configuration 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.

◆ DBEncDefaultKeyID

DBEncDefaultKeyID

Database encryption key ID to use for new encrypted databases.

◆ DBEncIRISTemp

DBEncIRISTemp

Encrypt IRISTemp database.

If the encrypt IRISTemp database property is enabled, the next time the system is restarted the IRISTemp database will be recreated as encrypted. In order to encrypt the IRISTemp 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.

◆ DBEncJournal

DBEncJournal

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.

◆ DBEncJournalKeyID

DBEncJournalKeyID

Database encryption key ID to use for encrypting journal files.

◆ DefaultSecurityDomain

DefaultSecurityDomain

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.

◆ DefaultSignatureHash

DefaultSignatureHash

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")

◆ InactiveLimit

InactiveLimit

Inactive login limit.

This property is the number of days a InterSystems IRIS security user account can be inactive before it is disabled. Setting this property to 0 will disable account inactivation.

◆ InvalidLoginAction

InvalidLoginAction

Action to take when the InvalidLoginLimit is reached for a user.

Bit 0 - Disable user account

◆ InvalidLoginLimit

InvalidLoginLimit

Invalid login limit.

This property is the number of consecutive times a user can attempt to log into a InterSystems IRIS 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.

◆ JWTIssuer

JWTIssuer

◆ JWTSigAlg

JWTSigAlg

◆ LoginCookieTimeout

LoginCookieTimeout

◆ PasswordExpirationDays

PasswordExpirationDays

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.

◆ PasswordHashAlgorithm

PasswordHashAlgorithm

Target hash algorithm for storing PBKDF2 password hashes.

More secure hashes increase the result's resistance to attack. If a user logs in via password, and their hash was calculated using a different algorithm, it will be re-calculated and re-stored appropriately. This allows frictionless migration to new PBKDF2 standards as users log in over time.

◆ PasswordHashWorkFactor

PasswordHashWorkFactor

Target work factor for storing PBKDF2 password hashes.

Higher values increase the result's resistance to attack, as well as CPU count required to authenticate passwords. If a user logs in via password, and the work factor of their hash does not match this value, it will be re-calculated and re-stored appropriately. This allows frictionless migration to new PBKDF2 standards as users log in over time.

◆ PasswordPattern

PasswordPattern

Password Pattern.

When a user is created in the InterSystems IRIS 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.

◆ PasswordValidationRoutine

PasswordValidationRoutine

Password validation routine.

When a user is created in the InterSystems IRIS 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
 }

◆ PercentGlobalWrite

PercentGlobalWrite

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 IRISSYS database. When this property is set to 0, only users with write access to the DB_IRISSYS resource can write to "%" globals. During intallation this is set to 1 for "Minimal" security, 0 for "Normal" and "Locked Down" security.

◆ PrivateJWKS

PrivateJWKS

◆ PublicJWKS

PublicJWKS

◆ RequiredRole

RequiredRole

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 configured 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.

◆ SMTPPassword

SMTPPassword

Password for sending email.

◆ SMTPServer

SMTPServer

Server DNS name for sending email.

◆ SMTPUsername

SMTPUsername

Username for sending email.

◆ SSLECPServer

SSLECPServer

Use SSL/TLS for ECP Server connections.

0 = None
1 = Accept
2 = Require

◆ SSLTelnetServer

SSLTelnetServer

Use SSL/TLS for Telnet Server connections (Windows only.)

0 = None
1 = Accept
2 = Require

◆ SecurityDomains

SecurityDomains

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.nosp@m.@dom.nosp@m.ainna.nosp@m.me.c.nosp@m.om.

◆ TwoFactorFrom

TwoFactorFrom

"From:" field for two-factor security token messages

◆ TwoFactorPWIssuer

TwoFactorPWIssuer

◆ TwoFactorTimeout

TwoFactorTimeout

Timeout for receiving security token in two-factor authentication, in seconds.

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ OnAddToSaveSet()

◆ Exists()

◆ Export()

◆ ExportAll()

◆ Get()

◆ GetInstallationSecuritySetting()

◆ GetProperties()

◆ Import()

◆ ImportAll()

◆ Modify()

Member Data Documentation

◆ AuditEnabled

◆ AuditEncrypt

◆ AuditFlags

◆ AutheEnabled

◆ ConfigurationSecurityEnabled

◆ DBEncDefaultKeyID

◆ DBEncIRISTemp

◆ DBEncJournal

◆ DBEncJournalKeyID

◆ DefaultSecurityDomain

◆ DefaultSignatureHash

◆ InactiveLimit

◆ InvalidLoginAction

◆ InvalidLoginLimit

◆ JWTIssuer

◆ JWTSigAlg

◆ LoginCookieTimeout

◆ PasswordExpirationDays

◆ PasswordHashAlgorithm

◆ PasswordHashWorkFactor

◆ PasswordPattern

◆ PasswordValidationRoutine

◆ PercentGlobalWrite

◆ PrivateJWKS

◆ PublicJWKS

◆ RequiredRole

◆ SMTPPassword

◆ SMTPServer

◆ SMTPUsername

◆ SSLECPServer

◆ SSLTelnetServer

◆ SecurityDomains

◆ TwoFactorFrom

◆ TwoFactorPWIssuer

◆ TwoFactorTimeout