Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo
back

NAE-XML Interface Development

User Requests

search

User Requests

The XML Interface accepts requests to:

User and group administration is unavailable with global sessions. Furthermore, administration is very limited for users without User Administration Permission. Such users can only query information about themselves using the UserInfoRequest element; all other user-related requests will yield an Insufficient Permissions error.

UserCreateRequest

Create a new user.

The authenticated user must have administrator privileges to create new users.

<UserCreateRequest>
    <ID>...</ID>
    <User>...</User>
    <Passwd>...</Passwd>
    <ModifyUserInfo>...</ModifyUserInfo> # optional
    <CustomAttributeList>
        <CustomAttribute>                #optional
            <Name>...</Name>
            <Value>...</Value>
        </CustomAttribute>
    </CustomAttributeList>
</UserCreateRequest>

The users created using this request are added to the Key Users group, which enables these users to perform basic key operations. However, while creating users from the CipherTrust Manager UI or REST interface, the users created are not added automatically to the Key Users group. This step needs to be done separately.

Element Description
ID Contains the user-specified request ID.
User Contains the username to create. The username cannot change.
Passwd Contains the password for this user.
ModifyUserInfo Indicates whether a user can change his or her own password. Possible values are true or false; the default is false. This element is optional.
CustomAttributeList Specifies the list of custom attributes. This element can contain multiple CustomerAttribute elements. This element is optional.
CustomAttribute Contains one Name and one Value element. This element is optional.

UserCreateResponse

Server response to a UserCreateRequest.

<UserCreateResponse>
   <ID>...</ID>
   <Success>...</Success>
</UserCreateResponse>
Element Description
ID Contains the user-specified request ID.
Success Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the new user is created. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.

Creating a User

In the example below, the client creates a new user.

<UserCreateRequest>
   <ID>4</ID>
   <User>new_user</User>
   <Passwd>SecretPassword</Passwd>
   <ModifyUserInfo>true</ModifyUserInfo>
</UserCreateRequest>
<UserCreateResponse>
   <ID>4</ID>
   <Success>true</Success>
</UserCreateResponse>

UserDeleteRequest

Delete an existing user.

The authenticated user must have administrator privileges to delete users.

<UserDeleteRequest>
   <ID>...</ID>
   <User>...</User>
</UserDeleteRequest>
Element Description
ID Contains the user-specified request ID.
User Contains the username to delete.

UserDeleteResponse

Server response to a UserDeleteResponse.

<UserDeleteResponse>
   <ID>...</ID>
   <Success>...</Success>
</UserDeleteResponse>
Element Description
ID Contains the user-specified request ID.
Success Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the new user is deleted. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.

Deleting a User

Below, the client deletes a user from the server.

<UserDeleteRequest>
   <ID>13</ID>
   <User>new_user</User>
</UserDeleteRequest>
<UserDeleteResponse>
   <ID>13</ID>
   <Success>true</Success>
</UserDeleteResponse>

UserModifyRequest

Modify the password or the Change Password permission for a user.

Users with administrator privileges can change the password or the Change Password permission for any user.

Users without administrator privileges may only change their own password through this interface if they have the Change Password permission enabled. They may not modify the Change Password permission.

<UserModifyRequest>
    <ID>...</ID>
    <User>...</User>
    <Passwd>...</Passwd>                   # optional
    <ModifyUserInfo>true</ModifyUserInfo>  # optional
    <CustomAttributeList>                   # include to add or update
        <CustomAttribute>               # custom attributes, optional
            <Name>...</Name>
            <Value>...</Value>
        </CustomAttribute>
        ...
    </CustomAttributeList>
    <DeleteCustomAttribute>             # include to delete an existing
        <Name>...</Name>                # custom attribute
        <Name>...</Name>
    </DeleteCustomAttribute>
    <DeleteAllCustomAttributes/>         # include to delete all custom attributes
</UserModifyRequest>
Element Description
ID Contains the user-specified request ID.
User Contains the name of the user to modify.
Passwd Contains the password if the password is to be changed. If the element is omitted, the existing password is unchanged. This element is optional.
ModifyUserInfo Contains the new password permission, if the permission is to be changed. Setting the value to true enables the user to change their own password. Setting the value to false disables this ability. If the element is omitted, the existing permission is unchanged. This element is optional.
CustomAttributeList Contains the custom attributes that will be added or updated. Child elements are CustomAttribute, Name, and Value. Values must be base64 encoded, and input is considered as text. If your original data contains non-printable characters, convert the original data to hex values, and then convert the hex values to base64.
CustomAttribute Contains one Name and one Value element. This element is optional.
DeleteCustomAttribute Deletes the custom attributes listed in the Name element.
DeleteAllCustomAttribute Deletes all the user's custom attributes.

UserModifyResponse

Server response to a UserModifyRequest.

<UserModifyResponse>
   <ID>...</ID>
   <Success>...</Success>
</UserModifyResponse>
Element Description
ID Contains the user-specified request ID.
Success Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the user modifications are implemented. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.

Modifying a User's Password

In the example below, the client modifies the password for a user.

<UserModifyRequest>
   <ID>5</ID>
   <User>new_user</User>
   <Passwd>another_password</Passwd>
</UserModifyRequest>
<UserModifyResponse>
   <ID>5</ID>
   <Success>true</Success>
</UserModifyResponse>

UserInfoRequest

Retrieve information about a single user.

Any user can request information about themselves; only users with administrator permissions can request information about other users.

<UserInfoRequest>
   <ID>...</ID>
   <User>...</User>
</UserInfoRequest>
Element Description
ID Contains the user-specified request ID.
User Contains the subject of the query.

By default, the system-defined groups are visible but can be masked if the mask_system_groups flag for the NAE interface is set to true. The flag can be changed using the ksctl utility. For details, refer to To create/modify the NAE interface to mask system groups from NAE requests.

UserInfoResponse

Server response to a UserInfoRequest.

<UserInfoResponse>
    <ID>...</ID>
    <Success>...</Success>
    <User>...</User>
    <ModifyUserInfo>...</ModifyUserInfo>
    <CustomAttributeList>
        <CustomAttribute>
            <Name>...</Name>
            <Value>...</Value>
        </CustomAttribute>
    </CustomAttributeList>
   <GroupList>
        <Group>...</Group>
        ...
   </GroupList>
</UserInfoResponse>
Element Description
ID Contains the user-specified request ID.
Success Indicates whether the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the User, ModifyUserInfo, GroupList, and Group elements described below. When the operation fails, the element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
User Contains the subject of the query.
ModifyUserInfo Contains the value of the change password permission: true if this user can change their password; false otherwise.
CustomAttributeList Contains the list of custom attributes. The actual values are base64 encoded. This element is not included if the user does not have any associated custom attributes.
GroupList Contains a list of groups to which the user belongs. This element is not included if the user does not belong to any groups.
Group Contains the name of the group.

Requesting User Information

In the example below, the client requests information about a user.

<UserInfoRequest>
   <ID>6</ID>
   <User>new_user</User>
</UserInfoRequest>
<UserInfoResponse>
   <ID>6</ID>
   <Success>true</Success>
   <User>new_user</User>
   <ModifyUserInfo>true</ModifyUserInfo>
</UserInfoResponse>

UserQueryRequest

Get information about all the users defined in the server.

The authenticated user must have administrator privileges to use this request.

<UserQueryRequest>
   <ID>...</ID>
</UserQueryRequest>

By default, the system-defined groups are visible but can be masked if the mask_system_groups flag for the NAE interface is set to true. The flag can be changed using the ksctl utility. For details, refer to To create/modify the NAE interface to mask system groups from NAE requests.

Element Description
ID Contains the user-specified request ID.

UserQueryResponse

Server response to a UserQueryRequest.

   <ID>...</ID>
   <Success>...</Success>
   <UserList>
      <UserData>
        <User>...</User>
        <ModifyUserInfo>...</ModifyUserInfo>
        <CustomAttributeList>
            <CustomAttribute>
                <Name>...</Name>
                <Value>...</Value>
            </CustomAttribute>
        </CustomAttributeList>
         <ModifyUserInfo>...</ModifyUserInfo>
         <GroupList>
            <Group>...</Group>
            ...
         </GroupList>
      </UserData>
      ...
   </UserList>
</UserQueryResponse>
Element Description
ID Contains the user-specified request ID.
Success Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the elements described below. When the operation fails, the response contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
UserList Contains a list of UserData elements for each user in the system.
UserData Contains a set of User, ModifyUserInfo and, optionally, GroupList elements that describe a user.
User Contains the username.
CustomAttributeList Contains the list of custom attributes. The actual values are base64 encoded. This element is not included if the user does not have any associated custom attributes.
ModifyUserInfo Contains the value of the change password permission: true if this user can change their password; false otherwise.
GroupList Contains a list of groups to which the user belongs. This element is not included if the user does not belong to any groups.
Group Contains the name of the group.

Querying for all User Information

In the example below, the client requests information about all of the NAE users on a CipherTrust Manager Appliance.

<UserQueryRequest>
   <ID>3</ID>
</UserQueryRequest>
<UserQueryResponse>
   <ID>3</ID>
   <Success>true</Success>
   <UserDataList>
      <UserData>
         <User>NAE_User1</User>
         <ModifyUserInfo>true</ModifyUserInfo>
         <GroupList>
            <Group>group1</Group>
         </GroupList>
      </UserData>
      <UserData>
         <User>NAE_User2</User>
         <ModifyUserInfo>true</ModifyUserInfo>
      </UserData>
         <User>NAE_User3</User>
         <ModifyUserInfo>true</ModifyUserInfo>
      </UserData>
   </UserDataList>
</UserQueryResponse>