persistent class %SYS.X509Credentials
extends %Persistent, %XML.Adaptor, %SYSTEM.Help
The %SYS.X509Credentials class defines the X.509 credentials which consist
of an X.509 certificate and an optionally associated private key.
An optional OwnerList may be specified to restrict which users have access to
these credentials. The normal Cache object and SQL methods for accessing this
data should not be used and will not work with normal security in order to
maintain the security of the credentials.
EMS NOTE: If EMSManageX509Credentials is defined, then SSL configurations will be
managed by the EMS server
• property Alias
as %String(MAXLEN=150) [ Required ];
The Alias is defined on import and identifies the X.509 certificate and private key.
• property Certificate
as %Binary(MAXLEN="") [ Required ];
The X.509 certificate.
• property IssuerDN
as %String(MAXLEN="");
Issuer DistinguishedName of the certificate.
This property is only set via the LoadCertificate method.
• property OwnerList
as %String(MAXLEN="");
The optional comma separated list of usernames which may access these credentials.
If no OwnerList is specified, the credentials are available to any user.
• property PeerNames
as %String(MAXLEN="");
PeerNames is an optional comma separated list of peers which expect this
certificate to be used. Each peer name will normally be a DNS name.
However, any application defined name may be used.
• property PrivateKey
as %Binary(MAXLEN="");
The private key associated with the certificate.
• property PrivateKeyPassword
as %String(MAXLEN=128);
Optional password for the private key.
• property PrivateKeyType
as %String(VALUELIST=",RSA,DSA") [ InitialExpression = "RSA",Required ];
The type of the associated private key.
Only RSA is aupported initially.
• property SerialNumber
as %String;
SerialNumber of the certificate -- unique for the Issuer.
This property is only set via the LoadCertificate method.
• property SubjectDN
as %String(MAXLEN="");
Subject DistinguishedName of the certificate.
This property is only set via the LoadCertificate method.
• property SubjectKeyIdentifier
as %Binary;
X.509 SubjectKeyIdentifier from the certificate.
This property is only set via the LoadCertificate method.
• property Thumbprint
as %Binary;
SHA1 Thumbprint of the certificate
This property is only set via the LoadCertificate method.
• method CheckPeerName(peerName As %String)
as %Boolean
Check if specified peer name is valid for this set of credentials.
• classmethod Delete(alias As %String)
as %Status
The Delete method deletes an existing X509Credentials object specified by its alias.
• method Equals(credentials As %SYS.X509Credentials)
as %Boolean
Return true if the same credentials -- same certificate in this case.
• classmethod Exists(Name As %String, ByRef X509Credential As %ObjectHandle, ByRef Status As %Status)
as %Boolean
X509Credential exists.
This method checks for the existence of a X509Credential in the security database.
Parameters:
Name - Name of the X509Credential to check existence of
Return values:
If Value of the method = 0 (X509Credential does not exist, or some error occured)
X509Credential = Null
Status = X509Credential "x" does not exist, or other error message
If Value of the method = 1 (X509Credential exists)
X509Credential = Object handle to X509Credential
Status = $$$OK
• classmethod Export(FileName As %String = "X509CredentialsExport.xml", ByRef NumExported As %Integer, X509Credentials As %String = "*")
as %Status
This method exports X509Credential records to a file in xml format.
Parameters:
Filename - Output file name
NumExported (byref) - Returns number of records exported.
X509Credentials - Comma separated list of X509Credentials to export, "*" = All
• classmethod FindByField(fieldName As %String, searchValue As %String, credentialsList As %ListOfObjects)
as %ListOfObjects
Find the %SYS.X509Credentials instances which have a match in the specified
field to the specified value.
If the credentialsList property is specified, then only matches from this
list are returned. Otherwise all matches from the database are returned.
The following searches are supported:
Alias - Unique, exact match on the Alias
Certificate - Unique, exact match on the certificate
SubjectKeyIdentifier - Unique, exact match to the SubjectKeyIdentifier
Thumbprint - Unique, exact match to the Thumbprint
SerialNumber - Exact match to the serial number
IssuerDN - Case insensitive match to the Issuer DistinguishedName
IssuerName - Case insensitive match to any Issuer DistinguishedName which contains the searchValue.
SubjectDN - Case insensitive match to the Subject DistinguishedName
SubjectName - Case insensitive match to any Subject DistinguishedName which contains the searchValue
PeerNames - Case insensitive match to any PeerNames list which contains the searchValue
OwnerList - Case insensitive match to any OwnerList list which contains the searchValue
A %ListOfObjects is returned containing the matching %SYS.X509Credentials instances.
The %ListOfObjects will have no entries if there are no matches.
If the field name is not valid, then "" will be returned.
• classmethod FindByFieldNumber(field As %Integer, searchValue As %String, caseSensitive As %Boolean, contains As %Boolean, credentialsList As %ListOfObjects)
as %ListOfObjects
Internal function to find the %SYS.X509Credentials instances which have a match in the specified
field number to the specified value.
If the credentialsList property is specified, then only matches from this
list are returned. Otherwise all matches from the database are returned.
• classmethod GetByAlias(alias As %String, pwd As %String)
as %SYS.X509Credentials
Get a X.509 credentials record based on the unique alias.
The record must have a null OwnerList or be owned by the current user to be returned.
• classmethod GetByCertificate(searchValue As %Binary)
as %SYS.X509Credentials
Get a X.509 credentials record based on the unique X.509 certificate.
The record must have a null OwnerList or be owned by the current user to be returned.
• classmethod GetByRSAKeyValue(searchValue As %XML.Security.RSAKeyValue)
as %SYS.X509Credentials
Get a X.509 credentials record which has a certificate whose
public key matches the specified RSAKeyValue.
The record must have a null OwnerList or be owned by the current user to be returned.
• classmethod GetBySubjectKeyIdentifier(searchValue As %Binary)
as %SYS.X509Credentials
Get a X.509 credentials record based on the unique SubjectKeyIdentifier.
The record must have a null OwnerList or be owned by the current user to be returned.
• classmethod GetByThumbprint(searchValue As %Binary)
as %SYS.X509Credentials
Get a X.509 credentials record based on the unique SHA1 Thumbprint.
The record must have a null OwnerList or be owned by the current user to be returned.
• classmethod GetNext(ByRef alias As %String)
as %SYS.X509Credentials
Return the next X.509 credentials object that is accessible to
the current user based on the alias argument. Return "" if no more objects available. The alias argument is
updated to correspond to the returned object.
• classmethod GetProperties(X509Credential As %ObjectHandle, ByRef Properties As %String)
as %Status
Get a X509Credential's properties.
Gets a X509Credential's properties from the security database.
Parameters:
X509Credential - Object handle to a X509Credentials record
Return values:
Properties - See the Get method for more information on properties returned
• classmethod Import(FileName As %String = "X509CredentialsExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0)
as %Status
Import X509Credential records from an xml file.
Parameters:
FileName - Filename to import X509Credential 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
• method LoadCertificate(filename As %String)
as %Status
Load a certificate from a certificate file.
• method LoadPrivateKey(filename As %String)
as %Status
Load a private key from a private key file.
• classmethod Modify(Name As %String, ByRef Properties As %String)
as %Status
Modify a X509Credential.
Modify an existing X509Credential's properties in the security database.
Parameters:
Name - Name of the X509Credential to modify
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,
the value is not modified.
• classmethod NormalizeDN(name As %String)
as %String
Convert variants of the string representation of a Distinguished Name as defined by
section 4 of RFC 2253 to normal form
• method Save()
as %Status
The Save method saves an X509Credentials object.
To save a new X509Credentials object use the following procedure:
- get a new object with %New.
- set required unique Alias property.
- set any needed properties.
- load the certificate with the LoadCertificate method.
- load the private key with the LoadPrivateKeymethod.
- call the Save method.
• query ListAll()
SQL Query
:
SELECT Alias, OwnerList, Certificate, PrivateKeyType, PrivateKey, PrivateKeyPassword, PeerNames, SubjectKeyIdentifier, Thumbprint, SerialNumber, IssuerDN, SubjectDN FROM X509Credentials
ORDER BY Alias
• query ListDetails()
SQL Query
:
SELECT Alias, OwnerList, PeerNames, IFNULL(PrivateKey,0,1) As HasPrivateKey FROM X509Credentials
ORDER BY Alias
• query ListPrivateKey()
SQL Query
:
SELECT Alias, OwnerList, PeerNames, IFNULL(PrivateKey,0,1) As HasPrivateKey FROM X509Credentials
WHERE PrivateKey IS NOT NULL
ORDER BY Alias
• index (IDIndex on Alias) [IdKey,Unique];
The IDKEY for the credentials is a unique user defined alias.
