%SYS.X509Credentials

persistent class %SYS.X509Credentials extends %Library.Persistent, %XML.Adaptor, %SYSTEM.Help [ Final ]

SQL Table Name: %SYS.X509Credentials

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.

Method Inventory

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 methods: AliasDisplayToLogical(), AliasGet(), AliasGetStored(), AliasIsValid(), AliasLogicalToDisplay(), AliasLogicalToOdbc(), AliasNormalize(), AliasSet()

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 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 methods: CAFileDisplayToLogical(), CAFileGet(), CAFileGetStored(), CAFileIsValid(), CAFileLogicalToDisplay(), CAFileLogicalToOdbc(), CAFileNormalize(), CAFileSet()

property Certificate as %Binary) [ Required ];

The X.509 certificate.

Property methods: CertificateGet(), CertificateGetStored(), CertificateIsValid(), CertificateLogicalToXSD(), CertificateXSDToLogical()

property IssuerDN as %String);

Issuer DistinguishedName of the certificate. This property is only set via the LoadCertificate method.

Property methods: IssuerDNDisplayToLogical(), IssuerDNGet(), IssuerDNGetStored(), IssuerDNIsValid(), IssuerDNLogicalToDisplay(), IssuerDNLogicalToOdbc(), IssuerDNNormalize()

property OwnerList as %String);

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 methods: OwnerListDisplayToLogical(), OwnerListGet(), OwnerListGetStored(), OwnerListIsValid(), OwnerListLogicalToDisplay(), OwnerListLogicalToOdbc(), OwnerListNormalize(), OwnerListSet()

property PeerNames as %String);

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 methods: PeerNamesDisplayToLogical(), PeerNamesGet(), PeerNamesGetStored(), PeerNamesIsValid(), PeerNamesLogicalToDisplay(), PeerNamesLogicalToOdbc(), PeerNamesNormalize(), PeerNamesSet()

property PrivateKey as %String) [ 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 methods: PrivateKeyDisplayToLogical(), PrivateKeyIsValid(), PrivateKeyLogicalToDisplay(), PrivateKeyLogicalToOdbc(), PrivateKeyNormalize()

property PrivateKeyPassword as %String (MAXLEN = 128, XMLIO = "IN") [ 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 methods: PrivateKeyPasswordDisplayToLogical(), PrivateKeyPasswordIsValid(), PrivateKeyPasswordLogicalToDisplay(), PrivateKeyPasswordLogicalToOdbc(), PrivateKeyPasswordNormalize()

property PrivateKeyType as %String (VALUELIST = ",RSA,DSA") [ InitialExpression = "RSA" , Required ];

The type of the associated private key. Only RSA is supported initially.

Property methods: PrivateKeyTypeDisplayToLogical(), PrivateKeyTypeGet(), PrivateKeyTypeGetStored(), PrivateKeyTypeIsValid(), PrivateKeyTypeLogicalToDisplay(), PrivateKeyTypeLogicalToOdbc(), PrivateKeyTypeNormalize(), PrivateKeyTypeSet()

property SerialNumber as %String;

SerialNumber of the certificate -- unique for the Issuer. This property is only set via the LoadCertificate method.

Property methods: SerialNumberDisplayToLogical(), SerialNumberGet(), SerialNumberGetStored(), SerialNumberIsValid(), SerialNumberLogicalToDisplay(), SerialNumberLogicalToOdbc(), SerialNumberNormalize()

property SubjectDN as %String);

Subject DistinguishedName of the certificate. This property is only set via the LoadCertificate method.

Property methods: SubjectDNDisplayToLogical(), SubjectDNGet(), SubjectDNGetStored(), SubjectDNIsValid(), SubjectDNLogicalToDisplay(), SubjectDNLogicalToOdbc(), SubjectDNNormalize()

property SubjectKeyIdentifier as %Binary;

X.509 SubjectKeyIdentifier from the certificate. This property is only set via the LoadCertificate method.

Property methods: SubjectKeyIdentifierGet(), SubjectKeyIdentifierGetStored(), SubjectKeyIdentifierIsValid(), SubjectKeyIdentifierLogicalToXSD(), SubjectKeyIdentifierXSDToLogical()

property Thumbprint as %Binary;

SHA1 Thumbprint of the certificate This property is only set via the LoadCertificate method.

Property methods: ThumbprintGet(), ThumbprintGetStored(), ThumbprintIsValid(), ThumbprintLogicalToXSD(), ThumbprintXSDToLogical()

property ValidityNotAfter as %TimeStamp [ Calculated , Transient , ReadOnly ];

X.509 ValidityNotAfter from the certificate.

Property methods: ValidityNotAfterCompute(), ValidityNotAfterDisplayToLogical(), ValidityNotAfterIsValid(), ValidityNotAfterLogicalToDisplay(), ValidityNotAfterLogicalToXSD(), ValidityNotAfterNormalize(), ValidityNotAfterOdbcToLogical(), ValidityNotAfterSQLCompute(), ValidityNotAfterXSDToLogical()

property ValidityNotBefore as %TimeStamp [ Calculated , Transient , ReadOnly ];

X.509 ValidityNotBefore from the certificate.

Property methods: ValidityNotBeforeCompute(), ValidityNotBeforeDisplayToLogical(), ValidityNotBeforeIsValid(), ValidityNotBeforeLogicalToDisplay(), ValidityNotBeforeLogicalToXSD(), ValidityNotBeforeNormalize(), ValidityNotBeforeOdbcToLogical(), ValidityNotBeforeSQLCompute(), ValidityNotBeforeXSDToLogical()

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 occurred)
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 = "*", IncludePrivateKey As %Boolean = 0) 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
IncludePrivateKey - boolean value. If 1 (true), then the private key and password will be included in the export file, otherwise it will be omitted. It is the responsibility of the caller to secure the resulting file.

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

Indexes

index (IDIndex on Alias) [IdKey, Type = key, Unique];

The IDKEY for the credentials is a unique user defined alias.

Index methods: IDIndexCheck(), IDIndexDelete(), IDIndexExists(), IDIndexOpen(), IDIndexSQLCheckUnique(), IDIndexSQLExists(), IDIndexSQLFindPKeyByConstraint(), IDIndexSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods

Storage

Storage Model: Storage (%SYS.X509Credentials)

^|"^^"_$zu(12)|SYS("Security","X509CredentialsD")(ID)

%%CLASSNAME

OwnerList

Certificate

PrivateKeyType

PrivateKey

PrivateKeyPassword

PeerNames

SubjectKeyIdentifier

Thumbprint

SerialNumber

IssuerDN

SubjectDN

CAFile

HasPrivateKey

Version