IMPORT-PRINCIPAL( ) method

Imports an unsealed or sealed security token as a RAW data type, creates a corresponding client-principal object, and assigns its handle value to the current Client-principal object handle. This corresponding client-principal object assumes all the property and attribute settings of the source client-principal object when it was exported using the EXPORT-PRINCIPAL( ) method.

Return type:

LOGICAL

Applies to:

Client-principal object handle

 

Syntax 

IMPORT-PRINCIPAL ( expression )

expression

A RAW expression containing the security token to import. If the specified expression has the Unknown value (?), the AVM raises a run-time error.

Caution:

To ensure that the transported identity is a trusted identity, it is your responsibility to ensure that you obtain the security token you are importing from a secure source and in a secure manner.

If you set properties on the receiving client-principal object handle before calling this method, either by having previously imported a security token or by setting them in a client-principal that you have created, the property values are lost.

If successful, this method returns TRUE. Otherwise, it returns FALSE with any messages returned in the ERROR-STATUS system handle.

This method also checks the LOGIN-EXPIRATION-TIMESTAMP attribute. If the client-principal object has expired before you can import it, the AVM sets the LOGIN-STATE attribute to "EXPIRED" and the method returns TRUE.

Depending on its sealed or unsealed state, you can use the imported object to assert or set the user identity it represents using the SEAL( ) method, SECURITY-POLICY:SET-CLIENT( ) method, or SET-DB-CLIENT function, as appropriate.

Calling this method does not generate an audit event or an audit record.

See also:

EXPORT-PRINCIPAL( ) method, SET-CLIENT( ) method, SET-DB-CLIENT function