This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).

Security.X509Users

persistent class Security.X509Users extends %Library.Persistent, %XML.Adaptor, %SYSTEM.Help

SQL Table Name: Security.X509Users

This class maps a key to a User. The keys should be obtained from X509 certificates. Use X509Users.GetLookupKey() go get a standard key from a certificate.

Property Inventory (Including Private)

Method Inventory (Including Private)

Properties

property Comment as %String (MAXLEN = 128);
Comment.
Property methods: CommentDisplayToLogical(), CommentGet(), CommentGetStored(), CommentIsValid(), CommentLogicalToDisplay(), CommentLogicalToOdbc(), CommentNormalize(), CommentSet()
property Enabled as Security.Datatype.BooleanYN [ InitialExpression = 1 ];
Allow to log in via this key.
0 - Disable login.
1 - Enable login.
Property methods: EnabledDisplayToLogical(), EnabledGet(), EnabledGetStored(), EnabledIsValid(), EnabledLogicalToDisplay(), EnabledLogicalToODBC(), EnabledLogicalToXSD(), EnabledNormalize(), EnabledSet(), EnabledXSDToLogical()
property LookupKey as %String (MAXLEN = 256) [ Required ];
Comment.
Property methods: LookupKeyDisplayToLogical(), LookupKeyGet(), LookupKeyGetStored(), LookupKeyIndexCheck(), LookupKeyIndexDelete(), LookupKeyIndexExists(), LookupKeyIndexOpen(), LookupKeyIndexSQLCheckUnique(), LookupKeyIndexSQLExists(), LookupKeyIndexSQLFindPKeyByConstraint(), LookupKeyIndexSQLFindRowIDByConstraint(), LookupKeyIsValid(), LookupKeyLogicalToDisplay(), LookupKeyLogicalToOdbc(), LookupKeyNormalize(), LookupKeySet()
property Username as %String (MAXLEN = 128);
UserName to be logged in as.
Property methods: UsernameDisplayToLogical(), UsernameGet(), UsernameGetStored(), UsernameIsValid(), UsernameLogicalToDisplay(), UsernameLogicalToOdbc(), UsernameNormalize(), UsernameSet()

Methods

classmethod Copy(LookupKey As %String, NewLookupKey As %String) as %Status
Copy an X509User.
Copy an existing X509User in the Security database to a new one.
Parameters:
LookupKey - LookupKey of the X509User to be copied.
NewLookupKey - LookupKey of the X509User to be created.
classmethod Create(LookupKey As %String, Username As %String, Enabled As %Boolean, Comment As %String) as %Status
Create a X509User.
Create a X509User in the Security database.
There are 2 ways to call this method and pass the parameters:

s x=##Class(Security.X509Users).Create(LookupKey,username,...)
or
s x=##Class(Security.X509Users).Create(LookupKey,.Properties)

Where Properties are contained in an array subscripted by property name, passed by reference. See the Get() method for a description of the Properies array. Valid properties for the Create() method are described below, other values are ignored.
Parameters:
LookupKey - Key used to lookup Username UserName - Name of the user associated with this key
Enabled - 0/1, account is disabled/enabled
Comment - Comment
classmethod Delete(LookupKey As %String) as %Status
Delete an X509User.
This method will delete a User from the security database.
Parameters:
LookupKey - Key to delete
classmethod Exists(LookupKey As %String, ByRef X509User As %ObjectHandle, ByRef Status As %Status) as %Boolean
X509 User exists.
This method checks for the existence of a user in the security database.
Parameters:
LookupKey - Lookup key of the user to check existence of
Requires the %Admin_Secure:USE privilege to change the $USERNAME value.
Return values:
If Value of the method = 0 (User does not exist, or some error occured)
User = Null
Status = User "x" does not exist, or other error message

If Value of the method = 1 (User exists)
User = Object handle to user
Status = User "x" already exists
classmethod Export(FileName As %String = "X509UsersExport.xml", ByRef NumExported As %Integer = 0, LookupKeys As %String = "*", Usernames As %String = "*") as %Status
This method exports X509User records to a file in xml format.
Parameters:
Filename - Output file name
NumExported (byref) - Returns number of records exported.
LookupKeys - Comma separated list of Keys to export, "*" = All
Usernames - Comma separated list of Usernames, "*" = All. Export X509Users containing only these usernames
classmethod Get(LookupKey As %String, ByRef Properties As %String) as %Status
Get a X509User's properties.
Gets a X509User's properties from the security database.
Parameters:
Username - Name of the user to get
Return values:
Properties - Array of properties
Properties("Comment") - Comment
Properties("Enabled") - 0=Disabled, 1=Enabled
Properties("LookupKey") - Key used to find Username
Properties("Username") - Name of associated user
classmethod GetX509LookupKey(CredentialsCandidate As %String) as %String
Return the lookup key (SubjectDN) for an X509 Certificate.
There are four different ways this can be called where:

1) Certificate = DER Encoded X509 Certificate
2) Certificate = PEM Encoded X509 Certificate
3) Certificate = Alias of %SYS.X509Credentials object
4) Certificate = A %SYS.X509Credentials object

If the certificate cannot be found or is invalid, an empty string is returned.
classmethod Import(FileName As %String = "X509UsersExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0) as %Status
Import User records from an xml file.
Parameters:
FileName - Filename to import User 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
classmethod Modify(LookupKey As %String, ByRef Properties As %String) as %Status
Modify a X509User's properties.
Modifies a X509User's properties from the security database.
Parameters:
LookupKey - Key of the X509User 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.
If a value is unchanged it is not set to prevent the property modified state from being set.

Queries

query List(LookupKeys As %String, Usernames As %String)
Selects LookupKey As %String, Username As %String, Comment As %String, Enabled As %String
List all userkey records, brief display.
Keys - Comma separated list of userkeys, "*" = All
Usernames - Comma separated list of Usernames, "*"=ALL
Note: This query may change in future versions

Indices

index (LookupKeyIndex on LookupKey) [IdKey, Type = key, Unique];
Index methods: LookupKeyIndexCheck(), LookupKeyIndexDelete(), LookupKeyIndexExists(), LookupKeyIndexOpen(), LookupKeyIndexSQLCheckUnique(), LookupKeyIndexSQLExists(), LookupKeyIndexSQLFindPKeyByConstraint(), LookupKeyIndexSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods (Including Private)

Storage

Storage Model: CacheStorage (Security.X509Users)

^|"^^"_$zu(12)|SYS("Security","X509UsersD")(ID)
=
%%CLASSNAME
Comment
Enabled
LookupKey
Username
Feedback