Home > Class Reference > %SYS namespace > Security.SSLConfigs

Security.SSLConfigs

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

SQL Table Name: Security.SSLConfigs

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.

Property Inventory

Method Inventory

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 or a pathname relative to the Cache' manager's directory.
Clients: Specify CAFile and/or CAPath
Servers: Specify CAFile and/or CAServer if VerifyPeer > 0
Property methods: CAFileDisplayToLogical(), CAFileGet(), CAFileGetStored(), CAFileIsValid(), CAFileLogicalToDisplay(), CAFileLogicalToOdbc(), CAFileNormalize(), CAFileSet()
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 Cache' manager's directory.
Clients: Specify CAFile and/or CAPath
Servers: Specify CAFile and/or CAServer if VerifyPeer > 0
Property methods: CAPathDisplayToLogical(), CAPathGet(), CAPathGetStored(), CAPathIsValid(), CAPathLogicalToDisplay(), CAPathLogicalToOdbc(), CAPathNormalize(), CAPathSet()
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 Cache' manager's directory. If not null, PrivateKeyFile must also be specified.
Property methods: CertificateFileDisplayToLogical(), CertificateFileGet(), CertificateFileGetStored(), CertificateFileIsValid(), CertificateFileLogicalToDisplay(), CertificateFileLogicalToOdbc(), CertificateFileNormalize(), CertificateFileSet()
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 methods: CipherListDisplayToLogical(), CipherListGet(), CipherListGetStored(), CipherListIsValid(), CipherListLogicalToDisplay(), CipherListLogicalToOdbc(), CipherListNormalize(), CipherListSet()
property Description as %String (MAXLEN = 256);
Description of the SSL configuration.
Property methods: DescriptionDisplayToLogical(), DescriptionGet(), DescriptionGetStored(), DescriptionIsValid(), DescriptionLogicalToDisplay(), DescriptionLogicalToOdbc(), DescriptionNormalize(), DescriptionSet()
property Enabled as Security.Datatype.BooleanYN [ InitialExpression = 1 ];
Configuration is enabled.
Property methods: EnabledDisplayToLogical(), EnabledGet(), EnabledGetStored(), EnabledIsValid(), EnabledLogicalToDisplay(), EnabledLogicalToODBC(), EnabledLogicalToXSD(), EnabledNormalize(), EnabledSet(), EnabledXSDToLogical()
property Name as %String (MAXLEN = 64, MINLEN = 1) [ Required ];
SSL configuration name.
Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIndexCheck(), NameIndexDelete(), NameIndexExists(), NameIndexOpen(), NameIndexSQLCheckUnique(), NameIndexSQLExists(), NameIndexSQLFindPKeyByConstraint(), NameIndexSQLFindRowIDByConstraint(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
property PrivateKeyFile as %String (MAXLEN = 255);
File containing this configuration's private key.
Can be an absolute pathname or a pathname relative to the Cache' manager's directory. If not null, CertificateFile must also be specified.
Property methods: PrivateKeyFileDisplayToLogical(), PrivateKeyFileGet(), PrivateKeyFileGetStored(), PrivateKeyFileIsValid(), PrivateKeyFileLogicalToDisplay(), PrivateKeyFileLogicalToOdbc(), PrivateKeyFileNormalize(), PrivateKeyFileSet()
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 methods: PrivateKeyPasswordGet(), PrivateKeyPasswordGetStored(), PrivateKeyPasswordIsValid(), PrivateKeyPasswordLogicalToDisplay(), PrivateKeyPasswordLogicalToOdbc(), PrivateKeyPasswordLogicalToXSD(), PrivateKeyPasswordSet(), PrivateKeyPasswordXSDToLogical()
property PrivateKeyType as Security.Datatype.PrivateKeyType (MAXVAL = 2, MINVAL = 1) [ InitialExpression = 2 , Required ];
Private key type, one of:
1 = DSA
2 = RSA
Property methods: PrivateKeyTypeDisplayToLogical(), PrivateKeyTypeGet(), PrivateKeyTypeGetStored(), PrivateKeyTypeIsValid(), PrivateKeyTypeLogicalToDisplay(), PrivateKeyTypeLogicalToODBC(), PrivateKeyTypeNormalize(), PrivateKeyTypeSet(), PrivateKeyTypeXSDToLogical()
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 methods: ProtocolsDisplayToLogical(), ProtocolsGet(), ProtocolsGetStored(), ProtocolsIsValid(), ProtocolsLogicalToDisplay(), ProtocolsLogicalToOdbc(), ProtocolsNormalize(), ProtocolsSet(), ProtocolsXSDToLogical()
property SNIName as %String;
The fully qualified DNS hostname of the server for use with the Subject Name Indication (SNI) TLS extension
Property methods: SNINameDisplayToLogical(), SNINameGet(), SNINameGetStored(), SNINameIsValid(), SNINameLogicalToDisplay(), SNINameLogicalToOdbc(), SNINameNormalize(), SNINameSet()
property Type as Security.Datatype.SSLType [ InitialExpression = 0 , Required ];
Intended type for this configuration.
0 = client
1 = server
Default is client (0)
Property methods: TypeDisplayToLogical(), TypeGet(), TypeGetStored(), TypeIsValid(), TypeLogicalToDisplay(), TypeLogicalToODBC(), TypeLogicalToXSD(), TypeNormalize(), TypeSet(), TypeXSDToLogical()
property VerifyDepth as %Integer (MINVAL = 0) [ InitialExpression = 9 , Required ];
Maximum number of CA certificates allowed in peer certificate chain.
Property methods: VerifyDepthDisplayToLogical(), VerifyDepthGet(), VerifyDepthGetStored(), VerifyDepthIsValid(), VerifyDepthLogicalToDisplay(), VerifyDepthNormalize(), VerifyDepthSet(), VerifyDepthXSDToLogical()
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)
Property methods: VerifyPeerDisplayToLogical(), VerifyPeerGet(), VerifyPeerGetStored(), VerifyPeerIsValid(), VerifyPeerLogicalToDisplay(), VerifyPeerNormalize(), VerifyPeerSet(), VerifyPeerXSDToLogical()

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

Indexes

index (NameIndex on Name) [IdKey, Type = key];
Name by which this configuration is referenced.
Index methods: NameIndexCheck(), NameIndexDelete(), NameIndexExists(), NameIndexOpen(), NameIndexSQLCheckUnique(), NameIndexSQLExists(), NameIndexSQLFindPKeyByConstraint(), NameIndexSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods

Storage

Storage Model: CacheStorage (Security.SSLConfigs)

^|$$$SecurityMapSSLConfigs|SYS("Security","SSLConfigsD")(ID)
=
%%CLASSNAME
CAFile
CAPath
CertificateFile
CipherList
Description
Enabled
Name
PrivateKeyFile
PrivateKeyPassword
PrivateKeyType
Protocols
Type
VerifyDepth
VerifyPeer
CRLFile

Storage Model: CacheStorage (Security.SSLConfigs)

^|$$$SecurityMapSSLConfigs|SYS("Security","SSLConfigsD")(ID,"1")
=
SNIName