Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [Security] >  [SSLConfigs]
Private  Storage   

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

Define the SSL/TLS configurations, and methods which manipulate them.
1) SSL configuration names are case sensitive.
2) Maximum length of a configuration name is 64 characters.
Once an SSL configuration is defined and activated, you can use the name of the configuration as a parameter to the open or use command in order to set up an SSL connection.
Open dev:(Host:Port:"M":/TLS="Name"):10
The %Admin Secure:USE permission is required to operate on an SSL configuration.

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
1 16 34 4 1


Summary

Properties
CAFile CAPath CertificateFile CipherList
Description Enabled Name PrivateKeyFile
PrivateKeyPassword PrivateKeyType Protocols SNIName
Type VerifyDepth VerifyPeer

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 Activate
ActivateAll Create Deactivate Delete
Exists Export Get GetCertificate
Help Import Modify TestConnection
Validate XMLDTD XMLExport XMLExportToStream
XMLExportToString XMLNew XMLSchema XMLSchemaNamespace
XMLSchemaType


Parameters

• parameter DOMAIN = "%Utility";
Default Localization Domain

Properties

• property CAFile as %String(MAXLEN=255);
File containing X.509 certificate(s) of trusted Certificate Authorities.
Can be an absolute pathname, a pathname relative to the manager's directory, or a special value "%OSCertificateStore" for OS-provided trusted CA certificate stores.
Clients: Specify CAFile and/or CAPath
Servers: Specify CAFile and/or CAServer if VerifyPeer > 0
• property CAPath as %String(MAXLEN=255);
Directory containing file(s) with X.509 certificate(s) of trusted Certificate Authorities.
Can be an absolute pathname or a pathname relative to the manager's directory.
Clients: Specify CAFile and/or CAPath
Servers: Specify CAFile and/or CAServer if VerifyPeer > 0
• property CertificateFile as %String(MAXLEN=255);
File containing this configuration's X.509 certificate.
Can be an absolute pathname or a pathname relative to the manager's directory. If not null, PrivateKeyFile must also be specified.
• property CipherList as %String(MAXLEN=255) [ InitialExpression = "ALL:!aNULL:!eNULL:!EXP:!SSLv2",Required ];
Colon-delimited list of enabled ciphersuites.
By default, disable anonymous, unencrypted, and SSLv2 ciphersuites.
• property Description as %String(MAXLEN=256);
Description of the SSL configuration.
• property Enabled as Security.Datatype.BooleanYN [ InitialExpression = 1 ];
Configuration is enabled.
• property Name as %String(MAXLEN=64,MINLEN=1) [ Required ];
SSL configuration name.
• property PrivateKeyFile as %String(MAXLEN=255);
File containing this configuration's private key.
Can be an absolute pathname or a pathname relative to the manager's directory. If not null, CertificateFile must also be specified.
• property PrivateKeyPassword as Security.Datatype.Password(MAXLEN=255);
Optional password used to decrypt this configuration's private key.
If not null, PrivateKeyFile and CertificateFile must also be specified.
• property PrivateKeyType as Security.Datatype.PrivateKeyType(MAXVAL=2,MINVAL=1) [ InitialExpression = 2,Required ];
Private key type, one of:
1 = DSA
2 = RSA
• property Protocols as Security.Datatype.Protocol(MAXVAL=31,MINVAL=1) [ InitialExpression = 24,Required ];
Protocols enabled.
Bit 0 - SSLv2
Bit 1 - SSLv3
Bit 2 - TLSv1.0
Bit 3 - TLSv1.1
Bit 4 - TLSv1.2
Default is TLSv1.1+TLSv1.2
• property SNIName as %String;
The fully qualified DNS hostname of the server for use with the Subject Name Indication (SNI) TLS extension
• property Type as Security.Datatype.SSLType [ InitialExpression = 0,Required ];
Intended type for this configuration.
0 = client
1 = server
Default is client (0)
• property VerifyDepth as %Integer(MINVAL=0) [ InitialExpression = 9,Required ];
Maximum number of CA certificates allowed in peer certificate chain.
• property VerifyPeer as %Integer(MAXVAL=3,MINVAL=0) [ InitialExpression = 0,Required ];
Peer certificate verification level.

Clients:
0 = None (continue even if certificate verification fails)
1 = Require server certificate (continue only if certificate verification succeeds)

Servers:
0 = None (do not request client certificate)
1 = Request client certificate (terminate if certificate is provided and verification fails)
3 = Require client certificate (continue only if certificate is provided and verification succeeds)

Methods

• method Activate() as %Status
Activate the configuration.
Activate the configuration for use when new TCP connections are OPENed with the /SSL or /TLS parameter.
• classmethod ActivateAll() as %Status
Activate all configurations.
Activate all defined SSL configurations.
• classmethod Create(Name As %String, ByRef Properties As %String) as %Status
Create an SSL configuration.
Create an SSL configuration in the Security database.
Parameters:
Name - Name of the SSL configuration to create
Properties - Array of properties corresponding to the class properties
For example, Properties("CAFile")=Filename
• method Deactivate() as %Status
Deactivate this configuration.
• classmethod Delete(Name As %String) as %Status
Delete an SSL configuration.
This method will delete an SSL configuration from the security database.
Parameters:
Name - Name of SSL configuration to delete
• classmethod Exists(Name As %String, ByRef SSLConfig As %ObjectHandle, ByRef Status As %Status) as %Boolean
SSL configuration exists.
This method checks for the existence of an SSL Configuration in the security database.
Parameters:
Name - Name of the SSL configuration to check existence of
Return values:
If Value of the method = 0 (SSL configuration does not exist, or some error occured)
SSLConfig = Null
Status = SSL configuration "x" does not exist, or other error message

If Value of the method = 1 (SSL configuration exists)
SSLConfig = Object handle to SSL configuration
Status = $$$OK
• classmethod Export(FileName As %String = "SSLConfigsExport.xml", ByRef NumExported As %Integer, SSLConfigs As %String = "*") as %Status
This method exports SSL configuration Objects to a file in xml format.
Parameters:
FileName - Output file name
NumExported (byref) - Returns number of XML records exported.
SSLConfigs - Comma separated list of SSL configurations to export, "*" = All
• classmethod Get(Name As %String, ByRef Properties As %String) as %Status
Get a SSL configuration's properties.
Gets a SSL configuration's properties from the security database.
Parameters:
Name - Name of the SSL configuration to get
Return values:
Properties - Array of properties.
For example, Properties("CAFile")=Filename
Note: Admin_Secure:Use permission required for this method since it returns an unhashed password.
• final method GetCertificate() as %String
Get the contents of the file named by CertificateFile.
• classmethod Import(FileName As %String = "SSLConfigsExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0) as %Status
Import SSL configuration records from an xml file.
Parameters:
FileName - Filename to import SSL configuration records 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
Warning: Import will fail if the certificate paths or certificates do not exist before the import.
• classmethod Modify(Name As %String, ByRef Properties As %String) as %Status
Modify an SSL configuration.
Modify an existing SSL configuration's properties in the security database.
Parameters:
Name - Name of the SSL configuration to modify
Properties - Array of properties to modify.
For example, Properties("CAFile")=Filename If a specific property is not passed in the properties array, or is the same as the existing value, the value is not modified.
• method TestConnection(Host As %String, Port As %Integer, ByRef Info As %String) as %Status
Test the SSL configuration.
Attempts to make an SSL connection to the passed Host and port.
Parameters:
Host - Ip name of the host to connect to
Port - Port # of the host to connect to
Return Values:
On success, Info is returned as an array of messages concerning the host which we connected to.
• method Validate(Host As %String, Port As %Integer) as %String
Validate the SSL configuration (DEPRECATED).
Use the TestConnection method instead.
Attempts to make an SSL connection to the passed Host and port.
Parameters:
Host - Ip name of the host to connect to
Port - Port # of the host to connect to
Return Values:
String of success or error messages.

Queries

• query Detail(Names As %String = "*", Types As %String = "*")
Selects Name As %String, Description As %String, Enabled As %String, CAFile As %String, CAPath As %String, CertificateFile As %String, CipherList As %String, PrivateKeyFile As %String, PrivateKeyPassword As %String, PrivateKeyType As %String, Protocols As %String, Type As %String, VerifyDepth As %String, VerifyPeer As %String, CRLFile As %String, EnabledInternal As %Integer, TypeInternal As %Integer, SNIName As %String
List all SSL configuration records, brief display.
Names - Comma separated list of SSL configuration names, "*" = All
Types - Comma separated list of SSL Types, 0=Clients, 1=Servers, *=All Note: This query may change in future versions
• query List(Names As %String)
Selects Name As %String, Description As %String, Enabled As %String, Type As %String, EnabledInternal As %Integer, TypeInternal As %Integer
List all SSL configuration records, brief display.
Names - Comma separated list of SSL configuration names, "*" = All
Note: This query may change in future versions
• query ListEMS()
Selects Name As %String
List all SSL configuration records, brief display.
Only includes SSL configuration records used by the EMS (i.e. configs intended for client use, with a private key, password, certificate, certificate authority, and not expired.)
Names - Comma separated list of SSL configuration names, "*" = All
• query ListNames()
Selects Name As %String
SQL Query :
SELECT Name FROM SSLConfigs
ORDER BY Name
List all SSL configuration records, brief display.
Names - Comma separated list of SSL configuration names, "*" = All

Indices

•index (NameIndex on Name) [IdKey];
Name by which this configuration is referenced.


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.