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

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

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 16 49 3 1


Summary

Properties
Alias CAFile Certificate IssuerDN
OwnerList PeerNames PrivateKey PrivateKeyPassword
PrivateKeyType SerialNumber SubjectDN SubjectKeyIdentifier
Thumbprint ValidityNotAfter ValidityNotBefore

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 BinaryToHexString
CheckPeerName Delete Equals Exists
Export FindByField FindByFieldNumber GetByAlias
GetByCertificate GetByCertificateWithPrivateKey GetByRSAKeyValue GetBySubjectKeyIdentifier
GetByThumbprint GetNext GetProperties Help
Import LoadCertificate LoadPrivateKey Modify
NormalizeDN RSADecrypt RSASHASign RSASize
Save XMLDTD XMLExport XMLExportToStream
XMLExportToString XMLNew XMLSchema XMLSchemaNamespace
XMLSchemaType


Parameters

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

Properties

• property Alias as %String(MAXLEN=150) [ Required ];
The Alias is defined on import and identifies the X.509 certificate and private key.
• 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 manager's directory.
When WS-Security validates a Signature where the the certificate is not included in the SOAP message, the certificate is found in an %SYS.X509Credentials object. If the CAFile property is specified in the %SYS.X509Credentials object, CAFile gives the path of the CA file. If the CAFile property is not specified, then iris.cer in the mgr directory is used as the CA file.
• 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 %String(MAXLEN="",XMLPROJECTION="NONE") [ Transient ];
The private key associated with the certificate stored as PEM encoded text. The private key will be in memory only when set before save. The private key will not be loaded from global during open since transient.
• property PrivateKeyPassword as %String(MAXLEN=128,XMLPROJECTION="NONE") [ Transient ];
Optional password for the private key. The private key password will be in memory only when set before save. The private key password will not be loaded from global during open since transient.
• 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.
• property ValidityNotAfter as %TimeStamp [ Calculated,Transient,ReadOnly ];
X.509 ValidityNotAfter from the certificate.
• property ValidityNotBefore as %TimeStamp [ Calculated,Transient,ReadOnly ];
X.509 ValidityNotBefore from the certificate.

Methods

• classmethod BinaryToHexString(input As %Binary) as %String
Change the binary data (stored in Thumbprint and SubjectKeyIdentifier) into formatted hex string. Like zzdump, 8-bit strings will be displayed in 1-byte words, ziswide() strings will be displayed in 2-byte words.
• 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 GetByCertificateWithPrivateKey(searchValue As %Binary) as %SYS.X509Credentials
    Get a X.509 credentials record based on the unique X.509 certificate for use with a private key. 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 RSADecrypt(ciphertext As %String, encoding As %Integer) as %String
    Decrypt using the private key and password for these credentials
    • method RSASHASign(bitlength As %Integer, data As %String) as %String
    Sign using the private key and password for these credentials
    • method RSASize() as %Integer
    Find the size of the signature using the private key and password for these credentials
    • 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.

    Queries

    • query ListAll()
    SQL Query :
    SELECT Alias, OwnerList, Certificate, PrivateKeyType, PeerNames, SubjectKeyIdentifier, Thumbprint, SerialNumber, IssuerDN, SubjectDN, CAFile, ValidityNotBefore, ValidityNotAfter FROM X509Credentials
    ORDER BY Alias
    • query ListDetails()
    SQL Query :
    SELECT Alias, OwnerList, PeerNames, HasPrivateKey, CAFile FROM X509Credentials
    ORDER BY Alias
    • query ListPrivateKey()
    SQL Query :
    SELECT Alias, OwnerList, PeerNames, HasPrivateKey FROM X509Credentials
    WHERE HasPrivateKey = 1
    ORDER BY Alias

    Indices

    •index (IDIndex on Alias) [IdKey,Unique];
    The IDKEY for the credentials is a unique user defined alias.


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