Skip to main content

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.
LogicalToDisplay 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 AuthorizeCN as %Boolean [ InitialExpression = 0 , Transient ];
Authorize a backup failover member to join a mirror.
Normally, mirroring with SSL requires the following steps:
  1. Add primary to mirror
  2. Add backup to mirror
  3. Authorize backup on primary
This presents difficulties for declarative mirror configuration via CPF. When this property is set to 1, the Distinguished Name is extracted from this mirror's SSL certificates and used to pre-authorize the backup member to join.
Property methods: AuthorizeCNDisplayToLogical(), AuthorizeCNGet(), AuthorizeCNIsValid(), AuthorizeCNLogicalToDisplay(), AuthorizeCNLogicalToXSD(), AuthorizeCNNormalize(), AuthorizeCNSet(), AuthorizeCNXSDToLogical()
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 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 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 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 = 4096) [ InitialExpression = "ALL:!aNULL:!eNULL:!EXP:!SSLv2" ];
Colon-delimited list of enabled ciphersuites for TLSv1.2 and below.
By default, disable anonymous, unencrypted, export, and SSLv2 ciphersuites.
Property methods: CipherListDisplayToLogical(), CipherListGet(), CipherListGetStored(), CipherListIsValid(), CipherListLogicalToDisplay(), CipherListLogicalToOdbc(), CipherListNormalize(), CipherListSet()
property Ciphersuites as %String (MAXLEN = 128) [ InitialExpression = $$$TLSDEFAULTCIPHERSUITES ];
Colon-delimited lists of enabled ciphersuites for TLSv1.3.
Property methods: CiphersuitesDisplayToLogical(), CiphersuitesGet(), CiphersuitesGetStored(), CiphersuitesIsValid(), CiphersuitesLogicalToDisplay(), CiphersuitesLogicalToOdbc(), CiphersuitesNormalize(), CiphersuitesSet()
property Description as %String (MAXLEN = 256);
Description of the SSL configuration.
Property methods: DescriptionDisplayToLogical(), DescriptionGet(), DescriptionGetStored(), DescriptionIsValid(), DescriptionLogicalToDisplay(), DescriptionLogicalToOdbc(), DescriptionNormalize(), DescriptionSet()
property DiffieHellmanBits as %Integer (VALUELIST = ",0,512,1024,2048,4096") [ InitialExpression = 0 ];
Size of Diffie Hellman key.
(Relevant for server configurations only)
Default is 0 (Auto)
Property methods: DiffieHellmanBitsDisplayToLogical(), DiffieHellmanBitsGet(), DiffieHellmanBitsGetStored(), DiffieHellmanBitsIsValid(), DiffieHellmanBitsLogicalToDisplay(), DiffieHellmanBitsNormalize(), DiffieHellmanBitsSet(), DiffieHellmanBitsXSDToLogical()
property Enabled as Security.Datatype.BooleanYN [ InitialExpression = 1 ];
Configuration is enabled.
Property methods: EnabledDisplayToLogical(), EnabledGet(), EnabledGetStored(), EnabledIsValid(), EnabledLogicalToDisplay(), EnabledLogicalToOdbc(), EnabledLogicalToXSD(), EnabledNormalize(), EnabledOdbcToLogical(), EnabledSet(), EnabledXSDToLogical()
property Name as %String (MAXLEN = 64, MINLEN = 1) [ Required ];
SSL configuration name.
Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
property OCSP as %Integer (MAXVAL = 1, MINVAL = 0) [ InitialExpression = 0 , Required ];
OCSP Stapling.

Clients:
0 = None
1 = Require valid OCSP Stapling (continue only if OCSP verification succeeds)

Servers:
0 = None
1 = Support OCSP Stapling
Property methods: OCSPDisplayToLogical(), OCSPGet(), OCSPGetStored(), OCSPIsValid(), OCSPLogicalToDisplay(), OCSPNormalize(), OCSPSet(), OCSPXSDToLogical()
property OCSPIssuerCert as %String (MAXLEN = 255);
OCSPIssuerCert.
For Servers with OCSP Stapling support, this is issuer certificate to be used when
requesting an OCSP response.
Property methods: OCSPIssuerCertDisplayToLogical(), OCSPIssuerCertGet(), OCSPIssuerCertGetStored(), OCSPIssuerCertIsValid(), OCSPIssuerCertLogicalToDisplay(), OCSPIssuerCertLogicalToOdbc(), OCSPIssuerCertNormalize(), OCSPIssuerCertSet()
property OCSPResponseFile as %String (MAXLEN = 255);
OCSPResponseFile.
For Servers with OCSP Stapling support, this is the path to store the cached OCSP response file.
Property methods: OCSPResponseFileDisplayToLogical(), OCSPResponseFileGet(), OCSPResponseFileGetStored(), OCSPResponseFileIsValid(), OCSPResponseFileLogicalToDisplay(), OCSPResponseFileLogicalToOdbc(), OCSPResponseFileNormalize(), OCSPResponseFileSet()
property OCSPURL as %String (MAXLEN = 255);
OCSPURL.
For Servers with OCSP Stapling support, this is the URL used to request an OCSP response
Note: this is populated automatically based on the server certificate.
Property methods: OCSPURLDisplayToLogical(), OCSPURLGet(), OCSPURLGetStored(), OCSPURLIsValid(), OCSPURLLogicalToDisplay(), OCSPURLLogicalToOdbc(), OCSPURLNormalize(), OCSPURLSet()
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 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()
deprecated property Protocols as Security.Datatype.Protocol (MAXVAL = 60, MINVAL = 4);
Protocols enabled.
Bit 2 - TLSv1.0
Bit 3 - TLSv1.1
Bit 4 - TLSv1.2
Bit 5 - TLSv1.3
DEPRECATED. Use TLSMinVersion and TLSMaxVersion instead.
Property methods: ProtocolsDisplayToLogical(), ProtocolsGet(), ProtocolsGetStored(), ProtocolsIsValid(), ProtocolsLogicalToDisplay(), ProtocolsLogicalToOdbc(), ProtocolsNormalize(), ProtocolsSet(), ProtocolsXSDToLogical()
deprecated property SNIName as %String;
The fully qualified DNS hostname of the server for use with the Subject Name Indication (SNI) TLS extension DEPRECATED.
Property methods: SNINameDisplayToLogical(), SNINameGet(), SNINameGetStored(), SNINameIsValid(), SNINameLogicalToDisplay(), SNINameLogicalToOdbc(), SNINameNormalize(), SNINameSet()
property TLSMaxVersion as Security.Datatype.TLSVersion (VALUELIST = ",2,4,8,16,32") [ InitialExpression = $s($$$IsOpenSSL10:$$$TLSv12,1:$$$TLSv13) , Required ];
Maximum TLS protocol version enabled.
2 - SSLv3 4 - TLSv1.0 8 - TLSv1.1 16 - TLSv1.2 32 - TLSv1.3 Default = TLSv1.3 Requirement is TLSMaxVersion >= TLSMinVersion
Property methods: TLSMaxVersionDisplayToLogical(), TLSMaxVersionGet(), TLSMaxVersionGetStored(), TLSMaxVersionIsValid(), TLSMaxVersionLogicalToDisplay(), TLSMaxVersionLogicalToOdbc(), TLSMaxVersionNormalize(), TLSMaxVersionSet(), TLSMaxVersionXSDToLogical()
property TLSMinVersion as Security.Datatype.TLSVersion (VALUELIST = ",2,4,8,16,32") [ InitialExpression = $s($$$IsOpenSSL10:$$$TLSv11,1:$$$TLSv12) , Required ];
Minimum TLS protocol version enabled.
2 - SSLv3 4 - TLSv1.0 8 - TLSv1.1 16 - TLSv1.2 32 - TLSv1.3 Default is TLSv1.2
Requirement is TLSMinVersion <= TLSMaxVersion
Property methods: TLSMinVersionDisplayToLogical(), TLSMinVersionGet(), TLSMinVersionGetStored(), TLSMinVersionIsValid(), TLSMinVersionLogicalToDisplay(), TLSMinVersionLogicalToOdbc(), TLSMinVersionNormalize(), TLSMinVersionSet(), TLSMinVersionXSDToLogical()
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.
method ConvertProtocols()
Convert deprecated Protocol property to new Min/MaxVersion
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 = "*", NoPwd As %Boolean = "0") 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 NoPwd - When true, PrivateKeyPassword is not exported
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.
deprecated 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, Type As %String, VerifyDepth As %String, VerifyPeer As %String, EnabledInternal As %Integer, TypeInternal As %Integer, Ciphersuites As %String, TLSMinVersion As %Integer, TLSMaxVersion As %Integer, OCSP As %Integer, OCSPURL As %String, OCSPIssuerCert As %String, OCSPResponseFile As %String, OCSPRequestFailures As %Integer, OCSPTimeout As %Integer, DiffieHellmanBits 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: Storage (Security.SSLConfigs)

^|$$$SecurityMapSSLConfigs|SYS("Security","SSLConfigsD")(ID)
=
%%CLASSNAME
CAFile
CAPath
CertificateFile
CipherList
Description
Enabled
Name
PrivateKeyFile
PrivateKeyPassword
PrivateKeyType
Protocols
Type
VerifyDepth
VerifyPeer
CRLFile
SNIName
TLSMaxVersion
TLSMinVersion
Ciphersuites
OCSP
OCSPURL
OCSPIssuerCert
OCSPResponseFile
OCSPRequestFailures
OCSPTimeout
DiffieHellmanBits
Version
FeedbackOpens in a new tab