DCMTK Howto: User Identity Negotiation

 

Howto: User Identity Negotiation

Since April 2008 DCMTK allows for handling a feature called User Identity Negotiation, which is an optional mechanism to send/receive user credentials, a Kerberos ticket or aSAML assertion during DICOM association negotiation.

The implemenation is part of the dcmnet module and is implemented (mainly) in the files dcuserid.cc and dcuserid.h. However, for accessing this feature one should use the APIfunctions provided by assoc.h.

At the moment there are 4 identification modes for User Identity Negotiation in DICOM:

1. Username
2. Username / Password
3. Kerberos
4. SAML

All of those are supported (on a lower level) by DCMTK. Note that all identity information (ie. also passwords) are transmitted in plain text, which is not an issue of DCMTK but designed like this in the DICOM standard. If you want this information to be encrypted, you should use a DICOM TLS network connection, which can be accomplished with DCMTK'sdcmtls module.

API for SCU (Client)

There are two different stages in association negotiation, where User Identity Negotiation is exchanged. The first is when the client sends it's negotiation request to the server (SCP). This request contains the identification request itself and can be accessed by the following functions:

Request: Identification mode "user"

To send a username when negotiating an association, use function

 

/** Sets User/Password authentication for User Identity Negotiation
 *  request.
 *  @param params - [in/out] The association parameters to be filled
 *  @param userName - [in]  The username to send (in UTF-8)
 *  @password - [in] Password in UTF-8
 *  @return EC_Normal if user identity could be set, error otherwise
 */
OFCondition
ASC_setIdentRQUserPassword(
    T_ASC_Parameters * params,
    const OFString& userName,
    const OFString& password,
    const OFBool& requestRsp = OFTrue);

 

Request: Identification mode "user / password"

For sending a user / password combination, use

 

/** Sets User/Password authentication for User Identity Negotiation
 *  request.
 *  @param params - [in/out] The association parameters to be filled
 *  @param userName - [in]  The username to send (in UTF-8)
 *  @password - [in] Password in UTF-8
 *  @return EC_Normal if user identity could be set, error otherwise
 */
OFCondition
ASC_setIdentRQUserPassword(
    T_ASC_Parameters * params,
    const OFString& userName,
    const OFString& password,
    const OFBool& requestRsp = OFTrue);

 

Request: Identification mode "Kerberos"

For Kerberos, use

 

/** Sets Kerberos authentication for User Identity Negotiation request.
 *  @param params     - [in/out] The association parameters to be filled
 *  @param kerbTicket - [in]  The kerberos ticket to send (will be copied)
 *  @param length     - [in] Length of kerberos ticket
 *  @return EC_Normal if kerberos ticket could be set, error otherwise
 */
OFCondition
ASC_setIdentRQKerberos(
    T_ASC_Parameters * params,
    const char* kerbTicket,
    const Uint16& length,
    const OFBool& requestRsp = OFTrue);

 

Request: Identification mode "SAML"

And least, for SAML use function

 

/** Sets SAML authentication for User Identity Negotiation request.
 *  @param params - [in/out] The association parameters to be filled
 *  @param saml   - [in]  The SAML information to send (will be copied)
 *  @param length - [in] Length of SAML information
 *  @return EC_Normal if SAML info could be set, error otherwise
 */
OFCondition
ASC_setIdentRQSaml(
    T_ASC_Parameters * params,
    const char* saml,
    const Uint16& length,
    const OFBool& requestRsp = OFTrue);

 

Response: Evaluating the SCPs response

If the server (SCP) sends an acknoledge to the association request package, there may be some User Identity Negotiaton data included that is a response to the request made by the SCU. To access the SCP's response, the function

 

void
ASC_getCopyOfIdentResponse(T_ASC_Parameters * params,
                           void*& buffer,  unsigned short& bufferLen);

 

is used. The function allocates memory - be sure to delete the result buffer when it is not needed anymore to release the associated memory.

API for SCP

There is only one function to access a received client's User Identification request:

 

/** Returns a copy of the User Identity Negotiation response value.
 *  CAUTION: The returned buffer (copy of orginal data) must be freed by the
 *  caller!
 *  @param params - [in]  The association parameters to get response from
 *  @param buffer - [out] The buffer to write to. Memory is allocated inside
 *                        function, so the returned buffer memory must be freed
 *                        by the caller. If there is no response or there was
 *                        was a problem, NULL is returned here.
 *  @param length - [out] Length of returned buffer. If there is a problem or no
 *                        response at all, this is set to 0.
 *  @return none
 */

------------------------------------------------------------------

柳北风儿

http://qimo601.iteye.com

转载：http://support.dcmtk.org/wiki/dcmtk/howto/useridentitynegotiation