%SYS.X509Credentials
Class %SYS.X509Credentials Extends (%Persistent, %XML.Adaptor, %SYSTEM.Help) [ Final, System = 4 ]
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.
Parameters
DOMAIN
Parameter DOMAIN = "%Utility";
Default Localization Domain
VERSION
Parameter VERSION [ Internal ] = 1;
SOURCECONTROL
Parameter SOURCECONTROL [ Internal ] = {"Revision path: $Id: //iris/2024.3.0/databases/sys/cls/SYS/X509Credentials.xml#1 $"_$c(13,10)_"Last Change: $DateTime: 2024/10/02 10:58:11 $"_$c(13,10)_"Changelist #: $Change: 7247250 $"};
Properties
Alias
Property Alias As %String(MAXLEN = 150) [ Required ];
The IDKEY for the credentials is a unique user defined alias. The Alias is defined on import and identifies the X.509 certificate and private key.
OwnerList
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.
Certificate
Property Certificate As %Binary(MAXLEN = "") [ Required ];
The X.509 certificate.
PrivateKeyType
Property PrivateKeyType As %String(VALUELIST = ",RSA,DSA") [ InitialExpression = "RSA", Required ];
The type of the associated private key. Only RSA is supported initially.
PrivateKey
Property PrivateKey As %String(MAXLEN = "", XMLIO = "IN") [ 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.
PrivateKeyPassword
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.
PrivateKeyExport
Property PrivateKeyExport As %String(MAXLEN = "", XMLIO = "OUT", XMLNAME = "PrivateKey") [ Internal, Transient ];
This property is used internally by InterSystems IRIS. You should not make direct use of it within your applications.
PrivateKeyPasswordExport
Property PrivateKeyPasswordExport As %String(MAXLEN = 128, XMLIO = "OUT", XMLNAME = "PrivateKeyPassword") [ Internal, Transient ];
This property is used internally by InterSystems IRIS. You should not make direct use of it within your applications.
HasPrivateKey
Property HasPrivateKey As %Boolean [ InitialExpression = 0, Internal ];
Returns if a private key is present even if no privileges.
CAFile
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.
PeerNames
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.
SubjectKeyIdentifier
Property SubjectKeyIdentifier As %Binary;
X.509 SubjectKeyIdentifier from the certificate. This property is only set via the LoadCertificate method.
Thumbprint
Property Thumbprint As %Binary;
SHA1 Thumbprint of the certificate This property is only set via the LoadCertificate method.
SerialNumber
Property SerialNumber As %String;
SerialNumber of the certificate -- unique for the Issuer. This property is only set via the LoadCertificate method.
IssuerDN
Property IssuerDN As %String(MAXLEN = "");
Issuer DistinguishedName of the certificate. This property is only set via the LoadCertificate method.
SubjectDN
Property SubjectDN As %String(MAXLEN = "");
Subject DistinguishedName of the certificate. This property is only set via the LoadCertificate method.
ValidityNotBefore
Property ValidityNotBefore As %TimeStamp [ Calculated, ReadOnly, SqlComputeCode = { Set {ValidityNotBefore} = $select({Certificate}="":"",1:$System.Encryption.X509GetField({Certificate},"ValidityNotBefore")) }, SqlComputed, Transient ];
X.509 ValidityNotBefore from the certificate.
ValidityNotAfter
Property ValidityNotAfter As %TimeStamp [ Calculated, ReadOnly, SqlComputeCode = { Set {ValidityNotAfter} = $select({Certificate}="":"",1:$System.Encryption.X509GetField({Certificate},"ValidityNotAfter")) }, SqlComputed, Transient ];
X.509 ValidityNotAfter from the certificate.
Version
Property Version As %Decimal(SCALE = 1) [ Internal ];
Version number of the record.
Used for Export/Import.
Methods
CertificateSet
Method CertificateSet(certificate As %Binary) As %Status [ Internal ]
Setter method for Certificate.
PrivateKeySet
Method PrivateKeySet(privateKey As %String) As %Status [ Internal, PlaceAfter = FieldNumber ]
Store private key only if user has %Admin_Secure.
PrivateKeyGet
Method PrivateKeyGet() As %String [ Internal, PlaceAfter = FieldNumber ]
Get private key only if user has %Admin_Secure.
PrivateKeyPasswordSet
Method PrivateKeyPasswordSet(privateKeyPassword As %String) As %Status [ Internal, PlaceAfter = FieldNumber ]
Set private key password.
PrivateKeyPasswordGet
Method PrivateKeyPasswordGet() As %String [ Internal, PlaceAfter = FieldNumber ]
Get private key password only if user has %Admin_Secure.
PrivateKeyExportGet
Method PrivateKeyExportGet() As %String [ Internal, Private ]
PrivateKeyExportSet
Method PrivateKeyExportSet(val As %String) As %Status [ Internal, Private ]
PrivateKeyPasswordExportGet
Method PrivateKeyPasswordExportGet() As %String [ Internal, Private ]
PrivateKeyPasswordExportSet
Method PrivateKeyPasswordExportSet(val As %String) As %Status [ Internal, Private ]
SubjectKeyIdentifierSet
Method SubjectKeyIdentifierSet(value As %Binary) As %Status [ Internal, Private ]
For SubjectKeyIdentifier to be read-only.
ThumbprintSet
Method ThumbprintSet(value As %Binary) As %Status [ Internal, Private ]
For Thumbprint to be read-only.
SerialNumberSet
Method SerialNumberSet(value As %Binary) As %Status [ Internal, Private ]
For SerialNumber to be read-only.
IssuerDNSet
Method IssuerDNSet(value As %String) As %Status [ Internal, Private ]
For IssuerDN to be read-only.
SubjectDNSet
Method SubjectDNSet(value As %String) As %Status [ Internal, Private ]
For SubjectDN to be read-only.
ValidityNotBeforeGet
Method ValidityNotBeforeGet() As %TimeStamp [ CodeMode = expression, Internal ]
Getter for ValidityNotBefore.
ValidityNotBeforeSet
Method ValidityNotBeforeSet(value As %TimeStamp) As %Status [ Internal, Private ]
For ValidityNotBefore to be read-only.
ValidityNotAfterGet
Method ValidityNotAfterGet() As %TimeStamp [ CodeMode = expression, Internal ]
Getter for ValidityNotAfter.
ValidityNotAfterSet
Method ValidityNotAfterSet(value As %TimeStamp) As %Status [ Internal, Private ]
For ValidityNotAfter to be read-only.
Equals
Method Equals(credentials As %SYS.X509Credentials) As %Boolean
Return true if the same credentials -- same certificate in this case.
Save
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.
%OnAfterSave
Method %OnAfterSave(insert As %Boolean) As %Status [ Internal, PlaceAfter = FieldNumber, Private ]
This callback method is invoked by the %Save method to provide notification that the object is being saved. It is called after the object's data has been successfully written to disk.
insert will be set to 1 if this object is being saved for the first time.
If this method returns an error then the call to %Save will fail.
%OnValidateObject
Method %OnValidateObject(ReadOnly As %Boolean = 0) As %Status [ Private, ServerOnly = 1 ]
Validate the object during save. Note that the PrivateKey property is accessed from memory during save.
%OnBeforeSave
Method %OnBeforeSave(insert As %Boolean) As %Status [ Internal, Private, ServerOnly = 1 ]
Caller of %Save must have secureity admin resource.
%OnOpen
Method %OnOpen() As %Status [ Internal, Private, ServerOnly = 1 ]
Make sure that HasPrivateKey is always correctly defined
BinaryToHexString
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.
LoadCertificate
Method LoadCertificate(filename As %String) As %Status
Load a certificate from a certificate file.
LoadPrivateKey
Method LoadPrivateKey(filename As %String) As %Status
Load a private key from a private key file.
Delete
ClassMethod Delete(alias As %String) As %Status
The Delete method deletes an existing X509Credentials object specified by its alias.
%OnDelete
ClassMethod %OnDelete(oid As %ObjectIdentity) As %Status [ Internal, Private, ServerOnly = 1 ]
Caller of %Delete must have security admin resource.
FieldNumber
ClassMethod FieldNumber(fieldName As %String) As %Integer [ Internal, Private ]
Internal method to return field position based on name.
GetByAlias
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.
GetBySubjectKeyIdentifier
ClassMethod GetBySubjectKeyIdentifier(searchValue As %Binary) As %SYS.X509Credentials [ PlaceAfter = FieldNumber ]
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.
GetByThumbprint
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.
GetByCertificate
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.
GetByCertificateWithPrivateKey
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.
GetByRSAKeyValue
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.
GetByField
ClassMethod GetByField(fieldName As %Integer, searchValue As %Binary) As %SYS.X509Credentials [ Internal ]
Get a X.509 credentials record based on the unique field name of the credentials object. The possible field names are Certificate, SubjectKeyIdentifier, Thumbprint, SerialNumber, IssuerDN, SubjectDN, PeerNames, OwnerList. Note that only Certificate, SubjectKeyIdentifier, Thumbprint are sure to have an exact match. FindByField shold normally be used for the other fields. The match is exact and case sensitive. The first match is returned. The record must have a null OwnerList or be owned by the current user to be returned.
GetByFieldNumber
ClassMethod GetByFieldNumber(field As %Integer, searchValue As %Binary) As %SYS.X509Credentials [ Internal, Private ]
Get a X.509 credentials record based on the unique field number of the credentials object. The record must have a null OwnerList or be owned by the current user to be returned.
CheckFieldName
ClassMethod CheckFieldName(fieldName As %String) As %Boolean [ Internal ]
Check that the field name is valid for search by FindByField
FindByField
ClassMethod FindByField(fieldName As %String, searchValue As %String, credentialsList As %ListOfObjects) As %ListOfObjects [ PlaceAfter = FieldNumber ]
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.
FindByFieldNumber
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.
CheckPeerName
Method CheckPeerName(peerName As %String) As %Boolean [ CodeMode = expression ]
Check if specified peer name is valid for this set of credentials.
GetNext
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.
NormalizeDN
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
Exists
ClassMethod Exists(Name As %String, ByRef X509Credential As %ObjectHandle, ByRef Status As %Status) As %Boolean
Escape special characters in quoted strings, remove quotes Replace unescaped ";" with "," Remove extra space around unescaped ",", "+", and "=" 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
Export
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.
GetProperties
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
Import
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
Modify
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.
RSADecrypt
Method RSADecrypt(ciphertext As %String, encoding As %Integer) As %String
Decrypt using the private key and password for these credentials
RSASize
Method RSASize() As %Integer
Find the size of the signature using the private key and password for these credentials
RSASHASign
Method RSASHASign(bitlength As %Integer, data As %String) As %String
Sign using the private key and password for these credentials
SetHasPrivateKeyWhereUnset
ClassMethod SetHasPrivateKeyWhereUnset() As %Status [ Internal ]