L_DicomCreateNetExt

#include "ltdic.h"

L_LTDIC_API HDICOMNET L_DicomCreateNetExt(pszPath, nMode, pCtxCreate)

L_TCHAR * pszPath;

/* character string */

L_INT32 nMode;

/* initialization mode */

pL_SSL_CTX_CREATE pCtxCreate;

/* pointer to a structure */

Allocates memory for the network structure and sets the site of the temporary files. This function is available in the Medical Suite Toolkit.

This function is an extended version of the L_DicomCreateNet function, to be used when changing security settings.

Parameter

Description

pszPath

Character string containing the location of the temporary files. DICOM uses temporary files during the course of creating a file. If this parameter is NULL, the DICOM temporary files are kept in the directory Windows places its own temporary files. If this parameter is not NULL, the temporary files are placed in the specified directory.

nMode

Flag that indicates which security mode to use when initializing the network structure. Possible values are:

 

Value

Meaning

 

DICOM_SECURE_NONE

Do not use any security mode.

 

DICOM_SECURE_ISCL

Use Integrated Secure Communication Layer protocol security.

 

DICOM_SECURE_TLS

Use Transport Layer Secure protocol security.

pCtxCreate

Pointer to the L_SSL_CTX_CREATE structure that is used when modifying the security defaults. This structure is used only if the nMode flag is DICOM_SECURE_TLS. Pass NULL to get the default values.

Returns

A DICOM Network handle.

Comments

This function is an extended version of the L_DicomCreateNet function, to be used when changing security settings.

Use this version if non-default security settings are desired. For more information about the security options, refer to L_SSL_CTX_CREATE.

Note that the following examples are functionally equivalent:

1.

HDICOMNET hNet;
hNet = L_DicomCreateNext(pszPath, nMode);

2.

HDICOMNET hNet;
hNet = L_DicomCreateNetExt (pszPath, nMode, NULL);

Free allocated memory by calling L_DicomFreeNet.

The LEADTOOLS DICOM DLL should be initialized before calling any DICOM Communication operations function. To initialize the DLL call L_DicomStartUp.

Required DLLs and Libraries

LTDIC

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

Platforms

Win32, x64

See Also

Functions:

L_DicomCreateNet, L_DicomFreeNet, L_DicomStartup, L_DicomSetCallbackExt, PRIVATEKEYPASSWORD, L_DicomSetClientCertificateTLS, L_DicomSetServerCertificateTLS, L_DicomSetCallback

Topics:

Working with DICOM Network Connections
Adding TLS Security to a DICOM Connection
DICOM Network Connection: Creating a Network Connection
DICOM Net: TLS Protocol

Example

This example creates an hNet object with security The hNet object is configured so that if a client connects: 1. it requires and verifies the client certificate 2. it will support SSL version 3 or TLS Version 1 for the handshake 3. it uses trusted certificate authority CA_CERT_NAME to verify the client certificate 4. it verifies the client certificate chain to a maximum depth of 2 The hNet is assigned the certificate SERVER_CERT_NAME, which contains a password encrypted private key The exPrivateKeyPassword callback function is used to supply the encryption password of the private key 

#ifndef CA_CERT_NAME
#define CA_CERT_NAME       TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\CA.pem")
#endif

#ifndef SERVER_CERT_NAME
#define SERVER_CERT_NAME   TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\Server.pem")
#endif 

L_INT EXT_CALLBACK exPrivateKeyPassword(
   HDICOMNET hNet,
   L_TCHAR *pszPassword,
   L_INT nSize,
   L_INT rwFlag,
   L_VOID *pUserData)
{
   UNREFERENCED_PARAMETER(pUserData);
   UNREFERENCED_PARAMETER(rwFlag);
   UNREFERENCED_PARAMETER(nSize);
   UNREFERENCED_PARAMETER(hNet);

   LPCTSTR pszMyPassword= TEXT("test");

   // copy the private key password into the pszPassword buffer, and return the length
   lstrcpy(pszPassword, pszMyPassword);
   return lstrlen(pszMyPassword);
}


L_INT DicomCreateNetExtExample(L_VOID)
{
   L_INT nRet = DICOM_SUCCESS;

   nRet = L_DicomStartUp();
   if (nRet != DICOM_SUCCESS)
      return nRet;

   L_SSL_CTX_CREATE ctxCreate;
   memset(&ctxCreate, 0, sizeof(L_SSL_CTX_CREATE));
   ctxCreate.uStructSize   = sizeof(L_SSL_CTX_CREATE);
   ctxCreate.uFlags        = FLAG_SSL_CTX_CREATE_METHOD_TYPE | FLAG_SSL_CTX_CREATE_VERIFY_MODE | 
      FLAG_SSL_CTX_CREATE_VERIFY_DEPTH | FLAG_SSL_CTX_CREATE_OPTIONS | FLAG_SSL_CTX_CREATE_CAFILE;
   ctxCreate.nMethodTypeSSL= TYPE_SSLV23_METHOD;
   
   ctxCreate.pszCAfile     = CA_CERT_NAME;
   ctxCreate.uVerifyMode   = L_SSL_VERIFY_PEER | L_SSL_VERIFY_FAIL_IF_NO_PEER_CERT;
   ctxCreate.nVerifyDepth  = 2;
   ctxCreate.nOptions      = L_SSL_OP_NO_SSLv2|L_SSL_OP_ALL;
   ctxCreate.nReserved1    = 0;
   ctxCreate.nReserved2    = 0;
   
   HDICOMNET hNet = L_DicomCreateNetExt(NULL, DICOM_SECURE_TLS, &ctxCreate);
   if (hNet)
   {
      L_TCHAR szMsg[200] = {0};
      lstrcpy(szMsg, TEXT("Security mode is Unknown."));
      // You can verify that the security mode is DICOM_SECURE_TLS
      L_UINT32 uSecurityMode = L_DicomGetSecureMode(hNet);
      switch(uSecurityMode)
      {
      case DICOM_SECURE_NONE:
         lstrcpy(szMsg, TEXT("Security mode is DICOM_SECURE_NONE."));
         break;
      case DICOM_SECURE_ISCL:
         lstrcpy(szMsg, TEXT("Security mode is DICOM_SECURE_ISCL."));
         break;
      case DICOM_SECURE_TLS:
         lstrcpy(szMsg, TEXT("Security mode is DICOM_SECURE_TLS."));
         break;
      }
      MessageBox(NULL, szMsg, TEXT(""), MB_OK);

      // Set up so the private key password callback gets called
      DICOMNETCALLBACKEXT CallbackExt;
      memset(&CallbackExt, 0, sizeof(DICOMNETCALLBACKEXT));
      CallbackExt.uStructSize = sizeof(DICOMNETCALLBACKEXT);
      CallbackExt.pfnPrivateKeyPassword = exPrivateKeyPassword;
      CallbackExt.pUserDataPrivateKeyPassword = NULL;

      L_DicomSetCallbackExt(hNet, &CallbackExt);

      // Assign the server the certificate
      // Note that SERVER_CERT_NAME contains both the password and an encrypted private key
      // When loading the private key, the OnPrivateKeyPassword virtual function is called
      // so that the encryption password "test" can be supplied
      nRet = L_DicomSetServerCertificateTLS(hNet, SERVER_CERT_NAME, L_TLS_FILETYPE_PEM, NULL);
      
      if (nRet == DICOM_SUCCESS)
         wsprintf(szMsg, TEXT("%s loaded successfully"), SERVER_CERT_NAME);
      else
         wsprintf(szMsg,TEXT("%s could not be loaded successfully -- error[%d]"), SERVER_CERT_NAME, nRet);
      MessageBox(NULL, szMsg, TEXT(""), MB_OK);
      
      //
      // Use the hNet 
      //
      
      
      // Cleanup
      L_DicomFreeNet(hNet);
   }
   L_DicomShutDown();
   return DICOM_SUCCESS;
}